fix: align WebVTT segments missing X-TIMESTAMP-MAP with media timestamps - #128
Merged
grabofus merged 2 commits intoMay 29, 2026
Merged
Conversation
grabofus
approved these changes
May 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR will...
Fix incorrect subtitle timing for WebVTT segments that do not include an
X-TIMESTAMP-MAPheader,which commonly occurs after HLS discontinuities.
When a VTT segment lacks
X-TIMESTAMP-MAP, cue timestamps are now aligned to the media timelineusing
initPTS. IfinitPTSis not yet available at parse time, parsing is deferred until itarrives (same behaviour as the existing MPEGTS timestamp map deferral). Additionally, cue IDs are
prefixed with the discontinuity counter (
cc) to prevent ID collisions across discontinuityboundaries.
Why is this Pull Request needed?
Subtitles were jumping or misaligned after discontinuities when the VTT segments did not carry an
X-TIMESTAMP-MAPheader. The parser was treating cue time0as wall-clock0instead ofaligning 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
Are there any points in the code the reviewer needs to double check?
webvtt-parser.ts—elsebranch (no timestamp map, initPTS present):cueOffset = -initPTS.baseTime / initPTS.timescale— this aligns cue time0to the segment's media start per the HLS spec. Verify this holds for your VOD and live stream configurations.timeline-controller.ts— deferred parsing: ThemissingInitPTScheck now usesstartsWith('Missing initPTS')instead of an exact string match, to cover both the MPEGTS and the new no-timestamp-map deferral case.cc > 0and the cue already had an explicit ID from the VTT file. Auto-generated IDs (hash-based) are unaffected.Resolves issues:
DORIS-2395
Checklist