VideoForge Video Pipeline

Critical

• Kling duration must be "5" or "10" (string enum) — floats like 5.00 cause Kie 500 errors
• NEVER pass Zillow photo URLs to Kling — they block external fetches. Upload to R2 first.
• negative_prompt max 500 chars — longer strings cause request body errors
• Double realtor fix: When realtor_in_frame: true, prompt MUST start with "The person is ALREADY in the frame" and MUST NOT describe person actions
• Pool safety: Realtor stands on deck, gestures toward pool, NEVER walks toward water
• Worker concurrency: 1 — only one video job per VPS at a time
• ALWAYS Kling pro mode (1080p native). NEVER use std (720p, causes blur+freezing). Runtime guardrail in kie.ts overrides std→pro. Duration: 5s for scene clips, 10s for clips paired with voiceover audio.
• Assembly: FFmpeg on VPS, Remotion for complex compositions only — Remotion OOMs on 6GB RackNerd VPS. Use FFmpeg normalize→concat→audio overlay for server-side assembly. Remotion only for local dev or Lambda with 4GB+ RAM.
• Grok Imagine for narrative/documentary clips — grok-imagine/text-to-video via Kie.ai. Pure text-to-video, no reference image needed. 5000 char prompts. Modes: fun/normal/spicy. Duration: 6/10s. Resolution: 480p/720p. Use for: documentary scenes, narrative visuals, any clip where you don't have a real reference photo. Use Kling only when you HAVE a real reference image to animate from.
• Force 1920x1080 normalization: ALL normalizeClip calls MUST pass explicit { width: config.video.outputWidth, height: config.video.outputHeight } — Kling native resolution varies per clip
• Exclude floorplan from photo pool: After detectFloorplanInPhotos(), remove floorplan URL from both flatPhotos AND additionalPhotos — otherwise it appears as a clip start frame
• Kling end-frame continuity: Parallel mode passes last_frame (next clip's room photo) to Kling so each clip morphs toward the next room — zero crossfade, seamless concat only
• Text overlay timing: Use getVideoDuration() on normalized clips for actual durations — never trust DB duration_seconds for overlay positioning
• CTA overlay minimum 4s: ctaDuration = Math.max(dur - 1.5, 4) — user must have time to read
• Sentinel clip pattern: First clip generates alone to probe Kie.ai credits before batch submission