cordova-plugin-media

Android Testsuite Chrome Testsuite iOS Testsuite Lint Test

此外掛程式提供在裝置上錄製和播放音訊檔案的功能。

注意：目前的實作並不符合 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 權限不再有效，並且不提供存取權。

如果此權限未列入以 API 等級低於 Build.VERSION_CODES.Q (SDK 29) 為目標的應用程式的允許清單，則此權限無法授予應用程式。

如果您需要新增此權限，請將以下內容新增至您的 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 物件完成目前的播放、錄製或停止動作後執行的回呼。(Function)

  • mediaError：(可選) 如果發生錯誤則執行的回呼。它會接收一個整數錯誤碼。(Function)

  • mediaStatus：(可選) 執行以指示狀態變更的回呼。它會接收一個整數狀態碼。(Function)

  • mediaDurationUpdate：(可選) 當檔案的持續時間更新並可用時執行的回呼。(Function)

注意：cdvfile 路徑支援作為 src 參數

var my_media = new Media('cdvfile://127.0.0.1/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();

支援的平台

  • 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();

    // 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();

支援的平台

  • 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();

    // 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 存取。錄製時指定的任何子目錄都必須已經存在。

  • 可以使用 documents 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