<!-- Generated by npm run docs. Do not edit by hand. -->

Rules

HLS Lens ships 84 rules. Most read one manifest — the claims it makes — and point at the line you have to fix; the cross/* rules read the master and its renditions together and report on the variant line of the master. For the defects that need the segment bytes (a gap that no EXT-X-DISCONTINUITY declares, a 1080p rung that codes 720p), run the deep check, which brings segcheck findings into the same Problems panel.

Severity maps onto the editor: error is a broken stream or a spec violation, warning is something players tolerate and viewers pay for, hint is advisory (mostly from the Apple HLS authoring specification).

Ids are stable: they are what hlsLens.diagnostics.skip pins.

Structure

Rules about the file being a playlist at all.

syntax/missing-extm3u

The playlist starts with #EXTM3U · error

A playlist whose first line is not #EXTM3U is not a playlist: players reject it outright, so nothing else in the file matters.

syntax/leading-bom

The file has no UTF-8 byte order mark · error

A BOM before #EXTM3U is invisible in most editors and makes strict players reject the playlist. It usually arrives from a template written on Windows or from a spreadsheet export.

syntax/mixed-playlist

A playlist is either a master or a media playlist, never both · error

EXT-X-STREAM-INF and EXTINF in the same file is undefined: a player picks one interpretation and ignores half the file. It is normally a packager writing the wrong template, or a copy-paste between two playlists.

syntax/unknown-tag

Every #EXT tag is one the spec defines · hint

Players must ignore tags they do not recognise, so a typo like EXT-X-TARGETDURATON reads as "no target duration at all" and nothing complains. A misspelled tag is silence, not an error.

syntax/version-too-low

EXT-X-VERSION covers the tags the playlist uses · error

The compatibility version tells a player what it must understand. Declaring less than the playlist uses is how a stream plays on your desk and fails on a TV app that honours the declared version.

syntax/define-malformed

Every EXT-X-DEFINE declares exactly one variable, once · error

A NAME with no VALUE, two ways of giving the same variable a value, or the same name defined twice all leave a player to choose — and the choice lands in a URI, so the wrong one is a request to the wrong host. IMPORT takes its value from the multivariant playlist, so it has nothing to import in a master.

syntax/undefined-variable

Every {$name} is a variable something declares · error

Substitution is textual and there is no error path: a reference nothing declares stays in the URI exactly as written, braces included, and the player requests it that way. The 404 names a host with a { in it, which is the one clue that this is what happened.

Master playlist

Rules about the ladder and the rendition groups.

master/missing-bandwidth

Every variant declares BANDWIDTH · error

BANDWIDTH is the only required attribute of EXT-X-STREAM-INF and the number ABR selection is built on. Without it a player cannot rank the variant and may skip it entirely.

master/missing-resolution

Video variants declare RESOLUTION · warning

Without RESOLUTION a player cannot avoid sending a 1080p rendition to a 360p viewport, and no client-side cap on resolution can work. Apple requires it for video renditions.

master/missing-codecs

Variants declare CODECS · warning

CODECS is what lets a player decide, before downloading anything, whether it can decode a rendition — and what Media Source Extensions needs to set up a buffer. Without it a browser player has to probe, which costs startup time and sometimes fails.

master/duplicate-bandwidth

No two variants share the same BANDWIDTH · warning

Two variants with identical BANDWIDTH are indistinguishable to ABR: the player picks whichever it saw first and the other rung is dead weight in the ladder.

master/missing-uri

Every EXT-X-STREAM-INF is followed by a URI · error

The line after EXT-X-STREAM-INF is the variant playlist. Without it the variant does not exist, and a player either skips it or fails to load the master.

master/undefined-group

AUDIO, SUBTITLES and CLOSED-CAPTIONS groups exist · error

A variant pointing at a rendition group that no EXT-X-MEDIA declares has no audio (or no subtitles) at all. It is the classic result of renaming a group in one place.

master/group-no-default

Each rendition group has a default · warning

With no DEFAULT=YES in a group, which audio or subtitle track a player starts with is its own choice — so the same stream starts in a different language depending on the device.

master/group-multiple-defaults

A rendition group has at most one default · error

Two DEFAULT=YES renditions of the same type in the same group contradict each other; the spec allows one, and players resolve the conflict differently.

master/rendition-missing-attributes

Every EXT-X-MEDIA declares TYPE, GROUP-ID and NAME · error

A variant resolves its alternate audio and subtitles by group name alone. A rendition missing the attributes that identify it cannot be resolved, and nothing fails loudly: the stream simply plays without the track.

master/rendition-uri

Subtitles are fetched, closed captions are carried in the video · error

A subtitles rendition with no URI has nothing to fetch. Closed captions are the opposite: they ride inside the video stream, so a URI is forbidden and INSTREAM-ID is what names the caption service. Both mistakes produce a track a player offers and cannot show.

master/rendition-forced

FORCED is only defined for subtitles · warning

FORCED marks the subtitle track a player shows even with subtitles switched off — the one that translates on-screen text. On an audio or video rendition it means nothing and players ignore it, which usually means the track was meant to be something else.

master/rendition-default-not-autoselect

A default rendition is one a player may select · error

DEFAULT=YES with AUTOSELECT=NO says both "play this unless told otherwise" and "never pick this automatically". The spec requires AUTOSELECT=YES when DEFAULT=YES; which of the two a player honours is its own decision.

master/rendition-duplicate-name

Two renditions of a group do not share a NAME · warning

NAME is what a player puts in its track picker. Two identical entries are indistinguishable to whoever has to choose, and which one they get depends on the order the player happened to read them in.

master/audio-group-mixed-channels

One audio group, one channel count · hint

Renditions of a group are alternatives a player switches between freely. A group mixing stereo and 5.1 changes the mix under the viewer when they change language, and on some devices restarts the audio pipeline to do it.

master/unused-group

Every rendition group is referenced by a variant · warning

A group no EXT-X-STREAM-INF names is never offered to anyone: the alternate audio is encoded, published and cached, and no player can reach it. It is the same rename as master/undefined-group, seen from the other side.

master/inconsistent-groups

The variants reference the same groups as each other · warning

A player picks a rung on bandwidth alone. If one rung names an AUDIO group and another does not, whether the viewer has alternate audio becomes a function of their connection at that moment — and it changes mid-playback, which no log explains.

master/no-iframe-stream

The master offers an I-frame playlist for trick play · hint

Without EXT-X-I-FRAME-STREAM-INF there is nothing to show while scrubbing: players fall back to seeking on the video renditions, which is slow and looks broken on a TV remote.

master/plaintext-uri

Child playlists are addressed over HTTPS · warning

An http:// URI inside an https:// manifest is blocked as mixed content by every browser player, and readable in transit everywhere else.

master/average-bandwidth-missing

Variants declare AVERAGE-BANDWIDTH · hint

BANDWIDTH is the peak a player must sustain; AVERAGE-BANDWIDTH is what the rendition actually costs. Players that have both make better decisions on a variable connection.

master/bandwidth-not-ascending

Variants are listed in ascending BANDWIDTH · hint

Some players start on the first variant listed. An unordered ladder makes the initial pick arbitrary, which shows up as a stream that sometimes starts at the top rung on a slow connection.

master/codecs-resolution-mismatch

The CODECS level can carry the declared RESOLUTION and FRAME-RATE · warning

An H.264 level caps the frame size and the macroblock rate. A rung that advertises avc1.4d401e (Main@3.0, 1620 macroblocks) and RESOLUTION=1920x1080 is telling players it cannot decode what it is offering: strict devices — TVs and set-top boxes, rarely the browser you tested in — refuse the rung and fall back, or fail.

master/ladder-spacing

Consecutive rungs are far enough apart, and not too far · hint

Rungs less than about 1.5x apart in bitrate are indistinguishable to ABR: it pays for a second encode and a second cache entry that no switching decision can use. A gap wider than about 2.5x is the opposite problem — when the connection cannot hold the upper rung there is nothing to fall back to except a much worse picture.

master/session-data

Session data carries one value under an id it does not share · error

EXT-X-SESSION-DATA exists so a player can read metadata without loading a rendition. With neither VALUE nor URI there is no datum; with both there are two answers; and two entries sharing DATA-ID and LANGUAGE make which one a player reads arbitrary.

master/content-steering

Content steering points somewhere, once, at a pathway that exists · error

Steering is what moves traffic between CDNs during playback. Without SERVER-URI there is nothing to poll, a second tag makes the pathway a player starts on arbitrary, and a PATHWAY-ID no variant declares steers every player onto a pathway with no renditions in it.

Media playlist

Rules about segments, timing, keys and the live window.

media/missing-target-duration

The media playlist declares EXT-X-TARGETDURATION · error

TARGETDURATION is required, and it is what a player uses to time its reloads. Without it a live playlist is polled at an arbitrary rate, or not at all.

media/extinf-exceeds-target

No segment is longer than EXT-X-TARGETDURATION · error

The spec requires every EXTINF, rounded to the nearest integer, to be at most TARGETDURATION. A longer segment breaks the reload timing a player derives from it, which shows up as a stall right at that segment.

media/target-duration-overstated

EXT-X-TARGETDURATION is close to the real segment duration · warning

A player reloads a live playlist on the target duration and buffers a multiple of it, so a target far above the real segments adds latency and a bigger buffer for nothing.

media/missing-endlist

A VOD playlist ends with EXT-X-ENDLIST · error

PLAYLIST-TYPE:VOD without EXT-X-ENDLIST tells a player the content is complete and then never says it ended: the player keeps reloading the playlist forever and the seek bar never settles.

media/missing-map

fMP4 segments come with an EXT-X-MAP init segment · error

A fragmented MP4 segment carries no codec configuration: without the initialisation segment from EXT-X-MAP there is nothing to initialise the decoder with, and playback fails immediately.

media/key-over-http

Content keys are fetched over HTTPS · error

An EXT-X-KEY URI on http:// hands the AES key to anyone on the path, which makes the encryption decorative. Unlike a password, a content key cannot be rotated without re-encrypting the content.

media/pdt-not-monotonic

EXT-X-PROGRAM-DATE-TIME moves forward · error

Wall-clock times that go backwards break every consumer that maps media time to real time: DVR windows, ad insertion, subtitle sync and any correlation with an event clock.

media/pdt-drift

EXT-X-PROGRAM-DATE-TIME agrees with the EXTINF durations · warning

Two PROGRAM-DATE-TIME tags whose distance does not match the segment durations between them mean the wall clock and the media timeline disagree — the manifest is telling two different stories about when a frame was captured.

media/pdt-missing

A live playlist carries EXT-X-PROGRAM-DATE-TIME · hint

Without a wall clock in the playlist there is no way to correlate a live stream with anything outside it: no absolute seeking in the DVR window, no matching an incident to a timestamp.

media/discontinuity-without-sequence

A sliding playlist with discontinuities declares EXT-X-DISCONTINUITY-SEQUENCE · warning

When a discontinuity slides out of a live window, players that joined at different times disagree on which discontinuity they are in unless the sequence number is declared. Ad breaks are where this shows up.

media/missing-uri

Every EXTINF is followed by a segment URI · error

An EXTINF with no URI after it is a segment that does not exist. Players stop at that point in the playlist.

media/part-without-server-control

Low-latency parts come with the EXT-X-SERVER-CONTROL that makes them usable · error

EXT-X-PART only reduces latency if the player can block on a playlist reload and knows how far from the live edge to start: that is CAN-BLOCK-RELOAD=YES and PART-HOLD-BACK. Without them the parts are downloaded and the latency stays where it was.

media/holdback-too-small

HOLD-BACK leaves a player three target durations of buffer · warning

The spec sets the floor at three target durations (three part durations for PART-HOLD-BACK). Below it a player starts too close to the live edge and rebuffers on the first hiccup.

media/part-without-part-inf

A playlist that publishes parts declares EXT-X-PART-INF · error

PART-TARGET is how a player sizes its part requests and its blocking reload. Parts with no target at all leave it guessing on every fetch, which is the opposite of the predictability low latency depends on.

media/part-exceeds-part-target

No part is longer than PART-TARGET · error

A player sizes its blocking reload on PART-TARGET. A part longer than the target arrives after the player expected the next one, which is a stall exactly at the live edge — where there is no buffer to absorb it.

media/part-target-too-large

A part is a fraction of a segment · warning

PART-TARGET at or above TARGETDURATION means a part is as long as a segment: the playlist pays the full cost of low latency — more requests, more tags, a blocking reload — and delivers none of the latency it exists for.

media/can-skip-until-too-small

CAN-SKIP-UNTIL leaves six target durations · warning

The spec puts the floor at six target durations. A boundary below it is one no conforming client is allowed to ask for, so the playlist deltas the server went to the trouble of supporting are never requested.

media/preload-hint

Preload hints are well formed and unique per type · error

A hint is a request the player makes before the resource exists, and it can only make one per type: a hint with no URI has nothing to request, and two hints of the same type leave the player to guess which one the server will answer.

media/preload-hint-not-preloading

The preload hint points at what does not exist yet · warning

A hint for a part the playlist already lists is a request the player would have made anyway, and a TYPE=PART hint in a playlist with no parts continues nothing. Both look like low latency in the manifest and cost a round trip in the player.

media/rendition-report

Rendition reports name a rendition and a position · error

URI and LAST-MSN are what a report is: which rendition, and how far along. Without both a switching player cannot use it and falls back to fetching the other playlist — the round trip the report exists to save.

media/rendition-report-out-of-step

Rendition reports are level with the playlist that carries them · warning

A report several segments behind this playlist means the rungs are not being published in step, or the report is stale. A player that switches on it asks for a segment that is not there yet, or restarts from one it has already played.

media/rendition-report-missing

A low-latency playlist reports the other renditions · hint

Without a rendition report, a player switching rungs has to fetch the other playlist before it can request anything from it. That round trip at the live edge is exactly what the low-latency tags were added to remove.

media/start-offset

EXT-X-START lands inside the playlist · warning

TIME-OFFSET is where playback begins. Past the end of the playlist a player falls back to its own default, so the tag does nothing; and a negative offset inside the three target durations a player buffers puts the start point where there is not yet enough media to play.

media/gap-segments

The playlist has no EXT-X-GAP segments · warning

EXT-X-GAP marks a segment the packager could not produce. Players skip it, so it is a hole in the content that the manifest is honest about — worth knowing before a viewer reports it.

media/short-live-window

A live playlist holds at least three target durations · warning

A player buffers a multiple of the target duration before it starts. A window shorter than three target durations makes joining unreliable and leaves no room to recover from a slow segment.

media/plaintext-segment

Segments are addressed over HTTPS · warning

An http:// segment URI in an https:// playlist is blocked as mixed content in browsers, and readable in transit everywhere else.

media/daterange

EXT-X-DATERANGE ranges are well formed and do not overlap · warning

Ad breaks are described by these ranges, and a player acts on them: a DURATION that disagrees with END-DATE, two ranges of the same CLASS covering the same seconds, or a CUE-IN with nothing to close all end the same way — an ad that does not start, does not end, or is billed and never shown.

media/key-rotation

A long-running live stream rotates its content key · hint

One key for the whole window means one key for the whole event: a key extracted from a browser once decrypts everything that follows, indefinitely. Rotation puts a bound on what a leak is worth.

media/key-dropped

Encryption is not switched off part-way through · warning

An EXT-X-KEY:METHOD=NONE after encrypted segments leaves the rest of the playlist in the clear. It is almost always a packager restarting without its key configuration rather than a deliberate decision, and nothing else in the stream complains.

media/iframe-playlist-shape

An I-frames-only playlist addresses byte ranges · warning

EXT-X-I-FRAMES-ONLY exists so a player can fetch single frames while scrubbing. Segments without EXT-X-BYTERANGE make it download a whole segment per thumbnail, which is the cost trick play was meant to avoid.

Across playlists

Rules that need the master and its renditions at once, from HLS Lens: Check Renditions Together. Every rendition is a valid playlist on its own; these are the ways they can disagree with each other.

cross/session-key-mismatch

The session key matches the keys the renditions use · warning

EXT-X-SESSION-KEY exists to let a player fetch the content key while it is still reading the master, instead of stalling on the first segment. A session key whose METHOD or KEYFORMAT no rendition uses is a fetch spent on a key that decrypts nothing — the stall it was meant to remove, plus a request.

cross/version-mismatch

Every rendition declares the same EXT-X-VERSION · warning

A player honours the version of the playlist it is reading. One rendition declaring less than the others means the tags the rest of the stream relies on may be ignored on exactly the rung a device happened to pick.

cross/target-duration-mismatch

Every rendition declares the same EXT-X-TARGETDURATION · warning

Target duration drives buffering and the reload interval. Renditions that disagree about it are segmented differently, which is the first symptom of two encoders that were not configured from the same source.

cross/playlist-type-mismatch

The renditions are all live, or all finished · error

One rendition carrying EXT-X-ENDLIST while the others are still live strands every player that switches to it: it believes the stream ended and stops. It is what a packager leaves behind when one encoder finishes early.

cross/media-sequence-mismatch

The live windows start at the same media sequence · warning

Windows that are offset mean a player switching rungs jumps forwards or backwards in time by the difference — visible as a skip or a repeat exactly when the connection got worse.

cross/segment-count-mismatch

The renditions hold the same number of segments · error

Renditions of one stream are segmented identically so a player can switch at any boundary. A different count is a different timeline, and switching lands somewhere the player did not intend.

cross/timeline-drift

Segment boundaries land at the same time in every rendition · error

Equal segment counts can still hide different boundaries. A player that switches rungs continues at the boundary it knows, so drift shows up as a picture that starts mid-segment or a fraction of a second repeated.

cross/discontinuity-mismatch

Discontinuities land on the same segment in every rendition · error

An ad break or an encoder restart that is one segment out on one rung breaks the switch precisely where the stream is already changing — the hardest place to diagnose from a single file.

cross/bitrate-vs-declared

BANDWIDTH covers the bitrate the rendition declares · warning

BANDWIDTH is the peak a rendition can reach, and ABR provisions against it. A playlist whose own EXT-X-BITRATE is higher than the master promises makes the player pick a rung the connection cannot carry, and rebuffer.

DASH

Rules for an .mpd. The extension stays HLS-first, but the same stream is usually packaged both ways from one mezzanine, and the defects are the same ones: a declared duration the segments do not fill, a hole in the timeline, a live manifest with no clock.

dash/not-an-mpd

The file is an MPD · error

A .mpd whose root is not <MPD> is nearly always an error page or a redirect saved by hand. Saying so once is more use than reporting every attribute it does not have.

dash/malformed-xml

The manifest is well-formed XML · error

Players parse an MPD strictly. A document that does not close its elements is not read at all, however good the rest of the packaging is.

dash/missing-presentation-duration

A static MPD declares @mediaPresentationDuration · warning

Without it a player cannot know how long the asset is: no seek bar, no end, and no way to tell a truncated manifest from a complete one.

dash/duration-vs-timeline

@mediaPresentationDuration matches the segment timeline · warning

The declared duration and the segments have to describe the same presentation. Claiming more media than the timeline addresses makes players stall at the end or seek into nothing; claiming less leaves the tail unreachable.

dash/timeline-gap

SegmentTimeline entries chain without gaps or overlaps · error

Each <S> starts where the previous one ended unless @t says otherwise. A @t that disagrees is a hole in the presentation — or two segments claiming the same seconds — and it is invisible until you add the durations up.

dash/dynamic-without-utctiming

A dynamic MPD carries UTCTiming · warning

A live DASH client computes which segment exists from its own clock and @availabilityStartTime. Without a UTCTiming element to synchronise to, a device whose clock is seconds off requests segments that do not exist yet, and buffers for reasons no server log explains.

dash/adaptationset-not-aligned

Adaptation sets with several representations declare @segmentAlignment · warning

A player may only switch representations at aligned boundaries. Without the flag it has to assume it cannot, and the adaptation the ladder was built for does not happen.

dash/missing-bandwidth

Every representation declares @bandwidth · error

@bandwidth is required by the schema and is what adaptation ranks representations on. Without it a representation cannot be chosen deliberately.

dash/missing-codecs

Representations declare @codecs · warning

Without @codecs — on the representation or inherited from the adaptation set — a player has to fetch media to find out whether it can decode it, which costs startup time and sometimes fails outright.

dash/segment-template-without-number

A segment template addresses more than one segment · error

A @media template with neither $Number$ nor $Time$ resolves every segment to the same URL: the player fetches the first segment forever.

dash/period-codecs-change

A representation keeps its codec across periods · warning

A period boundary is a seam a player crosses without stopping. A representation whose @codecs changes across it forces the decoder to be reconfigured mid-presentation, which on many devices is a visible stall or a black frame — and no single period shows it.

dash/period-missing-track

Every period carries the same tracks · warning

A track that stops existing at a period boundary is silence, or a subtitle that disappears, from that point on. Players do not go looking for it in the next period, and the manifest that dropped it is valid.

dash/period-not-contiguous

Periods run back to back · error

Periods chain: one starts where the last one ended. A gap between them is media no player can request, and an overlap is two periods claiming the same seconds — neither is visible inside either period, or in any <SegmentTimeline>.

dash/segment-template-without-init

A segment template names an initialisation segment · warning

Fragmented MP4 needs the initialisation segment to configure the decoder. Without @initialization the first media segment arrives with nothing to decode it.