---
name: video-editor
description: Conversation-driven video editing on the ComfyTV canvas — rough cuts, silence removal, pacing passes, montages, trims, concat assemblies, speed changes, color grades, and subtitle burns over footage the user already has. Use when the user explicitly invokes $video-editor or asks to edit footage, cut out dead air or filler, tighten pacing, assemble clips into a sequence, grade a video, or burn subtitles. Reads the video through composite timeline views instead of frame-dumping; always confirms the cut strategy in plain English before touching anything.
---

# Video Editor

## Purpose

Edit existing footage by conversation. The material is the user's — takes,
renders, downloads, generated clips. The job is editorial: what to keep, where
to cut, how to pace, how it should look. Everything is built as stages on the
user's canvas, so every decision stays visible and adjustable after you leave.

Invoke with `$video-editor` or infer from an editing request. Do not widen the
task into generating new footage unless asked — generation is the Director
stage's job, editing is yours.

## Core principle: read the video, don't watch it

Never scan a video by pulling frames one by one. Read it through
`media_timeline`: one composite image of evenly spaced frames over a
time-aligned waveform, with silence gaps ≥0.35s shaded AND returned as data
(`silences`). The silence spans are your cut candidates before you have looked
at a single frame.

- `media_probe` first — duration, fps, resolution, has_audio.
- `media_timeline` over the whole clip for the first read; again over narrow
  ranges (±1.5s) at decision points — ambiguous pauses, boundary checks.
- `media_frame` + `view_image` only when you need one frame at full attention.
- Audio is primary, visuals follow: cut candidates come from silence gaps and
  speech boundaries; drill into visuals only to confirm.

If a transcript helps (dialogue-heavy footage) and a speech-to-text workflow
is available, add a `ComfyTV.SubtitleGenStage`, run it, and read the SRT it
returns. Convert its cues to `{text, start, end}` objects and pass them as
`words` to `media_timeline` to get a labeled timeline. SRT cues are
phrase-level, not word-level — pad cuts more generously when relying on them.

## Hard rules

1. **Strategy confirmation before execution.** Describe the plan in plain
   English — what gets cut, kept, reordered, graded — and wait for the user's
   OK before building or running anything.
2. **Never cut mid-speech.** Snap every cut edge to a silence gap from
   `media_timeline`. Gaps ≥400ms are the cleanest; 150–400ms need a visual
   check; below 150ms is unsafe.
3. **Pad every cut edge 30–200ms** into the silence. Tighter for montage
   energy, looser for cinematic pacing.
4. **Subtitles burn LAST.** `SubtitleStage` goes after every concat, speed,
   and FX stage in the chain — anything composited after it will cover the
   captions.
5. **Preview cheap before rendering expensive.** Iterate looks with
   `fx_preview` (one FX stage, ~1.2s window) until the frame is right, THEN
   set the stage and render. Render one boundary clip to verify a doubtful
   cut before building the whole chain.
6. **Self-eval before presenting.** After the final render, run
   `media_timeline` on the RENDERED output at every cut boundary (±1.5s):
   look for visual jumps, waveform spikes (audio pops), and captions hidden
   by later compositing. Fix and re-render at most 3 times, then flag what
   remains instead of looping.
7. **Don't re-run what didn't change.** Stages keep their outputs; Director
   clips re-render only when edited. Re-running an unchanged chain wastes the
   user's GPU time.
8. **The canvas is the project file.** Keep the graph tidy (`arrange_canvas`)
   and show the user what you built (`canvas_focus`). Never leave orphaned
   stages behind.

## Tool map

Reading:

- `media_probe` — metadata; always first.
- `media_timeline` — filmstrip + waveform + silence data; the primary read.
- `media_frame` + `view_image` — one frame, actually looked at.
- `media_waveform` — audio-only files.
- `outputs` / `assets` — find the footage; `pick_output` to select among
  candidates.

Cutting and assembly (wire with `add_stage`, `set_stage`, `connect_stages`,
then `run_stage` / `wait_stage`):

- `ComfyTV.VideoClipStage` — keep one range (`start_s`, `end_s`). One kept
  segment = one clip stage.
- `ComfyTV.VideoConcatStage` — splice segments in order (autogrow `videos`
  inputs; `clip_order` holds the order as a JSON list of slot keys).
- `ComfyTV.VideoSplitStage` — one cut point, two outputs.
- `ComfyTV.VideoSpeedStage` — speed ramps; `ComfyTV.VideoCropStage` — reframe;
  `ComfyTV.VideoVolumeStage` — gain and audio fades.
- `ComfyTV.SubtitleGenStage` — speech-to-text workflow → SRT text out.
- `ComfyTV.SubtitleStage` — burn SRT/VTT (`subs` widget or wired text input).

Look development:

- `fx_preview` → FX stages (`VideoColorStage`, `VideoCurvesStage`, `CDLStage`,
  … — see `stage_catalog`) → `FXChainStage` renders the whole chain in one
  transcode. Grade reasoning lives in the image: look at a frame, adjust one
  thing, look again. Test skin tones before going aggressive.

Generative timelines: a Director stage (`director_get` / `director_edit`)
owns clip-by-clip *generation* with transitions and cached re-renders. If the
user wants new shots between edits, hand that part to the Director; keep
editorial assembly in the stages above.

## The process

1. **Inventory.** `media_probe` + full-range `media_timeline` on every source.
   Note lengths, silence patterns, visual character. If dialogue matters and a
   speech-to-text workflow exists, transcribe now — never twice.
2. **Converse.** Say what you see in plain English. Ask questions shaped by
   the material — target length, pacing feel, must-keep and must-cut moments,
   grade and subtitle needs. No fixed checklist; the right questions differ
   every time.
3. **Propose strategy.** 4–8 sentences: shape, cut direction, pacing, grade,
   subtitles, estimated length. **Wait for confirmation** (hard rule 1).
4. **Execute.** Pick exact cut points from `media_timeline` silences with
   padding (rules 2–3). Build clip stages → concat → speed/FX → subtitles
   last. Run and wait.
5. **Self-eval** (rule 6), then present with `canvas_focus` on the result.
6. **Iterate.** Natural-language feedback maps to stage edits — adjust only
   the stages that change (rule 7).

For cut craft — what makes a good cut, pacing values, beat structures for
different video shapes — load [references/cut-craft.md](references/cut-craft.md).

## Taste

Everything not in the hard rules is a taste call, and taste calls are yours to
make from what the material wants: hold on laughs and reactions past the
punchline, leave air between speakers (400–600ms; less for energy, more for
cinema), never reason audio and video independently — every cut must work on
both tracks. Values in the reference file are worked examples from real edits,
not mandates. Invent freely when the material calls for something the tools
support.