Media 物件是 PhoneGap 提供給 HTML5 應用存取裝置音訊能力的核心介面,同時涵蓋「播放」與「錄音」兩大用途。以下依序說明建構方式、方法清單、各方法的行為差異與錯誤處理。
var media = new Media(src, mediaSuccess, [mediaError]);
參數說明:
支援平台:Android、iOS。
media.getCurrentPosition:取得目前播放位置。media.getDuration:取得音訊總長度。media.play:開始或恢復播放。media.pause:暫停播放。media.release:釋放底層系統的音訊資源。media.seekTo:跳轉到指定位置。media.startRecord:開始錄音。media.stopRecord:停止錄音。media.stop:停止播放。唯讀屬性:_position 為目前播放位置(秒),播放過程中不會自動更新,需呼叫 getCurrentPosition 才會刷新;_duration 為媒體長度(秒)。
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);
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 有「停止」鈕,記得同時清掉位置輪詢的計時器,否則它會一直空轉。
my_media.play(); my_media.stop(); my_media.release();
release() 用來釋放底層作業系統的音訊資源。這個方法在 Android 上尤其關鍵,因為 Android 的 OpenCore(多媒體核心)實例數量有限,若不主動釋放,開啟幾個媒體後就會無法再建立新的 Media 物件。養成「用完就 release」的習慣,能避免大量難以追查的錄音/播放失效問題。
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);
}
.wav 格式,可利用 File API 先行建立,否則錄音會失敗。把上述片段組起來,一個可運作的播放器大致如下(省略部分重複的樣板):
<!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 回呼,它有兩個屬性: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 方便排查。