Controlling Audio with JavaScript

Technical Deep Dive & Specifications

The HTMLMediaElement JavaScript API Surface

The HTMLAudioElement inherits over 30 properties, methods, and event handlers from HTMLMediaElement:

+-------------------------------------------------------------------------------+
|                       HTMLMediaElement API ARCHITECTURE                       |
+-------------------------------------------------------------------------------+
|  METHODS                                                                      |
|  - play() : Promise<void>          Initiates playback pipeline                |
|  - pause() : void                  Suspends playback at currentTime           |
|  - load() : void                   Resets & executes Media Selection          |
|  - canPlayType(mime) : string      Probes codec support ("probably"|"maybe"|"")|
|  - fastSeek(time) : void           Performs fast, imprecise seek (if hardware)|
|                                                                               |
|  TIMELINE & STATE PROPERTIES                                                  |
|  - currentTime : number            Current playback position in seconds       |
|  - duration : number               Total duration in seconds (or NaN)         |
|  - paused : boolean                true if playback is currently paused       |
|  - ended : boolean                 true if playback reached duration          |
|  - playbackRate : number           Playback speed multiplier (0.5 to 4.0)     |
|  - preservesPitch : boolean        Maintains original pitch during speed shift|
|  - buffered : TimeRanges           Returns buffered byte ranges               |
|  - readyState : number (0–4)       Internal media buffer readiness            |
|  - networkState : number (0–3)     Network activity status                    |
+-------------------------------------------------------------------------------+

The readyState Lifecycle (0 to 4)

The readyState property indicates how much audio data has been loaded and decoded into memory:

Buffering Diagnostics & TimeRanges

The audio.buffered property returns a normalized TimeRanges object representing which segments of the timeline have been downloaded into the client cache:

Timeline: 0s ------------------- 30s ------------------- 60s ------------------- 90s
Buffer:   [=== Range 0 ===]               [=========== Range 1 ===========]
          start: 0.0s, end: 24.5s          start: 45.0s, end: 88.2s

const audio = document.querySelector('audio');

// Inspecting buffered ranges
function calculateBufferedPercentage(audio) {
  if (audio.buffered.length === 0 || isNaN(audio.duration)) return 0;
  
  // For standard continuous streaming, inspect Range 0
  const bufferedEnd = audio.buffered.end(audio.buffered.length - 1);
  const percent = (bufferedEnd / audio.duration) * 100;
  return Math.min(100, percent);
}

The Complete Media Event Sequence

[ New Source Assigned ]
         |
         +--> loadstart (Network request initialized)
         +--> loadedmetadata (Duration & channels resolved, readyState >= 1)
         +--> loadeddata (First frame rendered, readyState >= 2)
         +--> canplay (Can begin playback, readyState >= 3)
         +--> canplaythrough (Can play to end without buffering, readyState = 4)
         |
    (User calls play())
         |
         +--> play
         +--> playing (Audio actually emitting sound)
         +--> timeupdate (Fired 4–60 times per second during playback)
         |
    (Network stall occurs)
         |
         +--> waiting (Playback paused due to empty buffer)
         +--> playing (Resumed once buffer fills)
         |
    (End of track reached)
         |
         +--> ended

Sound Pooling Architecture for Rapid UI / Game SFX

Calling audio.play() on a single HTMLAudioElement while it is already playing will not create an overlapping sound; it simply resets or ignores the request.

To create polyphonic, overlapping sound effects, engineers build an Audio Pool:

class AudioPool {
  constructor(src, poolSize = 6) {
    this.pool = [];
    this.index = 0;
    this.poolSize = poolSize;

    for (let i = 0; i < poolSize; i++) {
      const sound = new Audio(src);
      sound.preload = 'auto';
      this.pool.push(sound);
    }
  }

  play() {
    const sound = this.pool[this.index];
    sound.currentTime = 0; // Rewind to start
    sound.play().catch(e => console.warn('Pool audio blocked:', e));
    
    // Cycle to next pooled instance
    this.index = (this.index + 1) % this.poolSize;
  }
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 81 (const audio = new Audio(...)): Instantiates an in-memory HTMLAudioElement directly in JavaScript without touching HTML markup.
• Line 92 (audio.preservesPitch = true): Instructs the browser's DSP resampler to use phase vocoder pitch correction, preserving voice pitch when speeding up or slowing down playback.
• Lines 102–105 (audio.currentTime = Math.min(...)): Demonstrates programmatic timeline scrubbing by writing directly to the currentTime float property.

Expected Browser Render Output

+-------------------------------------------------------------+
| Audio Engine Telemetry                                      |
|                                                             |
| +-------------+     +-------------+     +-------------+     |
| |      4      |     |    0.85s    |     |    1.50x    |     |
| | readyState  |     | currentTime |     | playbackRate|     |
| +-------------+     +-------------+     +-------------+     |
|                                                             |
| [ ▶ Play ]          [ ⏸ Pause ]         [ ⏩ Seek +1s ]     |
| Speed: [======o==============] 1.50x                         |
+-------------------------------------------------------------+