您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 訊息 >> iOS 相關資訊

PhoneGap API 中文help文件:Media 媒體播放與錄音

編輯:iOS 相關資訊

Media 物件是 PhoneGap 提供給 HTML5 應用存取裝置音訊能力的核心介面,同時涵蓋「播放」與「錄音」兩大用途。以下依序說明建構方式、方法清單、各方法的行為差異與錯誤處理。

備註:Media 的當前實作並未完全遵循 W3C 媒體捕獲規範,目前的設計以「方便好用」為優先。未來版本將逐步對齊 W3C 標準,因此現有的 API 有可能在升級後不再被支援,撰寫新專案時請留意。

一、建立 Media 物件

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

參數說明:

  • src(DOMString):指向音訊內容的 URI。
  • mediaSuccess(函數,選用):完成播放、錄音或停止時的回呼。
  • mediaError(函數,選用):發生錯誤時的回呼。
  • mediaStatus(函數,選用):狀態改變時的回呼。

支援平台:Android、iOS。

二、方法與唯讀屬性總覽

  • media.getCurrentPosition:取得目前播放位置。
  • media.getDuration:取得音訊總長度。
  • media.play:開始或恢復播放。
  • media.pause:暫停播放。
  • media.release:釋放底層系統的音訊資源。
  • media.seekTo:跳轉到指定位置。
  • media.startRecord:開始錄音。
  • media.stopRecord:停止錄音。
  • media.stop:停止播放。

唯讀屬性:_position 為目前播放位置(秒),播放過程中不會自動更新,需呼叫 getCurrentPosition 才會刷新;_duration 為媒體長度(秒)。

三、getCurrentPosition:非同步取得播放位置

media.getCurrentPosition(mediaSuccess, [mediaError]);

這是個非同步函數,成功後回傳目前位置並同步更新 _position。因此想即時顯示播放進度,需要用 setInterval 定時輪詢:

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

// 每秒更新一次播放位置
var mediaTimer = setInterval(function() {
    my_media.getCurrentPosition(
        function(position) {
            if (position > -1) {
                console.log((position / 1000) + " sec");
            }
        },
        function(e) {
            console.log("Error getting pos=" + e);
        }
    );
}, 1000);

四、getDuration:同步取得音訊長度

media.getDuration();

與前者不同,這是同步函數。若長度已知,直接回傳秒數;若尚不可知則回傳 -1。實務上常這樣處理:因為載入需要時間,剛建立物件時往往還拿不到長度,所以必須定時重試直到取到正值為止。

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 / 1000) + " sec";
    }
}, 100);

五、播放、暫停與停止

play()、pause()、stop() 三者都是同步函數,差別在語意:pause 之後可以用 play 從原處續播,而 stop 會結束播放,再次播放則從頭開始。因此若你的播放器 UI 有「停止」鈕,記得同時清掉位置輪詢的計時器,否則它會一直空轉。

六、release:Android 上特別重要

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

release() 用來釋放底層作業系統的音訊資源。這個方法在 Android 上尤其關鍵,因為 Android 的 OpenCore(多媒體核心)實例數量有限,若不主動釋放,開啟幾個媒體後就會無法再建立新的 Media 物件。養成「用完就 release」的習慣,能避免大量難以追查的錄音/播放失效問題。

七、錄音:startRecord 與 stopRecord

function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src, onSuccess, onError);
    mediaRec.startRecord();

    // 10 秒後停止錄音
    var recTime = 0;
    var recInterval = setInterval(function() {
        recTime = recTime + 1;
        setAudioPosition(recTime + " sec");
        if (recTime >= 10) {
            clearInterval(recInterval);
            mediaRec.stopRecord();
        }
    }, 1000);
}
iOS 特例:用於錄音的檔案必須事先存在且為 .wav 格式,可利用 File API 先行建立,否則錄音會失敗。

八、完整播放器的 HTML 骨架

把上述片段組起來,一個可運作的播放器大致如下(省略部分重複的樣板):

<!DOCTYPE html>
<html>
<head>
<title>Media Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// 等待 PhoneGap 就緒
document.addEventListener("deviceready", onDeviceReady, false);

var my_media = null;
var mediaTimer = null;

function onDeviceReady() {
    playAudio("https://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
}

function playAudio(src) {
    my_media = new Media(src, onSuccess, onError);
    my_media.play();

    if (mediaTimer == null) {
        mediaTimer = setInterval(function() {
            my_media.getCurrentPosition(
                function(position) {
                    if (position > -1) {
                        setAudioPosition((position / 1000) + " sec");
                    }
                },
                function(e) {
                    console.log("Error getting pos=" + e);
                    setAudioPosition("Error: " + e);
                }
            );
        }, 1000);
    }
}

function pauseAudio() {
    if (my_media) { my_media.pause(); }
}

function stopAudio() {
    if (my_media) { my_media.stop(); }
    clearInterval(mediaTimer);
    mediaTimer = null;
}

function onSuccess() { console.log("playAudio(): Audio Success"); }

function onError(error) {
    alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n');
}

function setAudioPosition(position) {
    document.getElementById('audio_position').innerHTML = position;
}
</script>
</head>
<body>
<a href="#" class="btn large" onclick="playAudio('https://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
<a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
<a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
<p id="audio_position"></p>
</body>
</html>

九、MediaError 與錯誤回呼

發生錯誤時,一個 MediaError 物件會被傳入 mediaError 回呼,它有兩個屬性:code(錯誤碼)與 message(描述訊息)。可用的錯誤碼常量如下:

  • MediaError.MEDIA_ERR_ABORTED:媒體作業中斷。
  • MediaError.MEDIA_ERR_NETWORK:網路錯誤。
  • MediaError.MEDIA_ERR_DECODE:解碼錯誤。
  • MediaError.MEDIA_ERR_NONE_SUPPORTED:格式不支援。
function (error) {
    // 處理錯誤
}

實務上最常遇到的是 MEDIA_ERR_NETWORK 與 MEDIA_ERR_NONE_SUPPORTED。前者多為線路或跨網域問題,後者則是因為 iOS 對 mp3 以外的格式支援有限,錄音時務必確認檔案為 wav。把錯誤碼直接顯示在使用者面前並不友善,建議在正式版本中轉成「播放失敗,請稍後再試」這類提示,同時把原始 code 寫進 log 方便排查。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved