Apple PlatformIssue Guide
#012 HLS Open

Live playlist discontinuity state changes for the same media sequence across reloads

HlsPlaybackApple forumInvestigatingGuidelineApple docs
GitHub source

Evidence not classified. This page is generated from GitHub Issue #12; GitHub remains the canonical authoring and discussion source.

Source#

Apple Developer Forums: https://developer.apple.com/forums/thread/824898

Problem#

A live/event HLS stream generated by FFmpeg stalls in Safari/iOS while Apple HLS tooling reports:

Media Entry discontinuity value does not match previous playlist for MEDIA-SEQUENCE 1

The final static playlist validates after the event ends, which can make the stream appear structurally correct when inspected only after completion.

The example playlist begins with:

#EXT-X-MEDIA-SEQUENCE:1
#EXT-X-PLAYLIST-TYPE:EVENT
#EXT-X-DISCONTINUITY

but does not show EXT-X-DISCONTINUITY-SEQUENCE.

Evidence level#

HLS authoring requirement + forum reproduction.

Apple's HLS Authoring Specification states that if live content will ever contain EXT-X-DISCONTINUITY, EXT-X-DISCONTINUITY-SEQUENCE must always be present. Apple also requires discontinuities to occur at the same points in time across variants and renditions.

The validator error is therefore best investigated as a playlist-evolution/state-consistency problem, not simply as a malformed final manifest.

Explanation#

For a live playlist, each reload is part of one evolving timeline. A media sequence number identifies a segment position in that evolving history, while the discontinuity sequence establishes the discontinuity domain that applies to it.

A useful model is:

playlist snapshot N
    MEDIA-SEQUENCE
    DISCONTINUITY-SEQUENCE
    discontinuity positions
          ↓
playlist snapshot N+1
    same logical timeline must remain consistent
          ↓
client maps media sequence → discontinuity state

If the same media-sequence entry appears with different discontinuity state across reloads, the client can no longer build one stable timeline from the snapshots.

The important distinction is:

final playlist is valid
        ≠
playlist evolution was valid

A validator run after EXT-X-ENDLIST sees only the final state and can therefore miss an inconsistency that existed during live updates.

Investigation#

Capture consecutive raw playlist responses while the event is active. For every snapshot record:

request timestamp
MEDIA-SEQUENCE
DISCONTINUITY-SEQUENCE
segment URI / sequence mapping
positions of EXT-X-DISCONTINUITY
PROGRAM-DATE-TIME if present
HTTP Date / Last-Modified / Age

Then construct a history table keyed by media sequence number:

msn | snapshot | discontinuity-sequence | discontinuity-before-segment
----+----------+------------------------+-----------------------------
  1 | A        | ...                    | ...
  1 | B        | ...                    | ...

The first media sequence whose discontinuity state changes between snapshots is the divergence boundary.

Also verify whether the initial EXT-X-DISCONTINUITY represents a real encoding/timestamp discontinuity. A discontinuity tag should describe an actual boundary in media continuity, not merely mark the beginning of an event.

Verification matrix#

Run mediastreamvalidator against the live stream for each case:

A. Current playlist behavior

B. Remove the initial EXT-X-DISCONTINUITY
   if there is no real media discontinuity

C. Keep the discontinuity but emit and maintain
   EXT-X-DISCONTINUITY-SEQUENCE across every reload

D. Multi-variant case: verify identical discontinuity
   boundaries across every audio/video rendition

Do not validate only the completed event. Preserve the intermediate playlist snapshots produced during the failing playback window.

Solution / Guideline#

For live HLS:

  1. Treat playlist history as protocol state, not a series of independent manifests.
  2. If the stream ever uses EXT-X-DISCONTINUITY, always emit a consistent EXT-X-DISCONTINUITY-SEQUENCE.
  3. Advance discontinuity state only when a discontinuity actually leaves the playlist window or the protocol semantics require it.
  4. Keep discontinuity boundaries aligned across variants/renditions.
  5. Do not insert an initial discontinuity simply as an event-start marker unless media continuity actually changes there.
  6. Validate while the stream is live, not only after EXT-X-ENDLIST.

Engineering rule#

For live HLS, correctness is a property of the sequence of playlist snapshots, not just the latest playlist.

When a failure disappears after the event completes, inspect:

snapshot evolution
→ media-sequence identity
→ discontinuity-sequence identity
→ discontinuity placement
→ cross-rendition alignment
→ client timeline construction

The first state that changes incompatibly for an already-known media sequence is the useful debugging boundary.

References#