Understand M3U8 playlists before debugging HLS playback

Know which playlist you opened

An HLS master playlist lists variant streams and optional renditions such as alternate audio. A media playlist lists the segments for one stream. Both commonly use the m3u8 extension, so inspect the tags before assuming what the URL represents.

Adaptive playback requires multiple encoded renditions and a master playlist that describes their bandwidth and codecs. A single media playlist can play successfully but cannot switch quality levels by itself.

Debug in dependency order

Start with the playlist response, then follow the exact segment URLs it contains. Relative paths resolve against the playlist URL, and every playlist, key and segment must be reachable by the browser under the required cross-origin policy.

• Confirm an HTTP 200 response
• Use the expected HLS MIME type
• Check CORS on playlists, keys and segments
• Verify that the browser supports the encoded audio and video codecs

Native and scripted playback differ

Safari commonly plays HLS through native media support. Other modern browsers generally use Media Source Extensions through a JavaScript HLS engine. The two paths can expose different error messages and codec limits, so test both when broad compatibility matters.

Use browser conversion for prototypes

A browser-based FFmpeg workflow is useful for short local tests and for learning package structure. Long videos, adaptive ladders, encryption and production-scale throughput belong in a native encoding pipeline with measured bitrate, keyframe and segment settings.

Upload the playlist and every segment together, preserve their relative paths and test through HTTPS from the same kind of origin policy used in production.

Recognize a minimal media playlist

This teaching fixture describes two six-second MPEG-TS segments and marks the presentation complete. It is a media playlist, not an adaptive master playlist. It will play only if real, compatible segment files are served at the listed paths; the text below is not a bundled video or a claim of measured playback.

A segment path is relative to the playlist location. If playlist.m3u8 lives at /video/demo/, segment-000.ts must resolve under that directory unless the playlist provides a different path. Copying only the playlist without its segments produces a valid-looking text file with unavailable media dependencies.

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:6.000,
segment-000.ts
#EXTINF:6.000,
segment-001.ts
#EXT-X-ENDLIST

Follow the first failed dependency

Use the browser's Network panel to inspect the playlist, then the first failed segment or key request. Check response status, the resolved URL and cross-origin headers on that dependency. A successful playlist response does not prove that the later media requests or encoded codecs are usable.

Video to M3U8 creates a ZIP containing a single media playlist and segments. It does not create a multi-bitrate ladder. Extract the package together, serve it over HTTPS and test the same origin and cross-origin paths visitors will use. Use only media you own or are authorized to distribute; the player does not grant rights to a third-party stream.

• Keep the playlist and segment paths together
• Inspect CORS on every requested dependency
• Check the actual audio and video codecs
• Use a native encoding pipeline for production ladders