moda-video-footage

moda-video-footage

PREREQUISITE — load moda-core once per session (step-0, write contract, free/metered map). Already loaded? Skip ahead. If you cannot load it, the non-negotiables: run moda doctor --json before anything; moda brand list before creating; writes that pin a revision use your last read's — on stale_revision, re-read and retry once (it heals); send the canvas link the moment it exists; stuck or failed? moda ask "<question>" — free and fast, never guess.

What this lane is

The user has REAL clips on disk — a shoot, a trip, screen recordings — and wants a cut: a film, a reel, a highlight. Analysis stays local (Rushes, the optional toolkit riding moda rushes, indexes and searches the footage on this machine and uploads nothing); only the selects that make the cut are uploaded, and the deliverable is always BOTH the editable Moda timeline and the rendered mp4. Generating new footage is moda-video-clip's; motion over designs and type is moda-video-motion's; this lane cuts what already exists.

Read references/footage.md before the first command — it is the whole workflow with its invariants; references/otio.md carries the timeline interchange contract the endgame rides. What follows is the shape, not a substitute for either.

Recipe — folder to film

1. Toolkit check: moda rushes doctor --json. Typed rushes_not_installed teaches the fix — moda rushes install (it states what it downloads first; sizes are multi-GiB). Can't install? Degrade honestly: pick selects by eye with your harness's own tools and skip to step 5 — say the selection was manual, never pretend an index ran.
2. Index: moda rushes ingest FOOTAGE --project INDEX → moda rushes analyze INDEX → moda rushes status INDEX --json. The project directory is persistent memory — keep it, reuse it across revisions, never wipe it to re-ask a question.
3. Brief + probes: one short exchange for target duration, tone, priorities. Then probe search quality with a few moda rushes search INDEX "…" --top-k 8 --json queries and moda rushes show INDEX mom_… --json — look at contact sheets and transcript evidence; captions can hallucinate and rank is not confidence.
4. Choose: moda rushes highlight INDEX --target-minutes N for the candidate pool (~2.5× the target, one per duplicate cluster — material, not a film), then moda rushes select INDEX mom_… --name … --reason … --json in play order, with exact rational trims via --items when a moment needs shaving. Reason at duplicate-cluster level; consume returned ids.
5. Extract + upload: moda rushes extract INDEX sel_… --handles 2s --out SELECTS --json (or upload whole originals when the folder is a few small files), moda file upload each select, rewrite the media map's pending entries to uploaded with the REAL returned asset ids.
6. Timeline: author cut-v001.otio and dry-run it first — moda edit import CANVAS_REF cut-v001.otio --media-map media-map.json --dry-run — against a canvas you created (moda canvas create --category animation); then apply the same command with --yes in place of --dry-run (replace mode clears the existing timeline, so it refuses unconfirmed). Read the fidelity report; surface every dropped/approximated item. New versions are new files — v002, v003 — never an overwrite of the only cut.
7. Draft, look, iterate: moda export CANVAS_REF --format mp4 --scope main_edit -o draft.mp4, sample frames, judge against the brief. Small fixes are moda edit apply operations against a fresh read; a recut is the next .otio version.
8. Deliver: the live canvas link FIRST — the human always gets an editable timeline — then the mp4 and the .otio version file when the user wants an interchange copy for Resolve/Premiere.

Everything here is unmetered: indexing, uploads, import, export and iteration are free, so iterate on the cut as much as the piece needs. A music bed is an upload away (an audio track on the same timeline); a generated score is moda-audio's lane.

Boundaries stated plainly

• Rushes never uploads, never calls cloud inference, and needs no Moda account; Moda's cloud renders and exports and never reads local disk. You are the bridge, and selected media is the only cargo.
• The user chose uploads of SELECTED media — never bulk-upload the folder.
• Supported transitions and visual tracks import and render. Unknown effects, unpaired overlaps and resource limits decline by name in validation.diagnostics; relay them honestly. Never claim an unsupported edit exported without loss.
• An audio-only timeline does not export as mp4 — keep a visual clip on the cut.
• Full inference is Linux x86_64 and Apple Silicon; elsewhere use the media-only profile or the manual degraded path, and say which ran.

Errors

Any typed error → moda-core's recovery reference. rushes_not_installed / rushes_update_required: run moda rushes install, then re-run the SAME command. otio_import_rejected: the fidelity items name each offender — fix them (upload + rewrite pending entries; re-reference intermediates with their own timings), never invent asset ids. stale_revision on an edit: re-read and retry once — it heals.

Make it recurring

The weekly cut from a growing folder → moda-automate; the finished film's social variants → moda-social; a designed cover still → moda-image.

See also: moda-video — the family fork · moda-video-motion — type and motion over the cut · moda-core — contract, recovery, everything Moda can do.

References

Doc	Load when
references/footage.md	ALWAYS before the first rushes command — the workflow, its caching/timing invariants, degraded paths
references/otio.md	before authoring or importing a timeline — media maps, fidelity report, exact-time discipline, OTIO vs edit ops
references/export.md	rendering the draft and final — scopes, ceilings, warnings
references/reading-and-verifying.md	the review loop; verifying without vision