Media 物件提供錄製與回放音訊的能力,是 PhoneGap 中處理聲音的核心 API。
var media = new Media(src, mediaSuccess, [mediaError]);
要注意的是,Media 的當時實作並未遵循 W3C Media Capture 規範,僅求方便;後續版本可能改為符合最新 W3C 標準並停止支援現有 API。
getCurrentPosition:取得目前播放位置getDuration:取得音檔總長度play / pause / stop:開始(或恢復)/暫停/停止播放seekTo:跳轉到指定位置startRecord / stopRecord:開始/停止錄製release:釋放底層系統的音訊資源唯讀屬性:_position(秒,播放中不自動更新,需呼叫 getCurrentPosition 才刷新)、_duration(秒)。支援平台為 Android 與 iOS。
media.getCurrentPosition(mediaSuccess, [mediaError]);
非同步函式,會回傳並更新 Media 物件的 _position。
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);
注意位置單位是毫秒,除以 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);
function playAudio(url) {
var my_media = new Media(url,
function() { console.log("playAudio():Audio Success"); },
function(err) { console.log("playAudio():Audio Error: " + err); }
);
my_media.play();
// 10 秒後暫停
setTimeout(function() { my_media.pause(); }, 10000);
}
三者皆為同步函式。pause 保留播放位置可續播,stop 則會結束播放。
var my_media = new Media(src, onSuccess, onError);
my_media.play();
my_media.stop();
my_media.release();
這個方法在 Android 上特別重要:OpenCore(多媒體核心)的實例數量有限,不再需要時必須主動釋放,否則後續建立 Media 會失敗。iOS 上則相對寬鬆。
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 先行建立。
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"https://www.w3.org/TR/html4/strict.dtd">
<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);
function onDeviceReady() {
playAudio("https://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
}
var my_media = null;
var mediaTimer = null;
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 回呼:
function(error) {
// 處理錯誤
}
常數對照:
MediaError.MEDIA_ERR_ABORTED:媒體中斷MediaError.MEDIA_ERR_NETWORK:網路錯誤MediaError.MEDIA_ERR_DECODE:解碼錯誤MediaError.MEDIA_ERR_NONE_SUPPORTED:格式不支援第一,一定要等 deviceready。PhoneGap 的 API 由原生層注入,頁面 DOM 完成不代表 phonegap.js 已就緒,過早呼叫會拿到 undefined。
第二,單位是毫秒。getCurrentPosition 與 getDuration 回傳的都是毫秒,這點與 HTML5 Audio 的秒為單位不同,容易混淆。
第三,定時器要記得清掉。範例中 stopAudio 除了 stop 還 clearInterval,若只在 pause 時不清,卸載頁面前 timer 會持續呼叫已釋放的 media 物件而拋錯。