buttercut 0.4.0 → 0.6.0

data/.claude/skills/roughcut/agent_prompt.md

@@ -0,0 +1,153 @@
+# Roughcut Agent Instructions
+
+You are a video editor AI agent. The user approved a narrative plan in their main conversation — direction and structure, not a paper cut. Your job: explore the library, find real moments that fill each beat, build the rough cut iteratively, review and refine against format conventions, then return the cut with your editorial notes.
+
+The plan is your compass. The library is your full toolkit.
+
+## Working style
+
+This is async work. **You do not ping the user mid-task.** You commit to a complete cut, then return with your reasoning and any alternatives you considered. The parent dialogues with the user from there.
+
+Within the task, work iteratively, not in one shot:
+1. Take one beat from the plan at a time.
+2. Read transcripts only for the videos you actually need.
+3. Drop candidate clips into the YAML — close enough, not perfect.
+4. Move on.
+5. After every couple of beats, **look back**. Cut earlier clips that get said better later. Tighten dragging beats. Swap in stronger moments.
+
+You'll touch the YAML many times. That's the point.
+
+The plan suggests footage per beat as a starting point. If a stronger moment lives in a video the plan didn't name, use it — note the deviation in your return notes so the user knows what you considered.
+
+## Workflow
+
+### 1. Read the library
+
+Open `libraries/[library-name]/library.yaml`. The library includes:
+- The full video inventory (filenames, paths, audio + visual transcript paths)
+- `footage_summary` — what the project is, the tone, the subjects
+- `user_context` — what you've learned about this user across sessions
+
+After reading the library, you can determine what files you'll need to read beat-by-beat.
+
+### 2. Set up the YAML
+
+Derive a slug from the plan's filename (the `[short-name]` portion of `plan_[short-name]_[timestamp].md`). Generate a fresh timestamp:
+
+```bash
+date +%Y%m%d_%H%M%S
+```
+
+Reuse the same timestamp string for the YAML and exported XML. Copy the template:
+
+```bash
+cp templates/roughcut_template.yaml "libraries/[library-name]/roughcuts/[slug]_[timestamp].yaml"
+```
+
+Set `description` in the YAML to a one-line summary of what the cut is.
+
+### 3. Build beat by beat
+
+**Clip file types** (all under `libraries/[library-name]/`):
+- **Summary** (`summaries/summary_*.md`) — high-level markdown about what happens in a clip. Short and quick to scan. Use to explore adjacent clips or remind yourself what's in a clip without loading the full transcript.
+- **Visual transcript** (`transcripts/visual_*.json`) — segment-level (roughly sentence): `start`/`end` (seconds), `text` (dialogue, `""` if silent), `visual` (shot description, only when visuals change). This is the primary file for picking moments.
+- **Audio transcript** (`transcripts/*.json`, same name without the `visual_` prefix) — same shape as the visual transcript plus a `words` array per segment with per-word `start`/`end`. Reach for it when you need word-level in/out points to trim inside a segment.
+
+For each beat in the plan:
+- Open visual transcripts for the videos that feed it.
+- Pick moments that make sense and drop clips into the YAML.
+- If the segment's dialogue should be cut down, grep to find the word-by-word timing in the audio transcript. These files can be large, so it's generally faster and better to grep for the moment, rather than loading the entire file into memory. See the worked example below.
+- After you've completed a scene or beat, consider going back to improve earlier beats if you can make them stronger, more cohesive, or can remove redundancy.
+
+**Worked example — trimming inside a segment.** A wordy segment from `transcripts/visual_DJI_123.json`:
+
+```json
+{
+  "start": 15.129,
+  "end": 17.195,
+  "text": "We're also using AI on the back end to try to find issues as well as try to find more test issues."
+}
+```
+
+The line restates itself — "to try to find issues as well as try to find more test issues." End the clip after the first "issues" instead. The audio transcript lives at the same path without the `visual_` prefix (`transcripts/DJI_123.json`). Grep for the word to get its `end` time:
+
+```bash
+grep -B 1 -A 2 '"word": "issues' libraries/[library-name]/transcripts/DJI_123.json
+```
+
+Returns both occurrences — pick the one matching context (the first "issues" ends at 16.272s, the final "issues." at 17.195s):
+
+```json
+{ "word": "issues",  "start": 16.152, "end": 16.272 },
+{ "word": "issues.", "start": 17.054, "end": 17.195 }
+```
+
+Trimmed clip: `in_point: 00:00:15.13`, `out_point: 00:00:16.27`. Drops nearly a second of redundant phrasing.
+
+**Each clip needs:**
+- `source_file`: filename only (from the video's entry in `library.yaml`)
+- `in_point`: start of the FIRST segment in the clip, `HH:MM:SS.ss`
+- `out_point`: end of the LAST segment in the clip, `HH:MM:SS.ss`
+- `dialogue`: spoken words for the span — concatenate across segments if the clip covers more than one
+- `visual_description`: shot description from the visual transcript
+
+Use `start`/`end` from segments directly — preserve sub-second precision (e.g. 2.849s → `00:00:02.85`).
+
+**Transcripts can be wrong — fix them in the `dialogue` field in the roughcut YAML.** Transcripts will sometimes make mistakes on technical terms, brand names, proper nouns and when dealing with speakers with accents. They're not perfect. If you can clearly tell from context what was actually said, write the corrected version into the clip's `dialogue` field in the roughcut YAML. Do NOT edit the transcript JSON files themselves.
+
+#### Examples:
+"RubyVeedums" → "Ruby Meetups"
+"Cloud Code" → "Claude Code"
+"Hot Wide Native" → "HotWire Native"
+
+Only correct when you're confident based on context. If a phrase is genuinely ambiguous, leave it or see if another take or cut works better.
+
+### 4. Review pass — format-aware refinement
+
+Once a complete first pass exists, do a deliberate review with the format in mind. The plan tells you what kind of cut this is (vlog, YouTube Short, long-form, documentary, etc.). Use that to ask:
+
+- **Beat lengths.** Are individual beats the right length for this format? A one-minute static exposition might be right for a documentary but probably not correct for a vlog. Five-second B-roll clips might work for a documentary, but don't make sense for a vlog either. Think about what you're building and what the tone and pacing should feel like. Revise timings when it will improve the pacing.
+- **Dialogue tightness.** Does any clip's dialogue feel too wordy for the format and audience? The audio transcript's word-level timestamps let you trim inside a segment — drop filler, weak openers, or restarts when sharpening helps. **Word-level trimming is a first-class part of this pass, not an edge case.**
+- **Redundancy.** Is a point made twice across different beats? Cut the weaker version.
+
+Use editorial judgment based on what you know about the user (`user_context`) and what the format calls for.
+
+### 5. Finalize the YAML
+
+- `total_duration`: sum of all clips, `HH:MM:SS.ss`
+- `created_date`: `YYYY-MM-DD HH:MM:SS`
+- Confirm `description` still reflects the cut
+
+### 6. Export
+
+Use the `editor` value passed inline in the prompt — the parent already resolved it. Run the matching command:
+
+```bash
+# Final Cut Pro X
+bundle exec ./.claude/skills/roughcut/export_to_fcpxml.rb libraries/[library-name]/roughcuts/[slug]_[timestamp].yaml libraries/[library-name]/roughcuts/[slug]_[timestamp].fcpxml fcpx
+
+# Premiere Pro
+bundle exec ./.claude/skills/roughcut/export_to_fcpxml.rb libraries/[library-name]/roughcuts/[slug]_[timestamp].yaml libraries/[library-name]/roughcuts/[slug]_[timestamp].xml premiere
+
+# DaVinci Resolve
+bundle exec ./.claude/skills/roughcut/export_to_fcpxml.rb libraries/[library-name]/roughcuts/[slug]_[timestamp].yaml libraries/[library-name]/roughcuts/[slug]_[timestamp].xml resolve
+```
+
+### 7. Return — with notes
+
+Return a conversational message. Include:
+- The path to the YAML
+- The path to the exported XML in the library
+- Your editorial notes — alternatives you considered, judgment calls, plan deviations, pacing flags
+
+Example:
+
+> YAML: libraries/foo/roughcuts/my_cut_20260501_143022.yaml
+> XML:  libraries/foo/roughcuts/my_cut_20260501_143022.fcpxml
+>
+> A couple of alternates I had in mind:
+>
+> - For the ending, the dinosaur-wins angle could work — we'd swap in clips X, Y, Z. Happy to rebuild if that's the direction.
+> - The intro currently runs 35s; if you want it tighter, just the helicopter takeoff (clip K) lands in 8s.
+
+The parent reads your notes and dialogues with the user. Small fixes happen at the parent level; bigger restructures may relaunch this skill with a revised plan.

data/.claude/skills/roughcut/export_to_fcpxml.rb

@@ -102,6 +102,31 @@ def main
   generator.save(output_path)
 
   puts "\n✓ Rough cut exported to: #{output_path}"
+
+  validate_fcpxml(output_path) if editor_symbol == :fcpx
+end
+
+def validate_fcpxml(xml_path)
+  dtd_path = File.expand_path('../../../dtd/FCPXMLv1_8.dtd', __dir__)
+  unless File.exist?(dtd_path)
+    puts "⚠ DTD not found at #{dtd_path}; skipping validation."
+    return
+  end
+
+  unless system('command -v xmllint > /dev/null 2>&1')
+    puts "⚠ xmllint not found; skipping validation."
+    return
+  end
+
+  # xmllint prints errors to stderr; --noout suppresses the doc dump on success.
+  output = `xmllint --noout --dtdvalid "#{dtd_path}" "#{xml_path}" 2>&1`
+  if $?.success?
+    puts "✓ FCPXML validates against FCPXMLv1_8.dtd"
+  else
+    warn "✗ FCPXML failed DTD validation:"
+    warn output
+    exit 1
+  end
 end
 
 main

data/.claude/skills/summarize-video/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: summarize-video
+description: Generates a short markdown summary of a video from its visual transcript. Covers overview, key visuals, notable dialogue, and b-roll. Run after analyze-video as the final footage analysis step; summaries become a required field on every video before any roughcut can be created. Always launch this skill using the Haiku model.
+---
+
+# Skill: Summarize Video (parent brief)
+
+Generates a short markdown summary from a video's visual transcript. Always launch on the **Haiku model**.
+
+`SKILL.md` is the parent's dispatch brief. The sub-agent's working prompt lives in `agent_prompt.md` — inline its contents when launching the Task agent. Don't pass `SKILL.md`.
+
+## Parallelism
+
+Launch (at most) 10 agents in parallel until all videos are summarized.
+
+## Pre-create the skeleton (parent step, before launching the agent)
+
+For each video, the parent runs:
+
+```bash
+ruby .claude/skills/summarize-video/summary_skeleton.rb <visual_transcript_path> <summary_output_path>
+```
+
+This writes a skeleton file with the header (filename + duration) filled in and four `<!-- FILL_X -->` placeholders in the body. The agent fills them via `Edit`. The skeleton + Edit pattern is required: without it, Haiku frequently refuses Write and dumps markdown into its reply instead.
+
+## Inputs to gather and pass inline
+
+- `visual_transcript_path` — absolute path to the visual transcript JSON
+- `summary_output_path` — absolute path to the pre-created skeleton file
+
+After the agent returns, update `library.yaml` with `summary: <filename>.md`.

data/.claude/skills/summarize-video/agent_prompt.md

@@ -0,0 +1,39 @@
+# Summarize Video (sub-agent prompt)
+
+You are a sub-agent on the Haiku model. The parent has pre-created a skeleton summary file at `<summary_output_path>` with the header (filename + duration) filled in and four placeholder markers in the body: `<!-- FILL_OVERVIEW -->`, `<!-- FILL_KEY_VISUALS -->`, `<!-- FILL_DIALOGUE -->`, `<!-- FILL_BROLL -->`.
+
+Your job is to replace each placeholder with content using the **Edit** tool. Your text reply is just a one-line confirmation.
+
+## Inputs (passed inline by the parent)
+
+- `visual_transcript_path` — absolute path to the visual transcript JSON
+- `summary_output_path` — absolute path to the pre-created skeleton file
+
+## Action 1 — Bash: extract the script
+
+```bash
+ruby .claude/skills/summarize-video/visual_script_extractor.rb <visual_transcript_path>
+```
+
+The stdout is your input data: a header followed by interleaved `[VISUAL]` descriptions and timestamped dialogue.
+
+## Action 2 — Read the skeleton
+
+Read `<summary_output_path>`. The Edit tool requires this before editing.
+
+## Action 3 — Edit each placeholder
+
+Use the **Edit** tool four times to replace each `<!-- FILL_X -->` marker with the corresponding content:
+
+- `<!-- FILL_OVERVIEW -->` → 2-3 sentences describing the narrative arc. Be specific; avoid vague endings like "the clip ends with..." or "discusses something."
+- `<!-- FILL_KEY_VISUALS -->` → 3-6 bullets covering locations, distinctive shots, visual changes.
+- `<!-- FILL_DIALOGUE -->` → 0–3 quotes formatted as `> [MM:SS] "Quote"`. For clips under 30 seconds, often 0 or 1 is enough — write `None` if nothing stands out. Skip filler ("um", "you know", "I have to be honest"). Use the `[MM:SS]` shown next to each line in the script.
+- `<!-- FILL_BROLL -->` → cutaway descriptions distinct from the main subject. For single-shot clips, write `None`. Do not speculate about how the footage could be used as b-roll elsewhere.
+
+## Action 4 — Reply with one line
+
+After the four Edits succeed, your text reply must be exactly:
+
+`✓ <video_filename> summarized`
+
+Nothing else. The file is the deliverable.

data/.claude/skills/summarize-video/summary_skeleton.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# Pre-create a summary skeleton file for the summarize-video skill,
+# with header (filename, duration) filled in and four placeholder markers
+# in the body for the sub-agent to replace via Edit.
+#
+# Usage:
+#   ruby summary_skeleton.rb <visual_transcript.json> <summary_output.md>
+
+require 'json'
+
+class SummarySkeleton
+  def self.create(transcript_path, output_path)
+    new(transcript_path, output_path).create
+  end
+
+  def initialize(transcript_path, output_path)
+    raise ArgumentError, "transcript_path is required" if transcript_path.nil? || transcript_path.empty?
+    raise ArgumentError, "output_path is required" if output_path.nil? || output_path.empty?
+
+    @transcript_path = transcript_path
+    @output_path = output_path
+  end
+
+  def create
+    File.write(output_path, skeleton)
+    puts "skeleton: #{output_path}"
+  end
+
+  private
+
+  attr_reader :transcript_path, :output_path
+
+  def data
+    @data ||= JSON.parse(File.read(transcript_path))
+  end
+
+  def video_filename
+    File.basename(data["video_path"].to_s)
+  end
+
+  def segments
+    data["segments"] or raise "transcript JSON has no 'segments' key: #{transcript_path}"
+  end
+
+  def total_duration
+    segments.last["end"].to_f
+  end
+
+  def format_timestamp(seconds)
+    total = seconds.to_i
+    "%02d:%02d" % [total / 60, total % 60]
+  end
+
+  def skeleton
+    <<~MD
+      # #{video_filename}
+      **Duration:** #{format_timestamp(total_duration)}
+
+      ## Overview
+      <!-- FILL_OVERVIEW -->
+
+      ## Key Visuals
+      <!-- FILL_KEY_VISUALS -->
+
+      ## Notable Dialogue
+      <!-- FILL_DIALOGUE -->
+
+      ## B-Roll
+      <!-- FILL_BROLL -->
+    MD
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  transcript_path, output_path = ARGV
+  abort("usage: summary_skeleton.rb <visual_transcript.json> <summary_output.md>") unless transcript_path && output_path
+  SummarySkeleton.create(transcript_path, output_path)
+end

data/.claude/skills/summarize-video/visual_script_extractor.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# Extract a human-readable script from a visual transcript JSON,
+# interleaving [VISUAL] descriptions with timestamped dialogue.
+# Prints to stdout for direct consumption by the summarize-video skill.
+#
+# Usage:
+#   ruby visual_script_extractor.rb <visual_transcript.json>
+
+require 'json'
+
+class VisualScriptExtractor
+  def self.extract(transcript_path)
+    new(transcript_path).extract
+  end
+
+  def initialize(transcript_path)
+    raise ArgumentError, "transcript_path is required" if transcript_path.nil? || transcript_path.empty?
+
+    @transcript_path = transcript_path
+  end
+
+  def extract
+    puts header
+    puts
+    puts format_script
+  end
+
+  private
+
+  attr_reader :transcript_path
+
+  def data
+    @data ||= JSON.parse(File.read(transcript_path))
+  end
+
+  def segments
+    data["segments"] or raise "transcript JSON has no 'segments' key: #{transcript_path}"
+  end
+
+  def header
+    "# Video: #{video_filename}\n# Duration: #{format_timestamp(total_duration)}"
+  end
+
+  def video_filename
+    File.basename(data["video_path"].to_s)
+  end
+
+  def total_duration
+    segments.last["end"].to_f
+  end
+
+  def format_script
+    segments.filter_map { |s| format_segment(s) }.join("\n\n")
+  end
+
+  def format_segment(segment)
+    text   = segment["text"].to_s.strip
+    visual = segment["visual"].to_s.strip
+    ts     = format_timestamp(segment["start"].to_f)
+
+    lines = []
+    lines << "[#{ts}] [VISUAL] #{visual}" unless visual.empty?
+    lines << "[#{ts}] #{text}" unless text.empty?
+
+    lines.empty? ? nil : lines.join("\n")
+  end
+
+  def format_timestamp(seconds)
+    total = seconds.to_i
+    "%02d:%02d" % [total / 60, total % 60]
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  transcript_path = ARGV[0]
+  abort("usage: visual_script_extractor.rb <visual_transcript.json>") unless transcript_path
+  VisualScriptExtractor.extract(transcript_path)
+end

data/.claude/skills/transcribe-audio/SKILL.md

@@ -3,81 +3,34 @@ name: transcribe-audio
 description: Transcribes video audio using WhisperX, preserving original timestamps. Creates JSON transcript with word-level timing. Use when you need to generate audio transcripts for videos.
 ---
 
-# Skill: Transcribe Audio
+# Skill: Transcribe Audio (parent brief)
 
-Transcribes video audio using WhisperX and creates clean JSON transcripts with word-level timing data.
+Transcribes video audio using WhisperX and produces a clean JSON transcript with word-level timing.
 
-## When to Use
-- Videos need audio transcripts before visual analysis
+`SKILL.md` is the parent's dispatch brief. The sub-agent's working prompt lives in `agent_prompt.md` — inline its contents when launching the Task agent. Don't pass `SKILL.md`.
 
-## Critical Requirements
+## Parallelism
 
-Use WhisperX, NOT standard Whisper. WhisperX preserves the original video timeline including leading silence, ensuring transcripts match actual video timestamps. Run WhisperX directly on video files. Don't extract audio separately - this ensures timestamp alignment.
+Launch at most **2 in parallel**. WhisperX is already multithreaded internally (~4 CPU threads via CTranslate2); 2 processes is the throughput-vs-RAM sweet spot on a 16GB Mac.
 
-## Workflow
+## Inputs to gather and pass inline
 
-### 1. Read Language from Library File
+The parent reads `library.yaml` and `settings.yaml` and passes these values inline in each agent's prompt:
 
-Read the library's `library.yaml` to get the language code:
+- `video_path` — absolute path to the video file
+- `transcript_output_dir` — where to write the transcript JSON (e.g. `libraries/<library>/transcripts`)
+- `language_code` — ISO 639-1 code (e.g. `en`, `es`) — parent maps from library.yaml's `language` name
+- `whisper_model` — model size from settings.yaml (e.g. `small`, `medium`, `turbo`)
+- `transcript_refinement` — boolean from library.yaml. If `true`, also pass:
+  - `user_context` (may be empty string)
+  - `footage_summary` (may be empty string)
 
-```yaml
-# Library metadata
-library_name: [library-name]
-language: en  # Language code stored here
-...
-```
+After the agent returns, update `library.yaml` with `transcript: <filename>.json`.
 
-### 2. Run WhisperX
+## Next step
 
-```bash
-whisperx "/full/path/to/video.mov" \
-  --language en \
-  --model medium \
-  --compute_type float32 \
-  --device cpu \
-  --output_format json \
-  --output_dir libraries/[library-name]/transcripts
-```
+Once all videos have audio transcripts, dispatch `analyze-video` for visual descriptions.
 
-### 3. Prepare Audio Transcript
+## Dependencies
 
-After WhisperX completes, format the JSON using our prepare_audio_script:
-
-```bash
-ruby .claude/skills/transcribe-audio/prepare_audio_script.rb \
-  libraries/[library-name]/transcripts/video_name.json \
-  /full/path/to/original/video_name.mov
-```
-
-This script:
-- Adds video source path as metadata
-- Removes unnecessary fields to reduce file size
-- Prettifies JSON
-
-### 4. Return Success Response
-
-After audio preparation completes, return this structured response to the parent agent:
-
-```
-✓ [video_filename.mov] transcribed successfully
-  Audio transcript: libraries/[library-name]/transcripts/video_name.json
-  Video path: /full/path/to/video_filename.mov
-```
-
-**DO NOT update library.yaml** - the parent agent will handle this to avoid race conditions when running multiple transcriptions in parallel.
-
-## Running in Parallel
-
-This skill is designed to run inside a Task agent for parallel execution:
-- Each agent handles ONE video file
-- Multiple agents can run simultaneously
-- Parent thread updates library.yaml sequentially after each agent completes
-- No race conditions on shared YAML file
-
-## Next Step
-
-After audio transcription, use the **analyze-video** skill to add visual descriptions and create the visual transcript.
-
-## Installation
-
-Ensure WhisperX is installed. Use the **setup** skill to verify dependencies.
+WhisperX must be installed. Use the **setup** skill to verify.

data/.claude/skills/transcribe-audio/agent_prompt.md

@@ -0,0 +1,53 @@
+# Transcribe Audio (sub-agent prompt)
+
+You are a sub-agent. Transcribe one video file using WhisperX and produce a clean JSON transcript with word-level timing.
+
+**Critical:** Use WhisperX, NOT standard Whisper. WhisperX preserves the original video timeline including leading silence, ensuring transcripts match actual video timestamps. Run WhisperX directly on the video file — don't extract audio separately.
+
+## Inputs (passed inline by the parent)
+
+- `video_path` — absolute path to the video file
+- `transcript_output_dir` — where to write the transcript JSON
+- `language_code` — ISO 639-1 code (e.g. `en`, `es`)
+- `whisper_model` — model size (e.g. `small`, `medium`, `turbo`)
+- `transcript_refinement` — boolean; if `true`, also expect:
+  - `user_context` — string, may be empty
+  - `footage_summary` — string, may be empty
+
+Do NOT read `library.yaml` or `settings.yaml`. If a required input is missing from your prompt, stop and ask the parent rather than inferring from the filesystem.
+
+## 1. Run WhisperX
+
+```bash
+whisperx "<video_path>" \
+  --language <language_code> \
+  --model <whisper_model> \
+  --compute_type float32 \
+  --device cpu \
+  --output_format json \
+  --output_dir <transcript_output_dir>
+```
+
+## 2. Prepare audio transcript
+
+```bash
+ruby .claude/skills/transcribe-audio/prepare_audio_script.rb \
+  <transcript_output_dir>/<video_basename>.json \
+  <video_path>
+```
+
+This script adds the video source path as metadata, removes unnecessary fields, and prettifies the JSON.
+
+## 3. (Optional) Refine the transcript
+
+If `transcript_refinement: true`, follow `.claude/skills/transcribe-audio/refine_instructions.md`, using the `user_context` and `footage_summary` strings the parent supplied inline. Do NOT open `library.yaml`. Skip if `transcript_refinement` is missing or `false`.
+
+## 4. Return success response
+
+```
+✓ <video_basename.mov> transcribed successfully
+  Audio transcript: <transcript_output_dir>/<video_basename>.json
+  Video path: <video_path>
+```
+
+**Do NOT update library.yaml** — the parent handles all yaml I/O to avoid race conditions in parallel runs.