Skip to content

fix: avoid cumulative live subtitle playlist drift - #8170

Open
yuxino wants to merge 2 commits into
video-dev:masterfrom
febug:fix/live-subtitle-playlist-alignment
Open

yuxino wants to merge 2 commits into
video-dev:masterfrom
febug:fix/live-subtitle-playlist-alignment

Conversation

@yuxino

@yuxino yuxino commented Nov 14, 2026 •

Copy link
Copy Markdown

This PR will...

Keep live WebVTT subtitles aligned after playlist refreshes.

Why is this Pull Request needed?

In the stream from #8159, captions appear initially and then disappear while playback continues. After mergeDetails has already shifted a subtitle playlist, the sequence-number fallback adds the main playlist's start again on each refresh.

Keep the start that a playlist already acquired when sequence numbers are the only remaining alignment hint. The sequence fallback still aligns fresh playlists. When a configured timeline offset is present, apply it once on refresh and include it in the trailing LL-HLS part.

hls-live-subtitle-drift-before-after.mp4

The clip shows the original reproduction and first fix in the project demo. Waiting time is omitted. The latest revision was replayed on the same public live stream, and subtitles were still visible after 22 playlist loads.

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

The guard sits after discontinuity and Program Date Time alignment, so those paths can still refine a playlist's start. Same-rendition updates with a configured offset avoid applying it twice.

npm run sanity-check passes, including 1,290 unit tests. Regressions cover successive refreshes, previously shifted playlists, a configured offset, and the trailing part hint. All 36 selected PDT, alternate-audio, and low-latency playback checks pass in Chromium. The Apple advanced sample remains unverified, with a fragLoadError observed in the earlier baseline and PR runs.

Resolves issues:

Fixes #8159

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 (not applicable)

Comment thread src/utils/level-helper.ts Outdated
Comment on lines +503 to +510
// A rendition may already have been slid by mergeDetails before aligning it
// with main. Apply only the difference from its existing start in that case.
const existingSliding = matchingStableVariantOrRendition
? 0
: newDetails.fragmentStart;
let sliding = 0;
if (advancedOrStable && delta < oldFragments.length) {
sliding = oldFragments[delta].start;
sliding = oldFragments[delta].start - existingSliding;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a difference? Why is adjustSliding being called on details that were already adjusted? It should not.

This branch has not been deployed

No deployments
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.

Webvtt in live stream disappear

2 participants