#EXT-X-GAP Explained: How HLS Marks Missing Segments in Live Streams

Most HLS errors are transient: a segment fetch fails, the player retries, and the stream continues. #EXT-X-GAP is different. It is the server telling the player, explicitly and permanently, that a segment it expected to receive no longer exists and never will. Understanding what that tag means — and what it does not mean — matters both for building a reliable player and for understanding what a download tool can and cannot recover.

What the tag declares

A normal media playlist entry looks like this:

#EXTINF:6.006,
seg001.ts

A GAP-tagged entry replaces the URI with the tag:

#EXT-X-GAP
#EXTINF:6.006,
seg001.ts

The URI is still present (so parsers that only read URIs do not break), but the #EXT-X-GAPtag instructs the player to skip that segment entirely without making a network request. The segment occupies its normal slot in the media sequence — the sequence counter does not reset or skip — so the player's position tracking stays accurate.

Why the tag exists

Live streams can experience gaps for several reasons:

• Encoder failure. If the encoder or packager goes offline during a live broadcast, the segments it would have produced simply never arrive at the CDN origin. Once the broadcast ends and the archive is finalised, those gaps are marked permanently with #EXT-X-GAP rather than left as missing URIs that would trigger endless retries.
• Origin outage during ingest.A CDN origin can lose contact with the encoder for a window of time. Segments produced in that window exist at the encoder but never reach storage. The result is a permanent hole in the CDN's copy.
• Deliberate segment removal. A broadcaster may remove a segment for legal or rights reasons after the fact. Replacing the URI with #EXT-X-GAP preserves the playlist structure and media sequence numbering while making the content unavailable.

The difference from a transient fetch error

When a segment fetch returns a 404 or a network timeout, a player like hls.js retries — up to its configured limit, then falls back to a lower bitrate or fires an error event. A GAP tag skips that entire cycle. No network request is made. There is nothing to retry. The segment is gone and the player advances.

This distinction matters for a stream recorder or download tool that encounters a GAP tag mid-conversion: retrying the URI is not an option. The tool has to decide what to put in that slot instead.

What a downloader does with a GAP

When the site's /convert route encounters#EXT-X-GAP during segment staging, it has two honest options:

• Skip and continue.Omit the missing segment from the output, which creates a jump in the video timeline equal to the segment's duration (typically 2–10 seconds for a standard HLS stream).
• Substitute silence and black. Generate a synthetic segment of the same duration filled with silence and black frames, preserving timeline continuity at the cost of a visible black patch.

There is no third option. The content behind the gap is not available anywhere on the CDN — not at a different quality level, not in a backup URL — because the tag exists specifically to indicate that the bytes were never stored. Unlike token-authenticated streams where the content exists but is gated, a GAP segment genuinely does not exist.

GAP tags and the converter

The site's converter fetches segments sequentially during the staging phase described in how to convert M3U8 to MP4 in your browser. A GAP-tagged segment logs a warning and is skipped rather than retried, producing a slightly shorter output file than the original broadcast duration. For most recordings this is transparent — a brief encoder hiccup mid-broadcast is already lost content; the download simply reflects reality.

If you are downloading an archived live stream and the output seems shorter than expected, or jumps suddenly in its timeline, the most likely explanation is one or more GAP tags in the original playlist that the converter faithfully skipped.

How to spot GAP tags in a playlist

Open the stream URL in the Stream Video Downloader extension, copy the .m3u8 URL, and fetch it directly in your browser or a text editor. Search for #EXT-X-GAP. Each occurrence is a permanent hole in the recording. The surrounding #EXTINF duration tag tells you exactly how many seconds of content are missing from that slot.