podcast-episode-producer

Files (3)

• SKILL.md
• metadata_plan.py · scripts/
• render_verify.py · scripts/

SKILL.md (first lines)

# Podcast episode producer

You are producing a finished podcast episode from a raw recording. The
goal is **a single ~30-90 minute mp4 the user can publish today**. You
own the whole flow end-to-end; ask the user for input only on
genuinely-ambiguous editorial calls (e.g. "do you want to keep this
tangent at 22:14?"), not on mechanics.

Completion means the whole producer pipeline, not a few cleanup edits.
If the user says "edit this", "prepare this episode", "finish this", or
similar, continue through structure, cleanup, visual/brand polish,
audio/package metadata, confirmation, render, verification, and handoff
unless a specific blocker prevents it. Do not stop after start/end trims,
dead-air cleanup, loudness, or a draft note and imply the episode is done.

## The editor-order playbook

Run these in order. After each step, summarize what you did in 1-2
short sentences before moving on. After the timeline draft,
present the cut list to the user and pause for confirmation before
rendering.

### 1. Preflight the project

- Call `list_assets` if available, then `view_episode`.
- Confirm raw video, clean audio, music, graphics, b-roll, and any
  sponsor/media assets are present. If separate audio exists but the
  timeline has no synced/paired graph representation, report a sync
  blocker instead of pretending the edit is ready.
- Use `bash`/`ffprobe` only for sanity checks such as duration, frame
  rate, audio streams, corrupt files, and sample rate. Do not mutate
  media or `project.otio.json` through `bash`.
- Target long-form delivery is usually 1080p or 4K, source frame rate,
  48 kHz audio, and timeline render via `start_render(scope="timeline")`.

### 2. Read the episode shape

- Call `view_episode` to see the full episode map (speakers, topics,
  duration, indexed channels).
- Call `find_episode_start` to identify the publishable start. Raw
  podcast recordings often begin with real transcript text that is
  still pre-roll, off-camera setup, or a rehearsed intro; do not infer
  the start from `read_index(offset=0)` or from the first dead-air gap.
- Run `podcast_flow_shape` before any extraction or cleanup on raw
  recordings longer than one normal episode, recordings with repeated
  starts/closes, or recordings that may contain planning chatter. This is
  the blocking episode-shape gate: use the returned transcript packet to
  classify flow semantically as one episode, multiple publishable
  episodes, clip candidates, and post-show/production spans. Literal
  boundary phrases are recall evidence only.
- Run `podcast_episode_spans` or `auto-cutter/scripts/episode_span_plan.py`
  as a secondary hint pass, not as the source of editorial truth. If the
  semantic flow review or span planner indicates multiple publishable
  spans, stop and ask the user which episode to produce before trimming.
- Do not continue to cleanup, visual polish, or render while
  `podcast_flow_shape` still reports `blocks_timeline_edits=true` and no
  explicit chosen span / user-choice escalation has been recorded.
- After the user chooses a span, or after semantic review confirms a
  single accepted span, immediately persist it with `apply_episode_spans`
  (`status="accepted"`, `create_stringouts=true`) and verify with
  `list_episodes`. If one raw cast is split into multiple episode
  projects/timelines, repeat this in each resulting project. Timeline
  clips alone are not sufficient episode-scope metadata.
- Call `shot_summary` if vision indexers ran — it tells you whether
  this is a heavy-B-roll edit (62%+ no-face shots = lots of cutaways)
  or a clean talking-head (>70% medium/close-up = minimal cutaways).
- If `view_episode` shows zero topics and zero moments, stop and tell
  the user the project hasn't been indexed yet. Don't try to edit raw
  footage without the brain.
- Use montage's richer index set when present: topic for chapter
  structure, editorial-moments for hooks/payoffs, shot for visual
  texture, face/gaze for direct-address moments, frame-quality for
  usable thumbnails, and CLIP/shot tools for cutaways.

### 3. Find the real start, ending, and cold open

Find the real start before cleanup. Also find the real ending: remove
tail chatter, "are we done?", standing up, technical talk, and dead air
after the useful close. If a stronger mid-episode moment exists, build a
cold open: hook first, then intro/title, then the chronological start.
Represent this as `Insert Clip`/`Move Clip`/`Trim Clip` graph edits, not
as render-time slicing.

After extracting or drafting the usable episode span, re-read the
timeline-relative transcript/topic map before creating chapters. This
second pass is how the old editor avoided source-time chapter drift:
the first pass finds the real episode inside a messy recording; the
second pass names the actual topic transitions in the extracted edit.
If the second pass still sees rehearsal, pre-show, post-show, or a
botched intro take, tighten the span before branding.

### 4. Identify the editorial spine

Pull the strongest 3-5 editorial beats. Use them to structure the
episode:

```
find_beat(kind="hook", min_score=0.7)         → opens the episode
find_beat(kind="cta",  min_score=0.6)         → closing thoughts / pitch
find_beat(kind="punchline", min_score=0.7)    → mid-episode peaks
find_beat(kind="emotional_peak", min_score=0.6)
```

For each surviving moment, call `inspect_moment(moment_id=...)` to see
the surrounding transcript window + any dependencies. Dependencies are
**load-bearing**: if a punchline depends on a setup 2 minutes earlier,
keep both.

### 5. Radio edit the conversation

This is an audio/story pass before visual polish. Listen through the
full episode context via transcript, moments, and timeline ranges; do
not edit isolated snippets without understanding callbacks.

Use:

```
find_dead_air(max_silence_s=1.5)
find_filler_words(aggressive=false)

From explicit09/montage, Apache-2.0.

More from explicit09/montage