auto-cutter

Files (7)

• SKILL.md
• cleanup_plan.py · scripts/
• episode_flow_shape.py · scripts/
• episode_span_plan.py · scripts/
• retake_plan.py · scripts/
• test_episode_flow_shape.py · tests/
• test_episode_span_plan.py · tests/

SKILL.md (first lines)

# Auto-cutter

Use this skill when the user wants a one-pass cleanup, "auto edit",
episode extraction, or filler/silence removal. The correct order is:
**extract the real episode first, then clean it**. Do not run mechanical
cleanup across pre-show chatter, rehearsed intros, setup, or multiple
takes.

## Workflow

### 1. Identify the publishable episode

Call `view_episode`, then `find_episode_start`. Treat the start
recommendation as a hypothesis, not a blind timestamp: inspect the
surrounding moment if there are rehearsals, pre-roll, or multiple
welcome phrases.

Then run the flow-shape gate before making extraction edits:

```
podcast_flow_shape(asset_id="<asset>")
```

Use the returned packet to classify the transcript flow semantically:
one publishable episode, multiple publishable episodes, clip candidates,
and post-show/production spans. This decision belongs to the active
editor/LLM. Regex-like boundary hints are recall evidence only and must
not decide the edit by themselves.

Also run the episode-span planner as a secondary hint source:

```bash
python3 <skill-root>/scripts/episode_span_plan.py \
  --transcript index/whisper/raw/<asset>.json \
  --audio-energy index/audio-energy/raw/<asset>.json \
  --topic index/topic/raw/<asset>.json
```

If `podcast_flow_shape` still blocks timeline edits, or if either the
semantic flow review or `requires_user_choice` identifies multiple
publishable spans, do not cut yet. Present the candidate episode spans
and ask which one to produce.

Once the user chooses a span, or once the semantic flow review confirms a
single accepted span, immediately call `apply_episode_spans` with
`episodes=[{..., "status": "accepted"}]` and `create_stringouts=true`, then call
`list_episodes` to verify the stored metadata before applying extraction
or cleanup edits. If the recording is split into multiple episode
projects/timelines, each resulting project must store its own accepted
episode span. Do not treat an EDL/timeline shape as the only record of
episode scope.

### 2. Build the extraction cut

Use `view_timeline` to get clip anchors. Apply one extraction envelope
with `Trim Clip` or `Insert Clip` operations anchored by `clip_uuid`.
Pass `reasoning` explaining why the chosen start/end are the real
episode boundaries.

### 3. Semantic retake cleanup

Run the semantic retake planner before dead-air/filler cleanup:

```bash
python3 <skill-root>/scripts/retake_plan.py \
  --transcript index/whisper/raw/<asset>.json \
  --audio-energy index/audio-energy/raw/<asset>.json \
  --topic index/topic/raw/<asset>.json \
  --moments index/editorial-moments/raw/<asset>.json \
  --clip-uuid <clip_uuid>
```

Review every candidate. For medium/high-risk retake cuts, call
`assess_edit_quality` at the cut boundary before applying. Use its
recommendation rather than defaulting to a dissolve: move the cut to a
cleaner boundary, stamp `Set Cut Intent`, use `Set Audio Lead` /
`Set Audio Trail` for J/L repairs, or cover with b-roll when the visual
cut is dirty. Apply only accepted retake cuts through `apply_edl`, then
call `view_timeline`.

### 4. Mechanical cleanup

Run the bundled helper if you have audio-energy and transcript sidecars:

```bash
python3 <skill-root>/scripts/cleanup_plan.py \
  --audio-energy index/audio-energy/raw/<asset>.json \
  --transcript index/whisper/raw/<asset>.json \
  --preset standard
```

Then cross-check with:

```
find_dead_air(max_silence_s=1.0)
find_filler_words(aggressive=false)
find_false_starts()
podcast_editorial_review_pack()
```

Do not let those scanners decide the edit. They are recall signals for
the active AI. Use `podcast_editorial_review_pack` to inspect
before/during/after transcript context and classify each candidate as
`cut`, `keep`, or `review` before applying cleanup. This is especially
important for off-camera coaching, "we weren't recording" moments,
natural pauses, and repeated intro attempts where literal phrases like
"welcome" are weaker evidence than conversational intent.

For social/short-form output, rerun with `--preset aggressive`; for
interviews or tutorials, use `--preset gentle`.

### 5. Apply and verify

Batch retake and cleanup cuts in groups of 5-10 `apply_edl` ops. After
each batch, call `view_timeline` and report running duration removed.
Render only after extraction, retake review, and cleanup are complete.
Before final render or final report, call `vedit_diff` and make sure
the audit shows only the intended extraction and cleanup edits.

From explicit09/montage, Apache-2.0.

More from explicit09/montage