Dokumentacja HTML z przykładami: Znacznik audio

Q: Jak dodać dźwięk do strony HTML?

Użyj . Atrybut controls pokazuje odtwarzacz przeglądarki z przyciskiem odtwarzania, osią czasu i głośnością. Bez niego element jest niewidoczny.

Q: Jak zapętlić dźwięk w HTML?

Dodaj atrybut loop: . Gdy plik się skończy, zacznie się od nowa.

Q: Jak odtworzyć dźwięk w JavaScripcie?

Utwórz lub wybierz element audio i wywołaj play(), na przykład new Audio('click.mp3').play() w obsłudze kliknięcia. play() zwraca obietnicę (promise), która zostaje odrzucona, jeśli przeglądarka zablokuje odtwarzanie.

Jak dodać dźwięk

Wskaż elementowi <audio> plik dźwiękowy i dodaj controls:

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

controls pokazuje odtwarzacz przeglądarki: odtwarzanie i pauzę, oś czasu, czas i regulację głośności. Bez controls element w ogóle nie zajmuje miejsca. Podgląd nie może wczytać plików z twojego komputera, więc ten przykład tworzy w przeglądarce skryptem krótki plik WAV i używa go jako src. Naciśnij odtwarzanie:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Audio</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <audio id="player" controls></audio>
  <p>Four notes, 1.8 seconds.</p>
  <script>
    // Builds a tiny WAV file in the browser (stand-in for song.mp3)
    function makeWav(notes) {
      const rate = 8000, samples = [];
      for (const [freq, secs] of notes) {
        const n = secs * rate;
        for (let i = 0; i < n; i++) {
          samples.push(Math.sin(2 * Math.PI * freq * i / rate) * 0.4 * Math.min(1, (n - i) / 400));
        }
      }
      const view = new DataView(new ArrayBuffer(44 + samples.length * 2));
      const text = (at, s) => [...s].forEach((c, i) => view.setUint8(at + i, c.charCodeAt(0)));
      text(0, 'RIFF'); view.setUint32(4, 36 + samples.length * 2, true); text(8, 'WAVEfmt ');
      view.setUint32(16, 16, true); view.setUint16(20, 1, true); view.setUint16(22, 1, true);
      view.setUint32(24, rate, true); view.setUint32(28, rate * 2, true);
      view.setUint16(32, 2, true); view.setUint16(34, 16, true);
      text(36, 'data'); view.setUint32(40, samples.length * 2, true);
      samples.forEach((s, i) => view.setInt16(44 + i * 2, s * 32767, true));
      return URL.createObjectURL(new Blob([view], { type: 'audio/wav' }));
    }
    document.getElementById('player').src = makeWav([[523, 0.4], [659, 0.4], [784, 0.4], [1047, 0.6]]);
  </script>
</body>
</html>

Odtwarzacz wygląda inaczej w Chrome, Firefoksie i Safari, bo każda przeglądarka rysuje własny. Usuń controls, a odtwarzacz zniknie, choć dźwięk nadal będzie dostępny do odtworzenia z JavaScriptu.

Atrybuty audio

Atrybut	Do czego służy
`controls`	Pokazuje odtwarzacz przeglądarki
`autoplay`	Próbuje rozpocząć odtwarzanie po załadowaniu (z dźwiękiem blokowane, patrz niżej)
`loop`	Zaczyna od nowa, gdy plik się skończy
`muted`	Startuje z wyłączoną głośnością
`preload`	`none` (nic nie pobiera do czasu odtworzenia), `metadata` (tylko długość) lub `auto` (decyduje przeglądarka)
`src`	Plik do odtworzenia; albo użyj dzieci `<source>` dla kilku formatów

Na stronach z wieloma odtwarzaczami, np. na liście odcinków podcastu, używaj preload="none" lub "metadata", żeby strona nie pobierała od razu każdego pliku.

Formaty i treść zastępcza

Wypisz kilka plików za pomocą <source>, a przeglądarka odtworzy pierwszy, który obsługuje. Tekst wewnątrz elementu pokazuje się tylko w przeglądarkach bez obsługi <audio>:

<audio controls preload="metadata">
  <source src="episode.opus" type="audio/ogg; codecs=opus">
  <source src="episode.mp3" type="audio/mpeg">
  <p>Your browser cannot play audio. <a href="episode.mp3">Download the episode</a>.</p>
</audio>

Format	Typ MIME	Uwagi
MP3	`audio/mpeg`	Działa we wszystkich obecnych przeglądarkach; bezpieczny wybór, gdy masz jeden plik
AAC (`.m4a`)	`audio/mp4`	Szerokie wsparcie, dobra jakość przy małym rozmiarze
Opus lub Vorbis (`.ogg`, `.webm`)	`audio/ogg`, `audio/webm`	Małe pliki; dodaj MP3 jako zapas, bo wsparcie w Safari zależy od wersji
WAV	`audio/wav`	Bez kompresji i duży; nadaje się do krótkich efektów dźwiękowych

Dlaczego autoplay nie działa

Przeglądarki nie pozwalają stronie samodzielnie zacząć wydawać dźwięku. autoplay albo wywołanie play(), zanim użytkownik kliknie lub dotknie ekranu, zostaje odrzucone. Ten przykład próbuje odtworzyć dźwięk po załadowaniu i wypisuje, co się stało, a potem daje przycisk:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Autoplay</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    button { font: inherit; padding: 6px 14px; }
  </style>
</head>
<body>
  <p id="result">Trying to play...</p>
  <button id="play">Play with a click</button>
  <script>
    // Builds a short beep as a WAV file (stand-in for a real sound file)
    function beep(freq, secs) {
      const rate = 8000, n = secs * rate;
      const view = new DataView(new ArrayBuffer(44 + n * 2));
      const text = (at, s) => [...s].forEach((c, i) => view.setUint8(at + i, c.charCodeAt(0)));
      text(0, 'RIFF'); view.setUint32(4, 36 + n * 2, true); text(8, 'WAVEfmt ');
      view.setUint32(16, 16, true); view.setUint16(20, 1, true); view.setUint16(22, 1, true);
      view.setUint32(24, rate, true); view.setUint32(28, rate * 2, true);
      view.setUint16(32, 2, true); view.setUint16(34, 16, true);
      text(36, 'data'); view.setUint32(40, n * 2, true);
      for (let i = 0; i < n; i++) view.setInt16(44 + i * 2, Math.sin(2 * Math.PI * freq * i / rate) * 12000, true);
      return URL.createObjectURL(new Blob([view], { type: 'audio/wav' }));
    }
    const sound = new Audio(beep(440, 0.5));
    const result = document.getElementById('result');
    sound.play()
      .then(() => { result.textContent = 'Autoplay worked this time.'; })
      .catch((err) => { result.textContent = 'Autoplay was blocked: ' + err.name; });
    document.getElementById('play').onclick = () => {
      sound.currentTime = 0;
      sound.play()
        .then(() => { result.textContent = 'Playing, because you clicked.'; })
        .catch((err) => { result.textContent = 'Still blocked: ' + err.name; });
    };
  </script>
</body>
</html>

Zwykle zobaczysz NotAllowedError, czyli błąd, który przeglądarka zgłasza, gdy blokuje odtwarzanie. Przycisk działa, bo kliknięcie liczy się jako zgoda. Każda przeglądarka ma własne dodatkowe reguły (Chrome na przykład zapamiętuje strony, na których często odtwarzasz multimedia), więc nigdy nie polegaj na autoplay: uruchamiaj dźwięk w reakcji na działanie użytkownika i zawsze obsługuj obietnicę zwracaną przez play().

new Audio(url) tworzy element audio w JavaScripcie bez dodawania go do strony, co przydaje się przy efektach dźwiękowych.

Własne kontrolki

Ukryj wbudowany odtwarzacz, pomijając controls, a potem steruj elementem przez jego API w JavaScripcie: play(), pause(), currentTime, duration, volume oraz zdarzenia takie jak timeupdate i ended:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Custom player</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    .player { display: flex; align-items: center; gap: 10px; max-width: 360px; padding: 10px; border: 2px solid #e5e7eb; border-radius: 10px; }
    .player button { font: inherit; width: 72px; padding: 6px 0; border: 0; border-radius: 6px; background: #2563eb; color: #fff; cursor: pointer; }
    progress { flex: 1; }
    #time { font-variant-numeric: tabular-nums; font-size: 14px; color: #374151; }
  </style>
</head>
<body>
  <div class="player">
    <button id="toggle" aria-label="Play">Play</button>
    <progress id="bar" value="0" max="1"></progress>
    <span id="time">0.0 s</span>
  </div>
  <audio id="audio"></audio>
  <script>
    function makeWav(notes) {
      const rate = 8000, samples = [];
      for (const [freq, secs] of notes) {
        const n = secs * rate;
        for (let i = 0; i < n; i++) {
          samples.push(Math.sin(2 * Math.PI * freq * i / rate) * 0.4 * Math.min(1, (n - i) / 400));
        }
      }
      const view = new DataView(new ArrayBuffer(44 + samples.length * 2));
      const text = (at, s) => [...s].forEach((c, i) => view.setUint8(at + i, c.charCodeAt(0)));
      text(0, 'RIFF'); view.setUint32(4, 36 + samples.length * 2, true); text(8, 'WAVEfmt ');
      view.setUint32(16, 16, true); view.setUint16(20, 1, true); view.setUint16(22, 1, true);
      view.setUint32(24, rate, true); view.setUint32(28, rate * 2, true);
      view.setUint16(32, 2, true); view.setUint16(34, 16, true);
      text(36, 'data'); view.setUint32(40, samples.length * 2, true);
      samples.forEach((s, i) => view.setInt16(44 + i * 2, s * 32767, true));
      return URL.createObjectURL(new Blob([view], { type: 'audio/wav' }));
    }
    const audio = document.getElementById('audio');
    const toggle = document.getElementById('toggle');
    audio.src = makeWav([[392, 0.5], [440, 0.5], [494, 0.5], [523, 1]]);
    toggle.onclick = () => {
      if (audio.paused) audio.play().catch((err) => { toggle.textContent = err.name; });
      else audio.pause();
    };
    audio.addEventListener('play', () => { toggle.textContent = 'Pause'; toggle.setAttribute('aria-label', 'Pause'); });
    audio.addEventListener('pause', () => { toggle.textContent = 'Play'; toggle.setAttribute('aria-label', 'Play'); });
    audio.addEventListener('timeupdate', () => {
      document.getElementById('bar').value = audio.currentTime / audio.duration || 0;
      document.getElementById('time').textContent = audio.currentTime.toFixed(1) + ' s';
    });
  </script>
</body>
</html>

Przycisk to prawdziwy <button>, więc działa z klawiatury, a jego etykieta zmienia się między Play i Pause. Na końcu pliku przeglądarka pauzuje element i wywołuje zdarzenie ended, więc przycisk sam wraca do Play. Budując własne kontrolki, bierzesz na siebie też to, co wbudowane dawały za darmo: obsługę klawiatury, etykiety i regulację głośności.

Dostępność

Nigdy nie włączaj dźwięku samoczynnie. Przerywa to czytniki ekranu i zaskakuje ludzi. Uruchamiaj dźwięk kliknięciem.
Udostępnij transkrypcję podcastów i nagrań mowy. Wystarczy link do wersji tekstowej pod odtwarzaczem, a wyszukiwarki też mogą ją przeczytać.
Zostaw controls albo zbuduj kontrolki z prawdziwych przycisków, żeby dźwięk dało się zatrzymać z klawiatury.

O wideo z dźwiękiem, napisach i plakatach przeczytasz na stronie o znaczniku video; <audio> ma większość jego atrybutów i całe API w JavaScripcie.

Częste błędy

Brak controls. Bez niego element jest niewidoczny i wygląda, jakby nic się nie stało.
Liczenie na to, że autoplay zadziała. Uruchamiaj odtwarzanie kliknięciem i obsługuj obietnicę z play().
Zła ścieżka lub typ pliku. Otwórz adres pliku bezpośrednio, żeby go sprawdzić, i dopasuj type do prawdziwego formatu (audio/mpeg dla MP3).
Wczytywanie każdego pliku z długiej listy. Użyj preload="none" lub "metadata".
Muzyka w tle, której nie da się wyłączyć. Zawsze daj widoczny sposób na pauzę.

Najczęściej zadawane pytania

Jak dodać dźwięk do strony HTML?

Użyj <audio src="song.mp3" controls></audio>. Atrybut controls pokazuje odtwarzacz przeglądarki z przyciskiem odtwarzania, osią czasu i głośnością. Bez niego element jest niewidoczny.

Dlaczego mój dźwięk nie odtwarza się automatycznie?

Przeglądarki blokują dźwięk, który zaczyna grać, zanim użytkownik wejdzie w interakcję ze stroną. Zamiast tego uruchom odtwarzanie kliknięciem przez audio.play(). Wyciszony element może odtworzyć się automatycznie, ale w przypadku audio rzadko ma to sens.

Jakiego formatu audio używać w HTML?

MP3 działa we wszystkich obecnych przeglądarkach, więc to bezpieczny wybór, gdy masz jeden plik. AAC w pliku .m4a też ma szerokie wsparcie. Aby zaoferować więcej niż jeden format, użyj elementów <source>.

Jak zapętlić dźwięk w HTML?

Dodaj atrybut loop: <audio src="rain.mp3" controls loop>. Gdy plik się skończy, zacznie się od nowa.

Jak odtworzyć dźwięk w JavaScripcie?

Utwórz lub wybierz element audio i wywołaj play(), na przykład new Audio('click.mp3').play() w obsłudze kliknięcia. play() zwraca obietnicę (promise), która zostaje odrzucona, jeśli przeglądarka zablokuje odtwarzanie.

Czy mogę zmienić wygląd odtwarzacza audio w HTML?

Tylko trochę: możesz ustawić jego szerokość, margines i display, ale przyciski w środku rysuje przeglądarka i w każdej wyglądają inaczej. Aby uzyskać własny wygląd, ukryj kontrolki i zbuduj swoje z przycisków i API audio w JavaScripcie.

Powiązane zagadnienia