Skip to content

fix: align WebVTT segments missing X-TIMESTAMP-MAP with media timestamps - #128

Merged
grabofus merged 2 commits into
master-dorisfrom
fix/DORIS-2395-hls-subtitles-after-discontinuity
May 29, 2026
Merged

grabofus merged 2 commits into
master-dorisfrom
fix/DORIS-2395-hls-subtitles-after-discontinuity

Conversation

@robybales3

Copy link
Copy Markdown

This PR will...

Fix incorrect subtitle timing for WebVTT segments that do not include an X-TIMESTAMP-MAP header,
which commonly occurs after HLS discontinuities.

When a VTT segment lacks X-TIMESTAMP-MAP, cue timestamps are now aligned to the media timeline
using initPTS. If initPTS is not yet available at parse time, parsing is deferred until it
arrives (same behaviour as the existing MPEGTS timestamp map deferral). Additionally, cue IDs are
prefixed with the discontinuity counter (cc) to prevent ID collisions across discontinuity
boundaries.

Why is this Pull Request needed?

Subtitles were jumping or misaligned after discontinuities when the VTT segments did not carry an
X-TIMESTAMP-MAP header. The parser was treating cue time 0 as wall-clock 0 instead of
aligning it to the actual media presentation timestamp, causing cues to appear at the wrong position
or not at all.

Ported from upstream video-dev/hls.js@12366c816.

How to test

Test stream with discontinuity (blank state 1:00–1:14, content resumes at 1:15):

https://sample-videos-zyrkp2nj.s3.eu-west-1.amazonaws.com/20260519_hls_vtt_doris_2395/master.m3u8

  1. Load the stream from the beginning
  2. Enable subtitles
  3. Let it play through the discontinuity at ~1:00 without seeking
  4. Expected (after fix): subtitles appear correctly after 1:15
  5. Before fix: subtitles were missing after the discontinuity

Are there any points in the code the reviewer needs to double check?

  • webvtt-parser.ts — else branch (no timestamp map, initPTS present): cueOffset = -initPTS.baseTime / initPTS.timescale — this aligns cue time 0 to the segment's media start per the HLS spec. Verify this holds for your VOD and live stream configurations.
  • timeline-controller.ts — deferred parsing: The missingInitPTS check now uses startsWith('Missing initPTS') instead of an exact string match, to cover both the MPEGTS and the new no-timestamp-map deferral case.
  • Cue ID prefixing: Only applied when cc > 0 and the cue already had an explicit ID from the VTT file. Auto-generated IDs (hash-based) are unaffected.

Resolves issues:

DORIS-2395

Checklist

  • changes have been done against master branch, and PR does not conflict
  • new unit / functional tests have been added (whenever applicable)
  • API or design changes are documented in API.md

@grabofus
grabofus merged commit eda5b74 into master-doris May 29, 2026
9 of 10 checks passed
@grabofus
grabofus deleted the fix/DORIS-2395-hls-subtitles-after-discontinuity branch May 29, 2026 14:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants