git:20260422.dacfb65 to git:20260927.c9cc65a

55 added, 80 removed. Audit A to A.

---

name: camera-vocabulary

- description: "Shot scale, camera move taxonomy, and cinematography rules for ai_video scene planning. Load when writing storyboard scenes in Phase 1."

+ description: "Shot scale and camera move values, and the motion-budget rule, for ai_video scene planning. Load when writing storyboard scenes in Phase 1."

---

# Camera Vocabulary

- 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.

+ Each scene carries a `shotScale` and a `cameraMove`. 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, texture |

- | `cu` | Close-up: face fills frame | Dialogue, reaction, emotion |

- | `mcu` | Medium close-up: chest up | Conversation, character focus |

- | `medium` | Medium: waist up | Standard dialogue, action |

- | `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 |

+ | Value | Framing |

+ |-------|---------|

+ | `ecu` | Extreme close-up: eyes, hands, small detail |

+ | `cu` | Close-up: face fills frame |

+ | `mcu` | Medium close-up: chest up |

+ | `medium` | Medium: waist up |

+ | `cowboy` | Cowboy: mid-thigh up |

+ | `wide` | Wide: full body + room |

+ | `very_wide` | Very wide: environment dominates |

+ | `aerial` | Overhead / bird's eye |

## Camera Moves

- Grouped semantically. Draw from multiple groups to create variety.

+ Grouped semantically.

### Push / Pull

- | Value | Motion | When to use |

- |-------|--------|-------------|

- | `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 |

+ | Value | Motion |

+ |-------|--------|

+ | `push_in` | Camera moves toward subject |

+ | `pull_out` | Camera moves away from subject |

+ | `dolly_forward` | Camera physically advances through space |

+ | `dolly_back` | Camera physically retreats through space |

### 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 |

+ | Value | Motion |

+ |-------|--------|

+ | `tracking` | Camera follows subject laterally |

+ | `arc` | Camera sweeps in a partial curve around subject |

+ | `orbit` | Camera circles the subject fully |

### 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 |

+ | Value | Motion |

+ |-------|--------|

+ | `crane_up` | Vertical camera rise |

+ | `crane_down` | Vertical camera descent |

+ | `jib` | Crane with lateral arc component |

### 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 |

+ | Value | Motion |

+ |-------|--------|

+ | `handheld_drift` | Organic, slightly unstable float |

+ | `snorri_cam` | Camera fixed to subject, world moves |

### Smooth

- | Value | Motion | When to use |

- |-------|--------|-------------|

- | `gimbal_glide` | Perfectly smooth lateral/forward glide | Ethereal calm, floating through space |

+ | Value | Motion |

+ |-------|--------|

+ | `gimbal_glide` | Perfectly smooth lateral/forward glide |

### 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 |

+ | Value | Motion |

+ |-------|--------|

+ | `whip_pan` | Fast horizontal snap |

+ | `crash_zoom` | Rapid lens zoom into subject |

+ | `rack_focus` | Focus shifts between foreground/background |

### 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 |

+ | Value | Motion |

+ |-------|--------|

+ | `tilt_up` | Vertical rotation upward |

+ | `tilt_down` | Vertical rotation downward |

+ | `dutch_tilt` | Camera tilted off-axis |

### 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 |

+ | Value | Motion |

+ |-------|--------|

+ | `locked_wide` | No movement, wide frame |

+ | `locked_close` | No movement, close frame |

+ | `static_macro` | No movement, extreme detail |

### 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 |

+ | Value | Motion |

+ |-------|--------|

+ | `pov` | Camera IS the subject's eyes |

+ | `over_shoulder` | Behind subject looking at their world |

## 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": "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.