Bug: Subtitles Throw Error

[dh-mux]

Is there an existing issue for this?

• I have searched the existing issues

Which package(s) or projects are affected?

SPF (@videojs/spf)

Browser/OS/Node environment

windows chrome - latest

Description

Looks like stream has TTML and WVTT - but the wvtt looks funky. May not be an issue but was a Mux sample
https://test-streams.mux.dev/tos_ismc/main.m3u8

Reduced test case

https://muxed-dev.s3.us-east-2.amazonaws.com/dh-hls.html

Steps to reproduce

1. Load stream: https://test-streams.mux.dev/tos_ismc/main.m3u8
2. click UI button to activate subtitles

Current Behavior

activating subtitles throw error

Expected Behavior

subtitles should work or console error why not

Errors

load-text-track-cues.ts:85 Failed to load VTT segment: Error: Failed to load VTT segment: https://test-streams.mux.dev/tos_ismc/tos_subs/text_1.mp4
at HTMLTrackElement.a (parse-vtt-segment.ts:48:14)
st @ load-text-track-cues.ts:85
await in st
(anonymous) @ load-text-track-cues.ts:269
(anonymous) @ combine-latest.ts:87
flush @ create-state.ts:227
(anonymous) @ create-state.ts:246
load-text-track-cues.ts:85 Failed to load VTT segment: Error: Failed to load VTT segment: https://test-streams.mux.dev/tos_ismc/tos_subs/text_2.mp4
at HTMLTrackElement.a (parse-vtt-segment.ts:48:14)
st @ load-text-track-cues.ts:85
await in st
(anonymous) @ load-text-track-cues.ts:269
(anonymous) @ combine-latest.ts:87
flush @ create-state.ts:227
(anonymous) @ create-state.ts:246
load-text-track-cues.ts:85 Failed to load VTT segment: Error: Failed to load VTT segment: https://test-streams.mux.dev/tos_ismc/tos_subs/text_3.mp4
at HTMLTrackElement.a (parse-vtt-segment.ts:48:14)
st @ load-text-track-cues.ts:85
await in st
(anonymous) @ load-text-track-cues.ts:269
(anonymous) @ combine-latest.ts:87
flush @ create-state.ts:227
(anonymous) @ create-state.ts:246
load-text-track-cues.ts:85 Failed to load VTT segment: Error: Failed to load VTT segment: https://test-streams.mux.dev/tos_ismc/tos_subs/text_4.mp4
at HTMLTrackElement.a (parse-vtt-segment.ts:48:14)
st @ load-text-track-cues.ts:85
await in st
(anonymous) @ load-text-track-cues.ts:269
(anonymous) @ combine-latest.ts:87
flush @ create-state.ts:227
(anonymous) @ create-state.ts:246
load-text-track-cues.ts:85 Failed to load VTT segment: Error: Failed to load VTT segment: https://test-streams.mux.dev/tos_ismc/tos_subs/text_5.mp4
at HTMLTrackElement.a (parse-vtt-segment.ts:48:14)
st @ load-text-track-cues.ts:85
await in st
(anonymous) @ load-text-track-cues.ts:269
(anonymous) @ combine-latest.ts:87
flush @ create-state.ts:227
(anonymous) @ create-state.ts:246
load-text-track-cues.ts:85 Failed to load VTT segment: Error: Failed to load VTT segment: https://test-streams.mux.dev/tos_ismc/tos_subs/text_6.mp4
at HTMLTrackElement.a (parse-vtt-segment.ts:48:14)
st @ load-text-track-cues.ts:85
await in st
(anonymous) @ load-text-track-cues.ts:269
(anonymous) @ combine-latest.ts:87
flush @ create-state.ts:227
(anonymous) @ create-state.ts:246
"

What version of the package are you using?

html@10.0.0-beta.6

[github-actions]

Triage notes

The error stack points to parse-vtt-segment.ts trying to handle .mp4 segment URLs — the stream uses WVTT cues packaged in fragmented MP4 (fMP4/CMAF) containers rather than plain .vtt files. The parser appears to be treating these as raw VTT text, which fails. Proper handling requires demuxing the MP4 box before extracting the VTT payload.

Related issues:

• Design: Strategy for Native Text Track Loading to Prevent Blocking Playback #988 — Design: Strategy for Native Text Track Loading (open, triage) — addresses blocking-playback concerns during text track loading; directly adjacent
• Architecture: Text Track Spike — Actors, Reactors, and Primitives Reference Implementations #1158 — Architecture: Text Track Spike (open) — in-progress spike on text track actors/reactors; may be the right place to address fMP4 WVTT demux support

Planning recommendations:

• Milestone: 26.2 (active cycle; this is a regression in beta.6 affecting a real-world HLS stream)
• Priority: P1 — subtitle feature is visibly broken on a common CMAF/fMP4 HLS format
• Epic: Consider linking to the text track architecture work in Architecture: Text Track Spike — Actors, Reactors, and Primitives Reference Implementations #1158 since a proper fix likely requires the demux pipeline being designed there
• Blocked by: Possibly Architecture: Text Track Spike — Actors, Reactors, and Primitives Reference Implementations #1158 if the fMP4 demux capability is being built as part of that spike

[github-actions]

PR #1218 (feat(spf): architecture reactors) resolved #1158 and completely rebuilt the text track loading infrastructure — loadTextTrackCues is now a proper reactor backed by TextTrackSegmentLoaderActor, and parse-vtt-segment.ts was rewritten.

fMP4 WVTT support is still missing. The new parseVttSegment still relies on a browser <track> element to parse VTT, so it only handles plain .vtt URLs. Streams with WVTT cues packaged in fMP4/CMAF containers will still fail — the MP4 box demux step is not implemented. The root cause from the triage note stands; this needs a dedicated fix independent of the architecture work.

The original error stack trace references old line numbers that no longer apply, but the underlying behavior (failed segment load on .mp4 URLs) should reproduce the same way on the rebuilt code.