Video Module

Composes final vertical (1080x1920) TikTok videos with background footage, animated captions, background music, and optional hook audio.

VideoService

generateVideo(synthesis: SynthesisResult, post: RedditPost, hookText?: string): Promise<Result<GeneratedVideo, VideoError>>

Orchestrates video composition:

1. Validate — ensures word timestamps are present
2. Background — picks a random background clip matching the audio duration
3. Captions — generates ASS subtitle file with per-word timing
4. Music — randomly selects background music track (optional)
5. Hook SFX — selects opening sound effect (optional)
6. Compose — runs FFmpeg to mux everything together
7. Cleanup — removes intermediate subtitle file

Sub-components

BackgroundPicker

Selects from local MP4 library at a random offset. Also manages auto-downloading via BackgroundFetcher when the library is below BACKGROUND_MIN_VIDEOS.

CaptionComposer

Generates ASS (Advanced SubStation Alpha) subtitle files with word-level animation effects:

• word-highlight (default) — highlights each word as it's spoken
• karaoke — progressively fills text color
• static — centered static text

FfmpegComposer

Complex FFmpeg pipeline that:

• Scales background to target resolution
• Burns in ASS subtitles
• Mixes audio layers: narration + background music (at configured dB) + hook SFX

MusicPicker / HookPicker

Randomly select tracks from configured asset directories.

GeneratedVideo

interface GeneratedVideo {
  videoPath: string;
  durationMs: number;
  post: RedditPost;
}

Error Codes

Code	Description
NO_BACKGROUNDS	No background videos available
BACKGROUND_PROBE_FAILED	FFprobe failed on background file
SUBTITLE_GENERATION_FAILED	ASS file generation error
FFMPEG_FAILED	Video composition error
OUTPUT_MISSING	FFmpeg completed but output file not found
INVALID_INPUT	Missing word timestamps