HTML5 的 HTMLMediaElement 是 HTMLVideoElement 與 HTMLAudioElement 的共同父類,所以影音兩者的 API 幾乎完全一樣。以下把常用的屬性、方法與事件整理成一份可查閱的清單。
// audio 可以直接用 new 建立
Media = new Audio("https://www.abc.com/test.mp3");
// audio 與 video 都可以透過標籤取得
Media = document.getElementById("media");
Media.error; // null 表示正常
Media.error.code; // 1 使用者中止 / 2 網路錯誤 / 3 解碼錯誤 / 4 URL 無效
Media.currentSrc; // 目前資源的 URL
Media.src = value; // 取得或設定資源 URL
Media.canPlayType(type);// 是否能播放某種格式
Media.networkState; // 0 未初始化 / 1 已就緒但未連線 / 2 正在下載 / 3 找不到資源
Media.load(); // 重新載入 src 指定的資源
Media.buffered; // 已緩衝區段,TimeRanges
Media.preload; // none / metadata / auto
Media.readyState; // 0 HAVE_NOTHING / 1 HAVE_METADATA / 2 HAVE_CURRENT_DATA
// 3 HAVE_FUTURE_DATA / 4 HAVE_ENOUGH_DATA
Media.seeking; // 是否正在跳轉
Media.currentTime = value; // 目前播放位置,賦值可跳轉
Media.startTime; // 一般為 0
Media.duration; // 總長度,串流會是 Infinity
Media.paused; // 是否暫停
Media.defaultPlaybackRate = v; // 預設播放速率
Media.playbackRate = v; // 目前播放速率,設定後立即生效
Media.played; // 已播放區段,TimeRanges
Media.seekable; // 可跳轉區段,TimeRanges
Media.ended; // 是否播放結束
Media.autoPlay; // 是否自動播放
Media.loop; // 是否循環
Media.play(); // 播放
Media.pause(); // 暫停
Media.controls; // 是否顯示原生控制列
Media.volume = value; // 音量 0~1
Media.muted = value; // 靜音
TimeRanges.length; // 區段數量
TimeRanges.start(index); // 第 index 段的開始時間
TimeRanges.end(index); // 第 index 段的結束時間
為什麼需要區段的概念?因為使用者隨便拖動進度條後,已緩衝的部分可能變成好幾段不連續的區間,buffered 與 played 正是用來描述這種情況。
var eventTester = function (e) {
Media.addEventListener(e, function () {
console.log((new Date()).getTime(), e);
});
}
eventTester("loadstart"); // 開始請求資料
eventTester("progress"); // 正在請求資料
eventTester("suspend"); // 延後下載
eventTester("abort"); // 主動中止下載(非錯誤導致)
eventTester("error"); // 請求資料時發生錯誤
eventTester("stalled"); // 網速失速
eventTester("play"); // play() 或 autoPlay 觸發
eventTester("pause"); // pause() 觸發
eventTester("loadedmetadata"); // 成功取得長度等 metadata
eventTester("loadeddata"); // 目前幀資料已載入
eventTester("waiting"); // 等待資料(非錯誤)
eventTester("playing"); // 開始播放
eventTester("canplay"); // 可播放,中途可能因緩衝暫停
eventTester("canplaythrough"); // 可預期完整播放完畢
eventTester("seeking"); // 正在尋找位置
eventTester("seeked"); // 尋找完成
eventTester("timeupdate"); // 播放時間改變
eventTester("ended"); // 播放結束
eventTester("ratechange"); // 播放速率改變
eventTester("durationchange"); // 總長度改變
eventTester("volumechange"); // 音量改變
$(function () {
var p = new Player();
p.read("play");
$("#stop").click(function () { p.pause(); });
$("#start").click(function () { p.play(); });
$("#show").click(function () { alert(p.duration()); });
setInterval(function () {
$("#currentTime").text(p.currentTime());
}, 1000);
});
function Player() {};
Player.prototype = {
box: new Object(),
read: function (id) {
this.box = document.getElementById(id);
},
play: function () {
this.box.play();
},
pause: function () {
this.box.pause();
},
src: function (url) {
this.box.src = url;
},
currentTime: function () {
return (this.box.currentTime / 60).toFixed(2);
}
};
Player.prototype.duration = function () {
return (this.box.duration / 60).toFixed(2);
};
實務上補充兩點:行動瀏覽器基於政策,通常不允許在没有使用者互動的情況下自動播放有聲音的媒體,因此 autoplay 往往要在使用者點擊後才生效;另外 duration 在 metadata 抵達前會是 NaN,取值前記得先確認 readyState。