<audio>: 嵌入式音訊元素

試一試

<figure>
  <figcaption>Listen to the T-Rex:</figcaption>
  <audio controls src="/shared-assets/audio/t-rex-roar.mp3"></audio>
  <a href="/shared-assets/audio/t-rex-roar.mp3"> Download audio </a>
</figure>

figure {
  margin: 0;
}

上面的示例展示了 <audio> 元素的基本用法。與 <img> 元素類似，我們在 src 屬性中包含要嵌入的媒體的路徑；我們可以包含其他屬性來指定資訊，例如我們是否希望它自動播放和迴圈，是否希望顯示瀏覽器的預設音訊控制元件等。

在開閉 <audio></audio> 標籤內的內容將作為不支援該元素的瀏覽器的備用內容顯示。

屬性

此元素的屬性包括全域性屬性。

autoplay

一個布林屬性：如果指定，音訊將盡快自動開始播放，無需等待整個音訊檔案下載完成。

注意：自動播放音訊（或帶有音軌的影片）的網站可能會給使用者帶來不愉快的體驗，因此應儘可能避免。如果您必須提供自動播放功能，則應使其成為可選加入（要求使用者明確啟用）。但是，這在建立源將在以後由使用者控制設定的媒體元素時非常有用。有關如何正確使用自動播放的更多資訊，請參閱我們的自動播放指南。

controls

如果存在此屬性，瀏覽器將提供控制元件，允許使用者控制音訊播放，包括音量、快進/快退以及暫停/恢復播放。

controlslist

當指定 controlslist 屬性時，它有助於瀏覽器選擇在瀏覽器顯示其自身控制元件集（即當指定了 controls 屬性時）時，為 audio 元素顯示哪些控制元件。

允許的值為 nodownload、nofullscreen 和 noremoteplayback。

crossorigin

此列舉屬性指示是否使用 CORS 來獲取相關的音訊檔案。啟用 CORS 的資源可以在 <canvas> 元素中重複使用而不會被汙染。允許的值是：

anonymous

傳送不帶憑據的跨域請求。換句話說，它傳送 Origin: HTTP 頭，但不帶 cookie、X.509 證書或執行 HTTP 基本認證。如果伺服器不向源站點提供憑據（透過不設定 Access-Control-Allow-Origin: HTTP 頭），資源將被汙染，其使用將受到限制。

use-credentials

傳送帶憑據的跨域請求。換句話說，它傳送 Origin: HTTP 頭，並帶有一個 cookie、一個證書或執行 HTTP 基本認證。如果伺服器不向源站點提供憑據（透過 Access-Control-Allow-Credentials: HTTP 頭），資源將被汙染，其使用將受到限制。

如果不存在，則在不進行 CORS 請求的情況下獲取資源（即，不傳送 Origin: HTTP 頭），從而阻止其在 <canvas> 元素中進行未汙染的使用。如果無效，則將其視為使用了列舉關鍵字 anonymous。有關更多資訊，請參閱 CORS 設定屬性。

disableremoteplayback

一個布林屬性，用於停用透過有線（HDMI、DVI 等）和無線技術（Miracast、Chromecast、DLNA、AirPlay 等）連線的裝置中的遠端播放功能。有關更多資訊，請參閱擬議的 遠端播放 API 規範。

在 Safari 中，您可以使用 x-webkit-airplay="deny" 作為備用方案。

loop

一個布林屬性：如果指定，音訊播放器在到達音訊末尾時會自動跳回開始處。

muted

一個布林屬性，指示音訊是否在初始時靜音。其預設值為 false。

preload

此列舉屬性旨在向瀏覽器提供關於作者認為將帶來最佳使用者體驗的提示。它可能具有以下值之一：

• none：表示不應預載入音訊。
• metadata：表示僅獲取音訊元資料（例如，長度）。
• auto：表示可以下載整個音訊檔案，即使預計使用者不會使用它。
• 空字串：auto 值的同義詞。

預設值因瀏覽器而異。規範建議將其設定為 metadata。

備註

• autoplay 屬性優先於 preload。如果指定了 autoplay，瀏覽器顯然需要開始下載音訊進行播放。
• 規範並未強制瀏覽器遵循此屬性的值；它只是一個提示。

src

要嵌入的音訊的 URL。這受 HTTP 訪問控制的約束。這是可選的；您可以改為在音訊塊內使用 <source> 元素來指定要嵌入的音訊。

事件

audioprocess 已棄用

ScriptProcessorNode 的輸入緩衝區已準備好進行處理。

canplay

瀏覽器可以播放媒體，但估計載入的資料不足以播放到媒體結束而無需停止以進一步緩衝內容。

canplaythrough

瀏覽器估計它可以在不停止內容緩衝的情況下播放媒體直到結束。

完成

OfflineAudioContext 的渲染已終止。

durationchange

duration 屬性已更新。

emptied

媒體已變為空；例如，如果媒體已載入（或部分載入），並且呼叫 HTMLMediaElement.load 方法以重新載入它，則會發送此事件。

ended

播放已停止，因為已達到媒體的末尾。

loadeddata

媒體的第一幀已完成載入。

loadedmetadata

元資料已載入。

loadstart

當瀏覽器開始載入資源時觸發。

pause

播放已暫停。

play

播放已開始。

playing

在因資料不足而暫停或延遲後，播放已準備好開始。

ratechange

播放速率已更改。

seeked

查詢操作完成。

seeking

查詢操作開始。

stalled

使用者代理正在嘗試獲取媒體資料，但資料意外地未能提供。

suspend

媒體資料載入已暫停。

timeupdate

currentTime 屬性指示的時間已更新。

volumechange

音量已更改。

waiting

由於暫時缺少資料，播放已停止。

用法說明

瀏覽器並非都支援相同的檔案型別和音訊編解碼器；您可以在巢狀的<source>元素中提供多個源，然後瀏覽器將使用它能理解的第一個源

<audio controls>
  <source src="myAudio.mp3" type="audio/mpeg" />
  <source src="myAudio.ogg" type="audio/ogg" />
  <p>
    Download <a href="myAudio.mp3" download="myAudio.mp3">MP3</a> or
    <a href="myAudio.ogg" download="myAudio.ogg">OGG</a> audio.
  </p>
</audio>

音訊源可以設定為任何有效的 URL，包括 HTTP(S) URL 和 資料 URL。使用 HTTP(S) URL 時，請注意瀏覽器的快取行為會影響檔案從伺服器請求的頻率。資料 URL 將音訊資料直接嵌入到 HTML 中，這對於小型音訊檔案很有用，但對於大型檔案不建議使用，因為它會增加 HTML 檔案的大小。

使用 <source> 元素時，瀏覽器會嘗試按順序載入每個源。如果某個源失敗（例如，由於無效 URL 或不支援的格式），則會嘗試下一個源，依此類推。在所有源都失敗後，會在 <audio> 元素上觸發 error 事件；不會在每個單獨的 <source> 元素上觸發 error 事件。

您還可以使用 Web Audio API 直接從 JavaScript 程式碼生成和操作音訊流，而不是流式傳輸預先存在的音訊檔案。您可以將 JavaScript 中的 srcObject 設定為 MediaStream 物件。這通常用於即時音訊流或即時音訊處理。

const audioElement = document.querySelector("audio");
navigator.mediaDevices
  .getUserMedia({ audio: true })
  .then((stream) => {
    audioElement.srcObject = stream;
  })
  .catch((error) => {
    console.error("Error accessing the microphone", error);
  });

請注意，MediaStream 源有侷限性：它們不可查詢，並且僅支援有限的編解碼器集。

我們提供了一份內容豐富且全面的媒體檔案型別指南以及可在其中使用的音訊編解碼器。還提供影片支援的編解碼器指南。

其他使用注意事項

• 如果您未指定 controls 屬性，則音訊播放器將不包含瀏覽器的預設控制元件。但是，您可以使用 JavaScript 和 HTMLMediaElement API 建立自己的自定義控制元件。
• 為了精確控制您的音訊內容，HTMLMediaElement 會觸發許多不同的事件。這還提供了一種監控音訊獲取過程的方法，以便您可以查詢錯誤或檢測何時有足夠的內容可用以開始播放或操作它。
• <audio> 元素不能像 <video> 元素那樣關聯字幕或說明。有關一些有用資訊和變通方法，請參閱 Ian Devlin 的WebVTT 和音訊。
• 要在支援該元素的瀏覽器上測試備用內容，您可以將 <audio> 替換為不存在的元素，例如 <notanaudio>。

有關使用 HTML <audio> 的一個很好的通用資訊來源是 HTML 影片和音訊初學者教程。

使用 CSS 樣式

<audio> 元素本身沒有固有的視覺輸出，除非指定了 controls 屬性，在這種情況下會顯示瀏覽器的預設控制元件。

預設情況下，預設控制元件的 display 值為 inline，通常最好將值設定為 block 以改善對定位和佈局的控制，除非您希望它位於文字塊或類似內容中。

您可以使用影響塊作為一個整體的屬性來樣式化預設控制元件，例如，您可以為其指定 border 和 border-radius、padding、margin 等。但是，您無法樣式化音訊播放器中的各個元件（例如，更改按鈕大小或圖示、更改字型等），並且不同瀏覽器中的控制元件也不同。

為了在不同瀏覽器中獲得一致的外觀和感覺，您需要建立自定義控制元件；這些控制元件可以按您希望的任何方式進行標記和樣式設定，然後可以使用 JavaScript 和 HTMLMediaElement API 來連線其功能。

影片播放器樣式基礎提供了一些有用的樣式技術——它是在 <video> 的背景下編寫的，但其中大部分同樣適用於 <audio>。

檢測軌道的新增和移除

您可以使用 addtrack 和 removetrack 事件來檢測何時將軌道新增到 <audio> 元素或從 <audio> 元素中移除軌道。但是，這些事件不會直接傳送到 <audio> 元素本身。相反，它們會發送到 <audio> 元素的 HTMLMediaElement 中與新增到元素的軌道型別對應的軌道列表物件

HTMLMediaElement.audioTracks

一個 AudioTrackList，包含所有媒體元素的音軌。您可以向此物件新增 addtrack 監聽器，以便在新音軌新增到元素時收到通知。

HTMLMediaElement.videoTracks

向此 VideoTrackList 物件新增 addtrack 監聽器，以便在影片軌道新增到元素時收到通知。

HTMLMediaElement.textTracks

向此 TextTrackList 新增 addtrack 事件監聽器，以便在新文字軌道新增到元素時收到通知。

例如，要檢測何時向 <audio> 元素新增或從中移除音軌，您可以使用以下程式碼：

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

elem.audioTrackList.onaddtrack = (event) => {
  trackEditor.addTrack(event.track);
};

elem.audioTrackList.onremovetrack = (event) => {
  trackEditor.removeTrack(event.track);
};

此程式碼監視音軌新增到元素和從元素中移除的情況，並呼叫音軌編輯器上的假想函式，以在編輯器的可用音軌列表中註冊和移除音軌。

您還可以使用 addEventListener() 來監聽 addtrack 和 removetrack 事件。

無障礙

帶有語音對話的音訊應提供準確描述其內容的字幕和文字記錄。字幕（使用 WebVTT 指定）允許聽力受損的人在錄音播放時理解其內容，而文字記錄則允許需要額外時間的人以適合自己的節奏和格式回顧錄音內容。

如果使用自動字幕服務，務必稽核生成的內容，以確保其準確地代表了源音訊。

<audio> 元素不直接支援 WebVTT。您必須找到提供該功能的庫或框架，或者自己編寫程式碼來顯示字幕。一種選擇是使用支援 WebVTT 的 <video> 元素播放音訊。

除了語音對話之外，字幕和文字記錄還應識別傳達重要資訊的音樂和音效。這包括情感和語調。例如，在下面的 WebVTT 中，請注意使用方括號為觀看者提供語調和情感洞察力；這有助於營造否則透過音樂、非語言聲音和關鍵音效等提供的氛圍。

1
00:00:00 --> 00:00:45
[Energetic techno music]

2
00:00:46 --> 00:00:51
Welcome to the Time Keeper's podcast! In this episode we're discussing which Swisswatch is a wrist switchwatch?

16
00:00:52 --> 00:01:02
[Laughing] Sorry! I mean, which wristwatch is a Swiss wristwatch?

此外，提供一些內容（例如直接下載連結）作為不支援 <audio> 元素的瀏覽器的備用是一種很好的做法

<audio controls>
  <source src="myAudio.mp3" type="audio/mpeg" />
  <source src="myAudio.ogg" type="audio/ogg" />
  <p>
    Download <a href="myAudio.mp3">MP3</a> or
    <a href="myAudio.ogg" download="myAudio.ogg">OGG</a> audio.
  </p>
</audio>

• Web 影片文字軌道格式 (WebVTT)
• WebAIM：字幕、文字記錄和音訊描述
• MDN 理解 WCAG，指南 1.2 解釋
• 理解成功標準 1.2.1 | W3C 理解 WCAG 2.0
• 理解成功標準 1.2.2 | W3C 理解 WCAG 2.0

示例

基本用法

以下示例顯示了 <audio> 元素播放 OGG 檔案的基本用法。如果頁面有許可權，它將由於 autoplay 屬性而自動播放，並且還包含備用內容。

<!-- Basic audio playback -->
<audio src="AudioTest.ogg" autoplay>
  <a href="AudioTest.ogg" download="AudioTest.ogg">Download OGG audio</a>.
</audio>

有關自動播放何時工作、如何獲得自動播放許可權以及何時適合使用自動播放的詳細資訊，請參閱我們的自動播放指南。

帶有 <source> 元素的 <audio> 元素

此示例使用巢狀 <source> 元素上的 src 屬性，而不是直接在 <audio> 元素上，來指定要嵌入的音軌。在 type 屬性中包含檔案的 MIME 型別總是很有用的，因為瀏覽器能夠立即判斷它是否可以播放該檔案，如果不能，就不會浪費時間。

<audio controls>
  <source src="foo.wav" type="audio/wav" />
  <a href="foo.wav" download="foo.wav">Download WAV audio</a>.
</audio>

帶有多個 <source> 元素的 <audio>

此示例包含多個 <source> 元素。如果瀏覽器能夠播放第一個源元素（Opus），它會嘗試載入它；否則它會回退到第二個（Vorbis），最後回退到 MP3

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

技術摘要

規範

瀏覽器相容性

另見

• Web 媒體技術

  • 媒體容器格式（檔案型別）
  • 網路上使用的音訊編解碼器指南

• Web Audio API

• HTMLAudioElement
• <source>
• <video>

• 學習區：HTML 影片和音訊

• 跨瀏覽器音訊基礎