@cordova-ohos/cordova-plugin-media

v3.0.0

Published

3 days ago

Cordova media Plugin

Downloads

154

0High
0Medium
0Low

cordova media ecosystem:cordova cordova-openharmony

cordova-plugin-media

cordova-plugin-media 是一个为 Cordova 应用提供音频录制、播放、暂停、停止等核心媒体操作能力的插件。该插件支持 Android、iOS、OHOS 主流移动平台，同时提供 Browser 平台的兼容实现，便于开发者快速构建具备媒体处理功能的跨平台应用（如语音备忘录、音频播放器等）。本文档主要OHOS系统的应用

1. 插件概述

1.1 核心功能

音频文件播放（支持本地文件、远程 URL 资源）
音频录制（支持自定义采样率、比特率、格式）
媒体操作控制（暂停、继续、停止、跳转播放位置）
播放 / 录制状态监听（如播放完成、录制中断、错误事件）
音量控制（系统音量、媒体音量独立调节）

1.2 支持平台

✅ Android (API Level 21+)
✅ iOS (12.0+)
✅ Browser (Chrome、Firefox 等现代浏览器)
✅ OHOS （5.0+）

2. 安装与卸载

2.1 前提条件

已安装 npm
已安装 hcordova
已创建 Cordova 项目（hcordova create myApp）

2.2 安装插件

在 Cordova 项目根目录执行以下命令：

#安装hcordova命令工具
npm install -g hcordova

#安装最新稳定版
hcordova plugin add cordova-plugin-media

#指定平台安装
hcordova plugin add cordova-plugin-media --platform ohos

# 从 GitCode 安装
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-media.git --platform ohos

2.3 卸载插件

如需移除插件，执行以下命令：

#全平台卸载
hcordova plugin remove cordova-plugin-media
#指定平台卸载
hcordova plugin remove cordova-plugin-media --platform ohos

3. 核心 API 文档

插件通过全局对象 media 暴露所有功能，创建媒体实例后即可调用对应方法。

3.1 1. 创建媒体实例

/*
* 创建媒体实例
* @param src - 音频资源路径（本地文件路径或远程 URL）
* @param successCallback - 成功回调（播放/录制完成时触发）
* @param errorCallback - 错误回调（发生错误时触发）
* @param statusCallback - 状态回调（状态变化时触发）
* @returns Media 对象 - 媒体操作实例
*/

const media = new Media(
   src,
   () => { console.log("操作完成"); },  // 成功回调
   (err) => { console.error("错误:", err); },  // 错误回调
   (status) => { console.log("当前状态:", status); }  // 状态回调
);

路径说明（重要）：

OHOS 本地文件：通过 cordova-plugin-file 插件设置生成的沙箱文件路径。
本地文件：需使用 cdvfile:// 协议路径或沙盒内绝对路径（例如 cdvfile://localhost/persistent/recording.m4a）。
远程资源：直接传入 HTTP/HTTPS URL（例如 https://localhost/persistent/recording.m4a），不存在跨域问题。

3.2 2. 媒体操作方法

| 方法名 | 描述 | 参数 | 返回值 | | ------------------------------------- | ----------------- | ----------------------------------------------------| --- | | play() | 播放音频 | 无 | 无 | | pause() | 暂停播放 | 无 | 无 | | stop() | 停止播放 / 录制 | 无 | 无 | | seekTo(milliseconds) | 跳转到指定播放位置 | milliseconds (数字)：目标位置（毫秒） | 无 | | startRecord() | 开始录制音频 | 无 | 无 | | stopRecord() | 停止录制音频 | 无 | 无 | | setVolume(volume) | 设置媒体音量 | volume (数字)：0.0 ~ 1.0（0 为静音，1 为最大音量） | 无 | | getCurrentPosition(successCallback) | 获取当前播放位置 | successCallback：回调参数为当前位置（毫秒） | 无 | | release() | 释放媒体资源（重要：避免内存泄漏） | 无 | 无 |

3.3 3. 媒体状态常量

通过 Media 对象的静态属性获取状态，可在 statusCallback 中判断当前状态：

| 常量 | 值 | 描述 | | ---------------------- | - | ---------- | | Media.MEDIA_NONE | 0 | 无媒体资源 | | Media.MEDIA_STARTING | 1 | 播放 / 录制开始中 | | Media.MEDIA_RUNNING | 2 | 播放 / 录制中 | | Media.MEDIA_PAUSED | 3 | 暂停中 | | Media.MEDIA_STOPPED | 4 | 已停止 |

3.4 4. 错误常量

错误回调中返回的 error.code 对应以下常量：

| 常量 | 值 | 描述 | | ------------------------------------- | - | -------------- | | MediaError.MEDIA_ERR_ABORTED | 1 | 操作被用户中止 | | MediaError.MEDIA_ERR_NETWORK | 2 | 网络错误（远程资源加载失败） | | MediaError.MEDIA_ERR_DECODE | 3 | 音频解码失败（格式不支持） | | MediaError.MEDIA_ERR_NONE_SUPPORTED | 4 | 无支持的媒体格式 |

4. 使用示例

以下示例包含音频录制和音频播放两个核心场景，需配合 cordova-plugin-file 获取本地文件路径（安装：hcordova plugin add cordova-plugin-file）。

//开始录制音频
var my_media = null;
function startRecord() {
    function onSuccess(successInfo) {
        alert(successInfo);
    }

    function onError(errorInfo) {
        alert("MediaErrorInfo:"+errorInfo);
    }

    window.resolveLocalFileSystemURL(cordova.file.externalDataDirectory, function(dirEntry) {
        var targetPath = dirEntry.toURL() + "test.m4a";
        my_media = new Media(targetPath, onSuccess, onError);
        /*
        var counter = 0;
        var timerDur = setInterval(function() {
            counter = counter + 100;
            if (counter > 2000) {
                clearInterval(timerDur);
            }
            var dur = my_media.getDuration();
            if (dur > 0) {
                clearInterval(timerDur);
                document.getElementById('mediaInfo').innerHTML = (dur) + " sec";
            }

        }, 1000);*/
        /*
        var mediaTimer = setInterval(function () {
            // get media position
            my_media.getCurrentPosition(
                // success callback
                function (position) {
                    if (position > -1) {
                        console.log((position) + " sec");
                    }
                },
                // error callback
                function (e) {
                    console.log("Error getting pos=" + e);
                }
            );
        }, 1000);
        */
        my_media.startRecord();
    });
}

//暂停录制
function pauseRecord() {
    my_media.pauseRecord();
    document.getElementById("mediaInfo").innerHTML = "录音已暂停";
}

//继续录制
function resumeRecord() {
    my_media.resumeRecord();
    document.getElementById("mediaInfo").innerHTML = "正在录音";
}

//停止录制
function stopRecord() {
    my_media.stopRecord();
    document.getElementById("mediaInfo").innerHTML = "录音结束";
}

//开始播放
function startPlaying() {
    if(my_media != null) {
        my_media.play();
        document.getElementById("mediaInfo").innerHTML = "正在播放";
    }
}

//暂停播放
function pausePlaying() {
    if(my_media != null) {
        my_media.pause();
        document.getElementById("mediaInfo").innerHTML = "已暂停播放";
    }
}

//继续播放
function resumePlaying() {
    if(my_media != null) {
        my_media.play();
        document.getElementById("mediaInfo").innerHTML = "正在播放";
    }
}

//停止播放
function stopPlaying() {
    if(my_media != null) {
        my_media.stop();
        document.getElementById("mediaInfo").innerHTML = "已停止播放";
    }
}

//关闭音量
function setVolume0() {
    if(my_media != null) {
        my_media.setVolume(0);
        document.getElementById("mediaInfo").innerHTML = "关闭声音";
    }
}

//设置音量
function setVolume1() {
    if(my_media != null) {
        my_media.setVolume(1);
        document.getElementById("mediaInfo").innerHTML = "原始声音";
    }
}

//跳转进度
function seekTo() {
    if(my_media != null) {
        my_media.seekTo(1000);
        document.getElementById("mediaInfo").innerHTML = "设置播放进度";
    }
}

//设置倍速
function setRate() {
    if(my_media != null) {
        my_media.setRate(0.5);
        document.getElementById("mediaInfo").innerHTML = "设置慢速播放";
    }
}

//释放资源
function releaseAudio() {
    if(my_media != null) {
        my_media.release();
        document.getElementById("mediaInfo").innerHTML = "已释放音频";
        my_media = null;
    }
}

5. OHOS权限

需在主工程module.json5中添加麦克风权限

{
    "name": "ohos.permission.MICROPHONE",
    "reason": "$string:microphoneInfo",
    "usedScene": {
        "abilities": [
        "EntryAbility"
        ],
        "when": "always"
    }
}

6. 支持的音频格式

播放：MP3、WAV、OGG、AAC
录制：推荐m4a

7. 参考资源

GitHub Android、iOS仓库：apache/cordova-plugin-media

8. 许可证

本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。