HTML5 的 <audio> 元素不只是個播放器,它背後的 HTMLMediaElement 介面提供了完整的程式化控制能力:播放、暫停、調音量、跳轉、改變播放速率,甚至查詢緩衝狀態。這份筆記把常用的 API 整理成一個可操作的展示頁。
<!doctype html>
<html lang="zh-Hant">
<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>
</header>
<article>
<section>
<h2>Audio Element</h2>
<audio id="audio" src="./media/music1.mp3" controls="controls"></audio>
<p>開啟開發者工具即可看到 console 訊息。</p>
</section>>
<section>
<h2>Controls</h2>
<button id="play">play</button>
<button id="pause">pause</button>
<button id="volume_down">volume-</button>
<button id="volume_up">volume+</button>
<button id="play_music1">playMusic1</button>
<button id="play_music2">playMusic2</button>
<button id="jump_to">jumpTo_30s</button>
<button id="mute">mute</button>
<button id="unmute">unmute</button>
<!-- 其餘按鈕:autoplay、loop、preload、playbackRate、
networkState、readyState、buffered、seekable、played -->
</section>
</article>
<aside>
<!-- 三個表格分別顯示:播放器屬性、資訊、播放狀態 -->
</aside>
</body>
</html>
window.onload = function () {
var audio = document.getElementById("audio");
document.getElementById("play").onclick = function () {
audio.play();
};
document.getElementById("pause").onclick = function () {
audio.pause();
};
// 音量:0 ~ 1 之間
document.getElementById("volume_down").onclick = function () {
audio.volume -= 0.2;
};
document.getElementById("volume_up").onclick = function () {
audio.volume += 0.2;
};
// 切換音源
document.getElementById("play_music1").onclick = function () {
audio.src = "./media/music1.mp3";
updateSrc();
};
document.getElementById("play_music2").onclick = function () {
audio.src = "./media/music2.mp3";
updateSrc();
};
document.getElementById("remove_music").onclick = function () {
audio.src = "";
};
// 跳到第 30 秒
document.getElementById("jump_to").onclick = function () {
audio.currentTime = 30;
};
document.getElementById("playback_rate_up").onclick = function () {
audio.playbackRate += 0.2; // 1 為正常速度
};
document.getElementById("playback_rate_down").onclick = function () {
audio.playbackRate -= 0.2;
};
document.getElementById("mute").onclick = function () {
audio.muted = true; // 靜音但不改變 volume 的值
};
document.getElementById("unmute").onclick = function () {
audio.muted = false;
};
document.getElementById("preload_metadata").onclick = function () {
audio.preload = "metadata"; // none / metadata / auto
};
buffered、seekable、played 三個屬性回傳的都是 TimeRanges 物件,需要逐一走訪其中的區間:
function readRanges(ranges) {
var n = ranges.length;
for (var i = 0; i < n; i++) {
console.log("(" + ranges.start(i) + ", " + ranges.end(i) + ")");
}
}
document.getElementById("get_buffered").onclick = function () {
readRanges(audio.buffered); // 已緩衝的區間
};
document.getElementById("get_seekable").onclick = function () {
readRanges(audio.seekable); // 可跳轉的區間
};
document.getElementById("get_played").onclick = function () {
readRanges(audio.played); // 已播放的區間
};
媒體元素的狀態變化多半靠事件通知,而不是輪詢。常用事件包含:
audio.addEventListener("loadstart", function () { console.log("event:loadstart"); });
audio.addEventListener("loadedmetadata", function () { console.log("event:loadedmetadata"); });
audio.addEventListener("loadeddata", function () { updateReadyState(); });
audio.addEventListener("canplay", function () { console.log("event:canplay"); });
audio.addEventListener("canplaythrough", function () { console.log("event:canplaythrough"); });
audio.addEventListener("play", function () { updatePaused(); });
audio.addEventListener("playing", function () { console.log("event:playing"); });
audio.addEventListener("pause", function () { updatePaused(); });
audio.addEventListener("ended", function () { updateEnded(); });
audio.addEventListener("timeupdate", function () { updateCurrentTime(); updatePlayed(); });
audio.addEventListener("durationchange", function () { updateDuration(); });
audio.addEventListener("volumechange", function () { updateVolume(); });
audio.addEventListener("ratechange", function () { updatePlaybackRate(); });
audio.addEventListener("seeking", function () { console.log("event:seeking"); });
audio.addEventListener("seeked", function () { console.log("event:seeked"); });
audio.addEventListener("progress", function () { updateBuffered(); });
audio.addEventListener("stalled", function () { console.log("event:stalled"); });
audio.addEventListener("suspend", function () { console.log("event:suspend"); });
audio.addEventListener("waiting", function () { console.log("event:waiting"); });
audio.addEventListener("abort", function () { console.log("event:abort"); });
audio.addEventListener("emptied", function () { updateSrc(); updateDuration(); });
};
duration 不一定是數字。在 metadata 尚未載入前,audio.duration 會是 NaN;串流來源甚至可能回傳 Infinity。所以任何用到 duration 的計算,都應該放在 durationchange 或 loadedmetadata 之後。
readyState 與 networkState 是數字列舉。readyState 從 0(沒有資料)到 4(資料充足可無縫播放);networkState 從 0(空)到 3(無來源)。做 UI 時建議把數字對照表列出來,否則除錯很痛苦。
自動播放會被瀏覽器阻擋。除了設 autoplay 屬性,現代瀏覽器通常還要求使用者先與頁面互動過,因此不要依賴自動播放作為必要流程。
格式支援因瀏覽器而異。想要無痛跨瀏覽器,做法是同時提供多個 <source>(例如 MP3 加 Ogg),並用 audio.canPlayType() 檢測。