CH02 / Formats & streaming

HLS and .m3u8 files: how to download a stream properly

Last updated Editorial team Video Downloader Info10 segments~6 min

Key takeaways

  1. An .m3u8 file is not a video: it is a UTF-8 text playlist that lists the short media segments making up an HTTP Live Streaming (HLS) stream.
  2. HLS was created by Apple and is documented by the IETF as RFC 8216, published in August 2017.
  3. A multivariant (master) playlist lists several quality levels; each level points to a media playlist that lists the actual segments.
  4. yt-dlp and FFmpeg can both read an .m3u8 URL and join its segments into a single MP4 without re-encoding, using stream copy.
  5. If the playlist references FairPlay or another DRM key system, the segments are protected and must not be decrypted without authorisation.
Racks of servers in a data centre, where HLS segments are stored and served
Image: Datacenter Server Racks (22370909788),Carl Lender from Sunrise, USA,CC BY 2.0,via Wikimedia Commons.

An .m3u8 file is a playlist, not a video. HLS (HTTP Live Streaming) cuts a video into short segments, lists them in a plain-text .m3u8 file, and lets the player fetch them one after another over ordinary HTTP. To download an HLS video, you give that playlist URL (or the page URL) to a tool that reads the list, fetches every segment and joins them into one file. yt-dlp and FFmpeg do exactly that, locally and without re-encoding.

This guide explains what is inside an .m3u8, how to save a stream cleanly, and where the legal line sits. Use it for streams you own, public-domain or openly licensed material, or content you have permission to keep (see is downloading videos legal?).

What is HLS and why do sites use it?

HLS was introduced by Apple and later published by the IETF as RFC 8216 in August 2017. It became the most widespread delivery format for online video because it has three practical advantages:

  • It works over plain HTTP. Segments are ordinary files, so any web server or CDN can cache them.
  • It adapts to bandwidth. The same video is encoded at several bitrates, and the player switches between them as the connection changes.
  • It supports live and on-demand. A live playlist keeps growing; a finished one ends with a closing tag.

Its main alternative is MPEG-DASH, which follows the same idea with an XML manifest.

What is inside an .m3u8 file?

There are two kinds of playlist, and you will usually meet both.

The multivariant playlist (often called the master playlist) lists the available quality levels:

#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1280x720,CODECS="avc1.64001f,mp4a.40.2"
720p/index.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.640028,mp4a.40.2"
1080p/index.m3u8

The media playlist lists the segments of one quality level:

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXTINF:6.0,
segment00000.ts
#EXTINF:6.0,
segment00001.ts
#EXT-X-ENDLIST

The tags worth recognising:

Tag Meaning
#EXT-X-STREAM-INF One quality variant: bandwidth, resolution, codecs
#EXTINF Duration of the next segment
#EXT-X-TARGETDURATION Maximum segment duration
#EXT-X-ENDLIST The stream is finished (on-demand); absent on a live stream
#EXT-X-MEDIA Alternative renditions: other audio languages, subtitles
#EXT-X-KEY The segments are encrypted; describes the method and key location

Segments are traditionally MPEG-TS files (.ts), but HLS also allows fragmented MP4 segments (.m4s or .mp4). The difference matters when you choose the final container.

How do I download an HLS stream with yt-dlp?

In most cases, give yt-dlp the page URL, not the playlist: it finds the .m3u8 itself, picks the best variant and merges the separate audio rendition if there is one.

# List the variants found behind the page
yt-dlp -F "https://example.org/my-own-webinar"

# Download the best variant, 4 segments in parallel
yt-dlp -N 4 "https://example.org/my-own-webinar"

If you only have the playlist URL, pass it directly; yt-dlp’s generic extractor handles .m3u8 links:

yt-dlp -o "webinar.%(ext)s" "https://cdn.example.org/path/master.m3u8"

-N (--concurrent-fragments) downloads several segments at once, which helps on long recordings. By default yt-dlp writes the result into an MP4 container; --hls-use-mpegts keeps MPEG-TS instead, which is more robust if the download may be interrupted, because a partial .ts file remains playable.

How do I download an .m3u8 with FFmpeg?

FFmpeg reads HLS playlists natively:

ffmpeg -i "https://cdn.example.org/path/master.m3u8" -c copy output.mp4
  • -i takes the playlist URL. With a multivariant playlist, FFmpeg exposes every variant as separate programs and picks a default.
  • -c copy copies the audio and video streams without re-encoding: fast and lossless.

To choose a specific variant, first inspect the playlist with ffprobe, then select streams with -map:

ffprobe -hide_banner "https://cdn.example.org/path/master.m3u8"
ffmpeg -i "https://cdn.example.org/path/master.m3u8" -map 0:p:2 -c copy output.mp4

0:p:2 means “program 2 of input 0”; the program numbers come from the ffprobe output. Very old FFmpeg builds needed the -bsf:a aac_adtstoasc filter when copying AAC audio from MPEG-TS into MP4; current builds insert it automatically, but the option is harmless if you meet an older version.

How do I record a live HLS stream?

A live playlist has no #EXT-X-ENDLIST: it is refreshed every few seconds with new segments. Both tools follow it until the broadcast ends or you press Ctrl+C:

yt-dlp --hls-use-mpegts "https://example.org/live/my-channel"
ffmpeg -i "https://cdn.example.org/live/index.m3u8" -c copy recording.ts

Recording to .ts first, then remuxing to MP4 afterwards, avoids losing everything if the connection drops. For dedicated live recording, see Streamlink and our workflow to archive your own livestreams.

Why does my HLS download fail?

Symptom Likely cause What to try
HTTP 403 on segments Signed URLs that expired, or missing headers Restart from the page URL with yt-dlp so it regenerates the links
Video without sound Audio is a separate #EXT-X-MEDIA rendition Use yt-dlp, which merges it, or map both streams in FFmpeg
Choppy or out-of-sync file Missing segments Re-run; use --hls-use-mpegts and retries
Unplayable output, #EXT-X-KEY with a key system DRM protection Stop: see below

What about encrypted HLS streams?

RFC 8216 defines encryption methods (AES-128 for whole segments, SAMPLE-AES for media samples). A service may deliver keys openly to any player, or restrict them through a commercial DRM key system such as Apple FairPlay. When a key system or licence server is involved, the stream is protected by a technical measure, and circumventing it is unlawful in the US, the EU and most other countries, whatever tool is used. Our DRM explainer describes how these systems work and which legal options remain, such as the official offline mode of the service.

How do I fix the most common HLS errors?

Most failures fall into a handful of patterns. Read the first error line in the log, then match it here:

Symptom Likely cause What to try
HTTP 403 on the playlist or on segments The signed URL or token has expired, or the server expects the headers of the page that embeds the player Start again from the page URL rather than a copied .m3u8 link, so the tool fetches a fresh token
Download stops after a few segments Network hiccup or rate limiting Raise retries with --fragment-retries 20 and lower parallelism (-N 1)
“Malformed AAC bitstream” when writing MP4 from TS ADTS audio inside MPEG-TS must be converted for MP4 Recent FFmpeg does this automatically; with an older build add -bsf:a aac_adtstoasc
Audio drifts out of sync on long recordings Timestamp jumps between segments, common on live streams Keep the raw .ts, then remux once with ffmpeg -i in.ts -map 0 -c copy out.mkv
Small gaps or frozen frames Some segments were skipped after repeated errors Re-run with --abort-on-unavailable-fragments to fail loudly instead of silently

Two habits prevent most of these. First, download from the page, not from a playlist URL copied out of the browser’s developer tools: page-level extractors know how to refresh tokens. Second, try the other downloader if one misbehaves. yt-dlp can fetch HLS with its own native code or hand the job to FFmpeg:

yt-dlp --downloader native URL
yt-dlp --downloader ffmpeg URL

How do I inspect a playlist before downloading?

FFmpeg’s ffprobe reads a master playlist and lists every variant it announces, with resolution and codecs:

ffprobe -hide_banner "https://example.org/stream/master.m3u8"

Each variant appears as a separate program. If the highest one is lower than the resolution the player shows, you probably copied a media playlist (one quality) rather than the master playlist (all qualities). Go back to the page URL and list formats with yt-dlp -F instead.

Quick checklist

  1. Prefer the page URL with yt-dlp; fall back to the .m3u8 URL.
  2. Check variants with -F or ffprobe before downloading.
  3. Always stream-copy; never re-encode just to change container.
  4. For live streams, record to .ts, remux afterwards.
  5. If you see a DRM key system, stop and look for a legal source.

Open-source tools in this guide

ToolLicence
yt-dlpUnlicense (public domain)
FFmpegLGPL 2.1+ (some builds GPL)

Frequently asked questions

Can VLC open an .m3u8 link?

Yes. VLC can play an HLS playlist URL through Media > Open Network Stream, and its Convert/Save option can write the stream to a file. For long recordings or many files, yt-dlp or FFmpeg are more reliable because they handle retries and stream copy explicitly.

Why do I get hundreds of .ts files instead of one video?

That happens when segments are downloaded individually, for example by a browser extension. HLS is designed that way. Use yt-dlp or FFmpeg on the playlist URL instead: they fetch every segment in order and write them into a single container.

Does downloading an HLS stream reduce quality?

No, as long as you use stream copy (-c copy in FFmpeg, the default in yt-dlp). The segments are joined bit for bit. Quality only drops if you choose a lower variant or re-encode the file.

Is an encrypted HLS stream always DRM?

Not always. RFC 8216 defines AES-128 and SAMPLE-AES encryption methods, and services may combine them with key systems such as Apple FairPlay. Whatever the method, if access to the key is restricted, treat the stream as protected and do not attempt to circumvent it.

How do I find the .m3u8 URL of a video?

Open your browser developer tools, go to the Network tab, filter on m3u8 and start playback. The playlist request appears in the list. In most cases you do not need it: giving yt-dlp the page URL lets it find the playlist automatically.

Sources and open data

  1. RFC 8216: HTTP Live Streaming · IETF / RFC Editor
  2. HTTP Live Streaming developer resources · Apple
  3. FFmpeg formats documentation (HLS demuxer and muxer) · FFmpeg project
  4. yt-dlp README (download options) · yt-dlp project