camera-vocabulary - SKILL.md Agent Skill

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

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.

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

Camera Moves

Grouped semantically. Draw from multiple groups to create variety.

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

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

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

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:

Location / environment
Shot scale
Camera move
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]:

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