תיעוד HTML עם דוגמאות להרצה: התגית audio

Q: איך מוסיפים אודיו לעמוד HTML?

השתמשו ב- . המאפיין controls מציג את הנגן של הדפדפן עם כפתור ניגון, ציר זמן ועוצמת קול. בלעדיו האלמנט בלתי נראה.

Q: איך מנגנים אודיו בלולאה ב-HTML?

הוסיפו את המאפיין loop: . כשהקובץ נגמר, הוא מתחיל שוב מההתחלה.

Q: איך מנגנים צליל עם JavaScript?

צרו או בחרו אלמנט אודיו וקראו ל-play(), למשל new Audio('click.mp3').play() בתוך handler של לחיצה. play() מחזיר promise שנדחה אם הדפדפן חוסם את הניגון.

איך מוסיפים אודיו

הפנו את האלמנט <audio> לקובץ קול והוסיפו controls:

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

controls מציג את הנגן של הדפדפן: ניגון והשהיה, ציר זמן, הזמן ובקרת עוצמת קול. בלי controls האלמנט לא תופס מקום בכלל. התצוגה המקדימה לא יכולה לטעון קבצים מהמחשב שלכם, לכן הדוגמה הזו בונה קובץ WAV קצר בדפדפן עם סקריפט ומשתמשת בו כ-src. לחצו על ניגון:

<!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>

הנגן נראה שונה ב-Chrome, ב-Firefox וב-Safari, כי כל דפדפן מצייר את שלו. מחקו את controls והנגן נעלם, אבל האודיו עדיין שם ו-JavaScript יכול לנגן אותו.

מאפייני אודיו

מאפיין	מה הוא עושה
`controls`	מציג את הנגן של הדפדפן
`autoplay`	מנסה להתחיל לנגן בטעינה (נחסם כשיש קול, ראו בהמשך)
`loop`	מתחיל שוב כשהקובץ נגמר
`muted`	מתחיל כשעוצמת הקול כבויה
`preload`	`none` (לא להוריד כלום עד הניגון), `metadata` (רק את האורך) או `auto` (הדפדפן מחליט)
`src`	הקובץ לנגן; או השתמשו באלמנטי `<source>` בפנים לכמה פורמטים

השתמשו ב-preload="none" או "metadata" בעמודים עם הרבה נגנים, כמו רשימת פרקים של פודקאסט, כדי שהעמוד לא יוריד כל קובץ מראש.

פורמטים וחלופות

פרטו כמה קבצים עם <source> והדפדפן ינגן את הראשון שהוא תומך בו. טקסט בתוך האלמנט מוצג רק בדפדפנים בלי תמיכה ב-<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>

פורמט	סוג MIME	הערות
MP3	`audio/mpeg`	מתנגן בכל הדפדפנים העדכניים; הבחירה הבטוחה כשיש קובץ אחד
AAC (`.m4a`)	`audio/mp4`	נתמך באופן רחב, איכות טובה בגודל קטן
Opus או Vorbis (`.ogg`, `.webm`)	`audio/ogg`, `audio/webm`	קבצים קטנים; הוסיפו MP3 כחלופה, כי התמיכה ב-Safari משתנה לפי גרסה
WAV	`audio/wav`	לא דחוס וגדול; מתאים לאפקטים קוליים קצרים

למה autoplay נכשל

דפדפנים לא מאפשרים לעמוד להתחיל להשמיע קול מעצמו. autoplay, או קריאה ל-play() לפני שהמשתמש לחץ או הקיש, נדחים. הדוגמה הזו מנסה לנגן בטעינה ומדפיסה מה קרה, ואז מציעה כפתור:

<!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>

בדרך כלל תראו NotAllowedError, השגיאה שהדפדפן נותן כשהוא חוסם ניגון. הכפתור עובד כי לחיצה נחשבת כרשות. לכל דפדפן יש כללים נוספים משלו (Chrome, למשל, זוכר אתרים שבהם אתם מנגנים מדיה לעיתים קרובות), אז לעולם אל תסמכו על autoplay: התחילו קול מפעולה של המשתמש, ותמיד טפלו ב-promise ש-play() מחזיר.

new Audio(url) יוצר אלמנט אודיו ב-JavaScript בלי להוסיף אותו לעמוד, וזה שימושי לאפקטים קוליים.

בנו פקדים משלכם

הסתירו את הנגן המובנה על ידי השמטת controls, ואז הפעילו את האלמנט עם ה-API שלו ב-JavaScript: play(), pause(), currentTime, duration, volume, ואירועים כמו timeupdate ו-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>

הכפתור הוא <button> אמיתי, ולכן הוא עובד עם המקלדת, והתווית שלו מתחלפת בין Play ל-Pause. בסוף הקובץ הדפדפן משהה את האלמנט ומפעיל את ended, כך שהכפתור חוזר ל-Play מעצמו. אם אתם בונים פקדים מותאמים, אתם גם לוקחים על עצמכם את מה שהמובנים נתנו בחינם: תמיכה במקלדת, תוויות ובקרת עוצמת קול.

נגישות

לעולם אל תתחילו קול מעצמו. זה מפריע לקוראי מסך ומבהיל אנשים. התחילו אודיו מלחיצה.
הציעו תמלול לפודקאסטים ולאודיו מדובר. קישור לגרסת טקסט מתחת לנגן מספיק, ומנועי חיפוש יכולים לקרוא אותה.
השאירו את controls, או בנו פקדים מכפתורים אמיתיים, כדי שאפשר יהיה להשהות את האודיו עם המקלדת.

לווידאו עם קול, כתוביות ותמונות פוסטר, ראו את העמוד על התגית video; ל-<audio> יש את רוב המאפיינים שלה ואת כל ה-API שלה ב-JavaScript.

טעויות נפוצות

שכחה של controls. בלעדיו האלמנט בלתי נראה, ונראה כאילו לא קרה כלום.
ציפייה ש-autoplay יעבוד. התחילו את הניגון מלחיצה וטפלו ב-promise של play().
נתיב או סוג קובץ שגויים. פתחו את כתובת הקובץ ישירות כדי לבדוק אותה, והתאימו את type לפורמט האמיתי (audio/mpeg ל-MP3).
טעינת כל הקבצים ברשימה ארוכה. השתמשו ב-preload="none" או "metadata".
מוזיקת רקע שאי אפשר לעצור. תמיד תנו לאנשים דרך גלויה להשהות.

שאלות נפוצות

איך מוסיפים אודיו לעמוד HTML?

השתמשו ב-<audio src="song.mp3" controls></audio>. המאפיין controls מציג את הנגן של הדפדפן עם כפתור ניגון, ציר זמן ועוצמת קול. בלעדיו האלמנט בלתי נראה.

למה האודיו שלי לא מתנגן אוטומטית?

דפדפנים חוסמים אודיו שמתחיל עם קול לפני שהמשתמש קיים אינטראקציה עם העמוד. התחילו את הניגון מלחיצה עם audio.play() במקום. אלמנט מושתק יכול להתנגן אוטומטית, אבל באודיו זה כמעט אף פעם לא שימושי.

באיזה פורמט אודיו כדאי להשתמש ב-HTML?

MP3 מתנגן בכל הדפדפנים העדכניים, ולכן הוא הבחירה הבטוחה לקובץ יחיד. גם AAC בקובץ .m4a נתמך באופן רחב. השתמשו באלמנטי <source> כדי להציע יותר מפורמט אחד.

איך מנגנים אודיו בלולאה ב-HTML?

הוסיפו את המאפיין loop: <audio src="rain.mp3" controls loop>. כשהקובץ נגמר, הוא מתחיל שוב מההתחלה.

איך מנגנים צליל עם JavaScript?

צרו או בחרו אלמנט אודיו וקראו ל-play(), למשל new Audio('click.mp3').play() בתוך handler של לחיצה. play() מחזיר promise שנדחה אם הדפדפן חוסם את הניגון.

אפשר לעצב את נגן האודיו של HTML?

רק מעט: אפשר לקבוע את הרוחב, השוליים וה-display שלו, אבל הכפתורים שבתוכו מצוירים על ידי הדפדפן ונראים שונה בכל אחד. למראה מותאם, הסתירו את ה-controls ובנו פקדים משלכם עם כפתורים וה-API של אודיו ב-JavaScript.

מושגים קשורים