npm package: @luqi_test/cordova-plugin-media
Description: Cordova media Plugin
Author: Huawei Device, Inc. Ltd. and
Latest version: 3.0.0

# 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 项目根目录执行以下命令：



```bash
#安装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 卸载插件

如需移除插件，执行以下命令：



```bash
#全平台卸载
hcordova plugin remove cordova-plugin-media
#指定平台卸载
hcordova plugin remove cordova-plugin-media --platform ohos
```

## 3. 核心 API 文档

插件通过全局对象 `media` 暴露所有功能，创建媒体实例后即可调用对应方法。

### 3.1 1. 创建媒体实例



```js
/*
* 创建媒体实例
* @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`）。

```js
//开始录制音频
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中添加麦克风权限
```json
{
    "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](https://github.com/apache/cordova-plugin-media)


## 8. 许可证

本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。