feat: add wordsPerLine and activeColor support to Captions

[SecurityQQ]

Summary

• Add wordsPerLine prop to <Captions> that groups N words per subtitle line instead of showing one word at a time
• Wire up activeColor prop (was defined in types but never used) to highlight the currently-spoken word with a different color using ASS \c override tags
• Fix overlapping subtitle lines at group boundaries by capping group end times to the next group's start time

Usage

<Captions 
  src={voiceover} 
  style="tiktok" 
  color="#ffffff"           // base word color
  activeColor="#FF8C42"     // highlighted active word
  fontSize={72} 
  wordsPerLine={3}          // show 3 words at a time
/>

Backward compatible

Omitting wordsPerLine keeps the existing 1-word-at-a-time behavior. No changes to existing templates required.

Tests

• 3 new unit tests for SRT conversion
• All 9 renderer tests pass

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

walkthrough

added word-level karaoke-style caption highlighting via convertSrtToAssGrouped, which chunks SRT entries and applies color overrides to active words in ASS format. extended caption and title props with wordsPerLine and font config options. included comprehensive tests for SRT-to-ASS conversion.

changes

cohort / file(s)	summary
caption rendering src/react/renderers/captions.ts	introduced convertSrtToAssGrouped() to group SRT entries by wordsPerLine and emit dialogues with per-word ASS color overrides. updated renderCaptions to compute activeColorAss and route between grouped and standard ASS conversion based on props.wordsPerLine.
type definitions src/react/types.ts	added fontPath and fontFamily optional properties to TitleProps, and wordsPerLine optional property to CaptionsProps for controlling word grouping in karaoke-style highlighting.
caption tests src/react/renderers/captions.test.ts	added test suite validating convertToSRT output, SRT-to-entry parsing, and word-level grouping via local parseSrt helper with regex-based time parsing and precision assertions.

sequence diagram(s)

sequenceDiagram
    participant Client
    participant renderCaptions as renderCaptions
    participant convertSrtToAss as convertSrtToAss
    participant convertSrtToAssGrouped as convertSrtToAssGrouped
    participant ASS as ASS Output

    Client->>renderCaptions: captions + wordsPerLine + activeColor
    renderCaptions->>renderCaptions: compute activeColorAss
    
    alt wordsPerLine provided
        renderCaptions->>convertSrtToAssGrouped: pass SRT + grouping params
        convertSrtToAssGrouped->>convertSrtToAssGrouped: parse & chunk SRT by wordsPerLine
        convertSrtToAssGrouped->>convertSrtToAssGrouped: apply \\c color overrides per word
        convertSrtToAssGrouped->>ASS: emit grouped dialogues with colors
    else standard flow
        renderCaptions->>convertSrtToAss: pass SRT (no grouping)
        convertSrtToAss->>ASS: emit standard dialogues
    end
    
    ASS->>Client: formatted caption output

Loading

estimated code review effort

🎯 3 (moderate) | ⏱️ ~22 minutes

possibly related prs

• feat: add fontPath and fontFamily props to Title component #181: both prs add fontPath and fontFamily to titleprops in the same type definitions file.
• feat: add withAudio prop to Captions — default to no audio #160: both prs extend captionsprops and modify the captions renderer (rendercaptions), impacting the same code paths.
• fix(captions): fix stretched text, compression artifacts, and add position prop #66: both prs modify src/react/renderers/captions.ts; the retrieved pr changes convertsrttoass behavior which directly affects the new pr's use of that function and its new convertsrttoassgrouped.

poem

🎨 words dance in color, each one glows ✨
grouped and timed, karaoke prose
fonts cascade, styling flows
caption magic—meow!—the feature grows 🎬

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	the title clearly and concisely summarizes the main changes: adding wordsPerLine and activeColor support to the captions component.
Description check	✅ Passed	the description is directly related to the changeset, detailing the new props, usage example, and testing approach that align with the file modifications.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/karaoke-captions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}