BirdCam Video Pipeline — Version 1

Drop bird-camera clips into a folder, get a reviewable vertical short plus a reproducible JSON edit manifest.

Architecture: Gemini understands the footage → structured clip database → deterministic planner → FFmpeg renders. The model never writes FFmpeg arguments; it only fills a strict JSON schema with a closed effect vocabulary.

Setup

cd path\to\video_maker
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env   # then add your GEMINI_API_KEY
python -m birdcam init

Requires FFmpeg + ffprobe on PATH (already installed).

Usage

Drop 10 or so clips into BirdCam\01_Inbox, then:

python -m birdcam run

That performs intake → Gemini analysis → planning → render → QA. The finished short lands in BirdCam\04_Review\Shorts\ next to its .qa.json report; the manifest that reproduces it is in BirdCam\Agent\manifests\.

Individual stages:

python -m birdcam intake    # hash, dedupe, probe, register new clips
python -m birdcam analyze   # Gemini video analysis -> SQLite
python -m birdcam plan      # pick best segments -> edit manifest JSON
python -m birdcam render    # manifest -> MP4 (latest manifest by default)
python -m birdcam thumbnail # vibrant funny thumbnail for a manifest (default: latest)
python -m birdcam status    # clip/project counts

Pipeline rules baked in

• Every source file is SHA-256 hashed; duplicates go to 99_Rejected.
• Source footage is never modified — clips move between folders untouched.
• Every render is reproducible from its manifest (birdcam render <manifest>).
• Shorts: 1080×1920, 20–45 s, 2–5 segments, max 2 captions, natural audio preserved, loudness-normalized, fade-out ending.
• Effects vocabulary: hard_cut, slow_zoom, punch_in, freeze_frame.
• Clips already used in a rendered short are deprioritized next time.
• QA checks: opens, aspect ratio, duration, audio present, bitrate, black frames, long silences. Report saved beside the output.

Next versions (per plan)

• V2 — watchdog folder watcher + daily Task Scheduler run
• V3 — more short styles, weekly long-form, intros/outros, AI review pass
• V4 — approval/rejection feedback loop into planning prompts