master.

cordova-plugin-media

此插件提供在设备上录制和播放音频文件的功能。

注意：当前实现不符合 W3C 媒体捕获规范，仅出于方便性提供。未来的实现将符合最新的 W3C 规范，并可能弃用当前 API。

此插件定义了一个全局 Media 构造函数。

虽然在全局范围内，但在 deviceready 事件之后才可用。

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(Media);
}

安装

cordova plugin add cordova-plugin-media

支持的平台

Android
iOS
浏览器

Android 特性

SDK 目标小于 29

从官方 Android 11 中的存储更新文档中，WRITE_EXTERNAL_STORAGE 权限不再有效，并且不提供访问权限。

如果此权限未被列入针对低于 Build.VERSION_CODES.Q (SDK 29) 的 API 级别目标的应用程序的允许列表，则无法将此权限授予应用程序。

如果您需要添加此权限，请将以下内容添加到您的 config.xml 中。

<config-file target="AndroidManifest.xml" parent="/*" xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" />
</config-file>

媒体

var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);

参数

src：包含音频内容的 URI。(DOMString)
mediaSuccess： (可选) 在 Media 对象完成当前播放、录制或停止操作后执行的回调。(函数)
mediaError： (可选) 如果发生错误，则执行的回调。它接受一个整数错误代码。(函数)
mediaStatus： (可选) 执行以指示状态更改的回调。它接受一个整数状态代码。(函数)
mediaDurationUpdate： (可选) 当文件持续时间更新并可用时执行的回调。(函数)

注意：cdvfile 路径作为 src 参数支持

var my_media = new Media('cdvfile://localhost/temporary/recording.mp3', ...);

常量

以下常量作为 mediaStatus 回调的唯一参数报告

Media.MEDIA_NONE = 0;
Media.MEDIA_STARTING = 1;
Media.MEDIA_RUNNING = 2;
Media.MEDIA_PAUSED = 3;
Media.MEDIA_STOPPED = 4;

方法

media.getCurrentAmplitude：返回音频文件中的当前振幅。
media.getCurrentPosition：返回音频文件中的当前位置。
media.getDuration：返回音频文件的持续时间。
media.play：开始或恢复播放音频文件。
media.pause：暂停播放音频文件。
media.pauseRecord：暂停录制音频文件。
media.release：释放底层操作系统的音频资源。
media.resumeRecord：恢复录制音频文件。
media.seekTo：移动音频文件中的位置。
media.setVolume：设置音频播放的音量。
media.startRecord：开始录制音频文件。
media.stopRecord：停止录制音频文件。
media.stop：停止播放音频文件。
media.setRate：设置音频文件的播放速度。

其他只读参数

position：音频播放中的位置，以秒为单位。
- 在播放期间不会自动更新；调用 getCurrentPosition 以更新。
duration：媒体的持续时间，以秒为单位。

media.getCurrentAmplitude

返回音频文件中的当前振幅。

media.getCurrentAmplitude(mediaSuccess, [mediaError]);

支持的平台

Android
iOS

参数

mediaSuccess：传递当前振幅 (0.0 - 1.0) 的回调。
mediaError： (可选) 如果发生错误，则执行的回调。

快速示例

// Audio player
//
var my_media = new Media(src, onSuccess, onError);

// Record audio
my_media.startRecord();

mediaTimer = setInterval(function () {
    // get media amplitude
    my_media.getCurrentAmplitude(
        // success callback
        function (amp) {
            console.log(amp + "%");
        },
        // error callback
        function (e) {
            console.log("Error getting amp=" + e);
        }
    );
}, 1000);

media.getCurrentPosition

返回音频文件中的当前位置。还会更新 Media 对象的 position 参数。

media.getCurrentPosition(mediaSuccess, [mediaError]);

参数

mediaSuccess：传递当前位置（以秒为单位）的回调。
mediaError： (可选) 如果发生错误，则执行的回调。

快速示例

// Audio player
//
var my_media = new Media(src, onSuccess, onError);

// Update media position every second
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);

media.getDuration

返回音频文件的持续时间（以秒为单位）。如果持续时间未知，则返回 -1。

media.getDuration();

快速示例

// Audio player
//
var my_media = new Media(src, onSuccess, onError);

// Get duration
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('audio_duration').innerHTML = (dur) + " sec";
    }
}, 100);

Android 特性

较新版本的 Android 具有积极的例程，限制了后台处理。如果您尝试在应用程序处于后台超过大约 5 分钟的时间内获取持续时间，则使用 mediaDurationUpdate 构造函数的回调将获得更一致的结果。

media.pause

暂停播放音频文件。

media.pause();

快速示例

// Play audio
//
function playAudio(url) {
    // Play the audio file at url
    var my_media = new Media(url,
        // success callback
        function () { console.log("playAudio():Audio Success"); },
        // error callback
        function (err) { console.log("playAudio():Audio Error: " + err); }
    );

    // Play audio
    my_media.play();

    // Pause after 10 seconds
    setTimeout(function () {
        my_media.pause();
    }, 10000);
}

media.pauseRecord

暂停录制音频文件。

media.pauseRecord();

支持的平台

快速示例

// Record audio
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // success callback
        function() {
            console.log("recordAudio():Audio Success");
        },

        // error callback
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        });

    // Record audio
    mediaRec.startRecord();

    // Pause Recording after 5 seconds
    setTimeout(function() {
        mediaRec.pauseRecord();
    }, 5000);
}

media.play

开始或恢复播放音频文件。

media.play();

快速示例

// Play audio
//
function playAudio(url) {
    // Play the audio file at url
    var my_media = new Media(url,
        // success callback
        function () {
            console.log("playAudio():Audio Success");
        },
        // error callback
        function (err) {
            console.log("playAudio():Audio Error: " + err);
        }
    );
    // Play audio
    my_media.play();
}

iOS 特性

numberOfLoops：将此选项传递给 play 方法以指定要播放媒体文件的次数，例如

  var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
  myMedia.play({ numberOfLoops: 2 })

playAudioWhenScreenIsLocked：将此选项传递给 play 方法以指定是否允许在屏幕锁定状态下播放。如果设置为 true（默认值），则会忽略硬件静音按钮的状态，例如
```
  var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
  myMedia.play({ playAudioWhenScreenIsLocked : true });
  myMedia.setVolume('1.0');
```

注意：要允许在屏幕锁定状态下播放或播放背景音频，您必须在 info.plist 文件中将 audio 添加到 UIBackgroundModes 中。请参阅 Apple 文档。另请注意，音频必须在转到后台之前启动。

文件搜索顺序：当仅提供文件名或简单路径时，iOS 会在 www 目录中搜索文件，然后在应用程序的 documents/tmp 目录中搜索。

  var myMedia = new Media("audio/beer.mp3")
  myMedia.play()  // first looks for file in www/audio/beer.mp3 then in <application>/documents/tmp/audio/beer.mp3

media.release

释放底层操作系统的音频资源。这对于 Android 尤其重要，因为媒体播放的 OpenCore 实例数量有限。应用程序应为不再需要的任何 Media 资源调用 release 函数。

media.release();

快速示例

// Audio player
//
var my_media = new Media(src, onSuccess, onError);

my_media.play();
my_media.stop();
my_media.release();

media.resumeRecord

恢复录制音频文件。

media.resumeRecord();

支持的平台

快速示例

// Record audio
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // success callback
        function() {
            console.log("recordAudio():Audio Success");
        },

        // error callback
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        });

    // Record audio
    mediaRec.startRecord();

    // Pause Recording after 5 seconds
    setTimeout(function() {
        mediaRec.pauseRecord();
    }, 5000);

    // Resume Recording after 10 seconds
    setTimeout(function() {
        mediaRec.resumeRecord();
    }, 10000);
}

media.seekTo

设置音频文件中的当前位置。

media.seekTo(milliseconds);

参数

milliseconds：在音频中设置播放位置的位置，以毫秒为单位。

快速示例

// Audio player
//
var my_media = new Media(src, onSuccess, onError);
    my_media.play();
// SeekTo to 10 seconds after 5 seconds
setTimeout(function() {
    my_media.seekTo(10000);
}, 5000);

media.setVolume

设置音频文件的音量。

media.setVolume(volume);

参数

volume：要设置的播放音量。该值必须在 0.0 到 1.0 的范围内。

支持的平台

Android
iOS

快速示例

// Play audio
//
function playAudio(url) {
    // Play the audio file at url
    var my_media = new Media(url,
        // success callback
        function() {
            console.log("playAudio():Audio Success");
        },
        // error callback
        function(err) {
            console.log("playAudio():Audio Error: "+err);
    });

    // Play audio
    my_media.play();

    // Mute volume after 2 seconds
    setTimeout(function() {
        my_media.setVolume('0.0');
    }, 2000);

    // Set volume to 1.0 after 5 seconds
    setTimeout(function() {
        my_media.setVolume('1.0');
    }, 5000);
}

media.startRecord

开始录制音频文件。

media.startRecord();

支持的平台

Android
iOS

快速示例

// Record audio
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // success callback
        function() {
            console.log("recordAudio():Audio Success");
        },

        // error callback
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        });

    // Record audio
    mediaRec.startRecord();
}

Android 特性

Android 设备以 AAC ADTS 文件格式录制音频。指定的文件应以 .aac 扩展名结尾。
硬件音量控制在任何 Media 对象处于活动状态时连接到媒体音量。一旦最后一个创建的 Media 对象调用了 release()，音量控制将恢复为其默认行为。控制也会在页面导航时重置，因为这会释放所有 Media 对象。

iOS 特性

iOS 仅录制到 .wav 和 .m4a 类型的文件，如果文件名扩展名不正确，则会返回错误。
如果没有提供完整路径，则录制将放置在应用程序的 documents/tmp 目录中。这可以通过使用 LocalFileSystem.TEMPORARY 的 File API 访问。在录制时指定的任何子目录必须已经存在。

可以使用文档 URI 录制和播放文件

  var myMedia = new Media("documents://beer.mp3")

从 iOS 10 开始，如果尝试访问隐私敏感数据，则必须在 info.plist 中提供使用说明。当系统提示用户允许访问时，此使用说明字符串将显示在权限对话框中，但如果您没有提供使用说明，则应用程序将在显示对话框之前崩溃。此外，Apple 会拒绝访问私有数据但没有提供使用说明的应用程序。

此插件需要以下使用说明

NSMicrophoneUsageDescription 描述了应用程序访问用户麦克风的理由。

要将此条目添加到 info.plist 中，您可以使用 config.xml 中的 edit-config 标签，如下所示

<edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
    <string>need microphone access to record sounds</string>
</edit-config>

media.stop

停止播放音频文件。

media.stop();

快速示例

// Play audio
//
function playAudio(url) {
    // Play the audio file at url
    var my_media = new Media(url,
        // success callback
        function() {
            console.log("playAudio():Audio Success");
        },
        // error callback
        function(err) {
            console.log("playAudio():Audio Error: "+err);
        }
    );

    // Play audio
    my_media.play();

    // Pause after 10 seconds
    setTimeout(function() {
        my_media.stop();
    }, 10000);
}

media.stopRecord

停止录制音频文件。

media.stopRecord();

支持的平台

Android
iOS

快速示例

// Record audio
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // success callback
        function() {
            console.log("recordAudio():Audio Success");
        },

        // error callback
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        }
    );

    // Record audio
    mediaRec.startRecord();

    // Stop recording after 10 seconds
    setTimeout(function() {
        mediaRec.stopRecord();
    }, 10000);
}

media.setRate

停止录制音频文件。

media.setRate(rate);

支持的平台

iOS
Android (API 23+)

参数

rate：要设置的播放速度。

快速示例

// Audio player
//
var my_media = new Media(src, onSuccess, onError);
    my_media.play();

// Set playback rate to 2.0x after 10 seconds
setTimeout(function() {
    my_media.setRate(2.0);
}, 5000);

MediaError

当发生错误时，MediaError 对象将返回到 mediaError 回调函数。

属性

code：下面列出的预定义错误代码之一。
message：描述错误详细信息的错误消息。

常量

MediaError.MEDIA_ERR_ABORTED = 1
MediaError.MEDIA_ERR_NETWORK = 2
MediaError.MEDIA_ERR_DECODE = 3
MediaError.MEDIA_ERR_NONE_SUPPORTED = 4