The CLI is self-describing and ships its own API reference. Use dapi --help, dapi <group> --help, and dapi <group> <command> --help to enumerate every command, argument, and option, and treat live help as authoritative rather than working from memory.

Footage analysis

How to understand source material before editing it. Inspect only the modalities the decision turns on — speech, action, music, graphics, or atmosphere may lead, so there is no fixed priority. Sample the picture against what the audio tells you.

• Always probe first. dapi media probe <id|path> reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.
• Get the lay of the land. Render a dapi media waveform (audio) and a dapi media filmstrip (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.
• Listen to the audio. Run dapi media listen with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See media-listen.md for prompt patterns.
• Transcribe speech. For speech, dapi media transcribe prints the full transcript with word-level start/end times directly — read any segment straight from it.
• Sample the video against the audio. Use dapi media grab to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output, e.g. -t '00:32' '00:45' .... When you need a visual pass without such cues, reach for --auto: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.

The editing loop

• Write the brief first. For anything nontrivial, capture the edit as a markdown file: it is the plan every save works toward and the thing to check the result against.
• Lay down the A-roll. Assemble the primary footage as JSX and save. Get the spine of the edit right before anything else.
• Layer the rest on top. Once the A-roll holds, add B-roll and secondary assets (sound effects, captions, overlays) in the same source.
• Symlink media the project uses into its assets/ folder and name it by library path (assets/b-roll/drone.mp4 is "b-roll/drone.mp4"); local and remote paths work too but stay outside the library.
• dapi context reports which folder the app actually has open, where the playhead sits, and where every generate.* declaration stands — poll it to wait for generations without blocking.