Capability: captions

approved

Subtitle rendering, selection, and appearance.

Purpose

Make the videos watchable across languages and in silent contexts: render subtitle tracks over the video and let users choose their language.

Behavior

• Initial state, before any user choice in the session: a track carrying default: true in content shows captions from the start; with no flagged track, captions start off.
• User preference is law. The moment the user explicitly toggles captions, in either direction, that choice becomes the user preference: it survives every configuration update and, through the stored user state (see the config contract), page loads and later visits on the same site. A later video's default: true never re-enables captions the user turned off, and never turns off captions the user wants. Content defaults matter only until the first explicit choice.
• Track selection when enabling without a default: the track matching the player's language selector; otherwise the first track in the list.
• Feed continuity: the preference (on or off, and the chosen language) carries across configuration updates. A video without the chosen language falls back per the selection order without flipping captions off.
• Rendering: caption text renders as the centered chip in the brand accent color above the control bar, identical in both layouts.
• This behavior follows the framework principle "user choices outlive configuration updates" (see the capability model), which captions share with playback speed and volume.

The captions menu

• With a single track, there is no menu: the CC control is a plain on and off toggle.
• With multiple tracks, the CC control opens the captions menu above itself, in the chapters menu's design language: a dark panel anchored above the control bar with an off row plus one row per track. Track labels come from content.tracks[].label; the active row is marked the way the chapters menu marks its active chapter. Interface strings of the menu come from the language catalogs.
• Selecting a track enables captions with that track; the off row disables captions.
• No dedicated design frame exists for this menu; the chapters menu frames are the visual reference, and this document is the behavioral one.

Visual sizing

• Landscape cues are centered between clamp(1rem, 3.2cqi, 2rem) side insets and sit at clamp(5.5rem, 13cqi, 7rem) from the bottom. The chip is capped at min(34rem, 72%), padded 0.55rem 1rem 0.65rem, and uses a 10px radius.
• Landscape caption text uses clamp(1.05rem, 2.25cqi, 1.6rem), weight 500, and line height 1.25.
• Portrait uses clamp(0.85rem, 3cqi, 1.35rem) side insets, the donor's compound cqi/cqb bottom clamp, a 92% chip maximum, 0.45rem 0.85rem 0.55rem padding, and clamp(0.96rem, 3.8cqi, 1.28rem) text.
• The playground has no dedicated captions menu. Its shell, rows, typography, and active marker therefore use the chapter-popup values; caption-specific behavior and labels remain LT-owned.

Surface in landscape

• Caption text as the centered accent chip above the control bar.
• The CC control in the bar: toggle with one track, menu trigger with several.

Surface in portrait

• Identical to landscape: the centered accent chip is the unified caption treatment in both layouts. This deliberately overrides the plain-text caption style visible in some portrait design frames, and is an explicit exception to the portrait-first rule, which governs glyphs, not caption styling.
• The CC control behaves as in landscape.

Configuration

• Caption tracks live in content.tracks; subtitle or caption tracks make the capability available and, by default, enabled.
• default: true on a track sets the initial state only; it never overrides a user's explicit session preference.
• capabilities.captions: false disables the capability without touching the content.

{
  "content": {
    "tracks": [
      {
        "kind": "subtitles",
        "label": "English",
        "srclang": "en",
        "src": "https://cdn.example.org/videos/842/en.vtt",
        "default": true
      }
    ]
  },
  "capabilities": {
    "captions": false
  }
}

Strings

Key	English default	Placeholders	Appears in
captions	Captions	none	Control and menu label
enableCaptions	Enable captions	none	Captions control aria label
disableCaptions	Disable captions	none	Captions control aria label
captionsOn	Captions on	none	Enabled announcement
captionsOff	Captions off	none	Disabled announcement
captionsOffOption	Off	none	Captions menu row
subtitles	Subtitles	none	Track-menu label

Page API hooks

• Turn captions on or off and select a track from the page; observe caption state events. Exact names live in the page API document.

Edge cases

• A malformed or unreachable track file is treated as absent. If it was the chosen track, selection falls back per the track selection order.
• Tracks of kind subtitles and kind captions both count for availability.
• A video with no subtitle tracks leaves the capability dormant and the CC control absent; the user preference is retained for later videos that have tracks.

Out of scope

• User-facing appearance settings (text size, background) at this stage.
• Automatic translation of tracks.