وثائق HTML قابلة للتشغيل: وسم audio

Q: كيف أضيف صوتًا إلى صفحة HTML؟

استخدم . السمة controls تُظهر مشغل المتصفح بزر تشغيل وشريط زمني ومستوى صوت. من دونها يكون العنصر غير مرئي.

Q: كيف أكرر الصوت في HTML؟

أضف السمة loop: . حين ينتهي الملف يبدأ من جديد.

Q: كيف أشغّل صوتًا بـ JavaScript؟

أنشئ عنصر audio أو حدده واستدعِ play()، مثل new Audio('click.mp3').play() داخل معالج نقر. 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، أو استدعاء 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 مثلًا يتذكر المواقع التي تشغّل فيها الوسائط كثيرًا)، فلا تعتمد أبدًا على التشغيل التلقائي: ابدأ الصوت من إجراء يقوم به المستخدم، وتعامل دائمًا مع الـ promise التي تُرجعها play().

new Audio(url) تنشئ عنصر صوت في JavaScript من دون إضافته إلى الصفحة، وهذا مفيد للمؤثرات الصوتية.

ابنِ عناصر التحكم الخاصة بك

أخفِ المشغل المدمج بترك controls، ثم تحكّم في العنصر بواجهة 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> يشترك معه في معظم السمات وفي واجهة 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؟

أنشئ عنصر audio أو حدده واستدعِ play()، مثل new Audio('click.mp3').play() داخل معالج نقر. play() تُرجع promise تُرفض إذا منع المتصفح التشغيل.

هل يمكنني تنسيق مشغل الصوت في HTML؟

قليلًا فقط: يمكنك ضبط عرضه وهامشه وطريقة عرضه، لكن الأزرار بداخله يرسمها المتصفح وتختلف من متصفح لآخر. لمظهر مخصص، أخفِ عناصر التحكم وابنِ عناصرك الخاصة بالأزرار وواجهة JavaScript الخاصة بالصوت.

مفاهيم ذات صلة