HTMLMediaElement: The Remote Control for Browser Media

Why it exists

Before a standard API, controlling audio and video with JavaScript was a mess of browser-specific hacks. The HTMLMediaElement API was created to provide a single, consistent interface for programmatically managing media playback, regardless of whether the element is <audio> or <video>. This simplifies building rich media experiences.

The mental model

Imagine a standard TV remote control. It has buttons for play, pause, volume, and mute, and a display showing the current time. The HTMLMediaElement API is the JavaScript equivalent of that remote. It's not the video or audio itself, but the interface you use to interact with it. Both <audio> and <video> elements are "TVs" that respond to this same standard "remote".

How it works

When you get a reference to an <audio> or <video> element in JavaScript (e.g., with document.querySelector('video')), the returned object inherits from HTMLMediaElement. This gives you access to all its properties and methods. You can read properties like .paused (a boolean) or .duration (in seconds). You can also set properties like .currentTime to seek to a specific point or .volume to adjust loudness. Calling methods like .play() and .pause() directly controls playback.

When to use it

Use this API whenever you need to go beyond the browser's default media controls. Common use cases include building a completely custom video player UI with your own buttons and scrub bar, automatically pausing a video when a user scrolls it out of view, or synchronizing on-screen text with specific timestamps in an audio track. It's also used to check how much of a media file has downloaded using the .buffered property.

When not to use it

If you just need to embed a simple video and the default browser controls are sufficient, you don't need to interact with this API directly; simply using the <video controls> tag is enough. For complex streaming like adaptive bitrate (DASH/HLS), you'll typically use a higher-level library like HLS.js or Shaka Player, which use this API under the hood but manage the complexity for you.

One canonical example

To make a video play when a button is clicked and update a time display:

const video = document.querySelector('video');
const playButton = document.querySelector('#playBtn');
const timeDisplay = document.querySelector('#time');

playButton.addEventListener('click', () => {
if (video.paused) {
video.play();
} else {
video.pause();
}
});

video.addEventListener('timeupdate', () => {
timeDisplay.textContent = Time: ${Math.floor(video.currentTime)}s;
});