HTML5 的 <audio> 與 <video> 元素,背後其實是一整套名為 Media API 的 JavaScript 介面。只要掌握了屬性、方法與事件這三層結構,就能完全擺脫瀏覽器預設控制列,做出屬於自己的播放器。本文以一個可操作的 Audio API 範例頁面為主軸,逐項拆解。
範例把介面切為三塊:一個 <audio> 元素、一整排控制按鈕,以及三張即時狀態表(播放器屬性、媒體資訊、播放狀態)。所有操作結果都輸出到 console,方便邊點邊觀察。
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>HTML Audio API</title>
<link rel="stylesheet" href="./style/main.css" />
<script src="./script/audio-controls.js"></script>
</head>
<body>
<header>
<h1>HTML5 Audio API</h1>
<p>HTML5 Audio API demo by <a href="https://github.com/LearnShare">LearnShare</a>.</p>
<p>
Last update @2013-04-23 20:40:00
+ add info table
update @2013-04-22 14:54:00
+ add DOM events
update @2013-04-22 12:47:00
+ add getCurrentSrc button
</p>
<p>
View code on <a href="https://github.com/LearnShare/LearnShare.github.io/tree/master/labs/audio/">LearnShare.github.io</a>.
API reference: <a href="https://developer.mozilla.org/zh-CN/docs/DOM/HTMLMediaElement">HTMLMediaElement</a> and <a href="https://www.w3schools.com/tags/ref_av_dom.asp">Audio/Video DOM References</a>
</p>
</header>
<article>
<section>
<h2>Audio Element</h2>
<audio id="audio" src="./media/music1.mp3" controls="controls"></audio>
<p>Open the <strong>developer tool</strong> to view console logs.</p>
</section>
<section>
<h2>Controls</h2>
<button id="play">play</button>
<button id="pause">pause</button>
<button id="get_paused">getPaused</button>
<button id="get_ended">getEnded</button>
<button id="volume_down">volume-</button>
<button id="volume_up">volume+</button>
<button id="get_volume">getVolume</button>
<button id="get_src">getSrc</button>
<button id="play_music1">playMusic1</button>
<button id="play_music2">playMusic2</button>
<button id="remove_music">removeMusic</button>
<button id="get_current_src">getCurrentSrc</button>
<button id="get_initial_time">getInitialTime</button>
<button id="get_duration">getDuration</button>
<button id="get_seeking">getSeeking</button>
<button id="jump_to">jumpTo_30s</button>
<button id="get_current_time">getCurrentTime</button>
<button id="get_played">getPlayed</button>
<button id="autoplay_on">autoplay_on</button>
<button id="autoplay_off">autoplay_off</button>
<button id="get_autoplay">getAutoplay</button>
<button id="controls_show">controls_show</button>
<button id="controls_hide">controls_hide</button>
<button id="get_controls">getControls</button>
<button id="loop_on">loop_on</button>
<button id="loop_off">loop_off</button>
<button id="get_loop">getLoop</button>
<button id="preload_metadata">preload_metadata</button>
<button id="get_preload">getPreload</button>
<button id="get_default_muted">getDefaultMuted</button>
<button id="mute">mute</button>
<button id="unmute">unmute</button>
<button id="get_muted">getMuted</button>
<button id="get_default_playback_rate">getDefaultPlaybackRate</button>
<button id="playback_rate_down">playbackRate-</button>
<button id="playback_rate_up">playbackRate+</button>
<button id="get_playback_rate">getPlaybackRate</button>
<button id="get_network_state">getNetworkState</button>
<button id="get_ready_state">getReadyState</button>
<button id="get_buffered">getBuffered</button>
<button id="get_seekable">getSeekable</button>
</section>
</article>
<aside>
<section>
<h3>Player Attrs</h3>
<table>
<tr><td>autoplay:</td><td id="autoplay"></td></tr>
<tr><td>controls:</td><td id="controls"></td></tr>
<tr><td>defaultMuted:</td><td id="default_muted"></td></tr>
<tr><td>defaultPlaybackRate:</td><td id="default_playback_rate"></td></tr>
<tr><td>loop:</td><td id="loop"></td></tr>
<tr><td>preload:</td><td id="preload"></td></tr>
</table>
</section>
<section>
<h3>Player Info</h3>
<table>
<tr><td>src:</td><td id="src"></td></tr>
<tr><td>currentSrc:</td><td id="current_src"></td></tr>
<tr><td>duration:</td><td id="duration"></td></tr>
<tr><td>currentTime:</td><td id="current_time"></td></tr>
<tr><td>ended:</td><td id="ended"></td></tr>
<tr><td>paused:</td><td id="paused"></td></tr>
<tr><td>muted:</td><td id="muted"></td></tr>
<tr><td>volume:</td><td id="volume"></td></tr>
<tr><td>playbackRate:</td><td id="playback_rate"></td></tr>
</table>
</section>
<section>
<h3>Play status</h3>
<table>
<tr><td>networkState:</td><td id="network_state"></td></tr>
<tr><td>readyState:</td><td id="ready_state"></td></tr>
<tr><td>buffered:</td><td id="buffered"></td></tr>
<tr><td>seekable:</td><td id="seekable"></td></tr>
<tr><td>played:</td><td id="played"></td></tr>
<tr><td>error:</td><td id="error"></td></tr>
</table>
</section>
</aside>
</body>
</html>
window.onload = function(){
// 取得 audio 元素
var audio = document.getElementById("audio");
// play()
document.getElementById("play").onclick = function(){
audio.play();
console.log("play");
};
// pause()
document.getElementById("pause").onclick = function(){
audio.pause();
console.log("pause");
};
// 播放狀態查詢
document.getElementById("get_paused").onclick = function(){
console.log("audio.paused: " + audio.paused);
};
document.getElementById("get_ended").onclick = function(){
console.log("audio.ended: " + audio.ended);
};
// 音量調整(0 ~ 1)
document.getElementById("volume_down").onclick = function(){
audio.volume -= 0.2;
console.log("volume-0.2");
};
document.getElementById("volume_up").onclick = function(){
audio.volume += 0.2;
console.log("volume+0.2");
};
document.getElementById("get_volume").onclick = function(){
console.log("audio.volume: " + audio.volume);
};
// 切換音源
document.getElementById("get_src").onclick = function(){
console.log("audio.src: " + audio.src);
};
document.getElementById("play_music1").onclick = function(){
audio.src = "./media/music1.mp3";
updateSrc(); updateCurrentSrc();
console.log("play music1");
};
document.getElementById("play_music2").onclick = function(){
audio.src = "./media/music2.mp3";
updateSrc(); updateCurrentSrc();
console.log("play music2");
};
document.getElementById("remove_music").onclick = function(){
audio.src = "";
console.log("remove music");
};
document.getElementById("get_current_src").onclick = function(){
console.log("audio.currentSrc: " + audio.currentSrc);
};
// 時間軸相關
document.getElementById("get_initial_time").onclick = function(){
console.log("audio.initialTime: " + audio.initialTime);
};
document.getElementById("get_duration").onclick = function(){
console.log("audio.duration: " + audio.duration);
};
document.getElementById("get_seeking").onclick = function(){
console.log("audio.seeking: " + audio.seeking);
};
document.getElementById("jump_to").onclick = function(){
audio.currentTime = 30;
console.log("jumpTo 30s");
};
document.getElementById("get_current_time").onclick = function(){
console.log("audio.currentTime: " + audio.currentTime);
};
document.getElementById("get_played").onclick = function(){
console.log("audio.played:");
var ranges = audio.played;
var n = ranges.length;
for (var i = 0; i < n; i++) {
console.log("(" + ranges.start(i) + "," + ranges.end(i) + ")");
}
};
// autoplay
document.getElementById("autoplay_on").onclick = function(){
audio.autoplay = true; updateAutoplay();
console.log("autoplay on");
};
document.getElementById("autoplay_off").onclick = function(){
audio.autoplay = false; updateAutoplay();
console.log("autoplay off");
};
document.getElementById("get_autoplay").onclick = function(){
console.log("audio.autoplay: " + audio.autoplay);
};
// 原生控制列顯示/隱藏
document.getElementById("controls_show").onclick = function(){
audio.controls = true; updateControls();
console.log("controls show");
};
document.getElementById("controls_hide").onclick = function(){
audio.controls = false; updateControls();
console.log("controls hide");
};
document.getElementById("get_controls").onclick = function(){
console.log("audio.controls: " + audio.controls);
};
// 迴圈播放
document.getElementById("loop_on").onclick = function(){
audio.loop = true; updateLoop();
console.log("loop on");
};
document.getElementById("loop_off").onclick = function(){
audio.loop = false; updateLoop();
console.log("loop off");
};
document.getElementById("get_loop").onclick = function(){
console.log("audio.loop: " + audio.loop);
};
// 預載策略
document.getElementById("preload_metadata").onclick = function(){
audio.preload = "metadata"; updatePreload();
console.log("preload metadata");
};
document.getElementById("get_preload").onclick = function(){
console.log("audio.preload: " + audio.preload);
};
// 靜音
document.getElementById("get_default_muted").onclick = function(){
console.log("audio.defaultMuted: " + audio.defaultMuted);
};
document.getElementById("mute").onclick = function(){
audio.muted = true; updateMuted();
console.log("audio mute");
};
document.getElementById("unmute").onclick = function(){
audio.muted = false; updateMuted();
console.log("audio unmute");
};
document.getElementById("get_muted").onclick = function(){
console.log("audio.muted: " + audio.muted);
};
// 播放速率
document.getElementById("get_default_playback_rate").onclick = function(){
console.log("audio.defaultPlaybackRate: " + audio.defaultPlaybackRate);
};
document.getElementById("playback_rate_down").onclick = function(){
audio.playbackRate -= 0.2;
console.log("playbackRate-0.2");
};
document.getElementById("playback_rate_up").onclick = function(){
audio.playbackRate += 0.2;
console.log("playbackRate+0.2");
};
document.getElementById("get_playback_rate").onclick = function(){
console.log("audio.playbackRate: " + audio.playbackRate);
};
// 網路與緩衝狀態
document.getElementById("get_network_state").onclick = function(){
console.log("audio.networkState: " + audio.networkState);
};
document.getElementById("get_ready_state").onclick = function(){
console.log("audio.readyState: " + audio.readyState);
};
document.getElementById("get_buffered").onclick = function(){
console.log("audio.buffered:");
var ranges = audio.buffered;
var n = ranges.length;
for (var i = 0; i < n; i++) {
console.log("(" + ranges.start(i) + "," + ranges.end(i) + ")");
}
};
document.getElementById("get_seekable").onclick = function(){
console.log("audio.seekable:");
var ranges = audio.seekable;
var n = ranges.length;
for (var i = 0; i < n; i++) {
console.log("(" + ranges.start(i) + "," + ranges.end(i) + ")");
}
};
// ---- DOM events ----
audio.addEventListener("abort", function(){ console.log("event:abort"); });
audio.addEventListener("canplay", function(){ console.log("event:canplay"); });
audio.addEventListener("canplaythrough", function(){ console.log("event:canplaythrough"); });
audio.addEventListener("durationchange", function(){
updateDuration(); console.log("event:durationchange");
});
audio.addEventListener("emptied", function(){
updateSrc(); updateCurrentSrc(); updateDuration(); updatePaused();
updateNetworkState(); updateReadyState(); updateBuffered();
updateSeekable(); updatePlayed();
console.log("event:emptied");
});
audio.addEventListener("ended", function(){
updateEnded(); console.log("event:ended");
});
audio.addEventListener("loadeddata", function(){
updateNetworkState(); updateReadyState(); updateBuffered(); updateSeekable();
console.log("event:loadeddata");
});
audio.addEventListener("loadedmetadata", function(){ console.log("event:loadedmetadata"); });
audio.addEventListener("loadstart", function(){ console.log("event:loadstart"); });
audio.addEventListener("pause", function(){ updatePaused(); console.log("event:pause"); });
audio.addEventListener("play", function(){ updatePaused(); console.log("event:play"); });
audio.addEventListener("playing", function(){ console.log("event:playing"); });
audio.addEventListener("progress", function(){
updateNetworkState(); updateReadyState(); updateBuffered(); updateSeekable();
console.log("event:progress");
});
audio.addEventListener("ratechange", function(){
updatePlaybackRate(); console.log("event:ratechange");
});
audio.addEventListener("seeked", function(){ console.log("event:seeked"); });
audio.addEventListener("seeking", function(){ console.log("event:seeking"); });
audio.addEventListener("stalled", function(){ console.log("event:stalled"); });
audio.addEventListener("suspend", function(){ console.log("event:suspend"); });
audio.addEventListener("timeupdate", function(){
updateCurrentTime(); updateEnded(); updatePlayed();
console.log("event:timeupdate");
});
audio.addEventListener("volumechange", function(){
updateVolume(); console.log("event:volumechange");
});
audio.addEventListener("waiting", function(){ console.log("event:waiting"); });
updateAutoplay(); updateControls(); updateDefaultMuted();
updateDefaultPlaybackRate(); updateLoop(); updatePreload();
updateSrc(); updateCurrentSrc(); updateDuration(); updateCurrentTime();
updateVolume(); updatePaused(); updateMuted(); updateEnded();
updatePlaybackRate(); updateNetworkState(); updateReadyState();
updateBuffered(); updateSeekable(); updatePlayed(); updateError();
};
// ---- 更新右側資訊表的函式 ----
function updateAutoplay(){
document.getElementById("autoplay").innerHTML = audio.autoplay;
}
function updateControls(){
document.getElementById("controls").innerHTML = audio.controls;
}
function updateDefaultMuted(){
document.getElementById("default_muted").innerHTML = audio.defaultMuted;
}
function updateDefaultPlaybackRate(){
document.getElementById("default_playback_rate").innerHTML = audio.defaultPlaybackRate;
}
function updateLoop(){
document.getElementById("loop").innerHTML = audio.loop;
}
function updatePreload(){
document.getElementById("preload").innerHTML = audio.preload;
}
function updateSrc(){
document.getElementById("src").innerHTML = audio.src;
}
function updateCurrentSrc(){
document.getElementById("current_src").innerHTML = audio.currentSrc;
}
function updateDuration(){
document.getElementById("duration").innerHTML = audio.duration;
}
function updateCurrentTime(){
document.getElementById("current_time").innerHTML = audio.currentTime;
}
function updateEnded(){
document.getElementById("ended").innerHTML = audio.ended;
}
function updatePaused(){
document.getElementById("paused").innerHTML = audio.paused;
}
function updateMuted(){
document.getElementById("muted").innerHTML = audio.muted;
}
function updateVolume(){
document.getElementById("volume").innerHTML = audio.volume;
}
function updatePlaybackRate(){
document.getElementById("playback_rate").innerHTML = audio.playbackRate;
}
function updateNetworkState(){
document.getElementById("network_state").innerHTML = audio.networkState;
}
function updateReadyState(){
document.getElementById("ready_state").innerHTML = audio.readyState;
}
// TimeRanges 型別的統一格式化輸出
function formatRanges(ranges){
var str = "";
var n = ranges.length;
for (var i = 0; i < n; i++) {
str += "(" + ranges.start(i) + "," + ranges.end(i) + ")";
if (i != n - 1) { str += "<br>"; }
}
return str;
}
function updateBuffered(){
document.getElementById("buffered").innerHTML = formatRanges(audio.buffered);
}
function updateSeekable(){
document.getElementById("seekable").innerHTML = formatRanges(audio.seekable);
}
function updatePlayed(){
document.getElementById("played").innerHTML = formatRanges(audio.played);
}
function updateError(){
document.getElementById("error").innerHTML = audio.error;
}
把上面的範例歸納一下,整個 API 其實分成三類:
可分為「可寫入」與「唯讀」兩組。src、volume、currentTime、muted、autoplay、loop、controls、preload、playbackRate 都可讀可寫;而 duration、currentSrc、paused、ended、networkState、readyState、error 則是唯讀狀態。
核心只有兩個:play() 與 pause()。其餘操作幾乎都能靠改屬性完成,例如跳轉只需設定 currentTime = 30。
這是自製播放器最該熟悉的部分。loadstart 到 canplaythrough 描述載入階段,timeupdate 是更新進度條的心跳(觸發頻率高,適合同步 UI),progress 反映緩衝進度,seeking/seeked 成對出現,volumechange 與 ratechange 則對應音量與速率變更。
關於 TimeRanges。 buffered、seekable、played 三者都不是單一區間,而是 TimeRanges 物件——因為使用者可能跳著聽,已緩衝的片段會是不連續的多段。所以必須用 length 搭配 start(i)/end(i) 逐段取出,如上例的 formatRanges()。
關於 autoplay。 現代瀏覽器普遍限制無互動的自動播放,實務上僅設定 audio.autoplay = true 未必真的會播,往往仍需使用者先與頁面互動。
關於 preload。 取值為 none/metadata/auto。行動裝置與省流量情境下設為 metadata 通常是較平衡的選擇。
HTML5 Media API 的設計相当克制——兩個方法就能播起來,剩下的空間全部留給開發者自己發揮。把 controls 關掉、接上自己的按鈕、監聽 timeupdate 更新進度條,一個外觀完全自訂的播放器就成形了。上面這份範例的價值,在於它把每個屬性與事件都攤開來讓你點一次、看一次 console,比讀十頁文件都快。