AI Film Studio

End-to-end AI film production for Claude Code. The agent handles creative decisions (story, prompts, pacing); pre-built scripts handle the API plumbing across image, video, audio, and final assembly.

What it does

Stage	Tool	Backed by
Inspiration / reference analysis	`analyze_reference.py`	Gemini video understanding (`gemini-3.8-flash`), ffmpeg scene detection, yt-dlp
Storyboard stills	`generate_image_gpt.py` (+ `generate_image_byteplus.py`, `generate_image_gemini.py`)	GPT Image 2 (OpenAI); Seedream 5 (Ark) and Nano Banana (Gemini) as fallbacks
Cinematic video	`generate_video_omni.py`, `generate_video_seedance.py`, `generate_video_ltx.py` (+ `generate_video_veo.py`)	Gemini Omni 1.1 Flash, Seedance 2.5 / 2.0 / mini, LTX 2.5 / 2.3; Veo 3.1 fallback
Voiceover / music / SFX	`generate_tts.py`, `generate_music.py`, `generate_sfx.py`	ElevenLabs
Asset hosting	`media_host.py` auto-uploads local refs	Amazon S3 (presigned or public URL); only needed for Seedance / Seedream
Assembly (fast)	`assemble.py`	ffmpeg
Assembly (graphics, transitions, captions)	`new_hyperframes_project.sh` + `build_hyperframes_timeline.py` + `render_hyperframes.sh`	HyperFrames (HTML → MP4; replaced Remotion, which lives in `legacy/`)

Works for short films, ads, product promos and social reels. Character consistency, first/last-frame interpolation, clip extension, audio-to-video, retakes, reference-video-driven generation (Seedance 2.5) and prompt guides for each model are documented in SKILL.md and reference/.

Install

With the open-source skills CLI (works for Claude Code, OpenCode, Codex, Cursor, and 50+ other agents):

npx skills add realaman90/skills          # interactive
npx skills add realaman90/skills -g -y    # global, non-interactive

Or clone straight into Claude Code's skills directory:

git clone https://github.com/realaman90/skills.git ~/.claude/skills/ai-film-studio

Either way, install the Python deps:

pip install -r requirements.txt
brew install ffmpeg          # macOS
node --version               # 22+ (HyperFrames renders via npx, pinned to [email protected])

Trigger words: film, movie, video, storyboard, animate, scene, voiceover, narration, soundtrack, clip, short film.

Setup

cp config.env.example config.env
# fill in your keys, then:
source config.env

Required keys (free tiers exist for most):

Key	Provider	Used by
`OPENAI_API_KEY`	OpenAI	GPT Image 2 stills
`GEMINI_API_KEY`	Google AI Studio	Omni video, reference-video analysis, Nano Banana / Veo fallbacks
`ELEVENLABS_KEY`, `ELEVENLABS_VOICE`	ElevenLabs	voice, music, SFX
`ARK_API_KEY`	BytePlus Ark	Seedance 2.5 / 2.0, Seedream 5
`LTXV_API_KEY`	LTX Video	LTX 2.5 / 2.3
`S3_BUCKET`, `S3_REGION`, `AWS_*`	Amazon S3	hosts local images/videos as URLs for Seedance / Seedream (`S3_PUBLIC_URL` optional; presigned URLs otherwise)

Quick start

# 0. Learn from a reference first (brief.md = style lock, pacing, shot plan, model per shot)
python scripts/analyze_reference.py --input "https://www.youtube.com/watch?v=..." \
  --goal "30s vertical product promo for X" --brand X --output refs/analysis

# 1. Storyboard still (GPT Image 2)
python scripts/generate_image_gpt.py \
  --prompt "A narrow Kyoto street at dusk, lanterns lit, light rain" \
  --output scene_01.png --aspect 16:9

# 2. Animate it (Gemini Omni)
python scripts/generate_video_omni.py \
  --prompt "In a single continuous shot, slow dolly forward. Ambient evening sounds, no music." \
  --image scene_01.png --duration 6 --output clip_01.mp4

# 3. Voiceover
python scripts/generate_tts.py --text "The street remembers." --output vo.mp3

# 4. Score
python scripts/generate_music.py --prompt "Cinematic ambient strings, slow build" \
  --duration 30 --output score.mp3

# 5. Assemble
python scripts/assemble.py --videos-dir clips/ \
  --narration vo.mp3 --music score.mp3 --output film.mp4

For title cards, text overlays, crossfades, captions, logo bugs and end cards, assemble with HyperFrames instead:

scripts/new_hyperframes_project.sh /tmp/film --aspect 9:16
python scripts/build_hyperframes_timeline.py --project /tmp/film --clip assets/clips/a.mp4:3 \
  --end-card "brand.com|3:cta=Shop now" --music assets/audio/score.mp3 --voiceover assets/audio/vo.mp3
scripts/render_hyperframes.sh /tmp/film renders/film.mp4

See SKILL.md and reference/hyperframes.md.

Reference docs

Topic	File
GPT Image 2 stills	`reference/gpt-image.md`
Gemini Omni video	`reference/omni.md`
Nano Banana prompting (fallback)	`reference/nano-banana.md`
Veo 3.1 prompting (fallback)	`reference/veo.md`
Seedance 2.5 / 2.0 (incl. content policy gotchas)	`reference/seedance.md`
Seedream 5 (BytePlus stills that pass the Seedance face filter)	`reference/seedream.md`
LTX 2.5 / 2.3 (every endpoint)	`reference/ltx.md`
ElevenLabs voice / music / SFX	`reference/elevenlabs.md`
Inspiration / reference analysis	`reference/inspiration.md`
HyperFrames assembly	`reference/hyperframes.md`
Hard-learned lessons	`reference/learnings.md`

Notes

Seedance blocks photorealistic human faces. Use 3D/Pixar-style characters, product shots, or fall back to Veo / LTX. See reference/seedance.md.
Models change frequently. If a script reports "model not found", run python scripts/list_models.py to discover current names.
Costs are real. Video is paid per second — draft with Omni --resolution 360p, Seedance --model fast/mini or ltx-2-3-fast, then upscale/regenerate the keepers. Reference analysis costs cents; run it before spending on clips.
HyperFrames installs its own agent skills (/hyperframes, /hyperframes-core, …) into ~/.claude/skills the first time it scaffolds — use them for anything beyond the generator.

License

MIT — see LICENSE.

ai-film-skills