buttercut 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4de766d8aca2ec00b99b20abd177310ade3b5145424677bf6b3e515487960b2
+  data.tar.gz: 97429c1df91a51ef44a921a0d2f3e8140adfa2c6c0943abf643d0967cea2e4bc
+SHA512:
+  metadata.gz: a6c30d9d4038725ef7b63cc15d5de34a8fc85e775bb3907896dae7d1bbde9f87abe7da263dec07ce0a27c7ec6b6d5940db00dc1bf40b24763a49c5381a9961b4
+  data.tar.gz: '029612e07d6fb9e806aecd10f5d89a95557d23e151a4fe53cb3ab393cd05b45ad89908881c982f6b7922e6227399306cbc51a4ef257404637b84f51a52c5e757'

data/.claude/commands/worktree.md

@@ -0,0 +1,24 @@
+# Create Worktree with Library
+
+Create a new git worktree with all libraries and media from main.
+
+## Arguments
+
+`<branch-name>` - The name for the new branch and worktree
+
+Example: `/worktree feature-test`
+
+User provided: $ARGUMENTS
+
+## Instructions
+
+1. Parse the branch name from arguments
+2. Always use the main branch worktree at `/Users/andrew/code/buttercut` as the source
+3. Create a new git worktree at `../<branch-name>` with a new branch of the same name
+4. Copy the entire `libraries/` directory from main: `/Users/andrew/code/buttercut/libraries/`
+5. Copy the `media/` directory from main (if it exists): `/Users/andrew/code/buttercut/media/`
+6. Run `mise trust` in the new worktree to trust the mise config
+7. Run `bundle install` in the new worktree to install Ruby dependencies
+8. Confirm success with the paths created
+
+If the branch name is missing, ask the user to provide it: `/worktree <branch-name>`

data/.claude/settings.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Skill(backup-library)",
+      "Skill(release)",
+      "Skill(update-buttercut)",
+      "Skill(setup)",
+      "Skill(transcribe-audio)",
+      "Skill(roughcut)",
+      "Skill(analyze-video)",
+      "Read(libraries/**)",
+      "Edit(libraries/**)",
+      "Write(libraries/**)",
+      "Read(templates/**)",
+      "Read(.claude/**)",
+      "Bash(ffprobe:*)",
+      "Bash(ffmpeg:*)",
+      "Bash(whisperx:*)",
+      "Bash(ruby:.claude/**)",
+      "Bash(mkdir:libraries/**)",
+      "Bash(mkdir:tmp/**)",
+      "Bash(rm:tmp/**)",
+      "Bash(ls:*)",
+      "Bash(zip:*)",
+      "Bash(cp:libraries/**)",
+      "Bash(unzip:backups/**)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

data/.claude/settings.local.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(./.claude/skills/roughcut/combine_visual_transcripts.rb:*)",
+      "Bash(./.claude/skills/roughcut/export_to_fcpxml.rb:*)",
+      "Skill(backup-library)",
+      "Skill(release)",
+      "Skill(update-buttercut)",
+      "Skill(setup)",
+      "Skill(transcribe-audio)",
+      "Skill(roughcut)",
+      "Skill(analyze-video)",
+      "Bash(ruby:*)",
+      "Bash(/Users/andrew/code/buttercut/.claude/skills/roughcut/combine_visual_transcripts.rb programmer-story-vlog ai_jobs_responses_c)",
+      "Bash(/Users/andrew/code/buttercut/.claude/skills/roughcut/combine_visual_transcripts.rb programmer-story-vlog ai_jobs_responses_a)",
+      "Bash(/Users/andrew/code/buttercut/.claude/skills/roughcut/combine_visual_transcripts.rb:*)",
+      "Bash(awk:*)",
+      "Read(libraries/**)",
+      "Edit(libraries/**)",
+      "Write(libraries/**)",
+      "Bash(whisperx:*)",
+      "Bash(git worktree add:*)",
+      "Bash(cat:*)",
+      "Bash(python3:*)",
+      "Bash(gh api:*)"
+    ],
+    "deny": [],
+    "ask": []
+  },
+  "outputStyle": "default"
+}

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

@@ -0,0 +1,89 @@
+---
+name: analyze-video
+description: Adds visual descriptions to transcripts by extracting and analyzing video frames with ffmpeg. Creates visual transcript with periodic visual descriptions of the video clip. Use when all files have audio transcripts present (transcript) but don't yet have visual transcripts created (visual_transcript).
+---
+
+# Skill: Analyze Video
+
+Add visual descriptions to audio transcripts by extracting JPG frames with ffmpeg and analyzing them. **Never read video files directly** - extract frames first.
+
+## Prerequisites
+
+Videos must have audio transcripts. Run **transcribe-audio** skill first if needed.
+
+## Workflow
+
+### 1. Copy & Clean Audio Transcript
+
+Don't read the audio transcript, just copy it and then prepare it by using the prepare_visual_script.rb file. This removes word-level timing data and prettifies the JSON for easier editing:
+
+```bash
+cp libraries/[library]/transcripts/video.json libraries/[library]/transcripts/visual_video.json
+ruby .claude/skills/analyze-video/prepare_visual_script.rb libraries/[library]/transcripts/visual_video.json
+```
+
+### 2. Extract Frames (Binary Search)
+
+Create frame directory: `mkdir -p tmp/frames/[video_name]`
+
+**Videos ≤30s:** Extract one frame at 2s
+**Videos >30s:** Extract start (2s), middle (duration/2), end (duration-2s)
+
+```bash
+ffmpeg -ss 00:00:02 -i video.mov -vframes 1 -vf "scale=1280:-1" tmp/frames/[video_name]/start.jpg
+```
+
+**Subdivide when:** Footage start, middle and end have different subjects, setting or angle changes
+**Stop when:** The footage no longer seems to be changing or only has minor changes
+**Never sample** more frequently than once per 30 seconds
+
+### 3. Add Visual Descriptions
+
+Read the visual video json file that you created earlier.
+
+**Read the JPG frames** from `tmp/frames/[video_name]/` using Read tool, then **Edit** `visual_video.json`:
+
+Do these incrementally. You don't need to create a program or script to do this, just incrementally edit the json whenever you read new frames.
+
+**Dialogue segments - add `visual` field:**
+```json
+{
+  "start": 2.917,
+  "end": 7.586,
+  "text": "Hey, good afternoon everybody.",
+  "visual": "Man in red shirt speaking to camera in medium shot. Home office with bookshelf. Natural lighting.",
+  "words": [...]
+}
+```
+
+**B-roll segments - insert new entries:**
+```json
+{
+  "start": 35.474,
+  "end": 56.162,
+  "text": "",
+  "visual": "Green bicycle parked in front of building. Urban street with trees.",
+  "b_roll": true,
+  "words": []
+}
+```
+
+**Guidelines:**
+- Descriptions should be 3 sentences max.
+- First segment: detailed (subject, setting, shot type, lighting, camera style)
+- Continuing shots: brief if similar, otherwise can be up to 3 sentences if drastically different.
+
+### 4. Cleanup & Return
+
+```bash
+rm -rf tmp/frames/[video_name]
+```
+
+Return structured response:
+```
+✓ [video_filename.mov] analyzed successfully
+  Visual transcript: libraries/[library]/transcripts/visual_video.json
+  Video path: /full/path/to/video_filename.mov
+```
+
+**DO NOT update library.yaml** - parent agent handles this to avoid race conditions in parallel execution.

data/.claude/skills/analyze-video/prepare_visual_script.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+require 'json'
+
+abort "Usage: ruby prepare_visual_script.rb <json_file>" if ARGV.empty?
+abort "Error: File not found: #{ARGV[0]}" unless File.exist?(ARGV[0])
+
+begin
+  data = JSON.parse(File.read(ARGV[0]))
+
+  data['segments']&.each { |s| s.delete('words') }
+  data.delete('word_segments')
+
+  # Reorder keys: language and video_path first, then segments, then everything else
+  reordered = {}
+  reordered['language'] = data['language'] if data['language']
+  reordered['video_path'] = data['video_path'] if data['video_path']
+  reordered['segments'] = data['segments'] if data['segments']
+  # Add any other keys that might exist
+  data.each { |k, v| reordered[k] = v unless reordered.key?(k) }
+
+  File.write(ARGV[0], JSON.pretty_generate(reordered))
+  puts "Prettified: #{ARGV[0]} (word-level timing removed)"
+rescue JSON::ParserError => e
+  abort "Error: Invalid JSON - #{e.message}"
+end

data/.claude/skills/backup-library/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: backup-library
+description: Creates compressed ZIP backups of libraries directory. Backs up library.yaml, transcripts, and roughcuts (not video files). This skill can also be useful when you need to restore a library.
+---
+
+# Skill: Backup Library
+
+Verify libraries directory exists:
+```bash
+ls -la libraries/
+```
+
+Run backup:
+```bash
+ruby .claude/skills/backup-library/backup_libraries.rb
+```
+
+Creates `backups/libraries_YYYYMMDD_HHMMSS.zip` containing the entire libraries directory.
+
+## Restore Library
+
+To restore from a backup, extract the ZIP file to the project root.
+```bash
+unzip backups/libraries_timestamp.zip -d .
+```
+This restores all libraries to their original locations.

data/.claude/skills/backup-library/backup_libraries.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Library Backup Utility
+# Creates compressed ZIP backups of the entire libraries directory
+
+require 'fileutils'
+require 'time'
+require 'zip'
+
+class LibraryBackup
+  def initialize(project_root = Dir.pwd)
+    @libraries_dir = File.join(project_root, 'libraries')
+    @backups_dir = File.join(project_root, 'backups')
+  end
+
+  def backup
+    unless Dir.exist?(@libraries_dir)
+      puts "❌ No libraries directory found"
+      return nil
+    end
+
+    FileUtils.mkdir_p(@backups_dir)
+
+    timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+    backup_path = File.join(@backups_dir, "libraries_#{timestamp}.zip")
+
+    puts "📦 Creating backup: #{backup_path}"
+
+    files = Dir.glob(File.join(@libraries_dir, '**', '*')).select { |f| File.file?(f) }
+
+    Zip::File.open(backup_path, Zip::File::CREATE) do |zipfile|
+      files.each do |file|
+        zipfile.add(file.sub("#{File.dirname(@libraries_dir)}/", ''), file)
+      end
+    end
+
+    puts "✅ Backed up #{files.size} files"
+    backup_path
+  end
+end
+
+# CLI
+if __FILE__ == $PROGRAM_NAME
+  LibraryBackup.new.backup
+end

data/.claude/skills/release/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: release
+description: Creates a new ButterCut release with version bump, changelog, git tag, gem build, and GitHub release. Use when publishing a new version.
+---
+
+# Skill: Release ButterCut
+
+Guides through the complete release process: version bump, changelog, git operations, gem publishing, and GitHub release creation.
+
+## When to Use
+
+- Publishing a new version of ButterCut
+- After merging features or fixes that should be released
+- Creating the first v0.1.0 release
+
+## Workflow
+
+### 1. Run Tests First
+
+**CRITICAL: Always run tests before releasing. Never release if tests fail.**
+
+```bash
+bundle exec rspec
+```
+
+If any tests fail, STOP immediately and ask user to fix before proceeding with release.
+
+### 2. Check Current State
+
+```bash
+# Read current version
+cat lib/buttercut/version.rb
+
+# Check git status (must be clean)
+git status
+
+# Check existing tags
+git tag -l
+```
+
+If git status is not clean, stop and ask user to commit or stash changes before proceeding.
+
+### 3. Determine New Version
+
+Ask user what type of release following [Semantic Versioning](https://semver.org/):
+- **MAJOR** (1.0.0): Breaking changes
+- **MINOR** (0.2.0): New features, backward compatible
+- **PATCH** (0.1.1): Bug fixes, backward compatible
+
+Calculate new version number based on current version and release type.
+
+### 4. Update Version File
+
+Edit `lib/buttercut/version.rb` with the new version:
+
+```ruby
+class ButterCut
+  VERSION = "0.2.0"  # Update this
+end
+```
+
+### 5. Gather Changelog Notes
+
+Ask user for release notes. Prompt with:
+- What changed in this release?
+- Any new features?
+- Any bug fixes?
+- Any breaking changes?
+
+### 6. Update or Create CHANGELOG.md
+
+If `CHANGELOG.md` exists, prepend new entry. Otherwise create it:
+
+```markdown
+# Changelog
+
+All notable changes to ButterCut will be documented in this file.
+
+## [0.2.0] - 2025-01-21
+
+### Added
+- Feature X
+- Support for Y
+
+### Fixed
+- Bug in Z
+
+### Changed
+- Improved W
+```
+
+### 7. Commit Version Bump
+
+```bash
+git add lib/buttercut/version.rb CHANGELOG.md
+git commit -m "Bump version to 0.2.0"
+```
+
+### 8. Create and Push Git Tag
+
+```bash
+git tag v0.2.0
+git push origin main
+git push origin v0.2.0
+```
+
+### 9. Build Gem
+
+```bash
+gem build buttercut.gemspec
+```
+
+This creates `buttercut-0.2.0.gem` file.
+
+### 10. Publish to RubyGems
+
+**First time setup check:**
+
+If this is the first release, verify RubyGems authentication:
+```bash
+gem signin
+```
+
+If not authenticated, provide instructions:
+1. Sign up at https://rubygems.org
+2. Run `gem signin` and follow prompts
+3. Store credentials for future releases
+
+**Publish the gem:**
+```bash
+gem push buttercut-0.2.0.gem
+```
+
+This makes the gem available for `gem install buttercut` worldwide.
+
+### 11. Create GitHub Release
+
+**Using GitHub CLI:**
+```bash
+gh release create v0.2.0 \
+  --title "v0.2.0" \
+  --notes "[Release notes from changelog]" \
+  buttercut-0.2.0.gem
+```
+
+**If `gh` CLI not available:**
+
+Guide user through manual release creation:
+1. Go to https://github.com/andrewford/buttercut/releases/new
+2. Choose tag: v0.2.0
+3. Set title: v0.2.0
+4. Paste changelog notes in description
+5. Attach buttercut-0.2.0.gem file
+6. Click "Publish release"
+
+Then wait for user confirmation that release is created before proceeding to cleanup.
+
+### 12. Cleanup
+
+```bash
+# Remove local gem file (it's on RubyGems and GitHub now)
+rm buttercut-0.2.0.gem
+```
+
+### 13. Verify Release
+
+Check that everything worked:
+- RubyGems page: https://rubygems.org/gems/buttercut
+- GitHub releases: https://github.com/andrewford/buttercut/releases
+- Git tags: `git tag -l`
+
+### 14. Return Success Response
+
+Provide summary:
+```
+✓ ButterCut 0.2.0 released successfully
+
+  Version: 0.2.0
+  Git tag: v0.2.0
+  RubyGems: Published at https://rubygems.org/gems/buttercut
+  GitHub Release: https://github.com/andrewford/buttercut/releases/tag/v0.2.0
+
+Installation:
+  gem install buttercut
+
+Upgrade:
+  gem update buttercut
+```
+
+## Critical Principles
+
+**Always run tests first** - Never release if tests fail
+**Git must be clean** - No uncommitted changes before release
+**Push before publish** - Tags must be pushed before creating GitHub release
+**Semantic versioning** - Follow semver strictly for version numbers
+**Changelog required** - Every release needs documented changes
+
+## Common Issues
+
+**Tests failing:** Ask user to fix tests before proceeding
+**Git not clean:** Ask user to commit or stash changes first
+**Tag already exists:** Verify this isn't a duplicate release
+**RubyGems authentication:** Guide through `gem signin` process
+**GitHub CLI not installed:** Provide manual release instructions

data/.claude/skills/roughcut/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: roughcut
+description: Creates video rough cut yaml file for use with Buttercut gem. Concatenates visual transcripts with file markers, creates a roughcut yaml with clip selections, then exports to XML format. Use this skill when users want a "roughcut", "sequence" or "scene" generated. These are all the same thing, just with different lengths.
+---
+
+# Skill: Create Rough Cut
+
+This skill handles the editorial process of creating rough cut timeline scripts from transcribed video footage. It launches a specialized agent that analyzes transcripts, makes editorial decisions, outputs a structured YAML rough cut, and exports it to Final Cut Pro XML format.
+
+**Note:** This skill is used for both full-length rough cuts (multiple minutes) and short sequences (30-60 seconds).
+
+## Prerequisites Check
+
+Before launching the roughcut agent, verify all transcripts are complete:
+
+1. **Check library exists:**
+   ```bash
+   ls libraries/[library-name]/library.yaml
+   ```
+
+2. **Verify visual transcripts:**
+   Read `libraries/[library-name]/library.yaml` and check that every video entry has both:
+   - `transcript` populated (audio transcript filename)
+   - `visual_transcript` populated (visual descriptions filename)
+
+   If any visual transcripts are missing:
+   - Inform user that transcript processing must be completed first
+   - Ask if they want Claude to finish transcript processing using the `transcribe-audio` and `analyze-video` skills
+   - Do not proceed with roughcut creation until all transcripts are complete
+
+## Launch Roughcut Agent
+
+Once prerequisites are verified, launch the roughcut creation agent using the Task tool:
+
+```
+Task tool with:
+- subagent_type: "general-purpose"
+- description: "Create rough cut from visual transcripts"
+- prompt: [See agent prompt template below]
+```
+
+### Agent Prompt Template
+
+When launching the agent, provide a detailed prompt with all necessary context:
+
+```
+You are a video editor AI agent creating a rough cut or sequence for the "{library_name}" library.
+
+USER REQUEST: {what_user_asked_for}
+
+LIBRARY CONTEXT:
+{paste relevant content from library.yaml - footage_summary, user_context, etc.}
+
+YOUR TASK:
+1. Read the roughcut creation instructions from .claude/skills/roughcut/agent_instructions.md
+2. Follow those instructions to create the rough cut
+3. Return the paths to the created YAML and XML files when complete
+
+DELIVERABLES:
+- Rough cut YAML file at: libraries/{library_name}/roughcuts/{roughcut_name}_{datetime}.yaml
+- Exported XML file for user's chosen video editor
+- Backup created via backup-library skill
+
+Begin by reading the agent instructions file.
+```
+
+## After Agent Completes
+
+When the agent returns:
+1. Inform the user of the created roughcut file (the xml file, not the yaml file) and its location
+2. Confirm the rough cut is ready to import into their video editor

data/.claude/skills/roughcut/agent_instructions.md

@@ -0,0 +1,109 @@
+# Roughcut Agent Instructions
+
+You are a video editor AI agent. Analyze footage, make editorial decisions based on user requests, and produce a YAML timing based rough cut.
+
+## Workflow
+
+### 1. Gather Preferences (if needed)
+
+- **Only ask questions if the user's initial request is vague or lacks critical details**
+- If the user has already provided clear instructions about structure, duration and pacing, skip questions and proceed directly to step 2
+- If clarification is needed, use AskUserQuestion tool to ask about whatever is missing, ie:
+  - Narrative structure preference
+  - Target duration
+  - Pacing preference
+
+### 2. Create Combined Visual Transcript
+
+Combine all visual transcripts into a single file:
+
+```bash
+mkdir -p tmp/[library-name] && cat libraries/[library-name]/transcripts/visual_*.json > tmp/[library-name]/[roughcut_name]_combined_visual_transcript.json
+```
+
+This outputs to `tmp/[library-name]/[roughcut_name]_combined_visual_transcript.json` in NDJSON format (one JSON object per line per video):
+```json
+{
+  "language": "en",
+  "video_path": "/full/path/to/video.mov",
+  "segments": [
+    {"start": 2.917, "end": 7.586, "text": "Hey, good afternoon.", "visual": "Man speaking to camera outdoors."},
+    {"start": 8.307, "end": 10.551, "text": "Today is going to be different."},
+    {"start": 10.551, "end": 15.0, "text": "", "visual": "Walking shot, buildings in background.", "b_roll": true}
+  ]
+}
+```
+
+**Segment fields:**
+- `start`, `end`: Timestamps in seconds
+- `text`: Dialogue (empty string `""` for silent segments)
+- `visual`: Shot description (only present when visual changes)
+- `b_roll`: `true` when segment is silent B-roll (only present when true)
+
+### 3. Read and Analyze Combined Transcript
+
+**Count lines and plan reading:**
+```bash
+wc -l tmp/[library-name]/[roughcut_name]_combined_visual_transcript.json
+```
+
+**Read the combined transcript in 5000-line chunks** using the Read tool with offset and limit parameters.
+
+After reading through footage sequentially, you can spend a little time thinking, and then create the roughcut yaml file.
+
+### 4. Create Rough Cut YAML
+
+**Generate a timestamp** using `date +%Y%m%d_%H%M%S` and use the resulting value as a literal string in all filenames for this roughcut session (YAML and XML).
+
+**Setup:**
+```bash
+cp templates/roughcut_template.yaml "libraries/[library-name]/roughcuts/[roughcut_name]_[timestamp].yaml"
+```
+
+**Build clips based on user's request:**
+- Use the user's stated goals to guide editorial decisions
+- Convert timestamps from seconds to `HH:MM:SS.ss` format (hundredths of second precision)
+- Reference video files using `source_file` from the combined JSON
+
+**CRITICAL - Timecode Logic:**
+- `in_point`: Start time of FIRST segment you want
+- `out_point`: End time of LAST segment you want
+- Use `start` and `end` from segments directly (preserve sub-second precision)
+- Example: segment at 2.849s-29.63s → in_point: `00:00:02.85`, out_point: `00:00:29.63`
+
+**CRITICAL - Required Fields:**
+Each clip needs:
+- `dialogue`: Spoken words from transcript (or `""` if silent B-roll)
+- `visual_description`: Shot description from visual transcript
+
+**Metadata:**
+- `created_date`: `YYYY-MM-DD HH:MM:SS`
+- `total_duration`: Sum of all clips in `HH:MM:SS.ss` format
+
+### 5. Export to Video Editor
+
+Check `library.yaml` for the `editor` field. If it's set, use that value. If it's not set or empty, ask the user for their editor choice (Final Cut Pro X, Adobe Premiere Pro, or DaVinci Resolve), then save their choice back to `library.yaml` (`fcpx`, `premiere`, or `resolve`).
+
+Export based on choice:
+```bash
+# Final Cut Pro X:
+bundle exec ./.claude/skills/roughcut/export_to_fcpxml.rb libraries/[library-name]/roughcuts/[roughcut_name]_[datetime].yaml libraries/[library-name]/roughcuts/[roughcut_name]_[datetime].fcpxml fcpx
+
+# Premiere Pro:
+bundle exec ./.claude/skills/roughcut/export_to_fcpxml.rb libraries/[library-name]/roughcuts/[roughcut_name]_[datetime].yaml libraries/[library-name]/roughcuts/[roughcut_name]_[datetime].xml premiere
+
+# DaVinci Resolve:
+bundle exec ./.claude/skills/roughcut/export_to_fcpxml.rb libraries/[library-name]/roughcuts/[roughcut_name]_[datetime].yaml libraries/[library-name]/roughcuts/[roughcut_name]_[datetime].xml resolve
+```
+
+### 6. Create Backup
+
+Run the `backup-library` skill to preserve the completed work.
+
+### 7. Report Results
+
+Provide summary with:
+- Rough cut name and duration
+- Number of clips included
+- File path for XML
+- Backup confirmation