Captions toggle in player UI doesn't activate text track on self-hosted

[julianwitzel]

Description

The Cap video player includes a captions/subtitles UI toggle, but on self-hosted deployments clicking it appears to have no effect. The captions VTT file is correctly:

• Generated by the transcription workflow
• Stored in S3 (transcription.vtt next to result.mp4)
• Loaded into the DOM as a <track kind="captions" src="blob:..."> element

However, the track's mode stays at "hidden" regardless of UI interaction.

Verified working manually

Setting the mode via JavaScript makes captions render correctly:

document.querySelector('video').textTracks[1].mode = 'showing';

This confirms the VTT file, cue parsing, and renderer are all working — only the UI toggle's binding to the track's mode is broken.

Reproduction

1. Self-host Cap, record a video with audio
2. Wait for transcription to complete (transcriptionStatus = 'COMPLETE' in DB)
3. Open the share page, click the captions toggle in the player
4. Observe: captions don't appear; track.mode remains "hidden"

Environment

• Cap web built from main (commit ~52b0acc85 / Apr 2026)
• Custom proxy.ts patches applied for /embed/ and /.well-known/ (per Self-hosted Cap Web doesn't support embeds #906/PR #906 Fix video embedding. #1415)
• Custom transcribe.ts patch for Transcription workflow fails on Docker image with Node 24 #1550
• Browser: Chrome on macOS

Possibly related: Cap uses Vidstack player which has its own captions handling — the toggle button likely sets internal player state but doesn't propagate to HTMLTrackElement.mode.

[linear]

CAP-699

[tembo]

Thanks for the detailed investigation. You've correctly identified the root cause: the captions toggle only controls the custom caption overlay rendering, not the native track.mode property.

Looking at the implementation in apps/web/app/s/[videoId]/_components/CapVideoPlayer.tsx, the track's mode is intentionally set to "hidden" and enforced via ensureTracksHidden(). This was added in PR #1075 specifically to prevent native browser caption rendering from appearing on top of Cap's custom overlay. The toggleCaptions state (line 142) only controls whether the currentCue && toggleCaptions overlay is rendered (around line 756), not the actual TextTrack.mode.

The flow for custom captions depends on:

1. Track mode staying "hidden" (allows cuechange events to fire)
2. The handleCueChange callback (line 393) updating currentCue state from activeCues
3. The overlay rendering when both currentCue and toggleCaptions are truthy

The likely issue on self-hosted is that the cuechange event listener is never being attached because setupTracks() runs in the handleLoadedMetadataWithTracks handler, but the caption <track> element may not have loaded its VTT file by that point. The blob URL loading could be async and may complete after setupTracks() already ran.

A potential fix would be adding a load event listener on the track element itself, or re-running setupTracks() after the track's readyState becomes 2 (loaded). The HLSVideoPlayer.tsx has the same pattern.

Related: This is separate from the transcription workflow issues on self-hosted (#1356, #1550) which affect whether the VTT file gets generated in the first place.