vidpipe 1.0.0

package/dist/tools/captions/captionGenerator.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Caption generator for the Advanced SubStation Alpha (ASS) subtitle format.
+ *
+ * ### Why ASS instead of SRT/VTT?
+ * ASS supports inline style overrides — font size, color, and animation per
+ * character/word — which enables the "active word pop" karaoke effect used
+ * in modern short-form video (TikTok, Reels). SRT and VTT only support
+ * plain text or basic HTML tags with no per-word timing control.
+ *
+ * ### Karaoke word highlighting approach
+ * Instead of ASS's native `\k` karaoke tags (which highlight left-to-right
+ * within a line), we generate **one Dialogue line per word-state**. Each line
+ * renders the entire caption group but with the currently-spoken word in a
+ * different color and size. Contiguous end/start timestamps between
+ * word-states prevent flicker. This gives us full control over the visual
+ * treatment (color, font-size, scale animations) without the limitations
+ * of the `\k` tag.
+ *
+ * @module captionGenerator
+ */
+import { Transcript, CaptionStyle } from '../../types';
+export declare function generateSRT(transcript: Transcript): string;
+export declare function generateVTT(transcript: Transcript): string;
+/**
+ * Generate premium ASS captions with active-word-pop highlighting.
+ *
+ * ### How it works
+ * Words are grouped by speech bursts (split on silence gaps > 0.8s or after
+ * 8 words). Within each group, one Dialogue line is emitted per word — the
+ * full group is shown each time, but the "active" word gets a different color
+ * and larger font size. This creates a karaoke-style bounce effect.
+ *
+ * @param transcript - Full transcript with word-level timestamps
+ * @param style - Visual style: 'shorts' (large centered), 'medium' (small bottom),
+ *   or 'portrait' (Opus Clips style with green highlight + scale animation)
+ * @returns Complete ASS file content (header + dialogue lines)
+ */
+export declare function generateStyledASS(transcript: Transcript, style?: CaptionStyle): string;
+/**
+ * Generate premium ASS captions for a single contiguous segment.
+ * Filters words within [startTime, endTime] (plus buffer), adjusts timestamps
+ * relative to the clip's buffered start so they align with the extracted video.
+ */
+export declare function generateStyledASSForSegment(transcript: Transcript, startTime: number, endTime: number, buffer?: number, style?: CaptionStyle): string;
+/**
+ * Generate premium ASS captions for a composite clip made of multiple segments.
+ * Each segment's words are extracted and remapped to the concatenated timeline,
+ * accounting for the buffer added during clip extraction.
+ */
+export declare function generateStyledASSForComposite(transcript: Transcript, segments: {
+    start: number;
+    end: number;
+}[], buffer?: number, style?: CaptionStyle): string;
+/**
+ * Generate ASS dialogue lines for a hook text overlay at the top of the video.
+ *
+ * The hook is a short attention-grabbing phrase (e.g. "Here's why you should
+ * learn TypeScript") displayed as a translucent pill/badge at the top of a
+ * portrait video for the first few seconds.
+ *
+ * Uses the `Hook` style defined in {@link ASS_HEADER_PORTRAIT} which has
+ * `BorderStyle: 3` (opaque box background) and `Alignment: 8` (top-center).
+ *
+ * The `\fad(300,500)` tag creates a 300ms fade-in and 500ms fade-out so the
+ * hook doesn't appear/disappear abruptly.
+ *
+ * @param hookText - The attention-grabbing phrase (truncated to 60 chars)
+ * @param displayDuration - How long to show the hook in seconds (default: 4s)
+ * @param _style - Caption style (currently only 'portrait' uses hooks)
+ * @returns A single ASS Dialogue line to append to the Events section
+ */
+export declare function generateHookOverlay(hookText: string, displayDuration?: number, _style?: CaptionStyle): string;
+/**
+ * Generate a complete portrait ASS file with captions AND hook text overlay.
+ */
+export declare function generatePortraitASSWithHook(transcript: Transcript, hookText: string, startTime: number, endTime: number, buffer?: number): string;
+/**
+ * Generate a complete portrait ASS file for a composite clip with captions AND hook text overlay.
+ */
+export declare function generatePortraitASSWithHookComposite(transcript: Transcript, segments: {
+    start: number;
+    end: number;
+}[], hookText: string, buffer?: number): string;
+//# sourceMappingURL=captionGenerator.d.ts.map

package/dist/tools/captions/captionGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captionGenerator.d.ts","sourceRoot":"","sources":["../../../src/tools/captions/captionGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAiB,YAAY,EAAE,MAAM,aAAa,CAAA;AA+ErE,wBAAgB,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAW1D;AAMD,wBAAgB,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAW1D;AA6LD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,GAAE,YAAuB,GAAG,MAAM,CAMhG;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,MAAY,EACpB,KAAK,GAAE,YAAuB,GAC7B,MAAM,CAiBR;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,EAC1C,MAAM,GAAE,MAAY,EACpB,KAAK,GAAE,YAAuB,GAC7B,MAAM,CA4BR;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,eAAe,GAAE,MAAY,EAC7B,MAAM,GAAE,YAAyB,GAChC,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,oCAAoC,CAClD,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,EAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAIR"}

package/dist/tools/captions/captionGenerator.js

@@ -0,0 +1,390 @@
+/**
+ * Caption generator for the Advanced SubStation Alpha (ASS) subtitle format.
+ *
+ * ### Why ASS instead of SRT/VTT?
+ * ASS supports inline style overrides — font size, color, and animation per
+ * character/word — which enables the "active word pop" karaoke effect used
+ * in modern short-form video (TikTok, Reels). SRT and VTT only support
+ * plain text or basic HTML tags with no per-word timing control.
+ *
+ * ### Karaoke word highlighting approach
+ * Instead of ASS's native `\k` karaoke tags (which highlight left-to-right
+ * within a line), we generate **one Dialogue line per word-state**. Each line
+ * renders the entire caption group but with the currently-spoken word in a
+ * different color and size. Contiguous end/start timestamps between
+ * word-states prevent flicker. This gives us full control over the visual
+ * treatment (color, font-size, scale animations) without the limitations
+ * of the `\k` tag.
+ *
+ * @module captionGenerator
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Pad a number to a fixed width with leading zeros. */
+function pad(n, width) {
+    return String(n).padStart(width, '0');
+}
+/** Convert seconds → SRT timestamp  "HH:MM:SS,mmm" */
+function toSRT(seconds) {
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    const s = Math.floor(seconds % 60);
+    const ms = Math.round((seconds - Math.floor(seconds)) * 1000);
+    return `${pad(h, 2)}:${pad(m, 2)}:${pad(s, 2)},${pad(ms, 3)}`;
+}
+/** Convert seconds → VTT timestamp  "HH:MM:SS.mmm" */
+function toVTT(seconds) {
+    return toSRT(seconds).replace(',', '.');
+}
+/** Convert seconds → ASS timestamp  "H:MM:SS.cc" */
+function toASS(seconds) {
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    const s = Math.floor(seconds % 60);
+    const cs = Math.round((seconds - Math.floor(seconds)) * 100);
+    return `${h}:${pad(m, 2)}:${pad(s, 2)}.${pad(cs, 2)}`;
+}
+// ---------------------------------------------------------------------------
+// Premium caption constants
+// ---------------------------------------------------------------------------
+/** Silence gap threshold in seconds – gaps longer than this split caption groups. */
+const SILENCE_GAP_THRESHOLD = 0.8;
+/** Maximum words displayed simultaneously in a caption group. */
+const MAX_WORDS_PER_GROUP = 8;
+/** Target words per display line within a group (splits into 2 lines above this). */
+const WORDS_PER_LINE = 4;
+/** ASS BGR color for the active (currently-spoken) word – yellow. */
+const ACTIVE_COLOR = '\\c&H00FFFF&';
+/** ASS BGR color for inactive words – white. */
+const BASE_COLOR = '\\c&HFFFFFF&';
+/** Font size for the active word. */
+const ACTIVE_FONT_SIZE = 54;
+/** Font size for inactive words (matches style default). */
+const BASE_FONT_SIZE = 42;
+// ---------------------------------------------------------------------------
+// Medium caption constants (smaller, bottom-positioned for longer content)
+// ---------------------------------------------------------------------------
+/** Font size for the active word in medium style. */
+const MEDIUM_ACTIVE_FONT_SIZE = 40;
+/** Font size for inactive words in medium style. */
+const MEDIUM_BASE_FONT_SIZE = 32;
+// ---------------------------------------------------------------------------
+// Portrait caption constants (Opus Clips style)
+// ---------------------------------------------------------------------------
+/** Font size for the active word in portrait style. */
+const PORTRAIT_ACTIVE_FONT_SIZE = 78;
+/** Font size for inactive words in portrait style. */
+const PORTRAIT_BASE_FONT_SIZE = 66;
+/** ASS BGR color for the active word in portrait style – green. */
+const PORTRAIT_ACTIVE_COLOR = '\\c&H00FF00&';
+/** ASS BGR color for inactive words in portrait style – white. */
+const PORTRAIT_BASE_COLOR = '\\c&HFFFFFF&';
+// ---------------------------------------------------------------------------
+// SRT (segment-level)
+// ---------------------------------------------------------------------------
+export function generateSRT(transcript) {
+    return transcript.segments
+        .map((seg, i) => {
+        const idx = i + 1;
+        const start = toSRT(seg.start);
+        const end = toSRT(seg.end);
+        const text = seg.text.trim();
+        return `${idx}\n${start} --> ${end}\n${text}`;
+    })
+        .join('\n\n')
+        .concat('\n');
+}
+// ---------------------------------------------------------------------------
+// VTT (segment-level)
+// ---------------------------------------------------------------------------
+export function generateVTT(transcript) {
+    const cues = transcript.segments
+        .map((seg) => {
+        const start = toVTT(seg.start);
+        const end = toVTT(seg.end);
+        const text = seg.text.trim();
+        return `${start} --> ${end}\n${text}`;
+    })
+        .join('\n\n');
+    return `WEBVTT\n\n${cues}\n`;
+}
+// ---------------------------------------------------------------------------
+// ASS – Premium active-word-pop captions
+// ---------------------------------------------------------------------------
+/**
+ * ASS header for landscape (16:9, 1920×1080) captions.
+ *
+ * ### Style fields explained (comma-separated in the Style line):
+ * - `Fontname: Montserrat` — bundled with the project; FFmpeg's `ass` filter
+ *   uses `fontsdir=.` so libass finds the .ttf files next to the .ass file.
+ * - `Fontsize: 42` — base size for inactive words
+ * - `PrimaryColour: &H00FFFFFF` — white (ASS uses `&HAABBGGRR` — alpha, blue, green, red)
+ * - `OutlineColour: &H00000000` — black outline for readability on any background
+ * - `BackColour: &H80000000` — 50% transparent black shadow
+ * - `Bold: 1` — bold for better readability at small sizes
+ * - `BorderStyle: 1` — outline + drop shadow (not opaque box)
+ * - `Outline: 3` — 3px outline thickness
+ * - `Shadow: 1` — 1px drop shadow
+ * - `Alignment: 2` — bottom-center (SSA alignment: 1=left, 2=center, 3=right;
+ *   add 4 for top, 8 for middle — so 2 = bottom-center)
+ * - `MarginV: 40` — 40px above the bottom edge
+ * - `WrapStyle: 0` — smart word wrap
+ */
+const ASS_HEADER = `[Script Info]
+Title: Auto-generated captions
+ScriptType: v4.00+
+PlayResX: 1920
+PlayResY: 1080
+WrapStyle: 0
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Default,Montserrat,42,&H00FFFFFF,&H0000FFFF,&H00000000,&H80000000,1,0,0,0,100,100,0,0,1,3,1,2,20,20,40,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+`;
+/**
+ * ASS header for portrait (9:16, 1080×1920) captions — used for shorts.
+ *
+ * Key differences from the landscape header:
+ * - `PlayResX/Y: 1080×1920` — matches portrait video dimensions
+ * - `Fontsize: 78` — larger base font for vertical video viewing (small screens)
+ * - `MarginV: 700` — pushes captions to the center-bottom area, leaving room
+ *   for the hook overlay at the top
+ * - Includes a `Hook` style: semi-transparent pill/badge background
+ *   (`BorderStyle: 3` = opaque box) for the opening hook text overlay
+ */
+const ASS_HEADER_PORTRAIT = `[Script Info]
+Title: Auto-generated captions
+ScriptType: v4.00+
+PlayResX: 1080
+PlayResY: 1920
+WrapStyle: 0
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Default,Montserrat,78,&H00FFFFFF,&H0000FFFF,&H00000000,&H80000000,1,0,0,0,100,100,0,0,1,3,1,2,30,30,700,1
+Style: Hook,Montserrat,56,&H00333333,&H00333333,&H60D0D0D0,&H60E0E0E0,1,0,0,0,100,100,2,0,3,18,2,8,80,80,60,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+`;
+/**
+ * ASS header for medium-style captions (1920×1080 but smaller font).
+ *
+ * Used for longer clips where large captions would be distracting.
+ * - `Fontsize: 32` — smaller than the shorts style
+ * - `Alignment: 2` — bottom-center
+ * - `MarginV: 60` — slightly higher from the bottom edge to avoid UI overlaps
+ */
+const ASS_HEADER_MEDIUM = `[Script Info]
+Title: Auto-generated captions
+ScriptType: v4.00+
+PlayResX: 1920
+PlayResY: 1080
+WrapStyle: 0
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Default,Montserrat,32,&H00FFFFFF,&H0000FFFF,&H00000000,&H80000000,1,0,0,0,100,100,0,0,1,2,1,2,20,20,60,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+`;
+/**
+ * Group words into caption groups split on silence gaps and max word count.
+ * All words within a group are displayed simultaneously; captions disappear
+ * entirely during gaps longer than SILENCE_GAP_THRESHOLD.
+ */
+function groupWordsBySpeech(words) {
+    if (words.length === 0)
+        return [];
+    const groups = [];
+    let current = [];
+    for (let i = 0; i < words.length; i++) {
+        current.push(words[i]);
+        const isLast = i === words.length - 1;
+        const hasGap = !isLast && words[i + 1].start - words[i].end > SILENCE_GAP_THRESHOLD;
+        const atMax = current.length >= MAX_WORDS_PER_GROUP;
+        if (isLast || hasGap || atMax) {
+            groups.push(current);
+            current = [];
+        }
+    }
+    return groups;
+}
+/**
+ * Split a caption group into 1–2 display lines.
+ * Groups with ≤ WORDS_PER_LINE words stay on one line; larger groups
+ * are split at the midpoint into two lines joined with \\N.
+ */
+function splitGroupIntoLines(group) {
+    if (group.length <= WORDS_PER_LINE)
+        return [group];
+    const mid = Math.ceil(group.length / 2);
+    return [group.slice(0, mid), group.slice(mid)];
+}
+/**
+ * Build premium ASS dialogue lines with active-word highlighting.
+ * Generates one Dialogue line per word-state: the full caption group is
+ * rendered with the currently-spoken word in yellow at a larger size while
+ * all other words stay white at the base size.  Contiguous end/start times
+ * between word-states prevent flicker.
+ */
+function buildPremiumDialogueLines(words, style = 'shorts') {
+    const activeFontSize = style === 'portrait' ? PORTRAIT_ACTIVE_FONT_SIZE
+        : style === 'medium' ? MEDIUM_ACTIVE_FONT_SIZE : ACTIVE_FONT_SIZE;
+    const baseFontSize = style === 'portrait' ? PORTRAIT_BASE_FONT_SIZE
+        : style === 'medium' ? MEDIUM_BASE_FONT_SIZE : BASE_FONT_SIZE;
+    const groups = groupWordsBySpeech(words);
+    const dialogues = [];
+    for (const group of groups) {
+        const displayLines = splitGroupIntoLines(group);
+        for (let activeIdx = 0; activeIdx < group.length; activeIdx++) {
+            const activeWord = group[activeIdx];
+            // Contiguous timing: end = next word's start, or this word's own end
+            const endTime = activeIdx < group.length - 1
+                ? group[activeIdx + 1].start
+                : activeWord.end;
+            // Render all words across display lines with the active word highlighted
+            const renderedLines = [];
+            let globalIdx = 0;
+            for (const line of displayLines) {
+                const rendered = line.map((w) => {
+                    const idx = globalIdx++;
+                    const text = w.word.trim();
+                    if (idx === activeIdx) {
+                        if (style === 'portrait') {
+                            // Opus Clips style: green color + scale pop animation
+                            return `{${PORTRAIT_ACTIVE_COLOR}\\fs${activeFontSize}\\fscx130\\fscy130\\t(0,150,\\fscx100\\fscy100)}${text}`;
+                        }
+                        return `{${ACTIVE_COLOR}\\fs${activeFontSize}}${text}`;
+                    }
+                    if (style === 'portrait') {
+                        return `{${PORTRAIT_BASE_COLOR}\\fs${baseFontSize}}${text}`;
+                    }
+                    return `{${BASE_COLOR}\\fs${baseFontSize}}${text}`;
+                });
+                renderedLines.push(rendered.join(' '));
+            }
+            const text = renderedLines.join('\\N');
+            dialogues.push(`Dialogue: 0,${toASS(activeWord.start)},${toASS(endTime)},Default,,0,0,0,,${text}`);
+        }
+    }
+    return dialogues;
+}
+/**
+ * Generate premium ASS captions with active-word-pop highlighting.
+ *
+ * ### How it works
+ * Words are grouped by speech bursts (split on silence gaps > 0.8s or after
+ * 8 words). Within each group, one Dialogue line is emitted per word — the
+ * full group is shown each time, but the "active" word gets a different color
+ * and larger font size. This creates a karaoke-style bounce effect.
+ *
+ * @param transcript - Full transcript with word-level timestamps
+ * @param style - Visual style: 'shorts' (large centered), 'medium' (small bottom),
+ *   or 'portrait' (Opus Clips style with green highlight + scale animation)
+ * @returns Complete ASS file content (header + dialogue lines)
+ */
+export function generateStyledASS(transcript, style = 'shorts') {
+    const header = style === 'portrait' ? ASS_HEADER_PORTRAIT : style === 'medium' ? ASS_HEADER_MEDIUM : ASS_HEADER;
+    const allWords = transcript.words;
+    if (allWords.length === 0)
+        return header;
+    return header + buildPremiumDialogueLines(allWords, style).join('\n') + '\n';
+}
+/**
+ * Generate premium ASS captions for a single contiguous segment.
+ * Filters words within [startTime, endTime] (plus buffer), adjusts timestamps
+ * relative to the clip's buffered start so they align with the extracted video.
+ */
+export function generateStyledASSForSegment(transcript, startTime, endTime, buffer = 1.0, style = 'shorts') {
+    const header = style === 'portrait' ? ASS_HEADER_PORTRAIT : style === 'medium' ? ASS_HEADER_MEDIUM : ASS_HEADER;
+    const bufferedStart = Math.max(0, startTime - buffer);
+    const bufferedEnd = endTime + buffer;
+    const words = transcript.words.filter((w) => w.start >= bufferedStart && w.end <= bufferedEnd);
+    if (words.length === 0)
+        return header;
+    const adjusted = words.map((w) => ({
+        word: w.word,
+        start: w.start - bufferedStart,
+        end: w.end - bufferedStart,
+    }));
+    return header + buildPremiumDialogueLines(adjusted, style).join('\n') + '\n';
+}
+/**
+ * Generate premium ASS captions for a composite clip made of multiple segments.
+ * Each segment's words are extracted and remapped to the concatenated timeline,
+ * accounting for the buffer added during clip extraction.
+ */
+export function generateStyledASSForComposite(transcript, segments, buffer = 1.0, style = 'shorts') {
+    const header = style === 'portrait' ? ASS_HEADER_PORTRAIT : style === 'medium' ? ASS_HEADER_MEDIUM : ASS_HEADER;
+    const allAdjusted = [];
+    let runningOffset = 0;
+    for (const seg of segments) {
+        const bufferedStart = Math.max(0, seg.start - buffer);
+        const bufferedEnd = seg.end + buffer;
+        const segDuration = bufferedEnd - bufferedStart;
+        const words = transcript.words.filter((w) => w.start >= bufferedStart && w.end <= bufferedEnd);
+        for (const w of words) {
+            allAdjusted.push({
+                word: w.word,
+                start: w.start - bufferedStart + runningOffset,
+                end: w.end - bufferedStart + runningOffset,
+            });
+        }
+        runningOffset += segDuration;
+    }
+    if (allAdjusted.length === 0)
+        return header;
+    return header + buildPremiumDialogueLines(allAdjusted, style).join('\n') + '\n';
+}
+// ---------------------------------------------------------------------------
+// Hook text overlay for portrait shorts
+// ---------------------------------------------------------------------------
+/** Maximum characters for hook text before truncation. */
+const HOOK_TEXT_MAX_LENGTH = 60;
+/**
+ * Generate ASS dialogue lines for a hook text overlay at the top of the video.
+ *
+ * The hook is a short attention-grabbing phrase (e.g. "Here's why you should
+ * learn TypeScript") displayed as a translucent pill/badge at the top of a
+ * portrait video for the first few seconds.
+ *
+ * Uses the `Hook` style defined in {@link ASS_HEADER_PORTRAIT} which has
+ * `BorderStyle: 3` (opaque box background) and `Alignment: 8` (top-center).
+ *
+ * The `\fad(300,500)` tag creates a 300ms fade-in and 500ms fade-out so the
+ * hook doesn't appear/disappear abruptly.
+ *
+ * @param hookText - The attention-grabbing phrase (truncated to 60 chars)
+ * @param displayDuration - How long to show the hook in seconds (default: 4s)
+ * @param _style - Caption style (currently only 'portrait' uses hooks)
+ * @returns A single ASS Dialogue line to append to the Events section
+ */
+export function generateHookOverlay(hookText, displayDuration = 4.0, _style = 'portrait') {
+    const text = hookText.length > HOOK_TEXT_MAX_LENGTH
+        ? hookText.slice(0, HOOK_TEXT_MAX_LENGTH - 3) + '...'
+        : hookText;
+    return `Dialogue: 1,${toASS(0)},${toASS(displayDuration)},Hook,,0,0,0,,{\\fad(300,500)}${text}`;
+}
+/**
+ * Generate a complete portrait ASS file with captions AND hook text overlay.
+ */
+export function generatePortraitASSWithHook(transcript, hookText, startTime, endTime, buffer) {
+    const baseASS = generateStyledASSForSegment(transcript, startTime, endTime, buffer, 'portrait');
+    const hookLine = generateHookOverlay(hookText, 4.0, 'portrait');
+    return baseASS + hookLine + '\n';
+}
+/**
+ * Generate a complete portrait ASS file for a composite clip with captions AND hook text overlay.
+ */
+export function generatePortraitASSWithHookComposite(transcript, segments, hookText, buffer) {
+    const baseASS = generateStyledASSForComposite(transcript, segments, buffer, 'portrait');
+    const hookLine = generateHookOverlay(hookText, 4.0, 'portrait');
+    return baseASS + hookLine + '\n';
+}
+//# sourceMappingURL=captionGenerator.js.map

package/dist/tools/captions/captionGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captionGenerator.js","sourceRoot":"","sources":["../../../src/tools/captions/captionGenerator.ts"],"names":[],"mappings":"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"}

package/dist/tools/ffmpeg/aspectRatio.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Supported output aspect ratios.
+ * - `16:9` — standard landscape (YouTube, desktop)
+ * - `9:16` — portrait / vertical (TikTok, Reels, Shorts)
+ * - `1:1`  — square (LinkedIn, Twitter)
+ * - `4:5`  — tall feed (Instagram feed)
+ */
+export type AspectRatio = '16:9' | '9:16' | '1:1' | '4:5';
+/** Social-media platforms we generate video variants for. */
+export type Platform = 'tiktok' | 'youtube-shorts' | 'instagram-reels' | 'instagram-feed' | 'linkedin' | 'youtube' | 'twitter';
+/**
+ * Maps each platform to its preferred aspect ratio.
+ * Multiple platforms may share a ratio (e.g. TikTok + Reels both use 9:16),
+ * which lets {@link generatePlatformVariants} deduplicate encodes.
+ */
+export declare const PLATFORM_RATIOS: Record<Platform, AspectRatio>;
+/**
+ * Canonical pixel dimensions for each aspect ratio.
+ * Width is always 1080 px for non-landscape ratios (the standard vertical
+ * video width); landscape stays at 1920×1080 for full HD.
+ */
+export declare const DIMENSIONS: Record<AspectRatio, {
+    width: number;
+    height: number;
+}>;
+export interface ConvertOptions {
+    /** Fallback to letterbox/pillarbox instead of cropping (default: false) */
+    letterbox?: boolean;
+}
+/**
+ * Convert a video's aspect ratio using FFmpeg center-crop.
+ *
+ * - 16:9 → 9:16: crops the center column to portrait
+ * - 16:9 → 1:1:  crops to a center square
+ * - Same ratio:  stream-copies without re-encoding
+ *
+ * @returns The output path on success
+ */
+export declare function convertAspectRatio(inputPath: string, outputPath: string, targetRatio: AspectRatio, options?: ConvertOptions): Promise<string>;
+/**
+ * Smart portrait (9:16) conversion → 1080×1920.
+ *
+ * Screen panel: 1080×1248 (65%), Webcam panel: 1080×672 (35%).
+ * Total: 1080×1920 — standard TikTok / Reels / Shorts dimensions.
+ *
+ * Falls back to center-crop 9:16 if no webcam is detected.
+ *
+ * @param inputPath - Source landscape video
+ * @param outputPath - Destination path for the portrait video
+ */
+export declare function convertToPortraitSmart(inputPath: string, outputPath: string): Promise<string>;
+/**
+ * Smart square (1:1) conversion → 1080×1080.
+ *
+ * Screen panel: 1080×700 (65%), Webcam panel: 1080×380 (35%).
+ * Total: 1080×1080 — standard LinkedIn / Twitter square format.
+ *
+ * Falls back to center-crop 1:1 if no webcam is detected.
+ *
+ * @param inputPath - Source landscape video
+ * @param outputPath - Destination path for the square video
+ */
+export declare function convertToSquareSmart(inputPath: string, outputPath: string): Promise<string>;
+/**
+ * Smart feed (4:5) conversion → 1080×1350.
+ *
+ * Screen panel: 1080×878 (65%), Webcam panel: 1080×472 (35%).
+ * Total: 1080×1350 — Instagram feed's preferred tall format.
+ *
+ * Falls back to center-crop 4:5 if no webcam is detected.
+ *
+ * @param inputPath - Source landscape video
+ * @param outputPath - Destination path for the 4:5 video
+ */
+export declare function convertToFeedSmart(inputPath: string, outputPath: string): Promise<string>;
+/**
+ * Generate platform-specific aspect-ratio variants of a short clip.
+ *
+ * ### Routing logic
+ * 1. Maps each requested platform to its aspect ratio via {@link PLATFORM_RATIOS}.
+ * 2. **Deduplicates by ratio** — if TikTok and Reels both need 9:16, only one
+ *    encode is performed and both platforms reference the same output file.
+ * 3. Skips 16:9 entirely since the source is already landscape.
+ * 4. Routes each ratio to its smart converter (portrait / square / feed) for
+ *    split-screen layout, falling back to {@link convertAspectRatio} for any
+ *    ratio without a smart converter.
+ *
+ * @param inputPath - Source video (16:9 landscape)
+ * @param outputDir - Directory to write variant files into
+ * @param slug - Base filename slug (e.g. "my-video-short-1")
+ * @param platforms - Platforms to generate for (default: tiktok + linkedin)
+ * @returns Array of variant metadata (one entry per platform, deduplicated files)
+ */
+export declare function generatePlatformVariants(inputPath: string, outputDir: string, slug: string, platforms?: Platform[]): Promise<{
+    platform: Platform;
+    aspectRatio: AspectRatio;
+    path: string;
+    width: number;
+    height: number;
+}[]>;
+//# sourceMappingURL=aspectRatio.d.ts.map

package/dist/tools/ffmpeg/aspectRatio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aspectRatio.d.ts","sourceRoot":"","sources":["../../../src/tools/ffmpeg/aspectRatio.ts"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;AAEzD,6DAA6D;AAC7D,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,UAAU,GACV,SAAS,GACT,SAAS,CAAA;AAEb;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,WAAW,CAQzD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAK7E,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAiDD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,WAAW,EACxB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAuCjB;AAiJD;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,QAAQ,EAA2B,GAC7C,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,WAAW,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAwC1G"}