Media APIs

Controlling audio and video in the browser — HTMLMediaElement, Web Audio API, MediaStream, getUserMedia, and the MediaRecorder API.

What it is, in plain English: The Media APIs in the browser cover playing, controlling, and creating audio and video. HTMLMediaElement (the interface behind

Where this bites you

play() returns a Promise, and browsers reject it when a page tries to start media with sound before the user has interacted with the page (autoplay policy). Code that calls play() and carries on as if it worked gets an unhandled NotAllowedError. The player UI then lies to the user: the button shows "pause" while nothing is playing.

// <audio src="tone.wav"></audio> <button id="play">▶</button>
const media   = document.querySelector("audio");
const playBtn = document.querySelector("#play");

media.play();                       // start on page load, before any click
playBtn.textContent = "⏸";          // assumes it worked
console.log("button shows:", playBtn.textContent, "| paused:", media.paused);
// button shows: ⏸ | paused: true
// Uncaught (in promise) NotAllowedError: play() failed because the user didn't interact with the document first.

Playing and controlling audio and video

HTMLMediaElement — the video and audio API

const video = document.querySelector("video");

// Playback control:
video.play();           // returns a Promise
video.pause();
video.currentTime = 0;  // seek to start (in seconds)
video.volume = 0.7;     // 0 to 1
video.muted  = true;
video.playbackRate = 2; // 2x speed

// State:
video.paused;           // true/false
video.ended;            // true/false
video.duration;         // total seconds (NaN until metadata loaded)
video.readyState;       // 0-4 (4 = can play through)

// Events:
video.addEventListener("play",       () => console.log("Playing"));
video.addEventListener("pause",      () => console.log("Paused"));
video.addEventListener("ended",      () => console.log("Ended"));
video.addEventListener("timeupdate", () => {
  const pct = (video.currentTime / video.duration * 100).toFixed(1);
  progressBar.style.width = pct + "%";
});
video.addEventListener("error",      (e) => console.error("Error:", e.target.error));

Building a custom video player

const video   = document.querySelector("video");
const playBtn = document.querySelector("#play");

playBtn.addEventListener("click", () => {
  if (video.paused) {
    video.play();
    playBtn.textContent = "⏸";
  } else {
    video.pause();
    playBtn.textContent = "▶";
  }
});

// Keyboard controls:
document.addEventListener("keydown", (e) => {
  if (e.key === " ")          video.paused ? video.play() : video.pause();
  if (e.key === "ArrowLeft")  video.currentTime -= 10;
  if (e.key === "ArrowRight") video.currentTime += 10;
  if (e.key === "ArrowUp")    video.volume = Math.min(1, video.volume + 0.1);
  if (e.key === "ArrowDown")  video.volume = Math.max(0, video.volume - 0.1);
});

The custom player above sets the button right after calling play(), so it has the same weakness whenever playback fails. Await the Promise and handle rejection. Better still, let the element's own play and pause events drive the button, so it always shows what really happened. (Muted media is generally allowed to autoplay, which is why background videos use muted.)

const media   = document.querySelector("audio");
const playBtn = document.querySelector("#play");

media.addEventListener("play",  () => { playBtn.textContent = "⏸"; });   // the button follows
media.addEventListener("pause", () => { playBtn.textContent = "▶"; });   // what really happened

async function tryPlay() {
  try {
    await media.play();             // play() returns a Promise: wait for it
  } catch (err) {
    console.log("blocked:", err.name);   // NotAllowedError until the user interacts
  }
  console.log("button shows:", playBtn.textContent, "| paused:", media.paused);
}
tryPlay();
// blocked: NotAllowedError
// button shows: ▶ | paused: true

Try It Yourself

// Web Audio API — create and control sound with JavaScript
const AudioContext = window.AudioContext || window.webkitAudioContext;
const ctx = new AudioContext();

function playBeep(frequency = 440, duration = 0.3, type = "sine") {
  const oscillator = ctx.createOscillator();
  const gainNode   = ctx.createGain();

// Connect: oscillator → gain → speakers
  oscillator.connect(gainNode);
  gainNode.connect(ctx.destination);

// Configure:
  oscillator.type      = type;           // "sine", "square", "sawtooth", "triangle"
  oscillator.frequency.value = frequency; // Hz (440 = A4 note)

// Fade out smoothly:
  gainNode.gain.setValueAtTime(0.5, ctx.currentTime);
  gainNode.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + duration);

// Play and stop:
  oscillator.start(ctx.currentTime);
  oscillator.stop(ctx.currentTime + duration);
}

// Play a scale (C major):
const notes = [261, 294, 330, 349, 392, 440, 494, 523]; // C D E F G A B C
notes.forEach((freq, i) => {
  setTimeout(() => {
    playBeep(freq, 0.3, "sine");
    console.log(`Playing: ${freq} Hz`);
  }, i * 350);
});

// HTMLMediaElement control (for <video> and <audio> elements):
const MEDIA_EXAMPLE = `
<video id="vid" src="movie.mp4" controls></video>
<script>
  const video = document.getElementById("vid");
  video.play();                     // start playback
  video.pause();                    // pause
  video.currentTime = 30;           // seek to 30 seconds
  video.volume = 0.5;               // 50% volume
  video.playbackRate = 1.5;         // 1.5x speed

video.addEventListener("timeupdate", () => {
    const pct = (video.currentTime / video.duration * 100).toFixed(0);
    progress.style.width = pct + "%";
  });
<\/script>`;

console.log("Web Audio API: playing a C major scale!");
console.log("HTMLMediaElement controls video/audio elements.");

Web Audio API and getUserMedia

Web Audio API — audio processing

const ctx = new AudioContext();

// Audio graph: source → effects → destination (speakers)
async function loadAndPlay(url) {
  const res    = await fetch(url);
  const buffer = await res.arrayBuffer();
  const audio  = await ctx.decodeAudioData(buffer);

  const source = ctx.createBufferSource();
  source.buffer = audio;

  const gainNode = ctx.createGain();
  gainNode.gain.value = 0.5;  // 50% volume

  source.connect(gainNode);
  gainNode.connect(ctx.destination);
  source.start();
  return source;
}

// Analyser — for visualisations (waveform, frequency bars):
const analyser = ctx.createAnalyser();
analyser.fftSize = 256;
source.connect(analyser);
analyser.connect(ctx.destination);

const data = new Uint8Array(analyser.frequencyBinCount);
function visualise() {
  analyser.getByteFrequencyData(data);
  // data = array of frequency magnitudes 0-255
  drawBars(data);
  requestAnimationFrame(visualise);
}

getUserMedia — camera and microphone

// Request camera/mic access:
const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: 1280, height: 720, facingMode: "user" },
  audio: true,
});

// Show in a video element:
const video = document.querySelector("video");
video.srcObject = stream;
video.play();

// Stop camera:
stream.getTracks().forEach(track => track.stop());

// Record audio/video with MediaRecorder:
const recorder = new MediaRecorder(stream);
const chunks   = [];

recorder.ondataavailable = (e) => chunks.push(e.data);
recorder.onstop = () => {
  const blob = new Blob(chunks, { type: "video/webm" });
  const url  = URL.createObjectURL(blob);
  const a    = document.createElement("a");
  a.href     = url;
  a.download = "recording.webm";
  a.click();
};

recorder.start();
setTimeout(() => recorder.stop(), 5000);  // record 5 seconds

AudioWorklet and MSE

// AudioWorklet — run audio processing on a dedicated audio thread (a Web Audio API feature):
await ctx.audioWorklet.addModule("my-processor.js");
const workletNode = new AudioWorkletNode(ctx, "my-processor");
source.connect(workletNode).connect(ctx.destination);

// my-processor.js:
// class MyProcessor extends AudioWorkletProcessor {
//   process(inputs, outputs, parameters) {
//     // Process audio samples here — runs on audio thread
//     const output = outputs[0];
//     output.forEach(channel => { channel.fill(0); });
//     return true;  // keep processor alive
//   }
// }
// registerProcessor("my-processor", MyProcessor);

// Media Source Extensions (MSE) — adaptive bitrate streaming:
// Used by YouTube, Netflix for DASH/HLS streaming
const mediaSource = new MediaSource();
video.src = URL.createObjectURL(mediaSource);
mediaSource.addEventListener("sourceopen", async () => {
  const sourceBuffer = mediaSource.addSourceBuffer("video/mp4; codecs='avc1.42E01E'");
  const response = await fetch("segment1.mp4");
  const buffer   = await response.arrayBuffer();
  sourceBuffer.appendBuffer(buffer);
});

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.