camera-vocabulary · diff
git:20260421.84b28fc to git:20260422.dacfb65
101 added, 24 removed. Audit A to A.
---
name: camera-vocabulary
- description: "Shot scale and camera move vocabulary for ai_video scene planning. Load when writing storyboard scenes in Phase 1."
+ description: "Shot scale, camera move taxonomy, and cinematography rules for ai_video scene planning. Load when writing storyboard scenes in Phase 1."
---
# Camera Vocabulary
- Reference for the agent when planning ai_video scenes. Pick one shot scale and one camera move per scene during Phase 1 storyboard planning.
+ Camera is a **first-class decision per shot**, not a throwaway clause. Pick `camera_move` and `shot_scale` BEFORE writing the prose prompt — they shape the shot. The runtime prefixes the Kling prompt with both as `[SHOT SCALE]` and `[CAMERA MOVE]` tags so the generator actually executes them.
## Shot Scales
| Value | Framing | When to use |
|-------|---------|-------------|
- | `ecu` | Extreme close-up: eyes, hands, small detail | Intimate emotion, critical object |
+ | `ecu` | Extreme close-up: eyes, hands, small detail | Intimate emotion, critical object, texture |
| `cu` | Close-up: face fills frame | Dialogue, reaction, emotion |
- | `mcu` | Medium close-up: head and shoulders | Conversation, character focus |
+ | `mcu` | Medium close-up: chest up | Conversation, character focus |
| `medium` | Medium: waist up | Standard dialogue, action |
- | `medium-wide` | Medium wide: knees up | Character in context |
- | `wide` | Wide: full body + environment | Establishing, physical action |
- | `establishing` | Very wide: environment dominates | Opening shots, location change |
- | `aerial` | Overhead / bird's eye | Scale, geography, transition |
+ | `cowboy` | Cowboy: mid-thigh up | Character with environment context, walking |
+ | `wide` | Wide: full body + room | Establishing character in space, physical action |
+ | `very_wide` | Very wide: environment dominates | Location change, scale, isolation |
+ | `aerial` | Overhead / bird's eye | Geography, transition, grandeur |
## Camera Moves
+ Grouped semantically. Draw from multiple groups to create variety.
+
+ ### Push / Pull
| Value | Motion | When to use |
|-------|--------|-------------|
- | `static` | No camera movement | Let the subject's motion carry the shot |
- | `push-in` | Camera moves toward subject | Building tension, drawing attention |
- | `pull-back` | Camera moves away from subject | Reveal, release, ending |
- | `pan-left` / `pan-right` | Horizontal rotation on axis | Following motion, surveying space |
- | `tilt-up` / `tilt-down` | Vertical rotation on axis | Reveal height, follow vertical motion |
- | `orbit` | Camera circles the subject | Dramatic emphasis, hero moment |
- | `tracking` | Camera follows subject laterally | Walking, running, chase |
- | `whip-pan` | Fast horizontal snap | Comedic timing, energy burst |
- | `crane-up` / `crane-down` | Vertical camera rise/descent | Opening/closing grandeur |
- | `zoom-in` / `zoom-out` | Lens zoom (not camera move) | Subtle focus shift |
+ | `push_in` | Camera moves toward subject | Building tension, drawing attention |
+ | `pull_out` | Camera moves away from subject | Reveal, release, ending |
+ | `dolly_forward` | Camera physically advances through space | Moving into a scene, entering a room |
+ | `dolly_back` | Camera physically retreats through space | Departing, farewell, distancing |
- ## Motion Budget Rule
+ ### Lateral
+ | Value | Motion | When to use |
+ |-------|--------|-------------|
+ | `tracking` | Camera follows subject laterally | Walking, running, procession |
+ | `arc` | Camera sweeps in a partial curve around subject | Transition, moderate emphasis |
+ | `orbit` | Camera circles the subject fully | Dramatic emphasis, hero moment, isolation |
- Every shot needs motion from EITHER the subject OR the camera — never both static.
+ ### Crane / Jib
+ | Value | Motion | When to use |
+ |-------|--------|-------------|
+ | `crane_up` | Vertical camera rise | Opening grandeur, reveal from above |
+ | `crane_down` | Vertical camera descent | Arrival, landing, grounding |
+ | `jib` | Crane with lateral arc component | Fluid elevation change with sweep |
- - Subject is still (posing, waiting) → use an active camera move (push-in, orbit, crane)
- - Subject is moving (running, sliding) → static or tracking camera is enough
- - Both moving → risk visual chaos; only for peak energy moments
+ ### Handheld
+ | Value | Motion | When to use |
+ |-------|--------|-------------|
+ | `handheld_drift` | Organic, slightly unstable float | Intimacy, documentary feel, unease |
+ | `snorri_cam` | Camera fixed to subject, world moves | Disorientation, intoxication, dream |
+ ### Smooth
+ | Value | Motion | When to use |
+ |-------|--------|-------------|
+ | `gimbal_glide` | Perfectly smooth lateral/forward glide | Ethereal calm, floating through space |
+
+ ### Snappy
+ | Value | Motion | When to use |
+ |-------|--------|-------------|
+ | `whip_pan` | Fast horizontal snap | Energy burst, surprise, comedic timing |
+ | `crash_zoom` | Rapid lens zoom into subject | Shock, sudden focus, impact |
+ | `rack_focus` | Focus shifts between foreground/background | Reveal connection, redirect attention |
+
+ ### Tilt
+ | Value | Motion | When to use |
+ |-------|--------|-------------|
+ | `tilt_up` | Vertical rotation upward | Reveal height, awe, looking up |
+ | `tilt_down` | Vertical rotation downward | Reveal below, grounding, descent |
+ | `dutch_tilt` | Camera tilted off-axis | Tension, unease, stylized energy |
+
+ ### Locked
+ | Value | Motion | When to use |
+ |-------|--------|-------------|
+ | `locked_wide` | No movement, wide frame | Stillness IS the statement — must have internal motion |
+ | `locked_close` | No movement, close frame | Portrait intensity — must have internal motion |
+ | `static_macro` | No movement, extreme detail | Texture, small object, time passing on surface |
+
+ ### Subjective
+ | Value | Motion | When to use |
+ |-------|--------|-------------|
+ | `pov` | Camera IS the subject's eyes | Immersion, what they see |
+ | `over_shoulder` | Behind subject looking at their world | Perspective, conversation, approach |
+
+ ## Rules
+
+ ### 1. Motion Budget — every shot needs motion
+
+ Every shot needs motion from EITHER the subject OR the camera — never both absent.
+
+ - **Subject is still** (posing, landscape, interior, still object) → pick an **assertive** camera move: `push_in`, `pull_out`, `orbit`, `arc`, `tracking`, `handheld_drift`, `crane_up/down`, `whip_pan`, `crash_zoom`, `rack_focus`. A static subject + static camera reads as a photograph, not a video shot.
+ - **Subject is moving** (running, sliding, walking, fighting) → `tracking`, `locked_wide`, or `static_macro` is enough — let the subject carry the motion.
+ - **Both moving** → risk visual chaos. Reserve for peak energy moments only.
+ - **Locked moves** (`locked_wide`, `locked_close`, `static_macro`) → only when stillness IS the statement AND something else in frame is visibly moving (water rippling, smoke curling, light flickering, a figure crossing behind).
+
+ ### 2. Fresh-scene rule — vary across adjacent shots
+
+ At least **2 of these 4** must change between every consecutive pair of shots:
+
+ 1. Location / environment
+ 2. Shot scale
+ 3. Camera move
+ 4. Palette / lighting
+
+ `ECU/crash_zoom → wide/tracking → medium/orbit` reads as deliberate cinematography.
+ `medium/push_in → medium/push_in → medium/push_in` reads as one confused camera operator.
+
+ **Forbidden sameness:** no two adjacent shots should share both the same shot scale AND the same camera move.
+
+ ### 3. Camera pool per video
+
+ Before writing scenes, pick **4-8 camera moves** that define this video's camera grammar — its visual identity. Every shot's `camera_move` should be drawn from this pool. This prevents both monotony (all push_in) and chaos (random moves with no through-line).
+
+ Example pool for a documentary: `[push_in, pull_out, crane_up, tracking, gimbal_glide, locked_wide, tilt_up, orbit]`
+ Example pool for high-energy: `[whip_pan, crash_zoom, handheld_drift, tracking, dutch_tilt, arc, pov, crane_down]`
+
+ ### 4. Pick camera BEFORE prompt
+
+ Write fields in this order: `shotScale` → `cameraMove` → then the `## Camera` / `## Subject` / `## Action` prompt sections. Camera choice shapes what the shot looks like — don't write the description first and try to fit a move after.
+
## Scene Fields
When planning scenes in Phase 1, write these structured fields on each `storyboard.scenes[i]`:
```json
{
"id": "scene-1",
"prompt": "...",
"duration": 5,
"refImages": ["ref1", "ref2"],
"shotScale": "wide",
- "cameraMove": "push-in"
+ "cameraMove": "tracking"
}
```
The `kling_generate` step auto-appends `[SHOT SCALE]` and `[CAMERA MOVE]` tags to the composed prompt at generation time. Do NOT write these tags in the scene prompt text.