紀錄工作經驗、相關知識,解決技術相關問題。

HTML

HTML audio 標籤用法:controls、autoplay 與多來源

HTML audio 標籤用法:controls、autoplay 與多來源 特色圖片

HTML audio 標籤是用來在網頁中嵌入音訊的元素,寫好音檔網址與 controls,瀏覽器就會顯示內建播放器。

白話一點,<audio> 就像在頁面上放一台小型播放機:你負責指定要播哪一首,按鈕與音量條由瀏覽器提供。

audio 最小寫法:src 與 controls

最基本的寫法是用 src 指定音檔網址,再加上 controls:

<audio controls src="podcast.mp3"></audio>

controls 是布林屬性,只要寫出來就算開啟。WHATWG 規格說明,有這個屬性時,表示作者沒有自己寫播放控制,要求瀏覽器提供它的操作介面,內容包含播放、暫停、拖曳進度與調整音量。

<audio> 開頭與結尾標籤都不能省略。

下圖是這段寫法加上一個沒有 controls 的 audio 並排的結果:

有 controls 的 audio 顯示播放器,沒有 controls 的 audio 沒有任何畫面

圖為 Windows 11、無頭 Chrome 158 的渲染畫面:有 controls 的 audio 顯示播放器(時間、進度條、音量與選單),沒有 controls 的 audio 不佔畫面。

補充說明:這是在上面環境讀到的結果,播放器外觀會因瀏覽器與作業系統而不同。同一段程式讀出的尺寸,有 controls 的元素是 300 × 54 像素,沒有 controls 的元素是 0 × 0,display 為 none。

沒有 controls 會怎樣

沒寫 controls 時,瀏覽器不會顯示播放器。

MDN 說明,這時可以改用 JavaScript 與 HTMLMediaElement API 自己做控制介面。WHATWG 規格也寫到,沒有 controls 的 audio 不會被瀏覽器顯示,因此也不能搭配延遲載入。

一般內容頁想讓讀者自己決定要不要聽,加上 controls 即可。

常用屬性

audio 常用的屬性整理如下,說明依 MDN 與 WHATWG 規格:

屬性作用補充
src音檔網址也可以改用內層的 <source> 指定
controls顯示瀏覽器內建控制介面布林屬性
loop播到結尾後自動回到開頭布林屬性
muted預設靜音要取消靜音必須移除屬性,寫 muted="false" 仍然是靜音
preload提示瀏覽器要預先下載多少值為 none、metadata、auto,只是提示,瀏覽器可以不照做
autoplay能播放時自動開始播放常被瀏覽器擋下,見下一節
crossorigin以 CORS 方式取得音檔值為 anonymous 或 use-credentials

preload 的預設值每個瀏覽器不同,規格建議設為 metadata,也就是只取得長度等中繼資料。

同時寫了 autoplay 與 preload 時,MDN 說明 autoplay 的優先權較高,因為要自動播放,瀏覽器本來就得開始下載。

組合起來的範例如下:

<audio controls loop preload="metadata" src="bgm.mp3"></audio>

autoplay:為什麼常常沒有自動播放

autoplay 的作用是讓音訊在可以播放時自動開始,不必等整個檔案下載完。

但 MDN 提醒,自動發出聲音對使用者來說常常是不愉快的體驗,能避免就避免;如果一定要提供,建議做成使用者主動開啟。WHATWG 規格也建議作者考慮完全不用自動播放,讓使用者自行決定何時開始。

瀏覽器通常會封鎖有聲音的自動播放。依 MDN 的自動播放指南,一般情況下,符合下列任一條件才會被允許:

  1. 音訊已靜音,或音量為 0。
  2. 使用者已經和網站互動過(點擊、觸碰、按鍵等)。
  3. 網站已被瀏覽器加入允許清單。
  4. 以 autoplay Permissions Policy 對 <iframe> 授權。

實際封鎖的條件與方式依瀏覽器而異,以上是 MDN 建議的判斷原則。

下圖是 <audio autoplay controls> 在使用者沒有任何操作的頁面上的情況:

audio 設定 autoplay 但沒有自動播放,未操作時呼叫 play() 回傳 NotAllowedError,點擊後 play() 成功

圖為 Windows 11、無頭 Chrome 158 的畫面(啟動參數 --autoplay-policy=document-user-activation-required):頁面載入 1 秒後 paused 為 true,未操作時呼叫 play() 得到 NotAllowedError,點擊按鈕後再呼叫 play() 則成功。

補充說明:這是在上面環境讀到的結果。Chrome 的自動播放政策可以用啟動參數改變,使用者的瀏覽器設定也不同,不能直接推論到所有讀者。

用 JavaScript 呼叫 play() 時,會回傳 Promise。被拒絕時可以判斷錯誤名稱,改顯示一個讓使用者自己按下的按鈕,這是 MDN 自動播放指南的建議做法:

const audio = document.querySelector("audio");

audio.play().catch((error) => {
  if (error.name === "NotAllowedError") {
    // 自動播放被擋下:顯示播放按鈕,讓使用者自己開始
  }
});

用 source 提供多種格式

不同瀏覽器支援的音訊格式與編碼不一定相同。MDN 的建議是在 <audio> 裡放多個 <source>,瀏覽器會使用它看得懂的第一個來源:

<audio controls>
  <source src="podcast.opus" type="audio/ogg; codecs=opus" />
  <source src="podcast.ogg" type="audio/ogg; codecs=vorbis" />
  <source src="podcast.mp3" type="audio/mpeg" />
</audio>

寫法上有幾個重點:

  1. 用了 <source> 就不要同時在 <audio> 上寫 src;兩者擇一。
  2. <source> 必須有 src。
  3. type 寫上檔案的 MIME 類型(必要時加上 codecs 參數)。規格說明,這樣瀏覽器不必先下載就能判斷能不能播放,不能播的來源會直接跳到下一個。
  4. 來源要由最想用的格式排到最保險的格式,因為瀏覽器是依序嘗試。

用下面這段 HTML,第一個來源故意寫上瀏覽器不認得的類型,第二個才是真正的 WAV:

<audio id="a" controls>
  <source src="/missing.xyz" type="audio/x-notreal" />
  <source src="/sample.wav" type="audio/wav" />
</audio>

在 Windows 11、Chrome 158 中,a.currentSrc 讀到的是第二個來源的網址,a.canPlayType("audio/x-notreal") 回傳空字串。canPlayType() 回傳 ""、"maybe" 或 "probably",其中空字串代表瀏覽器判斷無法播放。

補充說明:不要用 <source> 的 src 或 type 在頁面載入後動態切換音檔。規格說明,元素已經放進 audio 之後再改 src 或 type 沒有效果,要換音檔請直接改 <audio> 的 src。

備用內容與無障礙

audio 標籤內,<source> 之後的內容是給不支援 <audio> 的舊瀏覽器看的。WHATWG 規格寫明,支援 audio 的瀏覽器不應顯示這些內容,而且這段內容並不是用來解決無障礙問題。

寫法上常見的是放一條下載連結:

<audio controls>
  <source src="podcast.mp3" type="audio/mpeg" />
  <p><a href="podcast.mp3" download>下載 MP3 音檔</a></p>
</audio>

要讓聽障或其他讀者也能取得內容,規格建議在 audio 附近的文字中提供逐字稿或其他文字替代內容的連結。MDN 也說明,<audio> 沒辦法像 <video> 那樣直接關聯字幕,有口語內容的音訊應提供字幕與逐字稿。

小結

  • 寫 <audio controls src="..."> 就能顯示瀏覽器內建播放器;沒有 controls 就不會顯示。
  • loop、muted、preload 屬性可以搭配使用,preload 只是提示,不保證照做。
  • autoplay 常被瀏覽器封鎖,用 play() 時要處理 NotAllowedError。
  • 需要相容多種格式時,用 <source> 搭配 type,把想優先使用的格式放前面。

<source> 也能用在圖片的 <picture> 元素上,用法與 audio 不同,可以參考站內另一篇:HTML picture 與 source 標籤語法教學:Art Direction 裁切、AVIF 降級與深色模式實作。

參考資料與延伸閱讀

發佈留言