buttercut 0.4.0

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+# Export rough cut YAML to Final Cut Pro XML using ButterCut
+
+require 'date'
+require 'yaml'
+require 'buttercut'
+
+def timecode_to_seconds(timecode)
+  # Convert HH:MM:SS or HH:MM:SS.s to seconds (supports decimal seconds)
+  parts = timecode.split(':')
+  hours = parts[0].to_i
+  minutes = parts[1].to_i
+  seconds = parts[2].to_f  # to_f handles both "03" and "03.5"
+  hours * 3600 + minutes * 60 + seconds
+end
+
+def main
+  if ARGV.length < 2 || ARGV.length > 3
+    puts "Usage: #{$0} <roughcut.yaml> <output.xml> [editor]"
+    puts "  editor: fcpx (default), premiere, or resolve"
+    exit 1
+  end
+
+  roughcut_path = ARGV[0]
+  output_path = ARGV[1]
+  editor_choice = ARGV[2] || 'fcpx'
+
+  unless File.exist?(roughcut_path)
+    puts "Error: Rough cut file not found: #{roughcut_path}"
+    exit 1
+  end
+
+  # Load rough cut YAML
+  roughcut = YAML.load_file(roughcut_path, permitted_classes: [Date, Time, Symbol])
+
+  # Find library name from path
+  # Path pattern: libraries/[library-name]/roughcuts/[roughcut-name].yaml
+  library_match = roughcut_path.match(%r{libraries/([^/]+)/roughcuts})
+  unless library_match
+    puts "Error: Could not extract library name from path: #{roughcut_path}"
+    exit 1
+  end
+  library_name = library_match[1]
+
+  # Load library file to get full video paths
+  library_yaml = "libraries/#{library_name}/library.yaml"
+  unless File.exist?(library_yaml)
+    puts "Error: Library file not found: #{library_yaml}"
+    exit 1
+  end
+
+  library_data = YAML.load_file(library_yaml, permitted_classes: [Date, Time, Symbol])
+
+  # Build lookup map: filename -> full path
+  video_paths = {}
+  library_data['videos'].each do |video|
+    filename = File.basename(video['path'])
+    video_paths[filename] = video['path']
+  end
+
+  # Convert rough cut clips to ButterCut format
+  buttercut_clips = []
+
+  roughcut['clips'].each do |clip|
+    source_file = clip['source_file']
+
+    unless video_paths[source_file]
+      puts "Warning: Source file not found in library data: #{source_file}"
+      next
+    end
+
+    full_path = video_paths[source_file]
+    start_at = timecode_to_seconds(clip['in_point'])
+    out_point = timecode_to_seconds(clip['out_point'])
+    duration = out_point - start_at
+
+    buttercut_clips << {
+      path: full_path,
+      start_at: start_at.to_f,
+      duration: duration.to_f
+    }
+  end
+
+  # Validate and normalize editor choice
+  editor_symbol = case editor_choice.downcase
+  when 'fcpx', 'finalcutpro', 'finalcut', 'fcp'
+    :fcpx
+  when 'premiere', 'premierepro', 'adobepremiere'
+    :fcp7
+  when 'resolve', 'davinci', 'davinciresolve'
+    :fcp7
+  else
+    puts "Error: Unknown editor '#{editor_choice}'. Use 'fcpx', 'premiere', or 'resolve'"
+    exit 1
+  end
+
+  editor_name = editor_symbol == :fcpx ? "Final Cut Pro X" : "#{editor_choice.capitalize}"
+
+  puts "Converting #{buttercut_clips.length} clips to #{editor_name} XML..."
+
+  generator = ButterCut.new(buttercut_clips, editor: editor_symbol)
+  generator.save(output_path)
+
+  puts "\n✓ Rough cut exported to: #{output_path}"
+end
+
+main

data/.claude/skills/setup/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: setup
+description: Sets up a Mac for ButterCut. Installs all required dependencies (Homebrew, Ruby, Python, FFmpeg, WhisperX). Use when user says "install buttercut", "set up my mac", "get started", "first time setup", "install dependencies" or "check my installation".
+---
+
+# Skill: Mac Setup
+
+Sets up a Mac for ButterCut. Two installation paths available based on user preference.
+
+## Step 1: Check Current State
+
+First, run the verification script to see what's already installed:
+
+```bash
+ruby .claude/skills/setup/verify_install.rb
+```
+
+If all dependencies pass, inform the user they're ready to go.
+
+## Step 2: Ask User Preference
+
+If dependencies are missing, use AskUserQuestion:
+
+```
+Question: "How would you like to install ButterCut?"
+Header: "Install type"
+Options:
+  1. "Simple (recommended)" - "Fully automatic setup. We'll install everything for you using sensible defaults."
+  2. "Advanced" - "For developers who want control. You manage Ruby/Python versions with your preferred tools."
+```
+
+## Step 3: Run Appropriate Setup
+
+Based on user choice:
+
+- **Simple**: Read and follow `.claude/skills/setup/simple-setup.md`
+- **Advanced**: Read and follow `.claude/skills/setup/advanced-setup.md`
+
+## Step 4: Verify Installation
+
+After setup completes, run verification again:
+
+```bash
+ruby .claude/skills/setup/verify_install.rb
+```
+
+Report results to user.

data/.claude/skills/setup/advanced-setup.md

@@ -0,0 +1,141 @@
+# Advanced Setup (Developers)
+
+For developers who manage their own Ruby/Python environments. This guide tells you what's needed; you decide how to install it.
+
+## Required Versions
+
+Check `.ruby-version` and `.python-version` in the project root:
+
+- **Ruby**: 3.3.6
+- **Python**: 3.12.8
+
+These files are compatible with rbenv, pyenv, asdf, mise, and most version managers.
+
+## Checklist
+
+Work through each item. Skip any you already have.
+
+### 1. Xcode Command Line Tools
+
+```bash
+xcode-select -p 2>/dev/null || xcode-select --install
+```
+
+### 2. Homebrew
+
+Required for FFmpeg and libyaml. If you prefer another package manager, adapt accordingly.
+
+**Note:** Homebrew installation requires interactive terminal access (password prompts, confirmations). If running via an agent, the user must run the install command manually.
+
+```bash
+which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+### 3. Libyaml (Ruby Dependency)
+
+Required for Ruby's psych extension. Install before compiling Ruby:
+
+```bash
+brew install libyaml
+```
+
+### 4. Ruby 3.3.6
+
+Install using your preferred version manager (rbenv, asdf, mise, rvm, etc.).
+
+The project includes `.ruby-version` which most managers auto-detect.
+
+Verify:
+
+```bash
+ruby --version  # Should show 3.3.6
+```
+
+### 5. Bundler
+
+```bash
+gem install bundler
+```
+
+### 6. Python 3.12.8
+
+Install using your preferred version manager (pyenv, asdf, mise, etc.).
+
+The project includes `.python-version` which most managers auto-detect.
+
+Verify:
+
+```bash
+python3 --version  # Should show 3.12.8
+```
+
+### 7. FFmpeg
+
+```bash
+brew install ffmpeg
+```
+
+Or install via your preferred method.
+
+### 8. WhisperX
+
+Two options depending on how you manage Python:
+
+**Option A: Virtual Environment (Recommended)**
+
+Isolates WhisperX dependencies. Creates a wrapper script for easy access.
+
+```bash
+mkdir -p ~/.buttercut
+python3 -m venv ~/.buttercut/venv
+source ~/.buttercut/venv/bin/activate
+pip install --upgrade pip
+pip install whisperx
+deactivate
+
+# Create wrapper script
+cat > ~/.buttercut/whisperx << 'EOF'
+#!/bin/bash
+source ~/.buttercut/venv/bin/activate
+whisperx "$@"
+deactivate
+EOF
+chmod +x ~/.buttercut/whisperx
+
+# Add to PATH (adjust for your shell)
+echo 'export PATH="$HOME/.buttercut:$PATH"' >> ~/.zshrc
+```
+
+**Option B: Direct pip install**
+
+If you manage Python environments yourself and want whisperx globally available:
+
+```bash
+pip install whisperx
+```
+
+Ensure `whisperx` is in your PATH.
+
+### 9. ButterCut Ruby Dependencies
+
+From the buttercut directory:
+
+```bash
+bundle install
+```
+
+## Verification
+
+Run the verification script:
+
+```bash
+ruby .claude/skills/setup/verify_install.rb
+```
+
+All items should show OK.
+
+## Notes
+
+- The `.mise.toml` file is provided for mise users but is not required
+- WhisperX uses CPU-only mode for simplicity (no CUDA/GPU setup needed)
+- If you use pyenv-virtualenv or similar, you can install whisperx in a dedicated virtualenv instead of `~/.buttercut/venv`

data/.claude/skills/setup/simple-setup.md

@@ -0,0 +1,185 @@
+# Simple Setup (Non-Technical Users)
+
+Fully automatic installation. Run each step in order, waiting for each to complete. Don't move forward until each step is successful. This may be a non-technical user so adjust your explanations accordingly.
+
+**Note:** ButterCut encourages the use of the CPU version of WhisperX only. This simplifies installation and works reliably on all modern Macs with Apple Silicon.
+
+## Step 0: Check Install Location
+
+Check the current working directory. Warn if ButterCut is in a problematic location:
+
+**Problematic locations:**
+- `~/Desktop/` - Desktop gets cluttered, easy to accidentally delete
+- `~/Downloads/` - Often cleaned up automatically
+- `~/Library/Mobile Documents/` (iCloud) - Sync causes issues with git and large files
+- Any path containing spaces - Some CLI tools have issues
+
+**Recommended locations:**
+- `~/code/buttercut`
+- `~/projects/buttercut`
+
+If in a problematic location, ask if they'd like to move it. If yes:
+
+1. Run `mkdir -p ~/code` (or `~/projects` if that exists)
+2. Run `cp -R [current-path] ~/code/buttercut`
+3. Tell the user:
+   ```
+   I've copied ButterCut to ~/code/buttercut. To finish:
+   1. Delete [current-path] (drag to Trash)
+   2. Run this in Terminal: cd ~/code/buttercut && claude
+   ```
+
+If they prefer to stay in the current location, continue with setup.
+
+## Step 1: Xcode Command Line Tools
+
+```bash
+xcode-select -p 2>/dev/null || xcode-select --install
+```
+
+If `xcode-select --install` runs, a GUI dialog appears. **Tell user to click "Install" and wait** (5-10 minutes). Then verify:
+
+```bash
+xcode-select -p
+```
+
+Should return `/Library/Developer/CommandLineTools` or similar.
+
+## Step 2: Homebrew (Manual Installation Required)
+
+Check if Homebrew is installed:
+
+```bash
+which brew
+```
+
+If not installed, **tell the user to run the install command themselves**. Homebrew requires interactive terminal access (password prompts, confirmations) and cannot be installed by the agent directly.
+
+Tell the user to run:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Wait for the user to confirm installation is complete before continuing.
+
+After install, add to PATH (Apple Silicon):
+
+```bash
+eval "$(/opt/homebrew/bin/brew shellenv)"
+```
+
+Verify with `brew --version`. Don't proceed until brew works.
+
+Install libyaml (required for Ruby's psych extension):
+
+```bash
+brew install libyaml
+```
+
+## Step 3: Mise (Version Manager)
+
+```bash
+which mise || brew install mise
+```
+
+Activate mise in shell profile:
+
+```bash
+# Detect shell and add mise activation
+if [[ "$SHELL" == *"zsh"* ]]; then
+  grep -q 'mise activate' ~/.zshrc 2>/dev/null || echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
+  eval "$(mise activate zsh)"
+elif [[ "$SHELL" == *"bash"* ]]; then
+  grep -q 'mise activate' ~/.bash_profile 2>/dev/null || echo 'eval "$(mise activate bash)"' >> ~/.bash_profile
+  eval "$(mise activate bash)"
+fi
+```
+
+Verify: `mise --version`
+
+## Step 4: Ruby and Python via Mise
+
+From the buttercut directory:
+
+```bash
+mise trust
+mise install
+```
+
+**Note:** Ruby is compiled from source and can take 5-10 minutes. This is normal.
+
+Verify versions:
+
+```bash
+ruby --version    # Should show 3.3.6
+python3 --version # Should show 3.12.8
+```
+
+## Step 5: Bundler
+
+```bash
+which bundle || gem install bundler
+```
+
+## Step 6: FFmpeg
+
+```bash
+which ffmpeg || brew install ffmpeg
+```
+
+## Step 7: WhisperX Virtual Environment
+
+```bash
+mkdir -p ~/.buttercut
+
+if [ ! -d ~/.buttercut/venv ]; then
+  python3 -m venv ~/.buttercut/venv
+fi
+
+source ~/.buttercut/venv/bin/activate
+pip install --upgrade pip
+pip install whisperx
+deactivate
+```
+
+## Step 8: WhisperX Wrapper Script
+
+```bash
+cat > ~/.buttercut/whisperx << 'EOF'
+#!/bin/bash
+source ~/.buttercut/venv/bin/activate
+whisperx "$@"
+deactivate
+EOF
+chmod +x ~/.buttercut/whisperx
+```
+
+## Step 9: Add to PATH
+
+```bash
+if [[ "$SHELL" == *"zsh"* ]]; then
+  grep -q 'buttercut' ~/.zshrc 2>/dev/null || echo 'export PATH="$HOME/.buttercut:$PATH"' >> ~/.zshrc
+elif [[ "$SHELL" == *"bash"* ]]; then
+  grep -q 'buttercut' ~/.bash_profile 2>/dev/null || echo 'export PATH="$HOME/.buttercut:$PATH"' >> ~/.bash_profile
+fi
+```
+
+## Step 10: Install ButterCut Dependencies
+
+```bash
+bundle install
+```
+
+## Final Step
+
+Tell user to open a new terminal window for all changes to take effect.
+
+## Troubleshooting
+
+- **Xcode stuck**: `sudo rm -rf /Library/Developer/CommandLineTools` then retry
+- **Homebrew not in PATH**: Run `eval "$(/opt/homebrew/bin/brew shellenv)"`
+- **Mise not activating**: Open new terminal, run `mise doctor`
+- **Wrong Ruby/Python**: Run `mise trust && mise install` from buttercut directory
+- **WhisperX not found**: Ensure `~/.buttercut` is in PATH, open new terminal
+- **WhisperX import errors**: The wrapper script handles venv activation automatically; ensure you're using `~/.buttercut/whisperx` not calling whisperx directly

data/.claude/skills/setup/verify_install.rb

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+# Verifies all ButterCut dependencies are installed
+
+class DependencyChecker
+  def run
+    puts "ButterCut Dependency Check"
+    puts "=" * 40
+    puts
+
+    results = []
+
+    # Core dependencies (required)
+    results << check("Xcode CLI Tools", "xcode-select -p", "xcode-select --install")
+    results << check("Homebrew", "which brew", "See https://brew.sh")
+    results << check_ruby_version
+    results << check("Bundler", "which bundle", "gem install bundler")
+    results << check_python_version
+    results << check("FFmpeg", "which ffmpeg", "brew install ffmpeg")
+    results << check_whisperx
+    results << check_bundle_install
+
+    # Optional: show mise status if installed (not required)
+    check_mise_optional
+
+    puts
+    puts "=" * 40
+
+    passed = results.count { |r| r[:status] == :ok }
+    failed = results.select { |r| r[:status] == :missing }
+
+    if failed.empty?
+      puts "All #{passed} dependencies installed!"
+      puts "ButterCut is ready to use."
+      true
+    else
+      puts "#{passed}/#{results.size} dependencies installed"
+      puts
+      puts "Missing dependencies:"
+      failed.each do |r|
+        puts "  - #{r[:name]}: #{r[:install]}"
+      end
+      false
+    end
+  end
+
+  private
+
+  def check(name, cmd, install)
+    result = system("#{cmd} > /dev/null 2>&1")
+    status = result ? :ok : :missing
+    icon = result ? "OK" : "MISSING"
+    puts "#{icon.ljust(8)} #{name}"
+    { name: name, status: status, install: install }
+  end
+
+  def check_ruby_version
+    version_output = `ruby --version 2>/dev/null`.strip
+    if version_output.match?(/ruby 3\.3/)
+      puts "OK       Ruby (#{version_output.split[1]})"
+      { name: "Ruby 3.3.x", status: :ok }
+    elsif version_output.empty?
+      puts "MISSING  Ruby"
+      { name: "Ruby 3.3.x", status: :missing, install: "Install Ruby 3.3.6 (see .ruby-version)" }
+    else
+      puts "WRONG    Ruby (#{version_output.split[1]} - need 3.3.x)"
+      { name: "Ruby 3.3.x", status: :missing, install: "Install Ruby 3.3.6 (see .ruby-version)" }
+    end
+  end
+
+  def check_python_version
+    version_output = `python3 --version 2>/dev/null`.strip
+    if version_output.match?(/Python 3\.12/)
+      puts "OK       Python (#{version_output.split[1]})"
+      { name: "Python 3.12.x", status: :ok }
+    elsif version_output.empty?
+      puts "MISSING  Python"
+      { name: "Python 3.12.x", status: :missing, install: "Install Python 3.12.8 (see .python-version)" }
+    else
+      puts "WRONG    Python (#{version_output.split[1]} - need 3.12.x)"
+      { name: "Python 3.12.x", status: :missing, install: "Install Python 3.12.8 (see .python-version)" }
+    end
+  end
+
+  def check_whisperx
+    # Check various possible locations for whisperx
+    locations = [
+      "which whisperx",
+      "test -x ~/.buttercut/whisperx",
+      "test -x ~/.buttercut/venv/bin/whisperx"
+    ]
+
+    found = locations.any? { |cmd| system("#{cmd} > /dev/null 2>&1") }
+
+    if found
+      puts "OK       WhisperX"
+      { name: "WhisperX", status: :ok }
+    else
+      puts "MISSING  WhisperX"
+      { name: "WhisperX", status: :missing, install: "pip install whisperx (see setup instructions)" }
+    end
+  end
+
+  def check_bundle_install
+    gemfile_lock = File.join(Dir.pwd, "Gemfile.lock")
+
+    if File.exist?(gemfile_lock)
+      puts "OK       Bundle installed"
+      { name: "Bundle installed", status: :ok }
+    else
+      puts "MISSING  Bundle installed"
+      { name: "Bundle installed", status: :missing, install: "Run 'bundle install' in buttercut directory" }
+    end
+  end
+
+  def check_mise_optional
+    if system("which mise > /dev/null 2>&1")
+      puts
+      puts "(info)   Mise detected - using mise for version management"
+    end
+  end
+end
+
+success = DependencyChecker.new.run
+exit(success ? 0 : 1)

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

@@ -0,0 +1,83 @@
+---
+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
+
+Transcribes video audio using WhisperX and creates clean JSON transcripts with word-level timing data.
+
+## When to Use
+- Videos need audio transcripts before visual analysis
+
+## Critical Requirements
+
+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.
+
+## Workflow
+
+### 1. Read Language from Library File
+
+Read the library's `library.yaml` to get the language code:
+
+```yaml
+# Library metadata
+library_name: [library-name]
+language: en  # Language code stored here
+...
+```
+
+### 2. Run WhisperX
+
+```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
+```
+
+### 3. Prepare Audio Transcript
+
+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.