Skip to content
Katabench
Try free
9 min read The Katabench team

Design a video streaming platform: upload to edge

Design a video streaming platform around one split: at an assumed 200,000 viewers, the playback API moves 333 KB/s while the media path moves 600 Gbit/s.

A 5 Mbit/s file on a 3 Mbit/s connection takes 5/3, about 1.67 seconds, to download each second of video, so the player falls further behind the longer it plays. No amount of server work repairs that. The viewer needs a smaller version of the video, and needs the switch to happen mid-stream without a restart.

Everything distinctive about a video platform follows from that requirement. You encode each video several times, cut every encoding into short files, let the player choose between them on each request, and serve those files from caches near the viewer. The application servers end up handling almost none of the traffic, and the design goal is to keep it that way.

The number that shapes the architecture

These figures are assumptions for a mid-sized platform, not measurements of any real service. Swap in your own and redo the arithmetic, the way back-of-the-envelope estimation describes.

Text
Assume: 200,000 concurrent viewers at peak, 3 Mbit/s average, 6 s segments,
        20 minute average session, 2 KB playback API response,
        1,000 hours of new source video per day, 95% edge hit rate

bandwidth:      200,000 x 3 Mbit/s            = 600 Gbit/s
segment reads:  200,000 / 6 s                 = 33,333 requests/s
session starts: 200,000 / (20 x 60 s)         = 167 requests/s
API bandwidth:  167 x 2 KB                    = 333 KB/s
origin load:    600 Gbit/s x 5% miss          = 30 Gbit/s
origin reads:   33,333 x 5% miss              = 1,667 requests/s

The playback API serves 167 small responses a second. The media path moves 600 Gbit/s. Those two workloads differ by more than five orders of magnitude in bandwidth, and they want different hardware, different scaling and different failure handling, so they should not share a path.

Two workloads behind one play button

The decision

May this viewer watch this title? The answer differs per viewer and is small.

Requests
167/s
Bandwidth
333 KB/s

The bytes

The same immutable segments for everyone, and very many of them.

Requests
33,333/s
Bandwidth
600 Gbit/s

The design that fails: one service doing both

Servers sized for 167 small requests a second would also have to push 600 Gbit/s.

Numbers follow from the article's assumptions, which you should replace with your own.

Upload: accept quickly, encode durably

A two-hour source file takes far longer to transfer than a request worker should be tied up, and the encoding that follows takes longer still. Two requirements shape this part of the design: accepting an upload stays quick and authorized, and the expensive work survives retries and bursts. A creator uploading fifty videos should make a backlog longer without making the upload path slower, which is the property load leveling describes. How you arrange the parts is the design exercise, and design a file storage service covers the byte-handling side for a different product.

Assume a worker encodes all rungs of a video at real-time speed. Then 1,000 hours a day needs 1,000 / 24, about 42 workers on average, and 125 if uploads peak at three times the mean. Splitting long sources into chunks at keyframes lets several workers share one video, and a crash then costs one chunk instead of the whole encode.

Background work tends to get delivered more than once, so finishing a rung has to be safe to repeat, and the video becomes watchable only when every rung exists. On PostgreSQL 17:

SQL
CREATE TABLE videos (
    id     bigint PRIMARY KEY,
    status text NOT NULL CHECK (status IN ('uploading', 'processing', 'ready', 'failed'))
);

CREATE TABLE renditions (
    video_id bigint NOT NULL REFERENCES videos,
    rung     text NOT NULL,
    status   text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'done')),
    PRIMARY KEY (video_id, rung)
);

-- A worker finishes a rung. A redelivered job matches 0 rows.
UPDATE renditions SET status = 'done'
 WHERE video_id = 7 AND rung = '720p' AND status = 'pending';

-- Run after each rung commits. Matches only once every rung is done.
UPDATE videos v SET status = 'ready'
 WHERE v.id = 7 AND v.status = 'processing'
   AND NOT EXISTS (SELECT 1 FROM renditions r
                    WHERE r.video_id = v.id AND r.status <> 'done');

With two rungs, the sequence returned UPDATE 1, then UPDATE 0 for the publish attempt while 360p was still pending, UPDATE 0 for a redelivered 720p job, and UPDATE 1 twice once 360p finished. Workers should write output under a job-specific prefix and record the final location in that same update, so a half-written rung is never what a player finds.

Keep the source. If sources arrive at an assumed 20 Mbit/s, each hour costs 20 x 3,600 / 8 = 9 GB, more than the whole ladder below, and it is the only way to re-encode when a better codec or ladder comes along.

The ladder and why keyframes have to line up

A ladder is a set of encodings of the same video. Apple's HLS authoring specification publishes a nine-rung example from 145 kbit/s to 7,800 kbit/s and calls those figures initial targets to evaluate against your own content. Here is a smaller five-rung ladder, run with FFmpeg on a 60-second synthetic test pattern:

Bash
ffmpeg -f lavfi -i testsrc2=size=1920x1080:rate=30:duration=60 \
  -filter_complex "[0:v]split=5[a][b][c][d][e];[a]scale=-2:240[v0];[b]scale=-2:360[v1];[c]scale=-2:480[v2];[d]scale=-2:720[v3];[e]scale=-2:1080[v4]" \
  -map "[v0]" -map "[v1]" -map "[v2]" -map "[v3]" -map "[v4]" \
  -c:v libx264 -preset veryfast -pix_fmt yuv420p \
  -g 60 -keyint_min 60 -sc_threshold 0 \
  -b:v:0 400k -b:v:1 800k -b:v:2 1400k -b:v:3 2800k -b:v:4 5000k \
  -f hls -hls_time 6 -hls_playlist_type vod \
  -hls_segment_filename "v%v/seg_%03d.ts" \
  -master_pl_name master.m3u8 -var_stream_map "v:0 v:1 v:2 v:3 v:4" "v%v/index.m3u8"

(The run also set -maxrate and -bufsize per rung to cap peaks at 10% above target.) It produced a master playlist that is the whole interface between server and player, trimmed here to three of its five variants:

Text
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=453456,AVERAGE-BANDWIDTH=443028,RESOLUTION=426x240,CODECS="avc1.640015"
v0/index.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=2929792,AVERAGE-BANDWIDTH=2870509,RESOLUTION=1280x720,CODECS="avc1.64001f"
v3/index.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=5242944,AVERAGE-BANDWIDTH=4986035,RESOLUTION=1920x1080,CODECS="avc1.640028"
v4/index.m3u8

A player on a slow connection reads this list, measures its own throughput, and requests v0 or v3 accordingly. The server never decides. It serves plain files over HTTP, which is why any cache can hold them. RFC 8216 defines the format and requires that "Matching content in Variant Streams MUST have matching timestamps". Encoding every rung from one source gives you that. The three keyframe flags add aligned keyframes on top, so each segment starts decodable. -g 60 fixes a keyframe every two seconds at 30 fps, matching Apple's guidance, and -sc_threshold 0 stops the encoder adding extra ones at scene cuts. ffprobe shows segment 5 starting on a keyframe at 31.466667 s on all five rungs, so a player can switch at any segment boundary without a visual jump.

The output also checks the storage arithmetic. The rungs sum to 10.4 Mbit/s, which predicts 10.4 x 60 / 8 = 78 MB per minute, and the five folders held about 77,869 KB. That is 4.68 GB per hour of source, or 4.68 TB of renditions a day at 1,000 hours. Adding the 9 TB of sources gives 13.68 TB a day, about 5 PB a year.

Segment length is a real trade. Apple's specification says target durations should be 6 seconds. Shorter segments let the player react faster, but 2-second segments triple the example above to 100,000 requests a second.

Edge delivery: one decision, many identical files

Whether this person may watch this title depends on the viewer, the plan and the region, and the answer is small. The segment they then receive is the same bytes for everyone and never changes. A cache can serve the second kind of request as long as it never has to ask anyone about the first.

Under these assumptions the playback API moves 333 KB/s and the media path 600 Gbit/s, a ratio of about 225,000 to 1.

Signing every segment URL does not scale well, since a two-hour film at 6 seconds is 1,200 requests. AWS's CloudFront documentation recommends signed cookies for exactly this case, naming "all of the files for a video in HLS format" as its example. Other CDNs have an equivalent, such as a token scoped to a path prefix. Either way the edge verifies the credential by itself, with no call home.

Segments are immutable once published, so give them long cache lifetimes with immutable and a new path for any re-encode. CDN edge caching covers the header contract and the origin shield, which earns its place here. A popular release misses at every edge location at the same moment, and a shield turns those misses into a small number of origin reads per segment. Hit rate is not uniform across a catalog either. A 95% average usually means popular titles near 100% and a long tail far below it, so plan origin capacity for the tail as well.

Catalog and search stay small and boring

Titles, descriptions, thumbnails and per-rung locations fit in an ordinary relational database, cached heavily, because watch pages read the same rows over and over and edits are rare. Search is a derived index. Feed it from the catalog through change data capture and index only rows in ready, so a result never leads to a video that cannot play yet.

Takedowns are the case that crosses both paths. Removing a video has to update the catalog, drop it from the index, stop issuing credentials and purge the edge, and already-issued credentials stay valid until they expire. That delay is the reason for keeping their lifetimes short.

View counts should follow the same rule as analytics in any read-heavy system: player beacons go onto a queue and get aggregated later, never written during playback.

Drawing the two paths apart

Live streaming and DRM each add layers on top, and neither changes that ratio. Two challenges in the System Design Studio start from the failures behind it: long uploads occupying request workers for minutes, and one popular release overwhelming a service that sends every video through its own API. Arranging the components is left to you, and how it works explains what the checks report.

Practice System Design

More like this: System Design Studio →

Get new katas and .NET tips in your inbox

A short note when fresh kata land, plus the C# and performance tricks behind the grading. No spam, unsubscribe anytime.