Create Cast

Create Cast Skill

Multi-round collaborative workflow for casting characters in AI-generated movies.

Quick Start

cd .pi/skills/create-cast

# Start a new casting session
./run.sh start path/to/script.json

# Continue with answers to questions
./run.sh continue --session casting-20260204-abc123 --answers '{"q1": "approve"}'

# Check session status
./run.sh status --session casting-20260204-abc123

# Export identity packs
./run.sh export --session casting-20260204-abc123 --output ./characters

Philosophy

Casting is collaborative. The skill extracts characters, proposes specs, discovers reference actors, generates identity images, and assigns voices - but asks questions at each step to ensure alignment with the creator's vision.

Identity consistency is the goal. The output is a set of "identity packs" that Veo can use to maintain character consistency across multiple shots.

Casting Rounds

Round 1: Script Analysis
├── Parse script for character mentions
├── Extract dialogue to identify speakers
├── Infer physical descriptions from action text
├── Estimate screen time per character
└── Questions: Confirm character list and traits

Round 2: Reference Discovery (optional)
├── Call discover-talent for each main character
├── Build mood board of reference actors
└── Questions: Select reference actors or skip

Round 3: Identity Generation
├── Generate candidate looks via create-image
├── 3-5 options per character
└── Questions: Select best look or iterate

Round 4: Identity Pack Build
├── Generate front view (neutral lighting)
├── Generate 3/4 view (same lighting)
├── Generate full-body (outfit reference)
└── Questions: Approve angles or regenerate

Round 5: Voice Casting
├── Search existing voice models (learn-artist/tts-train)
├── Match voice type to available models
└── Questions: Approve voice or queue training

Commands

Start Casting Session

./run.sh start <script.json> [--json] [--auto-approve]

Begins a new casting session from a script file. Returns questions for Round 1.

Options:

• --json: Output structured JSON for agent parsing
• --auto-approve: Skip questions and use defaults (for automation)

Continue Session

./run.sh continue --session <ID> --answers '<JSON>'

Provide answers to questions and advance to the next round.

The answers JSON maps question IDs to responses:

{
  "confirm_characters": "approve",
  "sarah_trait_age": "early 30s",
  "villain_reference": "skip"
}

Check Status

./run.sh status --session <ID> [--json]

Get current session status: phase, pending questions, completed characters.

Export Identity Packs

./run.sh export --session <ID> --output <directory>

Export completed identity packs to a directory:

characters/
├── SARAH/
│   ├── identity_pack/
│   │   ├── front.png
│   │   ├── three_quarter.png
│   │   └── full_body.png
│   ├── character_bible.yaml
│   └── mood_board/
└── VILLAIN/
    └── ...

List Sessions

./run.sh list

List all active and completed casting sessions.

Character Spec Schema

name: SARAH
role: protagonist
screen_time_estimate: 45.0  # seconds
physical:
  age_range: "early 30s"
  gender: "female"
  build: "athletic"
  hair: "short dark"
  distinguishing: "determined expression"
personality:
  - determined
  - resourceful
  - guarded
voice_type: "confident, measured"
dialogue_count: 12
scenes: [1, 3, 5, 7]
bridge_attributes:
  - Resilience
  - Precision

Identity Pack Schema

character_name: SARAH
images:
  front: characters/SARAH/identity_pack/front.png
  three_quarter: characters/SARAH/identity_pack/three_quarter.png
  full_body: characters/SARAH/identity_pack/full_body.png
prompt_descriptors:
  - "early 30s woman"
  - "athletic build"
  - "short dark hair"
  - "determined expression"
  - "wearing practical clothing"
lighting_notes: "Neutral studio lighting for Veo reference"
voice_model: "florence-pugh-rvc"
created_at: "2026-02-04T12:34:56Z"

Integration with create-movie

This skill runs as Phase 2.5 in the create-movie pipeline:

Phase 2: Script (create-story)
    ↓
Phase 2.5: CASTING (create-cast) ← THIS SKILL
    ↓
Phase 3: Storyboard (create-storyboard)

The identity packs flow into Phase 4 (Generate) where Veo uses them for character consistency.

Automatic Invocation

# In create-movie orchestrator (after script phase)
from create_cast import run_casting_session

casting_result = run_casting_session(
    script_path=script_file,
    output_dir=characters_dir,
    model=model,
    auto_approve=auto_approve,
)

Skill Dependencies

Configuration

Environment variables:

TMDB_API_KEY=xxx           # For discover-talent
OPENAI_API_KEY=xxx         # For create-image (if using DALL-E)
FLUX_API_KEY=xxx           # For create-image (if using FLUX)

Example Workflow

Agent: "./run.sh start script.json"

Output: 
{
  "status": "needs_input",
  "phase": "ANALYSIS",
  "questions": [
    {
      "id": "confirm_characters",
      "question": "I found 3 characters: SARAH (45s), VILLAIN (30s), GUARD (10s). Confirm?",
      "options": ["approve", "add_character", "remove_character"]
    },
    {
      "id": "sarah_age",
      "question": "SARAH's age isn't specified. What age range?",
      "options": ["20s", "early 30s", "late 30s", "40s"]
    }
  ],
  "resume_command": "./run.sh continue --session casting-20260204-abc123 --answers '{...}'"
}

Agent: "./run.sh continue --session casting-20260204-abc123 --answers '{\"confirm_characters\": \"approve\", \"sarah_age\": \"early 30s\"}'"

Output:
{
  "status": "needs_input",
  "phase": "DISCOVERY",
  "questions": [
    {
      "id": "sarah_reference",
      "question": "For SARAH, I found these reference actors: [Florence Pugh, Mackenzie Davis]. Select one or skip?",
      "options": ["Florence Pugh", "Mackenzie Davis", "skip_reference"]
    }
  ]
}

Sanity Checks

./run.sh sanity
# or
./sanity/sanity.sh

Verifies:

1. Python syntax for all modules
2. Imports work correctly
3. CLI help displays
4. Schema validation
5. discover-talent integration (if available)