muapi-cinema-director

Original source / Raw SKILL.md

---
name: muapi-cinema-director
version: 0.1.0
description: Direct high-fidelity cinematic video with AI — translates creative intent into technical cinematographic directives for Veo3, Kling, and Luma video models via muapi.ai
---

# 🎬 AI Cinema Director Skill

**A specialized skill for AI Agents to direct high-fidelity cinematic video.**
The Cinema Director skill translates high-level creative intent into technical cinematographic directives for state-of-the-art video models (Veo3, Kling, Luma).

## Core Competencies

1. **Shot Composition Analysis**: Mapping emotional beats to appropriate framing (e.g., Extreme Close-Up for intimacy, Wide Shot for isolation).
2. **Camera Movement Orchestration**: Directing complex physical movements (Dolly, Truck, Crane) and lens-based effects (Rack Focus, Dolly Zoom).
3. **Lighting & Atmosphere Design**: Specifying temporal and stylistic lighting (Golden Hour, Chiaroscuro, Volumetric God Rays).
4. **Technical Parameter Optimization**: Automatically selecting optimal frame rates, aspect ratios, and model-specific biases.

---

## 🏗️ Technical Specification

### 1. Intent Mapping Table

| Creative Intent | Framing | Movement | Lighting |
| :--- | :--- | :--- | :--- |
| **Heroic Reveal** | Low Angle / Wide | Crane Up / Orbit | Rim Lighting / High Contrast |
| **Tense/Uneasy** | Dutch Angle | Handheld Shake | Low Key / Harsh Shadows |
| **Introspective** | Close-Up | Slow Push In | Soft Rembrandt / Window Light |
| **Majestic/Epic** | Extreme Wide | Drone Flyover | Golden Hour / Volumetric |
| **Melancholic** | Profile / Medium | Slow Pull Out | Blue Hour / Desaturated |

### 2. Physical Camera Movements
- `Dolly In/Out`: Physical camera movement on a track toward/away from the subject.
- `Truck Left/Right`: Lateral physical movement.
- `Crane/Jib`: Sweeping vertical movement from a height.
- `Orbit`: Circular movement around a center point.
- `Pedestal`: Vertical elevation change (without tilting).

### 3. Lens & Optical Controls
- `Shallow DOF`: Background blur (Bokeh).
- `Anamorphic`: Horizontal flares and wide-screen cinematic feel.
- `Rack Focus`: Shifting focus between planes within the shot.

---

## 🧠 Prompt Optimization Protocol (Agent Instruction)

**Before calling the script, the Agent MUST expand the user's raw prompt using these Director's Rules:**

1. **TECHNICAL INFUSION**: Transform "cool action" into a technical shot. 
   - *Formula*: `[Shot Type] + [Subject/Action] + [Environment] + [Lighting] + [Camera Movement] + [Lens Effect]`
2. **MOTION DYNAMICS**: Use cinematic verbs: *Dolly In* (intimacy), *Crane Up* (majestic), *Orbit* (heroic), *Truck* (parallel motion).
3. **LIGHTING RECIPES**: Apply specific illumination: *Volumetric God Rays*, *Teal-and-Orange Grade*, *Cyberpunk Rim Lighting*, *Rembrandt Portrait Lighting*.
4. **PHYSICS LOGIC**: Describe light relationships (e.g., "Neon reflections shimmering on rain-slicked asphalt") to trigger model reasoning.

---

## 🚀 Protocol: Using the Cinema Director

### Step 1: Define the Creative Brief
Provide the agent with a subject and a "Director's Intent."

### Step 2: Invoke the Script
The `generate-film.sh` script accepts a `--brief` which it expands using its internal knowledge of cinematography.

```bash
# Directing a scene
bash scripts/generate-film.sh 
  --subject "A lone samurai in a blizzard" 
  --intent "epic reveal" 
  --model "kling-master"
```

### Step 3: Handle the Async Response
Video generation is asynchronous. Use the returned `request_id` to poll for completion via `core/platform/check-result.sh`.

---

## ⚠️ Constraints & Guardrails

- **Temporal Consistency**: Avoid complex subject transformations in a single shot (e.g., "man turns into a bird").
- **Movement Collisions**: Do not combine contradictory movements (e.g., "Dolly In" and "Dolly Out" simultaneously).
- **Physical Realism**: Prefer movements possible with real-world equipment for a more professional "film" look.
- **Model Bias**: 
  - `Veo3`: Best for slow, high-quality aesthetic shots.
  - `Kling`: Best for complex character motion and physics.
  - `Luma`: Best for fast-paced, high-action cinematic sequences.

---

## ⚙️ Implementation Details
This skill acts as an "Expert Translator" for the `core/media/generate-video.sh` primitive. It maintains a dictionary of cinematic styles and injects technical directives into the prompt before execution.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/generate-film.sh

```bash
#!/bin/bash
# Expert Skill: AI Cinema Director
# Translates high-level intent into technical cinematographic directives.

SUBJECT=""
INTENT="cinematic"
MODEL="veo3"
ASPECT="16:9"
DURATION=5
AUDIO_FLAG=""
VIEW_FLAG=""

while [[ $# -gt 0 ]]; do
    case $1 in
        --subject) SUBJECT="$2"; shift 2 ;;
        --intent) INTENT="$2"; shift 2 ;;
        --model) MODEL="$2"; shift 2 ;;
        --aspect) ASPECT="$2"; shift 2 ;;
        --duration) DURATION="$2"; shift 2 ;;
        --no-audio) AUDIO_FLAG="--no-audio"; shift ;;
        --view) VIEW_FLAG="--view"; shift ;;
        *) shift ;;
    esac
done

if [ -z "$SUBJECT" ]; then
    echo "Usage: bash generate-film.sh --subject 'description' [--intent reveal|tense|epic] [--model veo3|kling] [--duration 5|10] [--no-audio] [--view]"
    exit 1
fi

# Director's Logic Table (Internal Knowledge)
case $INTENT in
    "reveal")
        FRAMING="Extreme wide shot"
        MOVEMENT="Slow crane up and tilt down"
        LIGHTING="Golden hour, volumetric god rays"
        LENS="Deep focus, high clarity"
        ;;
    "tense")
        FRAMING="Dutch angle, close-up"
        MOVEMENT="Handheld jittery movement"
        LIGHTING="Low key, harsh shadows, flickering neon"
        LENS="Shallow depth of field, anamorphic lens flare"
        ;;
    "epic")
        FRAMING="Low angle wide shot"
        MOVEMENT="Dolly in with circular orbit"
        LIGHTING="Dramatic rim lighting, high contrast"
        LENS="Anamorphic, 35mm film grain"
        ;;
    "melancholy")
        FRAMING="Medium shot, profile"
        MOVEMENT="Slow dolly out"
        LIGHTING="Blue hour, soft desaturated tones"
        LENS="Shallow bokeh, soft focus"
        ;;
    *)
        FRAMING="Cinematic medium shot"
        MOVEMENT="Smooth pan"
        LIGHTING="Natural studio lighting"
        LENS="Standard 50mm"
        ;;
esac

# Construct the technical Director's Prompt
DIRECTOR_PROMPT="[DIRECTOR_BRIEF]
SCENE: $SUBJECT
FRAMING: $FRAMING
CAMERA_MOTION: $MOVEMENT
LIGHTING_DESIGN: $LIGHTING
OPTICS: $LENS
[EXECUTE] High-fidelity cinematic footage. Professional color grade, 4k, hyper-realistic physics."

# Call the Core primitive
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
CORE_SCRIPT="$SCRIPT_DIR/../../../../core/media/generate-video.sh"

bash "$CORE_SCRIPT" --prompt "$DIRECTOR_PROMPT" --model "$MODEL" --aspect-ratio "$ASPECT" --duration "$DURATION" $AUDIO_FLAG $VIEW_FLAG --async --json

```