Design a video player

Requirements: what to ask before drawing anything

A video player looks like a solved problem: the browser has a video element with a controls attribute, and it plays video. The interview is about everything that attribute doesn't give you: one look in every browser, a seek bar with preview frames, captions people can restyle, quality menus for adaptive streams, keyboard shortcuts that don't fight the page, and numbers that tell the business whether people could actually watch. Spend the first five minutes finding out which of these matter here.

Ask from the outside in: who embeds the player (one app or many teams), what kind of video (short clips, long lessons, live), which devices, which rules (accessibility law, DRM). The table shows the answers this guide assumes and what would move if the answer changed.

Functional requirements

• Play and pause, by button, by clicking the video, and by keyboard.
• Seek by dragging or clicking a seek bar that shows how much is buffered and a preview frame with the time under the pointer.
• Volume and mute, remembered between visits. Playback speed from 0.25x to 2x.
• Captions and subtitles in several languages, with user styling (size, color, background).
• Quality menu with an Auto option for adaptive streams.
• Fullscreen and picture-in-picture.
• Resume where the learner stopped, on any device.
• Keyboard shortcuts in the style people know from YouTube: k or Space, j and l, arrows, f, m, c, digits.
• A component API: sources, tracks, poster, events, an imperative handle, theming, and plugin slots.

Non-functional requirements, with numbers

• Fast first paint: the poster image and a play button render with the page; the player's JavaScript must not hurt Largest Contentful Paint. Budget about 30 KB gzipped for the player shell, with the streaming engine (hls.js alone is well over 100 KB gzipped) loaded only when a stream actually starts.
• Fast start: under 1 second from pressing play to the first frame on a good connection, under 2.5 seconds on a slow 4G one.
• Few stalls: rebuffering under 1% of watch time at the 75th percentile.
• Responsive controls: every press gives visible feedback within 100 ms, even while the video is still loading.
• Accessible: every control reachable and usable by keyboard, every control named with its state, captions on for every course video.
• Works everywhere we ship: the last two versions of Chrome, Edge, Firefox, Safari, and iOS Safari.

Out of scope, and why

• Encoding, packaging, and the CDN: the server side of streaming. The YouTube guide covers it; we consume its output.
• Live streaming with low latency: it changes buffering and the seek bar enough to be its own problem. We touch on it in the interview chapter.
• Ads (VAST, VMAP, ad pods): a large topic of its own. We leave a plugin slot for it.
• Recommendations, comments, and the watch page around the player.

What makes a video player hard

Most components own their state: a dropdown is open because you set open to true. A video player does not. The real state lives inside the browser's media pipeline: a network stack downloading bytes, a decoder turning them into frames, and a clock moving the playhead.

Your UI only hears about that pipeline through events, and those events arrive late, in odd orders, and sometimes not at all. Five traits drive every decision in this guide.

1. The truth is somewhere else. Pressing play does not mean the video plays. play() returns a promise that can reject because of autoplay rules, and even after it resolves the video can stop to wait for data. The UI must show what the media element is doing, not what the user asked for.
2. Time is continuous, the UI is not. The playhead moves 30 to 60 frames a second, but timeupdate fires only every 15 to 250 ms (as rarely as 4 times a second), and a seek takes 50 ms on a fast connection or 3 seconds on a slow one. The seek bar must look smooth while the data under it is coarse and late.
3. One player, four kinds of input. Mouse users hover and drag, touch users tap and double-tap, keyboard users press shortcuts, and screen reader users move through controls that speak. Each needs the same features, and they fight: a hover preview means nothing on touch, and a single-letter shortcut can steal a key a screen reader needs.
4. The network decides quality. A 10 minute lesson at 1080p and 5 Mbps is about 375 MB. Nobody downloads that up front. Adaptive streaming fetches the video in 2 to 6 second segments and picks the quality per segment, so the player is also a small download scheduler.
5. Browsers differ in ways that matter. iPhone Safari won't make a div fullscreen, and it gets Media Source Extensions only through a newer ManagedMediaSource API. Desktop Firefox gained the picture-in-picture APIs only in 2026, and Firefox on Android still lacks them. A component used by many teams must hide these differences behind one API.

The wireframe names the parts we'll design. The viewport is the video element plus overlays on top of it: the big play button, the buffering spinner, captions, and error messages. The control bar sits at the bottom: the seek bar across the full width, then a row of buttons.

The settings menu opens above the control bar for speed, quality, and caption options. Everything is inside one container element, and that container is what goes fullscreen.

Native controls or our own: and the media element API underneath

The naive answer is one line: video src=lesson.mp4 controls. It plays, it's accessible enough, and it's free. Then the requests arrive.

Design wants the same controls in Chrome, Safari, and Firefox, which all draw them differently. Product wants preview frames on the seek bar, a quality menu, chapter markers, and a speed menu with 1.75x. Accessibility wants caption styling that works the same everywhere. The native controls can't be extended: you get what the browser draws, and you can't add a button to it.

The media element API you build on

The HTMLMediaElement interface (shared by video and audio) is the contract. You command it with methods and properties, and it reports back with events. Three parts deserve close reading.

play() returns a promise. It resolves when playback actually starts. It rejects with NotAllowedError when the browser blocks playback, usually because the video has sound and there was no user gesture, and with AbortError when a pause() or a new source interrupts it. Code that calls play() and ignores the result shows a pause icon over a video that never started, and logs an unhandled rejection.

async function requestPlay(video: HTMLVideoElement) {
  try {
    await video.play();
  } catch (err) {
    if (err instanceof DOMException && err.name === "NotAllowedError") {
      // Autoplay with sound blocked: show the big play button again.
      emit({ type: "PLAY_BLOCKED" });
    } else if (err instanceof DOMException && err.name === "AbortError") {
      // Interrupted by pause() or a new source: not an error for the user.
    } else {
      emit({ type: "ERROR", error: err });
    }
  }
}

Two numbers describe readiness. readyState says how much data is ready at the playhead, from 0 to 4. networkState says what the network side is doing. Together they answer the question every UI asks: can we play right now?

Events tell the story. About twenty media events exist, and a player listens to about fifteen of them. The timeline shows the order you'll usually see them in when a user loads a video, presses play, and seeks.

The player as a state machine

The naive model is a bag of booleans: isPlaying, isLoading, isSeeking, isEnded, hasError. Five booleans allow 32 combinations, and most are nonsense. Can the player be isPlaying and isEnded? isSeeking and hasError?

Each event handler flips one or two flags, and after a few months of bug fixes nobody knows which combinations are reachable. The classic symptom: the spinner stays on forever after a seek, because seeked cleared isSeeking but nothing cleared the isLoading that waiting set during the seek.

The states and what each one shows

Seeking needs memory. A user who seeks while playing expects playback to continue; one who seeks while paused expects to stay paused. So seeking carries a resume flag set from the state it came from, and seeked returns to playing or paused based on it. The same idea handles buffering: waiting during a seek is part of the seek, not a separate rebuffer, so it must not start the rebuffer timer.

type Status = "idle" | "loading" | "paused" | "playing" | "buffering" | "seeking" | "ended" | "error";
type State = { status: Status; resume: boolean; time: number };

function reduce(s: State, e: PlayerEvent): State {
  const is = (...list: Status[]) => list.includes(s.status);
  switch (e.type) {
    case "play":
      if (is("seeking")) return { ...s, resume: true };
      return is("idle", "paused", "ended") ? { ...s, status: "loading" } : s;
    case "playing":
      return is("loading", "buffering", "paused") ? { ...s, status: "playing" } : s;
    case "waiting":
      return is("playing") ? { ...s, status: "buffering" } : s;
    case "seeking":
      if (is("error", "idle", "seeking")) return s;
      return { ...s, status: "seeking", resume: is("playing", "buffering", "loading") };
    case "seeked":
      if (!is("seeking")) return s;
      return { ...s, status: s.resume ? "playing" : "paused" };
    case "pause":
      if (is("seeking")) return { ...s, resume: false };
      return is("playing", "buffering", "loading") ? { ...s, status: "paused" } : s;
    case "ended":
      return is("playing", "buffering") ? { ...s, status: "ended", resume: false } : s;
    case "error":
      return { ...s, status: "error" };
  }
  return s;
}

Note the seeked case: it only acts during a seek, and if the user was playing, it goes to playing even though frames might not be decoded yet. If data is missing, the element fires waiting right after, and the machine moves to buffering. Small steps, each one true for a moment, beat one big guess.

Timing rules: when to show the spinner

Most waiting events on a good connection last under 200 ms: a seek inside the buffer, a quality switch. Showing a spinner for each makes the player look broken. Show it only after the machine has been in loading, buffering, or seeking for 300 ms, and keep it at least 500 ms once shown so it doesn't flash. The timer belongs to the view layer, keyed on the state; the reducer stays pure.

Try the lab: fire waiting while paused (nothing happens, which is correct), seek while playing and then fire waiting (still seeking, no rebuffer counted), then fire seeked. Fire events in a silly order and watch the machine refuse transitions it doesn't allow.

The seek bar: buffered ranges, scrubbing, and preview frames

The seek bar is the most used and most subtle control. It shows four things at once: where the playhead is, how much is buffered ahead, where the pointer is hovering (with a preview frame and time), and, for long videos, chapter boundaries. It accepts mouse clicks, drags, touch drags, and keys. And it must not fight the video: while the user drags, timeupdate keeps firing with the old time and would yank the thumb back if we let it.

Drawing buffered ranges

video.buffered is a TimeRanges object: a list of start and end times the browser holds. It is usually one range, but after a seek it can be several: 0 to 40 seconds from the start, then 300 to 330 seconds from where the user jumped. Draw every range, not only the one at the playhead. On each progress event (and after seeked), read the ranges and convert each to left and width percentages of the duration.

function bufferedSegments(video: HTMLVideoElement) {
  const { buffered, duration } = video;
  if (!Number.isFinite(duration) || duration === 0) return [];
  const out: { left: number; width: number }[] = [];
  for (let i = 0; i < buffered.length; i++) {
    const start = buffered.start(i);
    const end = buffered.end(i);
    out.push({ left: (start / duration) * 100, width: ((end - start) / duration) * 100 });
  }
  return out;
}

Scrubbing with pointer capture

On pointerdown, call setPointerCapture(e.pointerId) on the bar. From then on, every pointermove and the final pointerup go to the bar even when the pointer leaves it, so a fast drag off the edge doesn't get lost. Set the CSS touch-action: none on the bar so a horizontal finger drag isn't taken by the browser for scrolling. Handle pointercancel (a phone call, a system gesture) by ending the drag without seeking.

While dragging, the thumb follows the pointer, not currentTime. Should the video seek on every move? A pointermove can fire 60 to 120 times a second, and each currentTime write starts a seek that may fetch a segment. Seeking on release only is cheap but feels dead.

The middle path: show the preview frame during the drag, and seek at most every 200 ms if the target is inside the buffer (cheap and smooth), else only on release. Firefox and Safari also offer fastSeek(), which jumps to the nearest keyframe for quicker but less exact previews; Chromium browsers don't have it, so feature-detect.

Preview frames on hover

WEBVTT

00:00:00.000 --> 00:00:05.000
thumbs-0.jpg#xywh=0,0,160,90

00:00:05.000 --> 00:00:10.000
thumbs-0.jpg#xywh=160,0,160,90

00:08:20.000 --> 00:08:25.000
thumbs-1.jpg#xywh=0,0,160,90

Keyboard and screen reader behavior

When the seek bar has focus, Left and Right move 5 seconds, Page Up and Page Down move 10% (or 60 seconds), Home goes to the start and End to the end. Up and Down step it like Right and Left, as the APG slider pattern expects. YouTube maps Up and Down on its seek bar to volume instead; either works if the help text says so.

The slider exposes aria-valuemin=0, aria-valuemax as the duration in seconds, aria-valuenow as the current second, and aria-valuetext in words, for example 1 minute 5 seconds of 12 minutes 14 seconds. Without aria-valuetext, a screen reader says 65, which means nothing. Update these attributes about once a second while playing, not on every timeupdate, so assistive technology isn't flooded.

Volume, speed, menus, and controls that hide themselves

The rest of the control bar looks like plain buttons, but each has a trap. Volume has a mute state separate from the level, and iPhones ignore the level entirely. Speed needs a menu that keyboard users can operate. And the whole bar must get out of the way while people watch, without vanishing from under a keyboard user's focus.

Volume and mute, remembered

The element has two separate properties: volume from 0 to 1 and muted true or false. Keep them separate in the UI too. Muting must not set volume to 0, or unmuting has nothing to return to.

When the user drags volume to 0, show the muted icon; when they drag it up from 0 while muted, unmute. Save both to localStorage on volumechange (debounced to about 500 ms while dragging) and restore them when the player mounts, so a learner who likes 40% doesn't reset it every lesson.

On iPhone and iPad, the hardware buttons own the volume: Safari treats volume as read-only and it always reads 1. Detect this once (set volume to 0.5 and read it back) and hide the slider, keeping only the mute button. The volume slider itself follows the same slider pattern as the seek bar, with aria-valuetext like 40 percent, and Up and Down arrows step it by 5%.

Playback speed

Set playbackRate to one of 0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2. Browsers keep the pitch natural by default (preservesPitch is true), so 1.5x lectures don't sound like cartoons. Persist the choice per user: learners who watch at 1.5x watch everything at 1.5x. Note that the playhead now moves faster than the wall clock, which matters for analytics: 10 minutes of content watched at 2x is 5 minutes of watch time.

The settings menu

Speed, quality, and captions live in one settings menu. Use the menu button pattern: the gear is a button with aria-haspopup=menu and aria-expanded, and the menu uses role=menu with menuitemradio items carrying aria-checked. Arrow keys move between items, Enter picks, and Escape closes and returns focus to the gear.

Submenus (Settings, then Speed) slide in place and keep the same keyboard rules. The focus-management lesson covers returning focus correctly.

Auto-hiding controls

Keyboard shortcuts that don't fight the page

People who watch a lot of video know YouTube's keys by heart, so match them. The question isn't which keys; it's where they listen. A player that grabs the k key on the whole document breaks the comment box under it, and a course page with three players can't have all three answering Space.

function onKeyDown(e: KeyboardEvent) {
  if (e.ctrlKey || e.metaKey || e.altKey || e.defaultPrevented) return;
  const t = e.target as HTMLElement;
  if (t.closest("input, textarea, select, [contenteditable=true]")) return;
  if (t.closest("[role=slider], [role=menu]") && /^Arrow|^Page|Home|End/.test(e.key)) return;
  if (e.key === " " && t.closest("button")) return; // the button handles it
  const action = keymap[e.key.length === 1 ? e.key.toLowerCase() : e.key];
  if (!action) return;
  e.preventDefault();
  action(player);
  announce(player.describe(action)); // "Volume 60 percent", "Forward 10 seconds"
}

Screen readers and single-letter keys

Screen readers on Windows (NVDA, JAWS) have a browse mode where single letters move through the page; in NVDA, for example, k jumps to the next link and f to the next form field. In browse mode those keys never reach the page, so our shortcuts don't fire, and that's correct. When the user tabs onto a control, the screen reader usually switches to focus mode and keys pass through.

Two rules follow. First, every shortcut must also exist as a button, because shortcuts are an extra, not the only way. Second, never put role=application on the player to force keys through: it switches off the screen reader's own navigation for everything inside.

A shortcut changes things without moving focus, so nothing is announced. Send a short message to a polite live region (Volume 60 percent, Captions on, Forward 10 seconds) and show the same text briefly over the video, the way YouTube shows a +10 bubble. The keyboard-navigation lesson covers roving focus inside the control bar.

Captions, subtitles, and audio descriptions

For a course platform sold to universities, captions are a legal requirement, not a feature. WCAG 2.2 success criterion 1.2.2 (level A) requires captions for prerecorded audio in video, and 1.2.5 (level AA) requires audio description for prerecorded video.

Two terms first. Captions are for viewers who can't hear the audio: they include speech plus sounds like [door slams] and speaker names. Subtitles translate speech for viewers who can hear but don't know the language. Both use the same format and the same code path.

WebVTT tracks and the textTracks API

Each caption file is a WebVTT file, attached as a track child of the video with kind (captions, subtitles, descriptions, chapters, or metadata), srclang, and label. A cue is a time range plus text, with optional settings for position and alignment. Streaming engines add caption tracks from the manifest the same way, so one code path covers both.

In script, video.textTracks lists the tracks. Each has a mode: showing (the browser draws it), hidden (loaded and firing events, not drawn), or disabled (inactive, so no cues and no events). A track fires cuechange when its activeCues change.

function useCaptions(video: HTMLVideoElement, lang: string | null, native: boolean) {
  const [lines, setLines] = useState<string[]>([]);
  useEffect(() => {
    const tracks = Array.from(video.textTracks);
    const track = tracks.find((t) => t.language === lang && (t.kind === "captions" || t.kind === "subtitles"));
    for (const t of tracks) if (t !== track && t.kind !== "metadata") t.mode = "disabled";
    if (!track) return setLines([]);
    track.mode = native ? "showing" : "hidden";
    const onChange = () => setLines(Array.from(track.activeCues ?? [], (c) => (c as VTTCue).text));
    track.addEventListener("cuechange", onChange);
    onChange();
    return () => track.removeEventListener("cuechange", onChange);
  }, [video, lang, native]);
  return native ? [] : lines;
}

Caption styling that users control

A good checklist comes from the US FCC rules for devices and software that play TV programming (47 CFR 79.103). They list what viewers must be able to change: font, text size, text color and opacity, background color and opacity, edge style (uniform outline, drop shadow, raised, depressed), and the color of the caption window behind the text. Even where those rules don't apply, they are what viewers expect.

The caption settings menu offers exactly those, stored per user and applied as CSS custom properties on the overlay. Defaults: white text on a black background at 75% opacity, about 4.5% of the player height so it scales with the player and grows in fullscreen. Offer sizes from 50% to 200%. The visual-accessibility lesson covers contrast rules.

Audio descriptions

Audio description narrates what's on screen (a diagram appears, the instructor points at line 12) in the gaps between speech. The cleanest delivery is a second audio rendition in the stream: the HLS manifest lists an English audio track and an English described audio track, and the player's audio menu switches between them without reloading.

A text track with kind=descriptions read aloud by a screen reader is an alternative for small libraries, but browsers don't voice it on their own, so the player would announce each cue in a live region. For short marketing clips, a separate described version of the video is often simplest.

Adaptive streaming behind one source API

A plain MP4 is one file at one quality. On a train, a 1080p file stalls; on fiber, a 480p file looks soft. Adaptive streaming fixes this: the server encodes the video at several qualities (a ladder, for example 240p to 1080p), cuts each into segments of 2 to 6 seconds, and lists them in a manifest (.m3u8 for HLS, .mpd for DASH).

The player picks a quality for each segment based on measured bandwidth and how much is buffered. This is adaptive bitrate (ABR) streaming. The YouTube guide covers the ladder, codecs, and the ABR algorithms in depth; here we care about how the component plays these streams in every browser.

Browsers don't read manifests themselves, except Safari, which plays HLS natively. Everywhere else, a JavaScript engine (hls.js, Shaka Player, or dash.js) downloads the manifest and segments and appends the bytes to the video through Media Source Extensions (MSE): a MediaSource object becomes the video's source, and SourceBuffers accept chunks of media.

On iPhone, plain MSE is not available. Since iOS 17.1, Safari offers ManagedMediaSource, a variant where the browser may evict buffered data to save memory and power, and hls.js supports it. It only opens when the video sets disableRemotePlayback or also lists an HLS source that AirPlay can use instead.

async function attachSource(video: HTMLVideoElement, src: { url: string; type: string }) {
  const isHls = src.type === "application/vnd.apple.mpegurl" || src.url.endsWith(".m3u8");
  if (!isHls) { video.src = src.url; return () => video.removeAttribute("src"); }
  const nativeHls = video.canPlayType("application/vnd.apple.mpegurl") !== "";
  const hasMse = "MediaSource" in window || "ManagedMediaSource" in window;
  if (nativeHls && isAppleWebKit()) { video.src = src.url; return () => video.removeAttribute("src"); }
  if (!hasMse) throw new PlayerError("SRC_NOT_SUPPORTED");
  const { default: Hls } = await import("hls.js"); // loaded only now
  const hls = new Hls({ capLevelToPlayerSize: true, startLevel: -1 });
  hls.loadSource(src.url);
  hls.attachMedia(video);
  return () => hls.destroy();
}

The quality menu

The menu lists Auto plus each level from the manifest (1080p, 720p, 480p, 360p). In Auto, show the level currently playing next to it, like Auto (720p), so a viewer can tell why it looks soft.

Picking a fixed level in hls.js has two flavors. Setting currentLevel switches at once by flushing the buffer (a short stall, a sharp picture now). Setting nextLevel switches from the next segment on without interrupting playback (no stall, a few seconds of the old quality). Use nextLevel for upgrades and currentLevel only when the user picks a lower level to stop stalls.

capLevelToPlayerSize keeps a 400 pixel wide embed from downloading 1080p. Remember the choice for the session only: a fixed quality saved forever turns into stalls on the next weak network.

Fullscreen, picture-in-picture, and phones

Fullscreen looks like one method call. The trap is which element you call it on. Call requestFullscreen() on the video, and the browser shows the video alone with its own native controls: our control bar, captions overlay, settings menu, and thumbnails stay behind on the page, invisible. Call it on the player's container, and everything we built comes along, scaled to the screen.

In fullscreen, a few things change. Controls hide with the same inactivity rules but the cursor hides too. Captions grow because they're sized relative to the player. And on phones, lock to landscape where allowed with screen.orientation.lock('landscape'), which only works in fullscreen and only on some Android browsers, so treat failure as normal.

Picture-in-picture

Video picture-in-picture moves the video into a small always-on-top window so a learner can follow along in their code editor. video.requestPictureInPicture() works in Chromium browsers, Safari (including iPhone), and desktop Firefox since version 153 (mid 2026). Firefox on Android has no API, and older Firefox versions only offer their own PiP toggle on videos, so hide our button unless document.pictureInPictureEnabled is true. The window shows only the video, with the browser's own small controls.

Wire the Media Session API (navigator.mediaSession with metadata and action handlers for play, pause, seek back, seek forward) so those controls, the lock screen, and hardware media keys all drive our player.

Document Picture-in-Picture goes further: documentPictureInPicture.requestWindow() opens an always-on-top window that holds any HTML, so we can move the whole player, custom controls and captions included, into it and back. It's available on desktop in Chrome and Edge since version 116 and in Firefox since version 151 (2026), but not in Safari or on mobile. Treat it as an upgrade: if present, use it for the PiP button; if not, fall back to video PiP.

Phones: touch, gestures, and playsinline

• No hover. Tapping the video shows the controls; tapping again hides them. It does not toggle play, because a tap that was meant to reveal controls must not pause the lesson. The center play button pauses.
• Double tap to seek. Double tap the left third to go back 10 seconds and the right third to go forward, with a ripple and a -10 or +10 label. Wait about 300 ms after the first tap to know whether a second one comes, which is why the single-tap reaction is slightly delayed on touch only.
• Big targets. At least 44 by 44 CSS pixels per control; a thicker seek bar while dragging; the hover preview appears above the finger during a drag, not under it.
• playsinline. Without the playsinline attribute, iPhone Safari can force the video into native fullscreen when it plays. With it, the video plays inside the page and our controls stay in charge.
• Data and battery. Default to preload=none on cellular for long videos, and cap quality to the player's size.

Architecture: the pieces and where the boundaries go

We now know the features. The architecture question is how to split them so that a team can theme the controls without touching streaming, swap hls.js for Shaka without touching the controls, and test the state machine without a browser. The split follows one rule: the media element is the source of truth, a controller turns its events into state, and everything else either reads that state or sends commands.

How data moves

Follow one lesson from page load to the first progress save. The page renders the poster and a play button from server HTML. On play, the source loader fetches the manifest from the CDN, the engine fetches segments and appends them through MSE, and the video fires events that the controller reduces into state. Controls render from state.

Meanwhile, side channels run: captions and thumbnails come from the CDN as VTT and images, the progress service saves the position with a PUT every 10 seconds, and analytics batch QoE events to a collector.

Two boundaries deserve a defense in the interview. First, why a separate source loader? Because the engine is the part most likely to change: today hls.js, tomorrow Shaka for DASH and Widevine, and native HLS on Apple. If the controls ever import hls.js types, swapping engines means touching every control.

Second, why commands instead of letting controls touch the element? Because a command can be validated, logged, and measured in one place. A seek that came from the keyboard, a plugin, or a drag goes through the same seek(t), so analytics can tell user seeks from programmatic ones and the state machine sees every one.

The controller has no React in it. It's a plain class that takes a video element, attaches listeners, and exposes subscribe, getState, and commands. The React components are a thin layer on top. That makes the same core usable from a web component build for teams on other frameworks, and lets the reducer and controller be tested in Node with a fake element that fires scripted events, which is exactly how the state lab in chapter 4 works.

Data model and the component API

The architecture chapter named the parts; this one pins down the data each part holds and the API teams see. The player holds little data, but it lives in five different places, and putting each piece in the right one prevents a class of bugs.

Media facts live in the element and are mirrored into the store. Preferences live in localStorage, watch progress on the server (learners switch devices), and thumbnail cues in an in-memory cache keyed by URL. Nothing about playback goes in the URL except an optional start time like ?t=95, for sharing a moment.

type PlayerState = {
  status: Status;                 // the state machine
  resume: boolean;                // resume after seek
  time: number; duration: number; // seconds; duration NaN until metadata
  buffered: [start: number, end: number][];
  volume: number; muted: boolean; rate: number;
  levels: { id: number; height: number; bitrate: number }[];
  level: number | "auto"; playingLevel: number | null;
  textTracks: { id: string; lang: string; label: string; kind: "captions" | "subtitles" }[];
  captionLang: string | null;
  fullscreen: boolean; pip: boolean;
  error: PlayerError | null;      // { code, message, retryable }
};

type Preferences = {              // localStorage "player:prefs"
  volume: number; muted: boolean; rate: number;
  captionLang: string | null;
  captionStyle: {
    font: string; size: number; color: string; opacity: number;
    bg: string; bgOpacity: number; window: string;
    edge: "none" | "uniform" | "shadow" | "raised" | "depressed";
  };
};

type Progress = { videoId: string; position: number; duration: number; completed: boolean; updatedAt: string };

The component API

<VideoPlayer
  ref={playerRef}                          // play(), pause(), seek(t), setRate(r), enterFullscreen()
  sources={[
    { url: "https://cdn.example.com/l42/master.m3u8", type: "application/vnd.apple.mpegurl" },
    { url: "https://cdn.example.com/l42/720p.mp4", type: "video/mp4" },
  ]}
  poster="https://cdn.example.com/l42/poster.avif"
  tracks={[{ src: "/l42/en.vtt", kind: "captions", lang: "en", label: "English", default: true }]}
  thumbnails="/l42/thumbs.vtt"
  chapters="/l42/chapters.vtt"
  title="Lesson 42: Closures"             // names the player region for screen readers
  startTime={progress?.position}
  preload="metadata"
  shortcuts="focus"                        // or "page" on the main watch page
  plugins={[analyticsPlugin({ videoId: "l42" }), skipIntroPlugin()]}
  onEnded={() => router.push(nextLessonUrl)}
  onError={(e) => log(e.code)}
/>

Events mirror the state machine, not raw media events. Teams get onPlay, onPause, onEnded, onSeek (with from and to times), onTimeUpdate (throttled to once a second, which is all a progress bar outside the player needs), onQualityChange, onCaptionChange, onFullscreenChange, and onError with our own error codes. Raw waiting and stalled are hidden behind onBufferingChange, so a consumer never has to rebuild the machine to know whether the user is staring at a spinner. Each event carries the player id, because pages with two players otherwise mix them up in logs.

Plugins get the store (read state, subscribe) and the command API, plus named slots to render into: controlBarEnd, overlay, settingsMenu. Analytics, skip intro, chapter markers, and later ads are all plugins, so the core stays small. Theming is CSS custom properties (--player-accent, --player-radius, --player-font) and slot replacement for teams that need a different button; never a prop per color. Progress uses two small endpoints.

GET /api/progress/l42
200 { "position": 95.2, "duration": 734, "completed": false, "updatedAt": "2026-03-02T10:04:11Z" }

PUT /api/progress/l42
{ "position": 105.4, "duration": 734, "updatedAt": "2026-03-02T10:04:21Z" }
204 No Content

Resume position, quality metrics, and recovering from errors

Three features decide whether the player is trusted in production: it remembers where you were, it tells the team when viewers suffer, and it recovers from failures instead of showing a black box. All three hang off the state machine, which is the payoff for building it.

Saving and restoring watch position

Saving on every timeupdate would send 4 or more requests a second. Save instead every 10 seconds while playing, and right away on pause, on seeked, on ended (marking the lesson complete), and when the page is hidden (visibilitychange to hidden, or pagehide). For that last save, use fetch with keepalive: true, which survives the tab closing and still allows the PUT; navigator.sendBeacon also survives but can only POST.

Also write the position to localStorage, so a reload offline still resumes. On restore, wait for loadedmetadata, then seek to the saved position if it's more than 5 seconds in and more than 10 seconds before the end; otherwise start at 0. Show a small Resumed from 1:35, Start over chip for a few seconds, because jumping without telling people feels like a bug.

Two edge cases show up in production. A learner with the same lesson open in two tabs writes two positions; the server keeps the write with the newest updatedAt, so whichever tab played last wins and an idle tab can't move them backwards. A learner who finished a lesson and opens it again should start at 0, not 10 seconds before the end, so restore skips positions marked completed.

Mark a lesson complete at 90% watched or on ended, whichever comes first, because many people close the tab during the credits.

Quality of experience metrics

Video teams track a short list of metrics that predict whether people keep watching. Each is measured from state machine transitions, which is why the controller, not the UI, is where analytics plug in.

Batch events in memory and send them every 30 seconds and on pagehide with sendBeacon. Tag each with a session id, video id, player version, browser, and the streaming path (native or hls.js), because the first question after a spike is always which browser. The analytics-tracking lesson covers batching and delivery in depth.

Errors and recovery

When the element fails, video.error.code says why: 1 MEDIA_ERR_ABORTED (the user or code stopped loading), 2 MEDIA_ERR_NETWORK, 3 MEDIA_ERR_DECODE, 4 MEDIA_ERR_SRC_NOT_SUPPORTED. Engines report richer errors (hls.js marks each as network or media, fatal or not). The source loader maps both into our own PlayerError with a code, a retryable flag, and a message for people.

Retries need limits and spacing. Wait 1, 2, then 4 seconds with a little random jitter, so ten thousand viewers of a popular lesson don't hit the CDN in lockstep after a blip. Keep showing the spinner while retrying, and switch to the error overlay only after the last attempt, with a Retry button that restarts at the current time. Log every retry, even successful ones: a rise in retries is the early warning before failures climb.

Performance and accessibility, end to end

A player is often the largest thing on the page, so it can ruin Largest Contentful Paint (LCP) and steal bandwidth from everything else. On a course page with a player above the fold, the poster is usually the LCP element. On a marketing page with five video cards, eager players would download five manifests and start five decoders before the user picks one.

Runtime cost matters too. Keep timeupdate work tiny, move the played bar with a CSS transform from a requestAnimationFrame loop that stops when paused or off screen, and pause offscreen autoplaying previews with IntersectionObserver to free the decoder. Destroy the engine and remove the src when the player unmounts, or phones leak decoders and memory across route changes.

Accessibility checklist, with the reasons

• A named region. The container has role=region and aria-label like Video player: Lesson 42, so screen reader users can jump to it.
• Buttons with state. Either the label changes (Play becomes Pause, Mute becomes Unmute) or the label stays and aria-pressed changes (Captions, pressed). Never both, or it reads Pause, pressed.
• Sliders that speak time. Seek and volume follow the slider pattern with aria-valuetext in words.
• Menus that behave like menus. The settings menu follows the menu button pattern with menuitemradio and returns focus on close.
• Visible focus on video. A focus ring that shows on both bright and dark frames: a two-color outline, plus a gradient scrim behind the control bar for icon contrast of at least 3 to 1.
• Announcements, not noise. One polite live region for shortcut results and errors. Don't announce every time update.
• Captions on by default for users who chose them once, with the styling menu from the captions chapter.
• Reduced motion. With prefers-reduced-motion, skip the double-tap ripple and bubble animations, and never autoplay with motion for those users.
• Autoplay with a way out. Video that starts by itself and runs more than 5 seconds needs a visible way to pause it (WCAG 2.2.2), and sound that starts by itself for more than 3 seconds needs pause or its own volume control (WCAG 1.4.2). Autoplaying previews start muted and keep the pause button reachable.
• No traps. Tab moves through controls in visual order and out of the player; fullscreen can be left with Escape and with a button.

Running it in the interview

A video player question rewards depth over breadth. Interviewers have heard the list of controls many times; what they listen for is whether you know the media element reports truth through events, whether you'd build a state machine, and whether keyboard and screen reader users are in your design from the first minute rather than at the end. Here's a 45 minute plan.

Draw the state machine early. It's the single diagram that shows senior thinking here, and every later topic (spinner timing, analytics, resume, errors) refers back to it. When you mention a browser difference, name the browser and the API: iPhone Safari and webkitEnterFullscreen, Firefox on Android and its missing picture-in-picture API. Specifics beat it depends.