System Design #13: Design a Video Player

Hey folks, Rahul here 👋

YouTube, Netflix, Disney+ — video players look like a solved problem until you try building one. Custom controls, adaptive bitrate streaming, buffering strategies, Picture-in-Picture, keyboard shortcuts, and accessibility for deaf/blind users. The <video> tag gets you 10% of the way there.

R — Requirements

Functional Requirements

Play/pause, seek, volume, fullscreen controls
Adaptive Bitrate Streaming (ABR) — auto quality switching
Manual quality selection (1080p, 720p, 480p, auto)
Captions/subtitles with multiple tracks
Playback speed control (0.5x – 2x)
Picture-in-Picture (PiP) mode
Keyboard shortcuts (Space, F, M, ←/→, ↑/↓)
Thumbnail preview on seek bar hover
Resume from last position ("Continue watching")

Non-Functional Requirements

Startup time: First frame within 2 seconds
Buffering: Minimize rebuffering events to <1% of playback time
Accessibility: Full keyboard control + screen reader announcements
Mobile: Touch gestures (double-tap seek, swipe volume)
Analytics: Buffer ratio, quality switches, engagement heatmap

A — Architecture

Streaming Protocols

Protocol	How It Works	Use When
HLS (HTTP Live Streaming)	Video split into .ts segments + .m3u8 manifest	Default choice. Safari native, rest via hls.js
DASH (MPEG-DASH)	Similar segmented approach + .mpd manifest	DRM required (Widevine), more flexible
Progressive MP4	Single file, byte-range requests	Short videos (<5min), simple hosting

Recommendation: HLS with hls.js. It covers 99% of use cases, works everywhere, and has excellent adaptive bitrate support.

Component Architecture

HLS.js Integration

D — Data Model

Player State

I — Interface Definition

Progress Bar with Buffer Visualization

Keyboard Shortcuts

O — Optimizations

1. Controls Auto-Hide

2. Thumbnail Sprite Sheet Preview

3. Resume Playback Position

4. Engagement Analytics

Production Gotchas Rahul Has Debugged 🔥

Autoplay Policies: Modern browsers block autoplay with sound. Always start muted for autoplay, then unmute on user interaction. Check video.play().catch() for the NotAllowedError.
iOS Fullscreen: iOS Safari forces native fullscreen controls for <video>. Add playsinline attribute to use custom controls inline. PiP also requires user gesture to activate.
requestAnimationFrame for Time Updates: Don't rely on the timeupdate event — it fires ~4x/second. Use requestAnimationFrame for smooth progress bar updates at 60fps.
Seek While Buffering: If the user seeks to an unbuffered position, HLS.js needs to flush the buffer and refetch. Show a loading spinner specifically for seek operations, not just for initial load.
Memory Leaks: HLS.js accumulates source buffers. Call hls.destroy() on unmount. Also revoke any URL.createObjectURL references used for blob sources.

Next: #14: Design an Image Carousel / Gallery — touch gestures, preloading strategies, virtualization for 1000+ images, and lightbox UX. 🖼️

import Hls from 'hls.js'; function useHlsPlayer(videoRef: RefObject<HTMLVideoElement>, src: string) { const hlsRef = useRef<Hls | null>(null); const [levels, setLevels] = useState<QualityLevel[]>([]); const [currentLevel, setCurrentLevel] = useState(-1); // -1 = auto useEffect(() => { const video = videoRef.current; if (!video) return; // Safari supports HLS natively if (video.canPlayType('application/vnd.apple.mpegurl')) { video.src = src; return; } if (!Hls.isSupported()) return; const hls = new Hls({ startLevel: -1, // Auto quality capLevelToPlayerSize: true, // Don't load 4K for a 360px player maxBufferLength: 30, // Buffer 30s ahead maxMaxBufferLength: 60, lowLatencyMode: false, // ABR tuning abrEwmaDefaultEstimate: 500000, // Initial bandwidth estimate (500kbps) abrBandWidthUpFactor: 0.7, // Conservative upswitch abrBandWidthFactor: 0.95, // Aggressive downswitch (avoid rebuffer) }); hls.loadSource(src); hls.attachMedia(video); hls.on(Hls.Events.MANIFEST_PARSED, (_, data) => { setLevels(data.levels.map((l, i) => ({ index: i, height: l.height, bitrate: l.bitrate, label: `${l.height}p`, }))); }); hls.on(Hls.Events.LEVEL_SWITCHED, (_, data) => { setCurrentLevel(data.level); }); hls.on(Hls.Events.ERROR, (_, data) => { if (data.fatal) { switch (data.type) { case Hls.ErrorTypes.NETWORK_ERROR: hls.startLoad(); // Retry break; case Hls.ErrorTypes.MEDIA_ERROR: hls.recoverMediaError(); break; default: hls.destroy(); break; } } }); hlsRef.current = hls; return () => hls.destroy(); }, [src]); const setQuality = (levelIndex: number) => { if (hlsRef.current) { hlsRef.current.currentLevel = levelIndex; // -1 for auto } }; return { levels, currentLevel, setQuality }; }