buttercut 0.5.0 → 0.7.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: buttercut
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Andrew Ford
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-25 00:00:00.000000000 Z
+date: 2026-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -24,20 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.13'
-- !ruby/object:Gem::Dependency
-  name: rubyzip
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -62,25 +48,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".claude/commands/worktree.md"
-- ".claude/scripts/script_extractor.rb"
 - ".claude/settings.json"
 - ".claude/settings.local.json"
-- ".claude/skills/analyze-video/SKILL.md"
-- ".claude/skills/analyze-video/prepare_visual_script.rb"
-- ".claude/skills/backup-library/SKILL.md"
-- ".claude/skills/backup-library/backup_libraries.rb"
-- ".claude/skills/release/SKILL.md"
-- ".claude/skills/roughcut/SKILL.md"
-- ".claude/skills/roughcut/agent_instructions.md"
-- ".claude/skills/roughcut/export_to_fcpxml.rb"
-- ".claude/skills/setup/SKILL.md"
-- ".claude/skills/setup/advanced-setup.md"
-- ".claude/skills/setup/simple-setup.md"
-- ".claude/skills/setup/verify_install.rb"
-- ".claude/skills/transcribe-audio/SKILL.md"
-- ".claude/skills/transcribe-audio/prepare_audio_script.rb"
-- ".claude/skills/transcribe-audio/refine_instructions.md"
-- ".claude/skills/update-buttercut/SKILL.md"
+- ".claude/skills"
 - CLAUDE.md
 - LICENSE
 - README.md
@@ -91,11 +61,12 @@ files:
 - lib/buttercut/fcpx.rb
 - lib/buttercut/version.rb
 - templates/library_template.yaml
+- templates/plan_template.md
 - templates/roughcut_template.yaml
 - templates/settings_template.yaml
 homepage: https://github.com/andrewford/buttercut
 licenses:
-- MIT
+- Nonstandard
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -112,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Video Editor XML generator with Agent skills for analyzing video, creating

data/.claude/scripts/script_extractor.rb

@@ -1,66 +0,0 @@
-#!/usr/bin/env ruby
-# Extract the plain-text script from a WhisperX-style transcript JSON.
-#
-# Usage:
-#   ruby .claude/scripts/script_extractor.rb <transcript.json> <output.txt>
-#
-# Output is one segment per paragraph (blank line between), trimmed, suitable
-# for proofreading by a human or a sub-agent without the overhead of the full
-# transcript JSON (word-level timing, scores, etc.).
-
-require 'json'
-
-class ScriptExtractor
-  def self.extract(transcript_path, output_path)
-    new(transcript_path, output_path).extract
-  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 extract
-    write_output(format_script)
-    report
-  end
-
-  private
-
-  attr_reader :transcript_path, :output_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 format_script
-    paragraphs = segments.map { |s| s["text"].to_s.strip }.reject(&:empty?)
-    paragraphs.join("\n\n") + "\n"
-  end
-
-  def write_output(text)
-    File.write(output_path, text)
-  end
-
-  def report
-    in_kb = (File.size(transcript_path) / 1024.0).round(1)
-    out_kb = (File.size(output_path) / 1024.0).round(1)
-    puts "Extracted script: #{output_path} (#{out_kb} KB from #{in_kb} KB source, #{segments.size} segments)"
-  end
-end
-
-if __FILE__ == $PROGRAM_NAME
-  transcript_path, output_path = ARGV
-  abort("usage: script_extractor.rb <transcript.json> <output.txt>") unless transcript_path && output_path
-  abort("file not found: #{transcript_path}") unless File.file?(transcript_path)
-  if File.expand_path(output_path) == File.expand_path(transcript_path)
-    abort("output path must differ from transcript path: #{transcript_path}")
-  end
-  ScriptExtractor.extract(transcript_path, output_path)
-end

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

@@ -1,97 +0,0 @@
----
-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. Inputs from the parent
-
-This skill runs as a sub-agent. Do NOT read `library.yaml` or `settings.yaml` — the parent has that context and passes everything inline in your prompt. Expect these inputs:
-
-- `video_path` — absolute path to the video file
-- `audio_transcript_path` — absolute path to the prepared audio transcript JSON
-- `visual_transcript_path` — absolute path to write the visual transcript JSON
-
-### 2. 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 <audio_transcript_path> <visual_transcript_path>
-ruby .claude/skills/analyze-video/prepare_visual_script.rb <visual_transcript_path>
-```
-
-### 3. 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
-
-### 4. 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** the file at `<visual_transcript_path>`:
-
-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.
-
-### 5. Cleanup & Return
-
-```bash
-rm -rf tmp/frames/[video_name]
-```
-
-Return structured response:
-```
-✓ [video_filename.mov] analyzed successfully
-  Visual transcript: <visual_transcript_path>
-  Video path: <video_path>
-```
-
-**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

@@ -1,25 +0,0 @@
-#!/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

@@ -1,26 +0,0 @@
----
-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

@@ -1,46 +0,0 @@
-#!/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, create: true) 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

@@ -1,214 +0,0 @@
----
-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. Update Gemfile.lock
-
-Run `bundle install` so `Gemfile.lock` reflects the new version:
-
-```bash
-bundle install
-```
-
-Verify the version updated in `Gemfile.lock` before proceeding.
-
-### 6. Gather Changelog Notes
-
-Ask user for release notes. Prompt with:
-- What changed in this release?
-- Any new features?
-- Any bug fixes?
-- Any breaking changes?
-
-### 7. 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
-```
-
-### 8. Commit Version Bump
-
-```bash
-git add lib/buttercut/version.rb Gemfile.lock CHANGELOG.md
-git commit -m "Bump version to 0.2.0"
-```
-
-### 9. Create and Push Git Tag
-
-```bash
-git tag v0.2.0
-git push origin main
-git push origin v0.2.0
-```
-
-### 10. Build Gem
-
-```bash
-gem build buttercut.gemspec
-```
-
-This creates `buttercut-0.2.0.gem` file.
-
-### 11. 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.
-
-### 12. 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.
-
-### 13. Cleanup
-
-```bash
-# Remove local gem file (it's on RubyGems and GitHub now)
-rm buttercut-0.2.0.gem
-```
-
-### 14. 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`
-
-### 15. 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

@@ -1,71 +0,0 @@
----
-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