<audio> Элемент HTML для встраивания аудио

Элемент <audio> HTML используется для встраивания звукового содержимого в документы. Он может содержать один или несколько источников аудио, заданных с помощью атрибута src или элемента <source>: браузер выберет наиболее подходящий вариант. Он также может служить местом назначения для потокового мультимедиа с использованием объекта MediaStream.

Попробуйте

<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

Логический атрибут: если он указан, воспроизведение аудио начнётся автоматически, как только это станет возможно, не дожидаясь полной загрузки аудиофайла.

Примечание: Сайты, на которых автоматически воспроизводится аудио (или видео со звуковой дорожкой), могут доставлять пользователям неудобства, поэтому по возможности этого следует избегать. Если вам необходимо автоматическое воспроизведение, сделайте его опциональным (пользователь должен включить его самостоятельно). Однако эта возможность может быть полезна при создании мультимедийных элементов, источник которых будет задан позднее под управлением пользователя. Дополнительные сведения о правильном использовании автоматического воспроизведения см. в нашем руководстве по автоматическому воспроизведению.

Примечание: Аудио с установленным атрибутом loading="lazy" не начнёт загружаться и воспроизводиться автоматически, пока элементы управления мультимедиа не окажутся рядом с областью просмотра или внутри неё. Аудио с отложенной загрузкой без атрибута controls не будет воспроизводиться автоматически.

controls

Если этот атрибут присутствует, браузер предложит элементы управления, с помощью которых пользователь сможет управлять воспроизведением аудио, в том числе регулировать громкость, перемещаться по записи и приостанавливать или возобновлять воспроизведение.

controlslist

Атрибут controlslist, если он указан, помогает браузеру выбрать элементы управления, которые следует показывать для элемента audio, когда браузер отображает собственный набор элементов управления (то есть когда указан атрибут controls).

Допустимые значения: nodownload, nofullscreen и noremoteplayback.

crossorigin

Этот перечисляемый атрибут указывает, следует ли использовать CORS для получения соответствующего аудиофайла. Ресурсы с поддержкой CORS можно использовать в элементе <canvas>, не делая его загрязнённым. Допустимые значения:

anonymous

Отправляет междоменный запрос без учётных данных. Иными словами, отправляет HTTP-заголовок Origin: без cookie, сертификата X.509 и без выполнения HTTP-аутентификации Basic. Если сервер не предоставляет учётные данные исходному сайту (не устанавливая HTTP-заголовок Access-Control-Allow-Origin:), ресурс будет загрязнён, а его использование — ограничено.

use-credentials

Отправляет междоменный запрос с учётными данными. Иными словами, отправляет HTTP-заголовок Origin: с cookie или сертификатом либо выполняет HTTP-аутентификацию Basic. Если сервер не предоставляет учётные данные исходному сайту (через HTTP-заголовок Access-Control-Allow-Credentials:), ресурс будет загрязнён, а его использование — ограничено.

Если атрибут отсутствует, ресурс загружается без CORS-запроса (то есть без отправки HTTP-заголовка Origin:), поэтому его нельзя использовать в элементах <canvas> без загрязнения. Если значение недопустимо, оно обрабатывается так, как если бы было указано перечисляемое ключевое слово anonymous. Дополнительные сведения см. в разделе Атрибуты настройки CORS.

disableremoteplayback

Логический атрибут, отключающий возможность удалённого воспроизведения на устройствах, подключённых по проводным (HDMI, DVI и т. д.) и беспроводным технологиям (Miracast, Chromecast, DLNA, AirPlay и т. д.). Дополнительные сведения см. в проекте спецификации Remote Playback API.

В Safari в качестве запасного варианта можно использовать x-webkit-airplay="deny".

loading

Указывает, как браузеру следует загружать аудио:

eager

Загружает аудио немедленно, независимо от того, находится ли оно в видимой области просмотра (значение по умолчанию).

lazy

Откладывает загрузку аудио, пока элементы управления не окажутся на рассчитанном браузером расстоянии от области просмотра.

Примечание: Чтобы аудиоэлементы могли визуально пересекаться с областью просмотра, они должны быть видимыми. Браузеры используют атрибут controls, чтобы сделать аудиоэлементы видимыми, поэтому он необходим для отложенной загрузки. Аудио с отложенной загрузкой без атрибута controls загружаться не будет.

Отложенная загрузка позволяет не расходовать сетевой трафик и место в хранилище на аудио, пока не станет достаточно ясно, что оно понадобится. Это повышает производительность в большинстве типичных случаев использования.

Аудио с отложенной загрузкой, расположенное в видимой области просмотра, может ещё не загрузиться к моменту срабатывания события load объекта Window. Это связано с тем, что событие срабатывает только для аудио с немедленной загрузкой — отложенная загрузка не учитывается, даже если аудио находится в видимой области просмотра при первоначальной загрузке страницы.

Загрузка откладывается только при включённом JavaScript. Это мера защиты от отслеживания: если бы браузер поддерживал отложенную загрузку при отключённых скриптах, сайт всё равно мог бы отслеживать примерное положение прокрутки пользователя на протяжении сеанса, размещая аудио в разметке страницы таким образом, чтобы сервер мог отслеживать количество запросов аудио и время их отправки.

Примечание: Атрибут loading="lazy" также влияет на атрибут autoplay, как описано в соответствующем разделе этой страницы.

loop

Логический атрибут: если он указан, при достижении конца аудиозаписи проигрыватель автоматически переместится к её началу.

muted

Логический атрибут, указывающий, будет ли звук изначально отключён. Значение по умолчанию — false.

preload

Этот перечисляемый атрибут предназначен для передачи браузеру подсказки о том, что, по мнению автора, обеспечит наилучшее взаимодействие с пользователем. Он может принимать следующие значения:

• none: указывает, что аудио не следует предварительно загружать.
• metadata: указывает, что загружаются только метаданные аудио (например, длительность).
• auto: указывает, что можно загрузить весь аудиофайл, даже если пользователь, вероятно, не будет его использовать.
• пустая строка: синоним значения auto.

Значение по умолчанию различается в разных браузерах. Спецификация рекомендует задавать значение metadata.

Примечание:

• Для аудио с установленным атрибутом loading="lazy" поведение preload применяется только тогда, когда элементы управления аудио находятся рядом с областью просмотра или внутри неё.
• Атрибут autoplay имеет приоритет над preload. Если указан autoplay, браузеру, очевидно, придётся начать загрузку аудио для воспроизведения.
• Спецификация не обязывает браузер следовать значению этого атрибута; это лишь подсказка.

src

URL аудио для встраивания. На него распространяются ограничения доступа HTTP. Этот атрибут необязателен: вместо него можно использовать элемент <source> внутри блока аудио, чтобы указать встраиваемое аудио.

События

audioprocess

Входной буфер объекта ScriptProcessorNode готов к обработке.

canplay

Браузер может воспроизводить мультимедиа, но считает, что загружено недостаточно данных для воспроизведения до конца без остановки для дополнительной буферизации содержимого.

canplaythrough

Браузер считает, что может воспроизвести мультимедиа до конца без остановки для буферизации содержимого.

complete

Рендеринг объекта 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, включая URL HTTP(S) и URL данных. При использовании URL HTTP(S) учитывайте, что поведение кэширования браузера влияет на частоту запросов файла к серверу. URL данных встраивают данные аудио непосредственно в HTML. Это может быть полезно для небольших аудиофайлов, но не рекомендуется для больших файлов, так как увеличивает размер HTML-файла.

При использовании элементов <source> браузер пытается последовательно загрузить каждый источник. Если источник не загружается (например, из-за недопустимого URL или неподдерживаемого формата), браузер пробует следующий и так далее. После того как все источники не загрузились, на элементе <audio> срабатывает событие error; события error не срабатывают для каждого отдельного элемента <source>.

Вместо потоковой передачи готовых аудиофайлов можно также использовать 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 и API HTMLMediaElement.
• Для точного управления аудиосодержимым элементы HTMLMediaElement генерируют множество различных событий. Это также позволяет отслеживать процесс получения аудио, чтобы обнаруживать ошибки или определять, когда данных достаточно для начала воспроизведения или обработки.
• Элементы <audio> не могут иметь связанные с ними субтитры или подписи так же, как элементы <video>. Полезную информацию и обходные решения можно найти в статье WebVTT и аудио Иэна Девлина.
• Чтобы проверить резервное содержимое в браузерах, поддерживающих этот элемент, можно заменить <audio> на несуществующий элемент, например <notanaudio>.

Хорошим общим источником информации об использовании HTML <audio> служит учебное пособие для начинающих Видео и аудио в HTML.

Стилизация с помощью CSS

Элемент <audio> сам по себе не имеет визуального представления, если не указан атрибут controls; в этом случае отображаются стандартные элементы управления браузера.

Для стандартных элементов управления по умолчанию задано значение inline свойства display. Часто целесообразно задать этому свойству значение block, чтобы упростить управление позиционированием и макетом, если только вы не хотите разместить элемент внутри текстового блока или аналогичного контейнера.

Стандартные элементы управления можно стилизовать с помощью свойств, влияющих на блок как единое целое: например, задать ему border и border-radius, padding, margin и т. д. Однако отдельные компоненты проигрывателя аудио стилизовать нельзя (например, изменить размер кнопок или значков, шрифт и т. д.), а элементы управления в разных браузерах различаются.

Чтобы обеспечить единый внешний вид во всех браузерах, необходимо создать собственные элементы управления; их можно разметить и стилизовать по своему усмотрению, а затем с помощью JavaScript и API HTMLMediaElement связать их с соответствующей функциональностью.

В статье Основы стилизации видеопроигрывателя приведены полезные приёмы стилизации — она посвящена элементу <video>, но многие из этих приёмов применимы и к элементу <audio>.

Обнаружение добавления и удаления дорожек

Обнаружить добавление и удаление дорожек элемента <audio> можно с помощью событий addtrack и removetrack. Однако эти события отправляются не самому элементу <audio>. Вместо этого они отправляются объекту списка дорожек внутри элемента <audio> — объекту HTMLMediaElement, соответствующему типу дорожки, добавленной в элемент:

HTMLMediaElement.audioTracks

Объект AudioTrackList, содержащий все аудиодорожки мультимедийного элемента. Чтобы получать уведомления о добавлении новых аудиодорожек в элемент, можно добавить к этому объекту обработчик события addtrack.

HTMLMediaElement.videoTracks

Добавьте обработчик события addtrack к этому объекту VideoTrackList, чтобы получать уведомления о добавлении видеодорожек в элемент.

HTMLMediaElement.textTracks

Добавьте обработчик события addtrack к этому объекту TextTrackList, чтобы получать уведомления о добавлении текстовых дорожек в элемент.

Например, чтобы обнаруживать добавление и удаление аудиодорожек элемента <audio>, можно использовать такой код:

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

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

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

Этот код отслеживает добавление и удаление аудиодорожек элемента и вызывает условную функцию редактора дорожек, чтобы зарегистрировать дорожку в списке доступных дорожек редактора или удалить её оттуда.

Для отслеживания событий addtrack и removetrack также можно использовать addEventListener().

Доступность

Аудио с речью должно сопровождаться субтитрами и расшифровками, точно описывающими его содержимое. Субтитры, заданные с помощью WebVTT, помогают людям с нарушениями слуха понимать содержимое аудиозаписи во время её воспроизведения, а расшифровки позволяют тем, кому требуется больше времени, изучать содержимое записи в удобном темпе и формате.

Если используются службы автоматического создания субтитров, важно проверить сгенерированное содержимое и убедиться, что оно точно передаёт исходное аудио.

Элемент <audio> напрямую не поддерживает WebVTT. Вам понадобится найти библиотеку или фреймворк с такой возможностью либо самостоятельно написать код для отображения субтитров. Один из вариантов — воспроизводить аудио с помощью элемента <video>, который поддерживает WebVTT.

Помимо речи, субтитры и расшифровки должны также описывать музыку и звуковые эффекты, передающие важную информацию, включая эмоции и интонацию. Например, в приведённом ниже примере 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 Video Text Tracks (WebVTT)
• WebAIM: субтитры, расшифровки и аудиоописания
• Понимание WCAG: пояснения к руководству 1.2
• Понимание критерия успеха 1.2.1 | Понимание WCAG 2.0 от W3C
• Понимание критерия успеха 1.2.2 | Понимание WCAG 2.0 от W3C

Примеры

Базовое использование

В следующем примере показано базовое использование элемента <audio> для воспроизведения файла OGG. Воспроизведение начнётся автоматически благодаря атрибуту autoplay — если странице разрешено это делать; также предусмотрено резервное содержимое.

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

Подробнее о том, когда работает автоматическое воспроизведение, как получить разрешение на его использование, а также когда и как его следует применять, см. в нашем руководстве по автоматическому воспроизведению.

Элемент <audio> с элементом <source>

В этом примере аудиодорожка для встраивания указывается с помощью атрибута src вложенного элемента <source>, а не непосредственно в элементе <audio>. Полезно всегда указывать MIME-тип файла в атрибуте type, чтобы браузер мог сразу определить, способен ли он воспроизвести этот файл, и не тратить время на неподдерживаемый файл.

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

Элемент <audio> с несколькими элементами <source>

В этом примере указано несколько элементов <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 Audio API

• HTMLAudioElement
• <source>
• <video>

• Учебный раздел: видео и аудио в HTML

• Основы кроссбраузерного воспроизведения аудио