gui-video-clipper/docs/superpowers/specs/2026-09-22-paged-teleprompter-subtitles-design.md

Paged Teleprompter Burn-In Subtitle Design

Date: 2026-09-22
Scope: Rewrite the ASS subtitle generation in clip_exporter.rs to use a paged teleprompter model instead of the current per-line rolling model.

Problem

The current rolling subtitle implementation generates 3 independent ASS Dialogue events per spoken line (Active → Context → Disappear), each with \move animations. When a new line arrives, both the new and previous lines scroll simultaneously, creating a jarring "2-line block jump" instead of a natural reading flow. The active line always resets to the bottom position, breaking the top-to-bottom reading direction users expect.

Design

Core Model: 2-Line Paged Blocks

Group spoken lines into pages of 2 lines each. Each page is a single ASS Dialogue event containing both lines separated by \N (ASS hard line break). Karaoke \k tags flow continuously from line 1 through line 2 within the same Dialogue event.

Reading flow: The viewer reads the top line (karaoke highlighting progresses left-to-right), then naturally drops to the bottom line (karaoke continues), then a cross-fade transitions to the next page.

Page Construction

Given a sequence of SpokenLine structs extracted from the VTT:

1. Pair lines into consecutive groups of 2: [line0, line1], [line2, line3], …
2. If the gap between two lines within a page exceeds 2 seconds, split them into separate pages instead of combining.
3. If the total line count is odd, the final page contains a single line.

Karaoke Tag Stitching

For a 2-line page with lines A and B, the Dialogue text is:

{\k<dur>}word1_A {\k<dur>}word2_A ... {\k<dur>}lastword_A\N{\k<dur>}word1_B ... {\k<dur>}lastword_B

The \k duration for each word equals the time from that word's VTT start to the next word's VTT start. For the last word of line A, its \k duration extends to the start of line B's first word — this naturally covers any gap (silence/pause) between the two lines without any special gap-filler logic.

The \N is purely a visual line break and does not interrupt the karaoke timeline.

For lines without <c> word timing tags, the entire line text gets a single \k equal to the line's full spoken duration.

Cross-Fade Transitions

Pages transition via a 300ms cross-dissolve:

• Outgoing page: ASS end time extended by 300ms past its natural end. Uses \fad(*, 300) for a 300ms fade-out.
• Incoming page: ASS start time moved 300ms before its natural start. Uses \fad(300, *) for a 300ms fade-in.
• The 300ms overlap produces a smooth cross-dissolve between pages.

Specific \fad values:

Page Position	\fad value
First page	\fad(0, 300)
Middle pages	\fad(300, 300)
Last page	\fad(300, 0)

When pages are separated by a long gap (>2s), the outgoing page fades out and the incoming page fades in independently — no visual overlap, just a clean silence gap.

Positioning

Each Dialogue uses \an2\pos(cx, y_bottom) — bottom-center anchor. With \an2, the 2-line \N block renders with line 2 at the anchor point and line 1 stacked above it. No \move tags are used. Pages are static in position; transitions are opacity-only via \fad.

Layout constants (matching existing style):

• cx = PlayResX / 2 = 960
• y_bottom = PlayResY - margin_v = 1080 - 40 = 1040

Edge Cases

Case	Handling
Odd number of lines	Last page has 1 line (single-line Dialogue, no \N)
Gap >2s between consecutive lines within a pair	Split into separate single-line pages
Non-speech cues ([Music], [Applause])	Standalone single-line Dialogue, no karaoke, just \pos
Lines without <c> word timing	Single \k tag covering the line's full spoken duration
Only 1 spoken line total	Single-line Dialogue with \fad(0, 0)

ASS Header and Style

Unchanged from the current implementation:

• PlayResX: 1920, PlayResY: 1080, ScaledBorderAndShadow: yes
• Style parameters (font size, colours, border style, outline, margin) derived from user's CaptionStyle settings
• Alignment: 2 (bottom-center) in style definition, reinforced with \an2 override in each Dialogue

What Gets Removed

The following components of the current implementation are replaced entirely:

• RollingLayout struct (position calculation for \move animations)
• Per-line 3-phase Dialogue generation (Active/Context/Disappear)
• All \move tags
• All \clip tags
• Phase-based timing calculations

What Gets Added

• build_page_karaoke_text(lines: &[&SpokenLine]) -> String — stitches word timings from 1-2 lines into a single karaoke text with \N separator
• Page grouping logic in vtt_to_ass_with_karaoke() — pairs lines, handles gap-based splitting
• Cross-fade timing logic — computes \fad and adjusted start/end times per page

What Stays the Same

• SpokenLine struct and extract_spoken_lines() — line extraction from VTT is unchanged
• build_karaoke_text() — per-line word timing extraction (reused internally by the new page builder)
• parse_vtt_word_timings() — VTT <c> tag parser
• ASS header/style generation
• build_ffmpeg_args_burnin_subs() — FFmpeg argument construction (unchanged, still uses ass= filter)
• All other export logic (lossless, muxed subtitles, progress reporting)

Files Changed

File	Change
src-tauri/src/services/clip_exporter.rs	Rewrite vtt_to_ass_with_karaoke() to use paged model. Remove RollingLayout. Add build_page_karaoke_text().

Single file change. No frontend, no new dependencies.