DPL plan format

Specification and schemas: licence to be confirmed. The rules that do the checking run on our servers and are not published.

Source revision: ddd20338847df7d1f7922a4a8c1f5a37781716f7. Download the specification (Markdown), with internal development notes removed.

JSON Schemas

• dpl.bench-1.schema.json
• dpl.brief-1.schema.json
• dpl.call-sheet-1.schema.json
• dpl.constraints-1.schema.json
• dpl.coverage-status-1.schema.json
• dpl.diagnostics-1.schema.json
• dpl.diff-1.schema.json
• dpl.dispositions-1.schema.json
• dpl.draft-1.schema.json
• dpl.draft-gate-1.schema.json
• dpl.draft-grammar-1.schema.json
• dpl.draft-next-1.schema.json
• dpl.edit-export-1.schema.json
• dpl.edit-guide-1.schema.json
• dpl.findings-1.schema.json
• dpl.missing-1.schema.json
• dpl.plan-1.schema.json
• dpl.replan-1.schema.json
• dpl.shoot-pack-1.schema.json
• dpl.shot-list-1.schema.json
• dpl.summary-1.schema.json
• dpl.takes-1.schema.json

DPL plan format — dpl.plan/1

Status: first version. Last updated 18 October 2026.

A DPL plan describes a film the way a director plans it: every scene and every shot, what each is for, where the audience's attention goes, and what is heard. It is useful on its own: a crew could shoot from it, a person can read its shot list, and tools can read its shots in industry terms. It depends on nothing else in this repository. Converting a plan to other formats is done by separate tools, which this format does not depend on.

How to read this page. Section 1 is the shape of the file, with two complete plans you can copy. Section 2 goes through every part of a plan (the work and its house style, the world, the structure, the shots, the picture layers, the sound and the transitions) and says what each part is for, so you know when to use it. Section 2.10 is the short-form profile for phone and small-crew shoots. Section 3 lists the details that switch the edit-readiness checks on. Section 4 has the camera terms. Section 5 is validation and how to read its diagnostics.

1. Shape

One JSON document, UTF-8. These rules hold everywhere:

• Names are snake_case. Terms (size, movement, kind and the rest) are snake_case strings from a fixed list. "Hold", "PushIn" and "static-shot" are not terms.
• Times are whole milliseconds from the start of the work (start_ms, end_ms; an end is exclusive). 1500.5 is refused, and so is 1500.0.
• Required members must be present. An absent term never falls back to a default.
• Optional members may be left out, or written null, which means the same. A list that is left out is empty. Where a default is shown, the reader applies it when the member is absent.
• Unknown members are refused, in every object. So is a misspelt term. Nothing is silently ignored.
• Ids are short, plain and unique where the tables below say so. Characters, props and locations share one namespace; shot ids are unique across the whole plan.

Schema. The exact members, terms and requirements are published as a JSON Schema (draft 2020-12), contracts/dpl/dpl.plan-1.schema.json; print it with dpl schema plan. It matches the reader member for member and is held to it by tests. contracts/dpl/README.md says what each schema covers and what only the validator can check. This page says what the members are for.

Reading the tables. Each object in section 2 has a table with its members in the schema's order. Type says what goes there: text, a whole number, a number, true or false, a list, another object (named in code font, and described in its own table), or one of a short list of terms. required marks a member that must be present; nothing else needs to be. Times are milliseconds unless the meaning says otherwise.

The smallest plan

One scene with one shot:

{"format": "dpl.plan/1", "work": {"id": "w", "title": "W"},
 "scenes": [{"id": "s1", "purpose": "Open.", "start_ms": 0, "end_ms": 2000,
   "shots": [{"id": "a", "purpose": "Show the door.", "subject": "A door.", "start_ms": 0, "end_ms": 2000,
              "camera": {"size": "wide", "movement": "hold"}}]}]}

A small plan to copy: two people talking

A dialogue scene with the details the edit-readiness checks look for: a line of action (axis), the people placed in every shot (staging), who speaks to whom (lines, one of them turning the scene), the job of each shot (coverage) and the set-up each is filmed from (setup). It validates with no diagnostics and dpl readiness finds nothing to report. Change the names and the words, keep the shape.

{
  "format": "dpl.plan/1",
  "work": {"id": "kitchen-short", "title": "The Kitchen", "thesis": "A marriage turns on one sentence about money.", "target_runtime_ms": 14000},
  "characters": [
    {"id": "MAYA", "description": "Maya, forties, has just learned the truth."},
    {"id": "TOM", "description": "Tom, her husband, who hid it."}
  ],
  "locations": [{"id": "KITCHEN", "description": "A small kitchen at dusk."}],
  "scenes": [
    {
      "id": "S1",
      "purpose": "Maya tells Tom what she knows; he cannot answer.",
      "change": "We know that she knows.",
      "start_ms": 0,
      "end_ms": 14000,
      "location": "KITCHEN",
      "axis": {"left": "MAYA", "right": "TOM"},
      "lines": [
        {"id": "L1", "speaker": "TOM", "to": "MAYA", "start_ms": 500, "end_ms": 2500, "text": "You're home early."},
        {"id": "L2", "speaker": "MAYA", "to": "TOM", "start_ms": 3500, "end_ms": 6500, "text": "I went to see your brother."},
        {"id": "L3", "speaker": "MAYA", "to": "TOM", "start_ms": 7500, "end_ms": 10000, "turn": true, "text": "He told me about the money."},
        {"id": "L4", "speaker": "TOM", "to": "MAYA", "start_ms": 12000, "end_ms": 13500, "text": "It's not what you think."}
      ],
      "shots": [
        {
          "id": "K1", "purpose": "Where they are: Maya at the door, Tom at the sink.", "subject": "KITCHEN",
          "start_ms": 0, "end_ms": 3000, "camera": {"size": "wide", "movement": "hold"}, "source": "footage",
          "characters": ["MAYA", "TOM"],
          "coverage": {"role": "establishing", "priority": "must"},
          "staging": [
            {"subject": "MAYA", "side": "left", "facing": "right"},
            {"subject": "TOM", "side": "right", "facing": "left"}
          ],
          "setup": "A"
        },
        {
          "id": "K2", "purpose": "Maya, as she says where she has been.", "subject": "MAYA",
          "start_ms": 3000, "end_ms": 7000, "camera": {"size": "medium", "movement": "hold"}, "source": "footage",
          "characters": ["MAYA"],
          "coverage": {"role": "single", "priority": "should"},
          "staging": [{"subject": "MAYA", "side": "left", "facing": "right"}],
          "setup": "B"
        },
        {
          "id": "K3", "purpose": "Tom takes it in.", "subject": "TOM",
          "start_ms": 7000, "end_ms": 9000, "camera": {"size": "medium", "movement": "hold"}, "source": "footage",
          "characters": ["TOM"],
          "coverage": {"role": "single", "priority": "should"},
          "staging": [{"subject": "TOM", "side": "right", "facing": "left"}],
          "setup": "C"
        },
        {
          "id": "K4", "purpose": "Maya says the sentence the scene turns on.", "subject": "MAYA",
          "start_ms": 9000, "end_ms": 11000, "camera": {"size": "medium_close_up", "movement": "push_in"}, "source": "footage",
          "characters": ["MAYA"],
          "coverage": {"role": "single", "priority": "must"},
          "staging": [{"subject": "MAYA", "side": "left", "facing": "right"}],
          "setup": "D"
        },
        {
          "id": "K5", "purpose": "Tom's face as it lands: he has no answer.", "subject": "TOM",
          "start_ms": 11000, "end_ms": 14000, "camera": {"size": "close_up", "movement": "hold"}, "source": "footage",
          "characters": ["TOM"],
          "coverage": {"role": "reaction", "priority": "must"},
          "staging": [{"subject": "TOM", "side": "right", "facing": "left"}],
          "setup": "C2"
        }
      ]
    }
  ]
}

Larger complete plans are in tests/corpus/ (a kitchen scene with a broken glass, a rooftop chase, a waking scene) and the fixture tests/contract/VideoEditor.Dpl.Plan.Tests/Fixtures/the-beacon.dpl.plan.json.

Examples below that are not complete plans are fragments: each is marked with the place it belongs, such as scenes[0].shots[0]. They are checked against that part of the schema by a test, so a term or member that is wrong in an example fails the build.

The top level

Plan (the plan itself)

2. What each part is for

2.1 The work

work is the film's identity and intent. Give it a thesis (what the film argues or makes the audience feel), so each scene can be asked what it does for that. Give target_runtime_ms and the validator warns when the scenes do not add up to it. design_notes, approach and quality_floor are for the director's own reasoning and the bar the finished film must clear; they are read by people and by review, not by the edit checks.

Work (work)

DesignNote (work.design_notes[])

2.2 House style

work.house_style holds the choices that belong to the whole film rather than to a scene: how its constructs look, how tightly picture follows the words, what structure it opts into, and how it is mixed. Every part is optional. A part you leave out switches its checks to report only.

HouseStyle (work.house_style)

Constructs and colours. map, highlight and chapter_card describe the film's map, highlight and chapter card in plain words. The structured palettes are optional beside them. Colours are CSS hex strings. These fields travel with the realisation document. A bound picture may override the drawing sounds with drawing_sound: false, or a drawing_sound object with enabled, per-kind switches and gain_db. Bindings provide the page image and normalised highlight rectangles, map vector polygons and place pin assets, split-screen pane assets and quoted text. bindings.word_timing carries eil.words/1 when a construct follows spoken words. A new engine release is required before production films can render these constructs.

MapConstructStyle (work.house_style.map_palette)

MapNamedPlace (work.house_style.map_palette.places[])

HighlightConstructStyle (work.house_style.highlight_palette)

ChapterConstructStyle (work.house_style.chapter_palette)

DrawingSoundStyle (work.house_style.drawing_sounds)

The presenter (playbook Part 1 §1.1–1.2). presenter sets who the presenter is and the longest the audience goes without seeing them. The checks count the gap from the film's start and to its end, and also report a presenter who never appears.

PresenterStyle (work.house_style.presenter)

ReadinessStyle (work.house_style.readiness)

Every member is optional. A member left out keeps the check's own figure. Without hold_*_ms, a hold limit is a multiple of the film's own pace (its median shot length, or timing.body_median_ms when declared), scaled by the shot's size: insert and cutaway 2 times the pace, reaction 2.5, neutral 1.5, times 1.25 for an extreme long shot falling to 0.75 for an extreme close-up. The reaction window is 1000 ms. A film cut slowly on purpose raises them; a very fast one lowers them. Whatever the limit, speech inside the shot is added to it: a reaction played under the other person's line, or an insert over the narration that reads the clause, lasts as long as the words need.

Picture timing (playbook Part 1 §1.3). timing sets how closely cuts follow the spoken words, and how long shots run. Omitting the whole object makes render verification report only. An explicit null for a median switches off that section's length gate. Slower musical films may choose their own targets.

TimingStyle (work.house_style.timing)

Structure on screen (playbook §1.4). structure opts into individual checks, all off unless set. A subscribe prompt is a caption overlay with style: "subscribe" over B-roll. An end card is a caption overlay with style: "end_card", a recommendation in text, and a built-in subscribe prompt; realisation binds its recommendation picture as the overlay's content: {kind: "image", asset: "..."} and the renderer shows it as a thumbnail. The end card may run across the shots of its scene. drawing_sounds.subscribe: true adds a soft local paper-grain entry sound to the small prompt. dplkit.subscribe_prompt, dplkit.end_card and dplkit.structure_style author these; dplkit.add_structure places both on timed shots without changing sound. The sponsor-loop check observes the fixed words and never changes them.

StructureStyle (work.house_style.structure)

Sound targets (playbook §1.5). sound sets how far the bed sits under the voice and how loud the finished mix is. The pipeline carries a plan's sound object into the house-style view used by mixing and verification; the separate style file remains unchanged on disk. With it, the pipeline attenuates the bed during speech (smoothly: down in 40 ms, back over 450 ms) and normalises the finished mix. Verification allows 3 dB bed-depth tolerance, 1 LUFS loudness tolerance, 0.2 dBTP true-peak tolerance, and at most 15% of cuts with transients for few (zero for none). Bed depth verification reports the median voiced-window depth and its p10 separately, and judges the median. With no sound object, these checks report only.

SoundTargetStyle (work.house_style.sound)

BedLift (work.house_style.sound.bed_lifts[])

LoudnessTarget (work.house_style.sound.loudness)

2.3 The world: characters, locations, props, rules

The world is what the story is made of. Declare each thing once and name it by id everywhere else, so the checks can follow a person, a place or an object from shot to shot. A character, a prop and a location share one namespace, because staging, attention and the camera's path can name any of them.

• Characters need a description (who they are in the story). Add appearance (what a picture of them must show) when the character will be generated: the validator warns (DPL-APPEARANCE) when a character is in two or more generated shots and the appearance does not fix their hair (or head covering) and clothing. costume and performance are for whoever dresses and directs them.
• Locations can name their parts (the door, the sink). A scene's entry and a camera path then say which part the audience arrives in or is carried into.
• Props are the objects the story depends on (the lamp that must be relit). A shot lists the props it shows; a scene's state_changes and a shot's states track how they change.
• Continuity rules are rules the picture must keep (a rule of light, a costume). A shot cites a rule by id in its continuity. A rule's measures say what it means in the rendered picture, so the render can be measured against it. A rule of light described to an image model with dark words is a trap: the validator warns (DPL-RULE) when a shot held to a strict rule of light is described as dark.
• must_not at the top level is what the whole film must never show or do. Each shot has its own.

Character (characters[])

Location (locations[])

Prop (props[])

ContinuityRule (continuity_rules[])

RuleMeasure (continuity_rules[].measures[])

{"id": "light-of-the-father", "domain": "light", "rule": "The Father of lights: no heavy shadow.",
 "measures": [{"kind": "min_brightness", "value": 0.4}, {"kind": "max_shadow_share", "value": 0.2}]}

Rigs

A character can be a cut-out puppet, so a shot can move it. rig: {"body": "figure"} is the standard jointed figure of ten parts: torso, head, upper_arm_l, upper_arm_r, forearm_l, forearm_r, thigh_l, thigh_r, shin_l and shin_r. {"body": "own", "parts": [...]} is a rig of parts cut from your own art, with exactly one root; a part that is named as one of the figure's roles is the one the actions move, and roles maps a role to a part where the names differ (the roles the validator accepts are the ten above and foot_l and foot_r). A shot then gives the character's staging a list of actions, section 2.6. The realiser turns the actions into the rig layer's keys (its port of tools/eil-prep/puppet.py, held to it by a parity fixture) and binds each part's picture from the character's binding: roles["role:<id>"].rig = {part: picture}. A part left unbound is reported (unbound_rig), never drawn half-bound. The figure stands on its staging side of the frame.

CharacterRig (characters[].rig)

RigPart (characters[].rig.parts[])

RigSecondary (characters[].rig.parts[].secondary)

RigAttachment (characters[].rig.parts[].attach)

{"body": "own",
 "parts": [
   {"id": "body", "size": [0.3, 0.6], "pivot": [0.5, 0.5], "at": [0.5, 0.6]},
   {"id": "head", "parent": "body", "size": [0.2, 0.2], "pivot": [0.5, 0.9], "at": [0.5, 0.05], "z": 1}],
 "roles": {"torso": "body", "head": "head"},
 "ground": [[0, 0.9], [1, 0.9]]}

2.4 Structure: sequences, journey, scenes

The structure says how the film is built. A scene is the unit: one place, one job, a run of shots. A sequence groups scenes into a larger movement and can say which way it is heading. A journey says where the camera travels across a sequence or the whole film.

Purpose everywhere. Every scene and every shot must say what it is for (purpose), not only what it shows (subject). A scene may also say what is different for the audience at its end (change). A plan with no purposes is a shot list; a plan with purposes can be edited, replanned and judged.

Scenes. Scenes run in time order, do not overlap, and between them cover the film; a gap is a warning (DPL-GAP). Within a scene, the shots do the same. Most of a scene's members are explained below or in the sections that follow: its lines, axis, travel and state_changes in 2.6 (they are what the readiness checks reason over), and its sound, hearing and phrases in 2.8.

Scene (scenes[])

Functions. functions is the scene's dramatic job in typed form, led by one shot or sound carrier of the scene and supported by others: propulsion, evidence, contrast, emphasis, reset, retention, humour, dread, anticipation, release or rest. These words are owned by DPL.

SceneFunction (scenes[].functions[])

Entry. entry says how the audience arrives in the scene's world, and into which part of the location. Use return or continue for a scene that is back in a place the audience knows; the geography check then does not ask for the people to be placed again.

SceneEntry (scenes[].entry)

Attention. Who or what should hold the audience at each moment: a primary and what comes after it. A beat can name its target and the effect it has on attention (concentrate it, hide something, disorient). Say so when the plan means to disorient or withhold, because the readiness checks then treat the departure as planned.

AttentionBeat (scenes[].attention[])

[{"primary": "Maya's face", "secondary": ["the letter in her hand"], "start_ms": 0, "end_ms": 6000},
 {"primary": "the lamp", "target": "lamp", "effect": "reveal", "over": "TOM", "resolves_to": "Tom's hands", "start_ms": 6000, "end_ms": 14000}]

Treatments. A scene can show the directions that were considered and the one taken. Exactly one is chosen; a single treatment is a warning (DPL-TREATMENT), because one direction means nothing was weighed.

Treatment (scenes[].treatments[])

[{"id": "t1", "angle": "stay on his face and close in", "idea": "One slow push on Tom while Maya speaks off screen.", "chosen": true, "why": "The scene is about what he cannot say."},
 {"id": "t2", "angle": "keep them both in the wide", "idea": "Hold the two of them apart across the kitchen.", "source": "owner note, 12 Oct", "why": "It spends the closeness we need for the last shot."}]

Strands. The three strands a film tells its story on are words, sound and picture. In a scene, give each strand exactly one part: one leads, the others answer, support or rest. A unison is all three striking together on one moment, and then all three are unison. A sequence's strands run across the sequence, with no one required to lead, and a sequence that gives strands also needs its direction. If one strand leads every scene of a sequence of four or more, the validator warns (DPL-STRANDS).

StrandPart (scenes[].strands[], sequences[].strands[])

Removals. Subtraction is a decision. A removal takes away a picture layer or one sound carrier (or one stem of it) at a moment, so picture and sound can lose something together on the same word.

Removal (scenes[].removals[])

[{"at_ms": 9000, "layer": "mist", "why": "the air clears on the word"}, {"at_ms": 9000, "carrier": "MUSIC", "stem": "drums", "why": "the drums drop out with it"}]

Accepts. A scene can accept a departure from editing convention, with its reason (a scene played in one take). The finding is then reported as overridden, not as a fault.

Acceptance (scenes[].accepts[])

Sequences. A sequence groups scenes by id. Use one when the film has movements that each head somewhere.

Sequence (sequences[])

{"id": "q1", "purpose": "From the whole sky to one man.", "scenes": ["S1", "S2"], "direction": "from vast to one",
 "strands": [
   {"strand": "words", "role": "lead", "does": "narrows from the heavens to a name"},
   {"strand": "sound", "role": "support", "does": "thins from a chord to one voice"},
   {"strand": "picture", "role": "answer", "does": "closes from the horizon to a face"}]}

The journey

A sequence, or the whole plan, can say where its camera travels (brief c, 5 Oct 2026; owner, 4 Oct: "Beats are silver; a journey is gold"). The axis says what the route measures: height for a ladder, distance out from home, inward toward a destination. The stages are the route in order. Each has an id, a value on the axis, and the place's name when a place is visited again (a place visited again is a new stage with the same name and a return reason, as M7's "down again to earth"). The destination is the stage where the route ends, with why. Each scene then names its journey_stage; its location, parts and entry stay as they are.

The plan validates the route's shape: at least two stages, a destination that is one of them, and a stage for every scene that names one (DPL-JOURNEY). Edit-readiness holds a plan that declares a journey to it (section 3). A plan with no journey gets no journey finding. With direction, the journey is carried into the editing stage (editorial.journey_stage@1). Fixtures: tests/corpus/journey/.

Journey (journey, sequences[].journey)

JourneyStage (journey.stages[])

JourneyDestination (journey.destination)

{"axis": "height",
 "stages": [{"id": "earth", "value": 0}, {"id": "heaven", "value": 3}, {"id": "earth2", "name": "earth", "value": 0, "return": "down again to earth"}],
 "destination": {"stage": "heaven", "why": "the whole climb is to see him"}}

2.5 Shots

A shot is a continuous run of picture. Say what it is for (purpose) and what it shows (subject); give its camera; name the characters and props in it. Everything else on a shot is optional and earns its place when a check or a maker needs it: coverage, staging, setup, states for the readiness checks (2.6); overlays, layers and window to build the picture (2.7); image_brief and motion_brief for whoever makes the picture, whether a crew or a generation model.

Shot (scenes[].shots[])

Source and recall. source says what the picture is made from. generated is a still made for the shot; generated_video moves (image to video); footage is recorded; still, graphic and typography are designed. A camera move on a still is realised as a move across it. recall reuses the approved picture or clip of an earlier movement (the same file, not a regeneration that looks different): set source to recall and name the movement and shot. Only a recall carries a recall member (DPL-RECALL).

Recall (scenes[].shots[].recall)

Motion ramp. motion_ramp is an authored slowing of the picture to stillness inside a shot, on a word (the storm on "be still"). It is not a freeze: the hold after it is the plan's intent. Only moving picture (generated_video, footage or recall) can ramp.

MotionRamp (scenes[].shots[].motion_ramp)

The camera. size and movement are required, in DPL's own terms (section 4). angle, lens and perspective are optional. perspective says whose view the shot takes. A subjective shot also names whose eyes it is, and the person whose eyes they are is never seen in it. eyeline says where eyes go: who looks at what, or that no one meets the lens. focus says how sharp the shot is, which can carry meaning (narrowed, disoriented, recovering). motion describes the character of a moving camera.

Camera (scenes[].shots[].camera)

MotionFeel (scenes[].shots[].camera.motion)

A travelling camera's path. A camera that travels gives its path: phases in time order, each with a movement, the size it arrives at, how it moves relative to a character, prop or location, on which side, and the part of the location it carries the viewer into. The relation (relation) is one of from, around, past, over, through, toward, into, away_from and with; give it together with the subject it is relative to. The human shot list spells the path out in industry terms, for example "0:03 ≈ Boom Shot (rise) from table → 0:04.5 Arc Shot around reader (over right shoulder) → 0:07 Drone Shot through window into garden" (fixture the-fly.dpl.plan.json).

PathPhase (scenes[].shots[].path[])

[{"at_ms": 0, "movement": "rise", "size": "medium", "relation": "from", "subject": "table"},
 {"at_ms": 1500, "movement": "arc", "relation": "around", "subject": "MAYA", "side": "over_right_shoulder"},
 {"at_ms": 4000, "movement": "drone", "relation": "through", "subject": "window", "into": "garden"}]

Introductions. introduces says what first comes into view in a shot, and how: an entrance, a discovery, a light_reveal, an emergence, a return or a cause. Say why it appears there. Converting tools carry it on as story-critical or (with minor) contextual.

ShotIntroduction (scenes[].shots[].introduces[])

Picture kinds. A shot's picture names what kind of picture it is: source_document, official_document, map, portrait, reconstruction, footage, presenter, chapter_card, visual_pun, quote_text, split_screen, sponsor_set or other. serves names the beat ids (section 2.8, sound.beat_functions) the shot answers. source_shown records evidence visible in another kind of shot, and note explains the choice. suggest-pictures prints defaults with reasons and whether a shot explicitly serves each beat. For a map, or a map-backed portrait, map_camera gives from and to geographic views [west, south, east, north] and a start_ms/end_ms interval inside the shot; the adapter carries that timing to realisation, which applies it to the bound map.

ShotPicture (scenes[].shots[].picture)

MapCameraPlan (scenes[].shots[].picture.map_camera)

{"id": "M1", "purpose": "Show how far the road runs.", "subject": "The road from Jerusalem to Jericho.",
 "start_ms": 0, "end_ms": 6000, "camera": {"size": "extreme_wide", "movement": "drift", "angle": "high", "lens": "wide",
   "perspective": "objective", "focus": "clear",
   "motion": {"path": "onward", "variation": "organic", "weight": "controlled", "force": "wind", "energy": "low"}},
 "source": "graphic", "props": ["lamp"],
 "picture": {"kind": "map", "serves": ["b1"], "note": "a map shows the distance faster than the words can",
   "map_camera": {"from": [30.0, 28.0, 38.0, 34.0], "to": [34.5, 31.2, 35.6, 32.0], "start_ms": 500, "end_ms": 5500}},
 "image_brief": "An aged map, warm paper, the road inked in red.", "motion_brief": "A slow push toward the city.",
 "must_not": ["modern roads"]}

2.6 Live-action facts: coverage, staging, lines, states

These are the facts the edit-readiness checks reason over (added 1 Oct 2026, docs/capability/EDIT_READINESS.md). All are optional. They let a plan answer, before anything is shot or generated, whether the edit will have what it needs. Section 3 says which detail switches which check on. Fixtures: tests/corpus/readiness/.

Coverage says what a shot gives the edit and how much it matters. role is one of establishing, master, two_shot, single, over_shoulder, reaction, insert, cutaway, pov or neutral. priority is must, should or nice; a must cannot be dropped without losing the scene's job, and dpl replan never drops one.

Coverage (scenes[].shots[].coverage)

The line of action (axis) is the line between two subjects. It says who is on the left of frame and who is on the right, from the camera's side of the line, and every shot keeps them there unless the camera crosses on screen (crosses_line). The checks need it to catch crossed-line cuts. Travel (travel) is the way travel runs across the screen in a scene, for a chase or a journey: left, right, toward or away. It is kept from shot to shot.

Axis (scenes[].axis)

Staging puts each subject in the frame: its side of frame (left, centre, right), where it looks (facing: left, right, camera, away) and which way it moves (moving: left, right, toward, away, none). A shot stages each subject once. The setup of a shot is a name for the camera set-up it is filmed from (A, B); shots that share a name are shot together, which is how the checks see a jump cut and how a replan finds a whole set-up to drop.

Staging (scenes[].shots[].staging[])

Lines are the spoken lines of a scene as the edit sees them: who says each (speaker), to whom (to), when, and turn when how the listener takes it is part of the moment, so the audience must see them. A turning line needs to. A speaker is a character, and a line is not said to its own speaker. to is a character, or one of three typed targets for a line that no single character takes: camera, audience or group (see "Lines to the camera, the audience or a room" below). Lines here are separate from the sound.speech lines that carry the recording (2.8). A scene where nobody speaks on screen says so with none (see "Saying no").

DialogueLine (scenes[].lines[])

Lines to the camera, the audience or a room

A presenter talks to the lens, a vox-pop answers an interviewer who is off screen, a safety video speaks to whoever is watching, a best man toasts the whole room. None of these has one character to look at, so to takes three typed targets instead of a character id:

dpl missing does not ask "who is this said to?" about a line that gives one of these targets, and it offers them as answers when it does ask.

[
  {"id": "L1", "speaker": "host", "to": "camera", "start_ms": 1000, "end_ms": 4000, "text": "Welcome back. Today: how to change a flat tyre."},
  {"id": "L2", "speaker": "host", "to": "audience", "start_ms": 4500, "end_ms": 7000, "text": "And yes, you can do this in a dress."},
  {"id": "L3", "speaker": "best_man", "to": "group", "among": ["bride", "groom", "mother"], "start_ms": 8000, "end_ms": 12000, "text": "Raise your glasses."}
]

Saying no

A plan that is silent about something and a plan that says there is none are different. A scene with no lines might be a silent scene or a scene nobody has described yet; dpl missing cannot tell, so it asks. none is the way to answer: a list of things the scene, the sequence or the film deliberately does not have, each with an optional why.

Absence (none[], scenes[].none[], sequences[].none[])

• spoken_lines (in a scene): nobody speaks on screen. The scene must have no lines (DPL-NONE if it has). Narration in sound.speech is separate and unaffected. dpl missing stops asking who speaks, and not_assessed stops listing "spoken lines".
• line_of_action (in a scene): the scene is staged without a line of action, as in 360-degree coverage or the line-free staging of Ozu. The scene must have no axis (DPL-NONE if it has), and must say why. dpl missing stops asking which side of the line the camera is on. RDY-AXIS has nothing to judge here (it does not fire on position, even if an axis is left in by mistake, which the validator reports). The eyeline and jump-cut checks still apply, and so does everything else: the declaration says there is no line, not that the staging is unchecked.
• journey (in the film or a sequence): the camera travels nowhere. The film or sequence must have no journey (DPL-NONE if it has). dpl missing stops asking whether the camera travels, when the film says so, or when every sequence does. A sequence's none says it has no journey of its own; a journey on the film still governs its scenes.

[{"kind": "spoken_lines", "why": "A silent scene: only the wind."},
 {"kind": "line_of_action", "why": "360-degree master: the camera circles the table, so no side of a line is kept."}]

[{"kind": "journey", "why": "The film stays in the one room."}]

Why a list of terms, not a flag per fact. Each absence carries its own reason, the list is one place to look, a new kind of "none" is one more term and not another member on another type, and the empty list is still the default, so a plan that says nothing reads exactly as before. A fact that is left out is not yet answered; only an entry in none is an answer.

State changes and states. A prop that changes (a glass breaks, a door opens) is recorded as a scene state_changes entry, with shown set when the audience must see it happen. A shot's states say what state each prop is in as the shot shows it. Together they let the checks catch a prop shown whole after it broke, or a change nobody sees.

A shot's states describe what is seen in it; a shot that contains a change may show either side of it. A shot that runs across a state_changes entry (the glass breaks at 23,200 ms inside a shot that runs 22,800 to 24,500) can truthfully be described by the state before the change or the state after it, so the checks accept either from or to for that prop in that shot. A shot that does not contain the change shows the state the prop is in at that time. No separate field says which.

StateChange (scenes[].state_changes[])

PropState (scenes[].shots[].states[])

{"id": "K7", "purpose": "The glass slips from his hand and breaks.", "subject": "glass",
 "start_ms": 22800, "end_ms": 24500, "camera": {"size": "detail", "movement": "hold"}, "source": "footage",
 "props": ["glass"], "coverage": {"role": "insert", "priority": "must"}, "setup": "E",
 "states": [{"prop": "glass", "state": "broken"}]}

Rig actions

A shot's staging of a rigged character can name its actions, one after another inside the shot. Each kind is one of walk, argue, turn_head, kneel, look_up, point, climb and stumble.

• walk goes to a frame x or box (to) or by a distance, with a step_ms for the length of a step cycle.
• argue swings an arm (side, left or right; right when absent).
• turn_head and look_up turn the head to an angle (to, degrees).
• kneel goes down to a kneel.
• point draws an arm back and strikes toward an angle (to) with the arm named by side; the strike lands about 60 per cent of the way through its span.
• climb is a run of climbing steps with a step_ms (900 when absent).
• stumble is a trip, a catching arm and a recovery. It takes no extra members.

An action is timed in one of two ways. Give start_ms and end_ms, which must fall inside the shot and follow the action before. Or give at, a word of a measured spoken line (line, word, and on: "stress" to land on the stress rather than the start), with a duration_ms: the hit lands on that word and the start is worked out from the duration. The line needs source_ms and a words entry for that word (2.8). The reader accepts at on any kind, but it is meant for point and climb, whose hit has a contact moment. Only a character with a rig can act (DPL-RIG).

StagingAction (scenes[].shots[].staging[].actions[])

ActionWordAnchor (scenes[].shots[].staging[].actions[].at)

[{"subject": "MAYA", "side": "left", "facing": "right", "moving": "right",
  "actions": [
    {"kind": "walk", "start_ms": 0, "end_ms": 2000, "distance": 0.3, "step_ms": 800},
    {"kind": "point", "at": {"line": "L1", "word": 2}, "duration_ms": 1000, "side": "left", "to": 20},
    {"kind": "stumble", "start_ms": 4000, "end_ms": 5500}]}]

2.7 Picture layers and overlays

Two ways to build a picture beyond a single image. Overlays put something over a shot's picture for part of its length: an inset, a nameplate, words that land, a counter, a diagram. Layers build the shot in depth: the room behind, anything between, the subject in front, each with its own timing and motion, so they can drift apart or slide off different ways. Without layers the shot is one picture.

Overlays. An overlay's kind must match its members: an inset shows a subject; a nameplate or caption has text; words has its words; a counter has a count running from one number to another; a diagram has a diagram. Only a diagram has nodes. A words, caption or nameplate on screen for under 800 ms is a warning, as too brief to read. A caption with timing starts on a spoken moment, so it needs an anchor; timing gives the allowed range for its end (held long enough, cleared in time), and its start is never moved to fit. style names a technique in lower-case words joined by underscores; realisation draws it. backing is the shape behind text (solid, accent, band, none), chosen per use.

A diagram is a simple animation over the picture that explains the point: labelled boxes placed on the frame, links that draw on between them, and markers that travel. Positions are fractions of the frame; times are film milliseconds, each tied by the plan's author to a word. It may run on across the following shots of its scene, since an argument drawn over a cut must not restart.

Overlay (scenes[].shots[].overlays[])

TimedWord (scenes[].shots[].overlays[].words[])

WordHighlight (scenes[].shots[].overlays[].words[].highlight)

Count (scenes[].shots[].overlays[].count)

CaptionTiming (scenes[].shots[].overlays[].timing)

Diagram (scenes[].shots[].overlays[].diagram)

DiagramNode (scenes[].shots[].overlays[].diagram.nodes[])

DiagramLink (scenes[].shots[].overlays[].diagram.links[])

DiagramMover (scenes[].shots[].overlays[].diagram.movers[])

[{"id": "ov1", "kind": "nameplate", "start_ms": 500, "end_ms": 3000, "purpose": "Name the speaker.", "position": "lower_third", "text": "Maya", "subtitle": "Tom's wife", "backing": "band"},
 {"id": "ov2", "kind": "counter", "start_ms": 3000, "end_ms": 5000, "purpose": "Show the debt growing.", "text": "pounds owed", "count": {"from": 0, "to": 40000}},
 {"id": "ov3", "kind": "words", "start_ms": 5000, "end_ms": 8000, "purpose": "Land the sentence word by word.", "style": "soft_rise",
  "words": [{"text": "the", "at_ms": 5000}, {"text": "money", "at_ms": 5400, "highlight": {"word": "money", "at_ms": 5800}}]},
 {"id": "ov4", "kind": "caption", "start_ms": 8000, "end_ms": 11000, "purpose": "Subtitle the quote.", "text": "He told me about the money.",
  "anchor": {"line": "L3", "boundary": "onset"}, "timing": {"min_hold_ms": 1500, "max_hold_ms": 4000, "within_shot": true}},
 {"id": "ov5", "kind": "diagram", "start_ms": 11000, "end_ms": 14000, "purpose": "Show where the money went.",
  "diagram": {"nodes": [{"id": "a", "label": "Tom", "x": 0.25, "y": 0.5, "at_ms": 11000}, {"id": "b", "label": "Brother", "x": 0.75, "y": 0.5, "at_ms": 11500, "tone": "claim"}],
              "links": [{"from": "a", "to": "b", "at_ms": 12000, "draw_ms": 800}],
              "movers": [{"id": "m", "label": "cash", "from": [0.25, 0.5], "to": [0.75, 0.5], "at_ms": 12500, "dur_ms": 1000}]}}]

Layers. A layer has a depth (background, intermediate, foreground), a subject, and a purpose. A foreground layer's subject must be a character or prop in the shot; a subject in front with no background layer is a warning, because the shot's own picture is then the background. A layer moves in three ways, which combine: a single motion (a hold, a drift, a rise, a slide, a push, a pull, a parallax, or a converge where layers travel into one frame and settle at at); keys, which animate it (offset, scale, rotation, opacity and which way it faces, eased between keys, and a key can land on a spoken moment); and actions, which repeat (a walk's bob, a breath, a flicker). parallax is how much the layer follows the shot's window, the camera as a window travelling over the painted picture.

Layer (scenes[].shots[].layers[])

LayerMove (scenes[].shots[].layers[].motion)

LayerPlace (scenes[].shots[].layers[].at)

LayerKey (scenes[].shots[].layers[].keys[], scenes[].shots[].window[])

LayerAction (scenes[].shots[].layers[].actions[])

[{"id": "sky", "depth": "background", "subject": "KITCHEN", "purpose": "The room behind.", "motion": {"kind": "drift", "direction": "left", "amount": "subtle"}},
 {"id": "maya", "depth": "foreground", "subject": "MAYA", "purpose": "Maya crosses the room.", "start_ms": 500, "region": "lower", "entrance": "fade", "exit": "fade",
  "pivot": [0.5, 0.92], "parallax": 1.6,
  "keys": [{"at_ms": 500, "x": -0.3, "turn": 1}, {"at_ms": 2500, "x": 0.1, "ease": "smooth"}],
  "actions": [{"kind": "walk", "amount": "moderate", "rate": 1.5}]}]

[{"at_ms": 0, "x": 0, "scale": 1.2}, {"at_ms": 4000, "x": -0.2, "scale": 1.2, "ease": "in_out"}]

2.8 Sound

Sound is planned at two levels. Per scene, sound[] says what speech, music, ambience, effects and authored silence are doing, hearing says whose ears the scene takes, and phrases says how each heard sound runs through it. Across the work, the top-level sound object places everything in film time: the carriers, the spoken lines, which carrier owns the foreground span by span, how sound crosses a change of picture, and the rules that protect moments such as an authored quiet.

Here is what the parts of sound are for:

• carriers name each source of sound once (a voice, a song, a room tone, a planned silence). Everything else refers to a carrier by id.
• speech is the fixed spoken words, placed in time. The plan never changes the words.
• beat_functions mark what the words are doing over film time, across scene boundaries (a claim from a source, a place, a new act). Each names a span; speech refers to existing line ids, words is a readable excerpt, and source names the evidence cited. Beats are in time order and may not overlap: one clear job at a time makes picture suggestions and findings unambiguous. A shot's picture.serves points back at them. Readiness checks source visibility, act cards, presenter gaps, sponsor setting and unserved beats; a scene's accepts can record a justified departure. No check changes the speech.
• beats say which carrier owns the foreground, span by span, and which carriers support or are withheld.
• bridges say how sound crosses a change of picture or world.
• rules protect moments, with spans, failure conditions and a reviewer's check. A rule that is an authored quiet says so in quiet: how it begins, how it ends, and whether it must hold against anything breaking in.
• events are sounds at a moment (a hit, a chime), tied to a picture, to a spoken moment or to a pulse.
• pauses make room in the speech for an event or a picture join.
• intensity is the lever for feeling: where a music carrier's drums come forward or sit back while its song plays on.
• takeovers are a carrier rising on one straight line in dB, with nothing ducking it, not even the voice.

Sound (sound)

SoundCarrier (sound.carriers[])

A pulse is a measured beat grid for music with a steady pulse. It carries on in the listener's head after the music stops, so later moments can land on it: a spoken line or an event with lands_on starts on a beat or bar of the carrier's pulse, within 40 ms, and a carrier with no pulse has nothing to land on (DPL-RHYTHM). A message is for a carrier that speaks (a talking drum, a sung line in another language): it is part of the story, so its phrases are never cut part-way and never buried.

Pulse (sound.carriers[].pulse)

CarrierMessage (sound.carriers[].message)

MessagePhrase (sound.carriers[].message.phrases[])

Speech and anchors. A spoken line is placed in film time, and, when the recording is measured, in its own recording as well (source_ms, and per-word offsets in words). A speech anchor names a spoken moment: a line's onset or offset, plus a signed offset. A sound event, an overlay, a layer key or a caption's clear_before can use one, and the authored time must agree with it, so the item follows the words when the speech is placed differently (docs/realisation/SPEECH_ANCHORS.md).

SpeechLine (sound.speech[])

SpeechWord (sound.speech[].words[])

SpeechAnchor (sound.events[].anchor, scenes[].shots[].overlays[].anchor, ...overlays[].timing.clear_before, layers[].keys[].anchor, window[].anchor)

LandsOn (sound.speech[].lands_on, sound.events[].lands_on)

BeatFunction (sound.beat_functions[])

The function of a beat function is one of claim_from_source, law_or_official_fact, where, who, unfilmed_event, action, opinion_or_joke, new_act, figure_of_speech, quote, promise_or_question, sponsor or call_to_action.

SoundBeat (sound.beats[])

SoundBridge (sound.bridges[])

SoundRule (sound.rules[])

SoundSpan (sound.rules[].spans[])

QuietDesign (sound.rules[].quiet)

SoundEvent (sound.events[])

SpeechPause (sound.pauses[])

IntensityPoint (sound.intensity[])

Takeover (sound.takeovers[])

{"carriers": [
   {"id": "VOICE", "kind": "speech", "job": "The narrator."},
   {"id": "DRUM", "kind": "music", "identity": "a talking drum", "job": "Calls the town.",
    "pulse": {"period_ms": 500, "phase_ms": 0, "beats_per_bar": 4},
    "message": {"language": "Yoruba", "meaning": "Come home.", "phrases": [{"in_ms": 0, "out_ms": 2000}]}}],
 "speech": [
   {"id": "L1", "carrier": "VOICE", "text": "He told me about the money.", "start_ms": 1000, "end_ms": 3000, "source_ms": 0,
    "words": [{"index": 1, "start_ms": 0}, {"index": 5, "start_ms": 1200, "stress_ms": 1300}]},
   {"id": "L2", "carrier": "VOICE", "text": "It's not what you think.", "start_ms": 6000, "end_ms": 7500, "lands_on": {"carrier": "DRUM", "unit": "beat"}}],
 "beat_functions": [{"id": "b1", "function": "claim_from_source", "start_ms": 1000, "end_ms": 3000, "speech": ["L1"], "words": "He told me about the money.", "source": "Tom's brother"}],
 "beats": [{"start_ms": 0, "end_ms": 4000, "foreground": "VOICE", "supporting": ["DRUM"], "purpose": "The voice leads; the drum is under it."}],
 "bridges": [{"id": "br1", "at_ms": 4000, "retained": ["DRUM"], "exiting": [], "entering": ["VOICE"], "rule": "The drum carries over the cut."}],
 "rules": [{"id": "r1", "rule": "Nothing under the confession.", "withhold": ["DRUM"], "spans": [{"name": "confession", "start_ms": 1000, "end_ms": 3000}],
            "quiet": {"begins": "hold_back", "ends": "return", "must_hold": true}}],
 "events": [{"id": "e1", "carrier": "DRUM", "at_ms": 3500, "what": "A single hit as the glass lands.", "length_ms": 800, "clear_of_speech": true,
             "anchor": {"line": "L1", "boundary": "offset", "offset_ms": 500}}],
 "pauses": [{"after_line": "L1", "length_ms": 2000, "for": "e1", "why": "Give the hit room."}],
 "intensity": [{"carrier": "DRUM", "at_ms": 3500, "level": "high", "why": "Feeling rises here.", "ramp_ms": 1000}],
 "takeovers": [{"carrier": "DRUM", "start_ms": 6000, "end_ms": 7500, "from_db": -18, "to_db": 0, "why": "The drum takes the room as he stops speaking."}]}

In the scene. The per-scene parts tell a reader why the sound is as it is.

SceneSound (scenes[].sound[])

Hearing (scenes[].hearing)

Phrase (scenes[].phrases[])

The kind of a carrier or of a scene's sound is one of speech, music, ambience, effect or silence.

2.9 Transitions

A transition records a join that was decided: what the audience learns across it, what stays the same, the simpler alternatives that were considered and why they were not chosen. A join between shots that is not listed is an unremarked cut. Join only neighbouring shots: from is a shot and to is the shot directly after it, including across a scene boundary.

kind is how the two shots join: cut, match_cut, jump_cut, smash_cut, dissolve, fade, wipe or hold. A hold keeps the subject and framing intent, so the join is felt as a hold. need says why the picture must change here (existing_sufficient, new_world, distinct_planes, comparison, attention_transfer, deliberate_break); simpler is the simplest join that was considered instead (none, hold, reframe, cut). serves says whether the change moves the story on (story) or only moves attention (attention). A join that serves the story needs a purpose saying what happens. If every change in a sequence only moves attention, the validator warns (DPL-MOMENTUM); three joins in a row with the same device is DPL-VARIETY.

With all of this direction, converting tools carry the plan's direction into other formats.

Transition (transitions[])

ConsideredAlternative (transitions[].considered[])

[{"from": "K1", "to": "K2", "kind": "dissolve", "purpose": "The room gives way to Maya's face.", "keeps": ["MAYA"], "need": "attention_transfer",
  "simpler": "cut", "considered": [{"choice": "cut", "why_not": "A cut loses the slow turn from room to person."}],
  "persisting": ["MAYA"], "style": "light_point_reveal", "duration_ms": 600, "serves": "story"}]

2.10 Short-form profile

The short-form profile is for shoots made on a phone, or with a small crew and real cameras, in a few hours: a promo, a Short, an interview, a two-person scene. It adds what the first market's constraints need: what the crew shoots with, who is there and when, the light, the shoot day, and where the work is delivered. It is opt-in. A plan says work.profile: "short"; a plan that does not (film is the default, and what every plan written before the profile is) reads, validates and is checked exactly as it was, and none of the rules below run on it. Every member below is optional and additive, and reading is as strict as everywhere else: an unknown member or a misspelt term is an error.

Shoot Plan (the Shoot Plan app's own planner) plans the same kind of shoot for people. The short-form rules are ported from its rules (planner rules 2026-10-06.r6) and cite them, so the two agree; tools/dpl/import/shoot_plan_to_dpl.py turns a Shoot Plan plan into this profile (see "From Shoot Plan" below).

A complete short-form plan: one presenter, a phone, one morning. It validates with no diagnostics. The kit, the people, the location's light, the delivery and the day are what the short-form rules read.

{
  "format": "dpl.plan/1",
  "work": {"id": "first-loaf", "title": "The first loaf", "profile": "short", "target_runtime_ms": 9000},
  "delivery": {"aspect": "9:16", "max_runtime_ms": 30000, "platform": "Instagram Reels"},
  "kit": {
    "cameras": [{"id": "phone", "kind": "phone", "description": "Main phone", "lens_multipliers": [0.5, 1, 3], "frame_rates": [24, 30, 60]}],
    "supports": ["handheld", "tripod"],
    "sound": ["phone_mic", "lav"],
    "lights": ["reflector"]
  },
  "people": [
    {"id": "maya", "name": "Maya", "roles": ["talent"], "character": "MAYA", "available": [{"from": "08:30", "to": "11:00"}]},
    {"id": "sam", "name": "Sam", "roles": ["camera", "sound"]}
  ],
  "characters": [{"id": "MAYA", "description": "Maya, who runs the bakery."}],
  "locations": [{
    "id": "FRONT", "description": "The bakery's front step in the morning.",
    "setting": "outdoor", "usable_light": [{"from": "07:30", "to": "16:30"}],
    "sun": "Low from the south-east until about 10:00", "acoustics": "quiet"
  }],
  "scenes": [{
    "id": "S1", "purpose": "Maya shows the first loaf of the day.", "start_ms": 0, "end_ms": 9000, "location": "FRONT",
    "provenance": {"by": "human"},
    "lines": [{"id": "L1", "speaker": "MAYA", "to": "camera", "start_ms": 500, "end_ms": 6000, "text": "First loaf of the day."}],
    "shots": [
      {
        "id": "S1A", "purpose": "Maya says it to the camera.", "subject": "MAYA", "start_ms": 0, "end_ms": 6000,
        "camera": {"size": "medium", "movement": "hold", "lens_multiplier": 1, "support": "tripod", "device": "phone", "orientation": "portrait"},
        "source": "footage", "characters": ["MAYA"], "coverage": {"role": "single", "priority": "must"}, "setup": "A",
        "filming": {"speech": true},
        "provenance": {"by": "human"}
      },
      {
        "id": "S1B", "purpose": "The loaf, close.", "subject": "The loaf on the board.", "start_ms": 6000, "end_ms": 9000,
        "camera": {"size": "detail", "movement": "hold", "lens_multiplier": 3, "support": "tripod", "device": "phone", "orientation": "portrait"},
        "source": "footage", "coverage": {"role": "insert", "priority": "should"}, "setup": "B",
        "provenance": {"by": "human"}
      }
    ]
  }],
  "schedule": {"days": [{
    "id": "day1", "date": "2026-10-24", "start": "09:00", "end": "10:00", "locations": ["FRONT"],
    "setups": [{"id": "A"}, {"id": "B", "not_before": "09:20"}],
    "tasks": [{"id": "tone-front", "kind": "room_tone", "location": "FRONT"}]
  }]}
}

Clock times are "HH:MM", 24-hour, with two digits each ("09:30", never "9:30" or "9.30am"); anything else is DPL-CLOCK. A window (from, to) is a span of clock time on a shoot day; with a day (a day id of the schedule) it applies on that day, without one on every day.

Work. work.profile is film (the default) or short. A plan with short-form members and no short profile gets one DPL-PROFILE warning and nothing else: the members are read and kept, and no short-form rule runs.

Delivery (delivery)

Real crews are served as well as phones: a camera is a phone (lenses as multipliers) or a camera (lenses in millimetres). A kit that lists nothing for a thing (a camera with no lenses, no supports, no frame rates) says nothing about it, so the check for that thing does not run, and dpl missing asks.

Kit (kit)

KitCamera (kit.cameras[])

KitLens (kit.cameras[].lenses[])

A lens is a prime (mm) or a zoom (min_mm and max_mm), never both and never neither (DPL-KIT).

Camera terms for the profile. A shot's camera has, besides the DPL terms of section 4: lens_multiplier (a phone's lens, for example 3) or focal_mm (a camera's lens in millimetres), never both; support (what carries the camera, from the kit's supports); device (a kit camera's id, so the shot is checked against that camera's lenses; any camera that can film it otherwise); frame_rate (frames per second, for a rate that is not the usual one, such as slow motion); and orientation (portrait, landscape or square: how the camera is held, which decides the frame's shape). The industry vocabulary (section 4) has no term for a support, an orientation or a multiplier. It does describe lenses by focal length (a wide-angle lens is 18 to 35 mm on the 35 mm frame it measures against), so dpl shot-list names a focal_mm lens with the nearest MovieLabs lens term, as an approximate match, after the crop factor; the vocabulary's one other overlap, Gimbal Shot as a synonym of Steadicam Shot, is why a gimbal is accepted for the steadicam move.

People are the cast and crew, each with roles and the times they are there.

Person (people[])

TimeWindow (people[].available[], locations[].usable_light[], locations[].access[])

Locations. The existing time_of_day and light stay prose for the people reading the plan. The profile adds typed facts beside them: setting (indoor or outdoor), usable_light (windows by clock time when there is light to film in; outdoors it is the daylight, indoors say it only when daylight is what lights the room), sun (where the sun is, in words, if known), access (windows when the crew may be at the place; without any, always), acoustics (quiet, controllable: the noise can be switched off, or fixed: it cannot) and quieter_position (true when a speaker may move somewhere quieter).

The schedule is the shoot days. A shot points to its day through its setup (the existing grouping of shots filmed from one camera position): the day lists the set-ups it films, in the order they are filmed. A shot whose set-up is on no day goes to the day that uses its scene's location. Shot ids and set-up ids are the keys a later take log (dpl.takes/1) records takes against, so none is made from order.

Schedule (schedule)

ShootDay (schedule.days[])

DaySetup (schedule.days[].setups[])

Move (schedule.days[].moves[])

CaptureTask (schedule.days[].tasks[])

filming on a shot says how it is filmed, when that is not what its coverage role implies.

Filming (scenes[].shots[].filming)

A scene or a shot may say who or what set it: provenance is { "by": ..., "ref": ... } with by one of human, draft_model, shoot_plan_planner, script_import or ingress, and an optional ref naming what it came from (a Shoot Plan shot id, a script line). It is inert metadata: no rule reads it. (It is not called source, which a shot already has: what the picture is made from.)

Provenance (scenes[].provenance, scenes[].shots[].provenance)

How the day is worked out. The shoot day is added up the way Shoot Plan's scheduler does it, with its own figures (the timing file, each value citing its Shoot Plan rule and rules version): the day's preparation; then for each visit to a location a move, a wait for access, the location setup and, before the first speech there, a sound check; each shot takes its role's working time (its setup, then its takes, each of recording plus a pad either side, and a reset between takes); room tone and voiceover tasks go last before leaving; and the spare time is the larger of 5 minutes and 15% of the work done (waiting excluded). The day's committed time is the work plus the spare time, and it must fit between start and end. The order is the plan's: set-ups as the day lists them, shots in plan order inside a set-up. Nothing searches for a better order.

The short-form rules (dpl readiness; each finding says in its message which expectation breaks, and the rules are in docs/capability/EDIT_READINESS.md). They are production-feasibility findings, listed after the story and rhythm findings and before the eye-trace and space ones. Major means the shot cannot be filmed as planned.

Ask the plan what it is missing. A short-form plan with no kit, delivery, people or schedule gets no feasibility check at all, each rule returning without a word. dpl missing asks for them (kinds kit, delivery, people, schedule, light and sound), with the answer's shape.

From Shoot Plan. tools/dpl/import/shoot_plan_to_dpl.py plan.json [--intake intake.json] --out plan.dpl.plan.json reads a Shoot Plan plan (and, if given, the intake it was made from) and writes this profile. Every element carries provenance shoot_plan_planner; each Shoot Plan shot keeps its id; minute 0 of the shoot is put on the clock at --day-start (09:00 by default). What DPL has no place for is listed in an import report beside the plan, never dropped. The converted Shoot Plan examples are in tests/corpus/short/.

{"id": "FRONT", "description": "The bakery's front step in the morning.", "setting": "outdoor",
 "usable_light": [{"from": "07:30", "to": "16:30"}], "access": [{"from": "07:00", "to": "12:00"}],
 "sun": "Low from the south-east until about 10:00", "acoustics": "fixed", "quieter_position": false}

{"role": "MASTER", "takes": 1, "record_ms": 40000, "once": true, "preroll_ms": 60000, "postroll_ms": 30000, "speech": true}

{"id": "cam-b", "kind": "camera", "description": "Mirrorless body", "lenses": [{"mm": 35}, {"min_mm": 24, "max_mm": 70}],
 "crop_factor": 1.5, "sensor": "APS-C", "frame_rates": [24, 25, 50]}

3. Which details make the checks work

The edit-readiness checks (dpl readiness) read typed facts, not prose. A check whose facts are absent returns without a finding, which is not the same as passing: not_assessed in the findings, and dpl missing, say when that happened. So a plan that wants the checks to speak must give them the details below. The rules themselves, and the corrected table of what each one needs, are in docs/capability/EDIT_READINESS.md.

Beat functions and the house structure receive these findings (each scene can accept a code with a why):

Ask the plan what it is missing. dpl missing plan.json says, in the plan's own names, what to ask the person who knows the film so the checks can read it ("In scene S1, which side of the line between MAYA and TOM is the camera on, and where does each stand?"), with the paths the answer fills and the rules it unlocks. It exits 4 when a question blocks the assessment of a scene. Do not invent a detail to silence a question. When the honest answer is "none", say so with none ("Saying no", 2.6): a scene where nobody speaks declares spoken_lines, a scene staged without a line of action declares line_of_action with its reason, and a film that goes nowhere declares journey. The question is then answered and no longer asked.

4. Camera terms and the industry vocabulary

Plans use DPL's own camera terms (Terms.cs):

They follow common industry usage, and each is mapped to the MovieLabs Creative Vocabulary in a pinned, versioned table (IndustryVocabulary/). The mapping says how close each match is:

• exact: the same idea (55 of the 59 DPL camera terms);
• approximate: the nearest industry term, with a note saying what differs: detail ≈ Extreme Close-Up Shot, rise and descend ≈ Boom Shot, drift ≈ Static Handheld Shot;
• none: the vocabulary has no term (none today).

MovieLabs' Establishing Shot is the one v1.0 term no DPL term maps to: in DPL, establishing is what a shot is for (its purpose, or its coverage role), not a size. perspective has no MovieLabs category.

Upgrading. Plans store DPL terms only, so a new MovieLabs version never invalidates a plan. Adopting one means adding a mapping class for it, checked by the tests against the published file, and listing it in IndustryVocabularies.All; renderings then use it by default, and earlier versions stay selectable (--vocabulary movielabs@1.0). The v1.0 mapping is checked against the pinned file (SHA-256 6bdbbec4…, from the 7 September 2026 design freeze): hash, version, every slug and every term name.

5. Validation

The schema (contracts/dpl/dpl.plan-1.schema.json) describes what the reader accepts. Reading is strict: an unknown member, a misspelt term ("Hold", "PushIn", "static-shot"), a missing required member, or a fractional millisecond is an error, never silently defaulted or ignored.

A plan that reads is then validated: ids are unique and every reference resolves, times run forward and stay inside their scene and the work, required text is not empty, and the editorial and sound rules hold. Each fault is reported with a DPL-* code, an error (the plan is unusable downstream) or a warning (for a director to look at). The full list of codes, with what each enforces, is the one table in contracts/dpl/README.md; it is checked against the code by a test, so this page does not repeat it.

Reading diagnostics

Each diagnostic has five parts: the code (the rule), the severity (error or warning), the path (a JSON path into the plan, such as $.scenes[1].shots[0].purpose), the message (what is wrong) and the fix (what to change next). dpl validate plan.json prints the first four, one line each, and exits 1 when there is an error. dpl validate plan.json --format json writes all five as dpl.diagnostics/1 (schema contracts/dpl/dpl.diagnostics-1.schema.json):

{
  "schema": "dpl.diagnostics/1",
  "plan_hash": "9f2c1e7ab04d58c3e6a1f20b97d4c85e3a6b1d0f2e8c7945a3b6d1e0f4c2a8b7",
  "valid": false,
  "summary": { "errors": 1, "warnings": 0 },
  "diagnostics": [
    {
      "code": "DPL-DUPLICATE",
      "severity": "error",
      "path": "$.scenes[2].shots[0].id",
      "message": "Shot \"SH01\" appears twice.",
      "fix": "Rename $.scenes[2].shots[0].id to an id no other shot uses, for example \"SH05\"; shot ids are unique across all scenes (first use: $.scenes[0].shots[0])."
    }
  ]
}

• Act on the fix, at the path. The fix uses the plan's own ids and paths. It names the field to add or change, the ids that do exist (one of: kitchen, hall), or the terms that are allowed (one of: extreme_wide, wide, ...). A misspelling is matched to the closest id or term, and a long list is cut to the nearest few, in a fixed order, so the same plan always gives the same advice. When no single id stands out, no guess is made.
• Errors first, then validate again. Errors make the plan unusable downstream; warnings are for a director to look at (the fix says how to clear them). A change can clear several diagnostics at once, or reveal others, so validate after each round.
• DPL-JSON means the plan was not read. The reader stops at the first fault (an unknown member, a misspelt term, a missing member, a fractional millisecond, a syntax error), so it comes alone, with the path of the value and a fix that names what was expected there. The one exception is a null where a list item or a map value should be ("scenes": [null]): every such item is reported, at its own path. The validator never sees an unread plan.
• plan_hash is present only when the plan could be read. It is the SHA-256 of the plan in its standard layout, the same revision hash dpl readiness and dpl missing report, so an answer can be tied to the plan it was about.
• Messages do not change; fixes may improve. The message text is stable (tests and films depend on it). The fix is advice and may be reworded; the golden file tests/contract/VideoEditor.Dpl.Plan.Tests/Golden/diagnostics.golden.json shows the current wording for eleven codes.

The other commands say what to do next in their errors too: dpl apply lists the finding ids, or the fix ids on that finding, when the one you gave does not exist; dpl replan says which limit could not be met, by how much, and what to relax; any input that cannot be read names what was expected there. Exit codes are unchanged.

Slices

dpl slice cuts some scenes of a plan, with everything they refer to, into a smaller plan of its own, so an agent can work on one scene without holding the whole film (docs/dpl/DPL_CONTEXT_TOOLS.md). A slice is an ordinary valid plan; the one thing that marks it is slice_of.

SliceOf (slice_of)

{"plan_hash": "9f2c1e7ab04d58c3e6a1f20b97d4c85e3a6b1d0f2e8c7945a3b6d1e0f4c2a8b7", "scenes": ["kitchen"], "shots": ["k1", "k2", "k3"]}

A slice keeps the whole film's clock (its first scene may start well after 0). Because a plan with slice_of is cut from a longer film, dpl validate does not report the time before its first scene as a DPL-GAP, RDY-JOURNEY-PROGRESS does not say it fails to arrive when it holds no scene at the destination, and RDY-STATE does not judge a prop against a state it only guessed from its first shot (docs/dpl/DPL_CONTEXT_TOOLS.md). A hand-written plan never needs slice_of; leave it out.

6. Renderings

Both are derived from the plan and add nothing to it. Neither is produced from a plan with errors.

• Shot list for people (dpl shot-list plan.json): Markdown, per scene: purpose, change, attention, a shot table in industry names (≈ marks an approximate term), decided joins with the alternatives considered, and spoken lines, beat functions and picture kinds when declared.
• Shot list for tools (dpl shot-list plan.json --format json, dpl.shot-list/1, schema contracts/dpl/dpl.shot-list-1.schema.json): every shot with its DPL term and industry term (category, slug, name, match, note) and the vocabulary name, version and file hash; optional beat functions and picture kinds are carried with their times.

7. Command line

dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- validate plan.json [--format json]   # exit 0 valid, 1 invalid; json: dpl.diagnostics/1 with a fix for each
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- shot-list plan.json [--format json] [--vocabulary movielabs@1.0]
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- suggest-pictures plan.json [--format json]  # advisory only
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- format plan.json         # standard layout
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- terms                    # DPL terms and industry names
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- readiness plan.json [--format json]   # edit-readiness findings
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- apply plan.json findings.json <finding> <fix>
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- replan plan.json constraints.json [--out revised.json] [--format json]   # dpl.replan/1
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- bench tests/corpus/readiness   # the benchmark (short-form mutants included)
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- missing plan.json [--format json]    # what to ask the human (dpl.missing/1); exit 4 when one blocks
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- takes validate plan.json takes.json    # the take log (dpl.takes/1) against the plan; see docs/dpl/DPL_TAKES.md
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- takes merge a.json b.json [--out merged.json]   # join two take logs by op_id; exit 6 on a conflict
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- coverage-status plan.json takes.json [--location L] [--format json]   # "did we get it?" (dpl.coverage-status/1); exit 5 while a must-have shot has no good take
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- draft start brief.json [--format json] [--plan-out skeleton.json]   # a valid skeleton plan, the layers to write it in, the first action (dpl.draft/1); see docs/dpl/DPL_DRAFTING.md
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- draft next plan.json [--brief brief.json] [--format json]   # the layer reached, what it lacks, the questions, tested fixes, one next action (dpl.draft-next/1)
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- draft gate plan.json [--format json]   # ready to shoot? pass or fail with a certificate (dpl.draft-gate/1); exit 7 on a fail
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- schema plan                 # JSON Schema: plan | findings | shot-list | constraints | diagnostics | missing | replan | bench | takes | coverage-status | brief | draft | draft-next | draft-gate | draft-grammar | summary | diff | dispositions
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- summary plan.json [--findings f.json] [--format json|markdown]   # the plan in about 300 words (dpl.summary/1)
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- slice plan.json --scene S1 | --shots a,b | --sequence Q    # a sub-plan with slice_of
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- diff old.json new.json [--old-findings f --new-findings g]   # what changed, by id (dpl.diff/1)
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- disposition plan.json <finding-id> accepted --reason "..." --by name   # dpl.dispositions/1
dotnet run --project tools/dpl/VideoEditor.Dpl.Cli -- readiness plan.json --dispositions d.json   # remembered decisions hold while the evidence is unchanged

- reads the plan from standard input. Exit codes: 0 success, 1 invalid plan, 64 usage, 65 not UTF-8 (or JSON that is not what the command expects, such as a malformed constraints file), 66 cannot read the file. readiness, reconcile and bench use 2, replan uses 3 when the constraints cannot be met, missing uses 4 when a question blocks the assessment of a scene, coverage-status uses 5 while a must-have shot in scope has no good or circled take, takes merge uses 6 when one op_id names two different takes, and draft gate uses 7 when the plan is not ready.

8. Not in this version

• Other formats. Converting a plan to other formats is done by separate tools, not by this format.
• Reading industry terms in. Plans are written in DPL terms. Accepting MovieLabs terms as input (for example from the ingress) is not yet supported.
• Performance and affect (the portrayals in the earlier library) and per-shot sound are not yet modelled.
• More real plans. Kingdom of God's shot plan records movements and carriers but no framing or camera, so it cannot yet be imported without inventing them.