An M3U8 tester checks that an HLS playlist loads and plays. This one goes further: it reads the master and media playlists, downloads at most 256 KB of the first segment to see which tracks really exist, tests the AES-128 key, detects DRM, live and on-demand streams, and prints the ffmpeg command that keeps picture and sound together.
What the tester checks
A player only tells you whether the video starts. The tester also reads what the player keeps to itself, from the playlists and from the first bytes of a real segment:
| Check | What you learn |
|---|---|
| Master or media playlist | Whether you have the playlist with every quality, or one variant copied from DevTools |
| Variants | Resolution, bitrate, codecs and frame rate of each quality, and the one a download would use |
| Separate audio | An audio track declared with EXT-X-MEDIA:TYPE=AUDIO and its own URI: the most common cause of silent downloads |
| Real tracks | Video only, audio only or both, read from the MPEG-TS program table, the fragmented MP4 init segment or raw AAC, MP3 and AC-3 |
| Encryption | None, AES-128 (the key URL is fetched and must return 16 bytes), SAMPLE-AES, or DRM |
| DRM | Widevine, PlayReady and FairPlay keys in the playlist, and CENC-encrypted init segments |
| Live or on-demand | Total duration and segment count, Low-Latency HLS, playlists still growing |
| Server answers | HTTP 403, 404 or 410, a web page returned instead of a playlist, a DASH manifest, an expired signed URL |
| Oddities | Byte ranges, discontinuities from inserted ads, segments disguised as .jpg or .png |
What the stats mean
When the preview plays, the Live stats panel under the player refreshes every second and pauses with the video. The Quality list lets you leave the choice to hls.js (Auto) or lock one variant, and the variant playing is highlighted in the Variants table.
| Stat | What it tells you |
|---|---|
| Resolution (real) | The size of the picture the browser actually decodes. If it differs from the variant's declared RESOLUTION, the playlist describes its qualities wrongly. |
| Quality playing and declared bitrate | The variant hls.js plays, whether Auto chose it or you fixed it, and the BANDWIDTH the master playlist declares for it. |
| Bandwidth estimate | The download speed hls.js measures on the last segments. Auto picks the best variant whose bitrate fits under it. An estimate below the declared bitrate means stalls are coming. |
| Buffer ahead | Seconds already downloaded past the playhead. On-demand streams usually build up to about 30 seconds; live streams keep only a few seconds because the edge is close. A buffer that keeps falling to zero is a stall. |
| Dropped / decoded | Frames the browser had to skip because it could not decode or draw them in time. More than about 1% means the device struggles with this quality or codec, not the network. |
| Segments loaded and last segment | How many segments came in, how long the last one took and its size. A load time close to the segment duration means the connection barely keeps up. |
| Stream type | VOD (the playlist ends with EXT-X-ENDLIST), live (a sliding window) or event (a live playlist that keeps every segment). |
| Live latency and latency vs target | For a live stream: how far the playhead is behind the live edge, and how far that is from the latency hls.js aims for, which comes from the segment duration or the playlist's hold-back values. |
The two graphs show the buffer and the bandwidth estimate over the last 60 seconds of playback. Under the diagnosis, the Player events log lists what the player did (playlist parsed, quality switches, first segment) and turns every hls.js error into a probable cause and a next step. Tick Errors and warnings only to hide the rest, or copy the log to paste it in a bug report.
Why won't my M3U8 stream play?
Six causes cover almost every failure. Each one leaves a trace in the event log or in the diagnosis:
- The server only accepts its own player (CORS). The log says the browser could not read the playlist or the segments "(CORS or network)", and a yellow box offers the alternatives. When the playlist loads but the segments fail, the segment server is the one refusing. The stream may be fine: test it with
npx m3u8-doctorin a terminal, where CORS does not apply. - The link expired or needs the site's cookies or Referer (HTTP 403). Signed URLs carry a token and an expiry time. The log shows "Access refused to the playlist (HTTP 403)", or to a segment or the key, and the diagnosis says when a signed URL looks expired. Copy a fresh URL and test it right away.
- A playlist or a segment is gone (HTTP 404 or 410). The content was removed, the token expired, or on a live stream a segment already slid out of the window.
- The URL is not an HLS playlist. hls.js reports
manifestParsingErrorwhen the answer does not start with#EXTM3U: a login page, the video page itself, or a DASH manifest. The diagnosis says what the server returned. To find the right address, filter the Network tab of DevTools onm3u8, or drop a HAR file into the M3U8 sniffer, which lists every playlist the page loaded. - The browser cannot decode the codec. HEVC (H.265) plays only where the browser and the hardware decode it, and Dolby audio (AC-3, E-AC-3) is refused by most desktop browsers. The log says the codecs are not supported; the Codecs column of the Variants table shows which variant uses what. ffmpeg still copies such a stream without decoding it.
- The stream is encrypted in a way the page cannot open. DRM (Widevine, PlayReady, FairPlay) never plays outside the site's own player, and the diagnosis names the system. With AES-128, a key URL that answers 403 gives
keyLoadError: the key server wants the site's cookies or token.
A stream that plays but keeps pausing is a different problem: the log shows bufferStalledError and the buffer graph drops to zero. Compare the bandwidth estimate with the declared bitrate, then lock a lower quality in the Quality list.
Why a stream plays but downloads without sound
Adaptive streams often keep the audio apart from the picture. The master playlist lists the qualities on #EXT-X-STREAM-INF lines and points each of them to an audio group. When that group has its own URI, the video playlist carries pictures only, and the player quietly loads two playlists at once.
Copy only the video URL into ffmpeg and you get a silent file. The fix is two inputs mapped together:
ffmpeg -i "video.m3u8" -i "audio.m3u8" -map 0:v:0 -map 1:a:0 -c copy out.mp4
The tester finds both URLs and prints that command for you. When you paste a single variant, it reads the first segment: if there is no audio track inside, it says so and tells you to go back to the master playlist. Other causes of silent files, such as a muted preview or an audio codec the container cannot hold, are covered in the guide to videos downloaded without sound.
Reading the result
- Green check: confirmed, nothing to do. For example "Picture and sound found (H.264 + AAC)".
- Blue i: useful context, such as byte-range segments or a browser User-Agent being required.
- Yellow !: a download would work but needs care: separate audio, discontinuities, a signed URL close to expiry.
- Red ✗: blocking. A silent variant, a forbidden playlist or key, DRM. No command is printed for DRM content.
AES-128 is not DRM
AES-128 is the standard encryption of HLS. The playlist names a key URL, and any player allowed to fetch that key can decrypt the segments, ffmpeg included. The tester fetches the key, checks that it is 16 bytes long, and decrypts the start of the first segment to read its tracks. If the key returns 403, the site wants a cookie, a token or a Referer that the request did not carry. The encrypted M3U8 guide walks through those cases.
Widevine, PlayReady and FairPlay are DRM: the key never leaves a licensed decryption module. The tester names the system and stops there.
Testing a live stream
A playlist without #EXT-X-ENDLIST is live. The preview starts near the live edge, and the printed command records from now until you press q, into a .ts file that stays playable even if the recording is cut. A sliding live playlist cannot give back what aired before you started. Once you stop, you can convert the TS recording to MP4 without re-encoding.
Use it from the command line
The engine of this page is open source: m3u8-doctor on GitHub, MIT licensed, with no dependencies. In a terminal it is not limited by CORS and it can send the headers a site expects:
npx m3u8-doctor "https://cdn.example.com/hls/index.m3u8" --referer "https://example.com/watch/42"
It prints the same diagnosis, quotes the command for bash, zsh or PowerShell, and has a --json mode for scripts. To save the stream without a terminal, the online M3U8 to MP4 converter remuxes it in your browser when its server allows it, and the M3U8 to MP4 guide compares ffmpeg with the other methods.
Limits worth knowing
- A web page can only read streams whose server allows it (CORS). Many video sites allow only their own player: the tester then says it could not read the stream, which says nothing about the stream itself.
- Browsers do not let a page set the Referer, cookies or User-Agent of its requests. Sites that check them work from the command line or from the page where the video plays.
- The tester reads at most 256 KB of the first segment (or an init segment of up to 2 MB) per playlist. It never downloads the whole video.
- Where the browser plays HLS by itself instead of through hls.js (older iPhones), the quality list, the bandwidth estimate and the latency are not available; the picture size, the buffer and the frame counters still are.
- DASH manifests (
.mpd) are recognized and sent to the DASH MPD analyzer.