codex-video-editor

---
name: codex-video-editor
description: Create and revise reproducible, music-led montage videos locally from user-supplied raw video, music, voiceover, ambience, and sound effects. Use when Codex must inspect footage, describe and catalog shots, design an agreed narrative, build an agreed storyboard, select exact source ranges, assemble an FFmpeg timeline, mix supplied audio, render preview or master MP4 files, validate audiovisual continuity, or iterate an existing local editing project. Do not use for source sets over 30 minutes, deliverables over 90 seconds, dialogue-first or long-form edits, text-to-video generation, live-stream editing, motion graphics, a single trim or transcode, or general FFmpeg questions.
---

# Codex Video Editor

Create a short montage without external APIs. Keep every decision and render reproducible, reviewable, and reversible.

## Enforce v1 boundaries

- Accept only local, user-supplied media totaling at most 30 minutes. Never call third-party APIs. Never fetch stock media or models. Never install packages or download model weights silently; stop and request explicit approval for any environment change.
- Use Python 3.11 or 3.12 for v1. Treat any other interpreter version as a preflight blocker and use the resolved `<python>` executable in every command.
- Produce music-led montages up to 90 seconds as SDR H.264/AAC MP4. Limit delivery to 1080p, constant frame rate, `yuv420p` video, and 48 kHz stereo audio. Allow one continuous music bed, optional supplied voiceover, selective source ambience, and sound effects.
- Use local transcription only to inspect supplied audio and protect speech boundaries. Treat dialogue-led story editing, diarization, and transcript-derived assembly as out of scope.
- Before relying on optional ASR on a new machine, optionally run the manual acceptance check `<python> "<skill-root>/tools/profile_asr.py" --model-dir <local-base> --audio <representative>`. Accept only local-only base CPU/int8 batch-1 with `passed: true` and `peak_rss_bytes < 2000000000`. Do not make this resource-heavy check part of normal CI or routine editing.
- Use hard cuts and simple fades or dissolves. Defer titles, captions, stabilization, denoising, automatic reframing, advanced color matching, motion effects, multicamera sync, and NLE interchange.
- Let Codex choose the sequence from bounded candidate sets. Defer beam search, dynamic programming, and other automatic sequence optimizers.
- Preserve source files. Never modify, rename, or move them as part of an edit.

## Resolve the bundled tools once

- Resolve `<skill-root>` to the absolute directory containing this `SKILL.md`; never assume the current working directory is the skill directory. Every `scripts/...`, `tools/...`, and `references/...` path below is relative to that root.
- Resolve `<python>` once to an existing Python 3.11 or 3.12 executable. Prefer the skill checkout's `.venv/bin/python` on macOS/Linux or `.venv/Scripts/python.exe` on Windows when present. Verify the choice with `<python> "<skill-root>/scripts/doctor.py" --json`; do not fall back to an unsupported system Python.
- Treat angle-bracket names in commands as placeholders. Pass project and media paths independently; do not copy bundled scripts into the project.

## Follow the project lifecycle

1. **Freeze the brief.** Confirm the idea, audience, tone, ordered plot, target duration, aspect ratio, resolution, FPS, pace, ordering constraints, required and forbidden moments, audio priority, and delivery destination. Write a complete brief JSON file; initialization rejects a brief that leaves the required preflight choices implicit. Treat the immutable brief snapshot inside each revision as authoritative.
2. **Run preflight and initialize.** Run `<python> "<skill-root>/scripts/doctor.py" --json`, save the emitted JSON, and require `ready: true` before continuing. Initialize with `<python> "<skill-root>/scripts/project.py" init <project> --brief <brief.json> --toolchain-lock <doctor.json>`; initialization snapshots the brief into `revisions/r0001/brief.json`. Treat PySceneDetect, librosa, and local faster-whisper as optional capability tiers and record every fallback.
3. **Register or verify sources.** Register every intended source before analysis. Register every video with `<python> "<skill-root>/scripts/project.py" add-input <project> <source> --kind video --source-audio <mute|candidate|required>`. Register every standalone audio input with `--kind audio --audio-role <music|voiceover|ambience|sfx>`. Registration hashes and probes each source locally. The per-video `--source-audio` choice is required and persists canonically as `source_audio`; `required` demands a matching ambience clip in the timeline, while `mute` forbids one. Run `<python> "<skill-root>/scripts/project.py" verify <project>` whenever resuming. Read [references/artifact-contract.md](references/artifact-contract.md) before creating artifacts.
4. **Analyze and annotate hierarchically.** Run `<python> "<skill-root>/scripts/analyze.py" <project>` after registration. Use repeated `--input-id <id>` options to narrow a run; registered music inputs receive beat maps automatically. Transcribe only deliberately selected inputs by supplying both an already-local `--transcript-model <directory>` and repeated `--transcribe-input-id <id>`; retain each returned project-relative `transcript_path` for speech-boundary QC. The first combined index explicitly records semantic status `pending`. Inspect each candidate's start/middle/end/visual-interest strip and machine signals, then write a complete, evidence-bound Codex semantic-annotation draft using the literal template in the artifact contract. Rerun the same analysis selection and settings with `--semantic-annotations <draft.json>` until the resulting index reports semantic status `complete`. Register that completed index with `<python> "<skill-root>/scripts/project.py" put-artifact <project> --revision <revision> --artifact-type analysis_index --file <complete-index.json>` and retain the returned descriptor SHA-256. `analysis_index` is the canonical schema and revision-manifest kind; the CLI also accepts `analysis-index`, and the stored filename is `analysis-index.json`. Increase sampling only for ambiguous or shortlisted regions. Reuse the content-addressed machine-analysis cache across revisions, and do not begin narrative work from a pending or unregistered index.
5. **Design and approve the narrative.** Apply [references/editorial-heuristics.md](references/editorial-heuristics.md). Draft at least two footage-grounded alternatives. Set the narrative's top-level `analysis_index_sha256` to the registered `analysis_index` descriptor SHA-256, not to `semantic_annotations.machine_analysis_sha256`. Each alternative must cover the exact target duration with ordered beats containing a timing range, chosen timing, purpose, emotional energy, audio treatment, and evidence objects containing the exact indexed `input_id`, required `candidate_id`, and an integer-microsecond range inside that candidate's semantic usable range. Present the alternatives, record the chosen identifier in `selected_alternative_id`, then store the narrative with `<python> "<skill-root>/scripts/project.py" put-artifact <project> --revision <revision> --artifact-type narrative --file <narrative.json>` and record explicit approval with `<python> "<skill-root>/scripts/project.py" approve <project> --revision <revision> --gate narrative --actor <actor>`.
6. **Build and approve the storyboard.** After narrative approval, select exact source ranges by `input_id`, representative frames, ordering, source and output durations, explicit rational playback speed, transition types and durations, crop policy, audio treatment, and alternates. Keep speed at `{"num": 1, "den": 1}` unless a different constant speed in `1/4..8/1` is an intentional editorial choice; show the user every non-1× choice before approval. Never embed approval state. Use absolute evidence-image paths or paths relative to one chosen asset root. Start from the literal draft template in the artifact contract, then validate and render review HTML with `<python> "<skill-root>/scripts/storyboard.py" <draft.json> --output <storyboard.html> --normalized-output <storyboard.json> --fps <approved-fps> [--asset-root <root>]`. Store the normalized JSON with `put-artifact`, which attaches the owning revision and validates project source ranges; present the review, including visible speed labels, then approve gate `storyboard`.
7. **Materialize the timeline.** After storyboard approval, create `timeline.json` from its cards. Reference every selected source by registered `input_id`, never by a file path. Keep video, music, voiceover, ambience, and sound effects as independent tracks. Use integer microseconds, link every video clip to its storyboard card, and preserve the approved video input, source start, `source_duration_us`, `output_duration_us`, rational `speed`, output start, transition type, and transition duration exactly. Treat speed as video-only: never infer it from unequal durations, time-stretch an audio track, or include a video's source audio unless an explicit independent ambience clip selects it. On every transcribed audio or source-ambience clip, copy the analyzer's project-relative `transcript_path` unchanged so QC can resolve it from the project root and reject trims inside words. Store the timeline with `put-artifact`, which validates source ranges, output spans, storyboard alignment, and per-video source-audio rules before encoding.
8. **Render and inspect a preview.** Store the timeline with `put-artifact`, then run `<python> "<skill-root>/scripts/render.py" <project> --revision <revision> --profile preview` and `<python> "<skill-root>/scripts/qc.py" <project> --revision <revision> --profile preview`. QC must reject a missing, incomplete, or stale `renders/<revision>/preview/render-lock.json`; the lock must bind the exact output, timeline, revision brief, toolchain, input manifest and source hashes, and render implementation. Inspect the full preview and generated cut-review HTML. Apply [references/quality-gates.md](references/quality-gates.md) and convert subjective concerns into timestamped findings. After any timeline or render-input change, render and QC a new preview before requesting rough-cut approval.
9. **Revise immutably.** Use `<python> "<skill-root>/scripts/project.py" new-revision <project> --change-request <reason>` whenever changing approved work. The child carries the parent's brief snapshot byte-for-byte by default; supply `--brief <complete-brief.json>` to give the child a changed aspect ratio, resolution, FPS, duration, or other delivery contract. Never edit project-root `brief.json` to revise an edit. The revision-neutral `analysis_index` carries forward byte-for-byte; revision-owned narrative, storyboard, and timeline JSON is rebound and rehashed while the narrative keeps the same analysis digest. Approvals and renders do not carry forward; reapprove every gate in the child. If the new brief makes carried timing invalid, use `--no-carry-forward` and rebuild revision-owned planning artifacts. If `inputs.json` changed, also use `--no-carry-forward`, register a new complete index, and rebuild its bound narrative. Restrict local repairs to affected beats when the approved narrative remains valid.
10. **Approve, render, and release the master.** Require current narrative and storyboard approvals, preview QC with zero technical blockers, and explicit rough-cut approval with `<python> "<skill-root>/scripts/project.py" approve <project> --revision <revision> --gate rough_cut --actor <actor>`. Rough-cut approval must bind the exact preview, timeline, preview render lock, and QC report; do not approve if any binding is missing or stale. Then run `<python> "<skill-root>/scripts/render.py" <project> --revision <revision> --profile master` and QC the master with the same revision and `--profile master`. Visually and audibly review the encoded master, then record the immutable content-bound result with `<python> "<skill-root>/scripts/project.py" editorial-review <project> --revision <revision> --actor <actor> --decision <approved|changes_requested> [--findings <findings.json>]`. Run `project.py delivery-ready` and require `ready: true` before handoff. A changes-requested decision starts a child revision. This delivery review is human evidence, not a fourth render-authority gate.

## Apply approval and failure rules

- Treat `narrative`, `storyboard`, and `rough_cut` approval as three separate gates; bind `rough_cut` to the reviewed preview. Never infer approval from silence, an earlier gate, or approval of the general idea.
- Bind every approval, render lock, and QC report to the owning revision's exact brief SHA-256. A parent remains governed by its own brief after a child changes format.
- Store approvals append-only in `approvals.jsonl`, including artifact hashes, actor, decision, and timestamp. Bind rough-cut records to preview, timeline, render-lock, and QC-report hashes, and revalidate the lock's complete provenance whenever checking approval status. Use `<python> "<skill-root>/scripts/project.py" invalidate` to append invalidations and cascade them by default.
- Treat `editorial-review.json` as immutable delivery evidence outside `APPROVAL_GATES`. Record it only against a current passing master bundle; never overwrite it. Require `delivery-ready` to revalidate the current master, QC, render lock, brief, timeline, inputs, sources, toolchain, and approved review before release.
- Approve a narrative only after the lifecycle revalidates its exact current `analysis_index_sha256`, every `(input_id, candidate_id)` evidence reference, every semantic usable range, and the current input-manifest binding. Stale narrative provenance makes its approval and dependent storyboard and rough-cut approvals non-current. Once a narrative has ever been approved in a revision, do not replace that revision's `analysis_index`, even after invalidation; create a child revision.
- Stop on a missing required input, hash mismatch, undecodable stream, unsatisfied mandatory story beat, or unavailable required FFmpeg capability. Report the exact blocker and the smallest corrective action.
- Mark degraded analysis in its artifacts. Treat pending, incomplete, or unregistered semantic analysis as a planning blocker. Never claim reliable beat alignment without a confident beat grid or speech continuity without timestamped local ASR and review.
- Never conceal a missing shot by duplicating footage, freezing a frame, implicitly changing playback speed, or synthesizing filler. Use constant video speed only when its exact ratio and source/output ranges are visible in and approved with the storyboard; otherwise bring the conflict back to storyboard review.
- Prefer deterministic scripts for probing, timing, validation, and rendering. Use Codex judgment for semantic descriptions, narrative choices, storyboard review, and timestamped editorial findings.

## Keep the handoff complete

Return only a `delivery-ready` revision: its identifier, `revisions/<revision>/brief.json` and digest, `revisions/<revision>/master.mp4`, duration and format, input and artifact hashes, `toolchain-lock.json`, `renders/<revision>/master/render-lock.json`, master QC report, `renders/<revision>/master/editorial-review.json`, and any warnings or deferred editorial choices. Make the next iteration start from project artifacts rather than reconstructing state from conversation.