--- description: "Synchronized caption display with word-level highlighting, custom styling via CSS parts, and WebVTT/JSON caption file support." --- # ef-captions ## Attributes - **target** (string) - Selector for ef-video or ef-audio element - **captions-script** (string) - ID of script element with JSON captions - **captions-src** (string) - URL to JSON captions file - **captions-data** (object) - Direct captions data object # Captions Synchronized captions with word highlighting. ## Import ```tsx import { Captions, CaptionsSegment, CaptionsActiveWord, CaptionsBeforeActiveWord, CaptionsAfterActiveWord } from "@editframe/react"; ``` ## Basic Usage ```html live ``` ```tsx ``` ## Caption Data Format ```json { "segments": [ { "start": 0, "end": 3, "text": "Sentence one." } ], "word_segments": [ { "start": 0, "end": 0.5, "text": "Sentence" }, { "start": 0.5, "end": 1.0, "text": "one." } ] } ``` Times are in seconds relative to the parent timegroup. ```json { "segments": [ { "text": "Hello world", "start": 0, "end": 2000, "words": [ { "word": "Hello", "start": 0, "end": 500 }, { "word": "world", "start": 500, "end": 2000 } ] } ] } ``` ## With Video ```tsx import { Timegroup, Video, Captions } from "@editframe/react"; ``` ## Styled Segments Use caption components for custom styling: ```tsx ``` ## Word Highlighting ```tsx ``` ## Background Box ```tsx ``` ## Active Word Styling ### Color Highlighting ```html live ``` ### Background Box Style ```html live ``` ### Underline and Shadow ```html live ``` ### Animated Pop Effect ```html live ``` ### Slide-In Animation ```html live ``` ## Segment-Level Styling ### Full Segment Display ```html live ``` ### Multi-Line Segments ```html live ``` ## Karaoke-Style Captions ### Classic Karaoke ```html live ``` ### Progress Bar Karaoke ```html live
``` ### Gradient Progression ```html live ``` ## Custom Timing Examples ### Fast-Paced Captions ```html live ``` ### Slow Dramatic Timing ```html live ``` ### Multiple Speakers ```html live ``` ## Loading Captions ### From External File ```html ``` ### From Inline Script ```html ``` ### Via JavaScript ```html ``` ## Sub-Elements `ef-captions` uses child elements to separate caption text into styleable parts. These elements act as **slots** — they're containers that `ef-captions` fills with text. You style them with CSS classes, and `ef-captions` handles updating their content. All caption sub-elements use `display: inline` by default for natural text flow. They act as transparent containers — the text flows as if the element boundaries don't exist. ### ef-captions-active-word The word currently being spoken. Automatically hidden when empty or contains only punctuation. **CSS Variables:** - `--ef-word-seed` - Deterministic random (0-1) per word for animations **Behavior:** - Adds trailing space automatically for proper word spacing - Hidden via `hidden` attribute when no active word ### ef-captions-before-active-word All words in the current segment that have already been spoken. **Behavior:** - Adds trailing space when followed by active word - Hidden via `hidden` attribute when no prior words ### ef-captions-after-active-word All words in the current segment not yet spoken. **Behavior:** - No leading space (active word adds trailing space) - Hidden via `hidden` attribute when no upcoming words ### ef-captions-segment The full text of the current caption segment. **Behavior:** - Hidden via `hidden` attribute when no active segment - Can be used alone or alongside word-level elements ### Layout Patterns ```html
``` ### Technical Notes - All sub-elements use light DOM (not shadow DOM) for styling simplicity - Parent `ef-captions` element updates child `textContent` directly - Empty or punctuation-only content automatically hides elements via `hidden` attribute - Elements maintain text flow by using `display: inline` with no margins/padding - `--ef-word-seed` provides deterministic randomness based on word index (not random each frame) ## Generate Captions Use the Editframe CLI to generate captions from video/audio files: ```bash npx editframe transcribe video.mp4 -o captions.json ``` ```bash # Transcribe with specific language npx editframe transcribe video.mp4 --language en -o captions.json # Transcribe audio file npx editframe transcribe audio.mp3 -o captions.json ``` Then load the generated captions: ```html live ``` See [transcription.md](references/transcription.md) for complete transcription workflow documentation. This uses `whisper_timestamped` to create word-level timestamps. Install it first: ```bash pip3 install whisper-timestamped ``` See [references/transcription.md](references/transcription.md) for more details. ## Multiple Caption Tracks ```tsx ``` ## Dynamic Captions ```tsx interface CaptionTrack { id: string; src: string; language: string; } const tracks: CaptionTrack[] = [ { id: "en", src: "/assets/captions-en.json", language: "English" }, { id: "es", src: "/assets/captions-es.json", language: "Spanish" }, ]; const [selectedTrack, setSelectedTrack] = useState(tracks[0]); ```