buttercut 0.6.0 → 0.7.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: buttercut
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Andrew Ford
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-04 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,32 +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/agent_prompt.md"
-- ".claude/skills/analyze-video/prepare_visual_script.rb"
-- ".claude/skills/backup-library/SKILL.md"
-- ".claude/skills/backup-library/backup_libraries.rb"
-- ".claude/skills/cut-planner/SKILL.md"
-- ".claude/skills/release/SKILL.md"
-- ".claude/skills/roughcut/SKILL.md"
-- ".claude/skills/roughcut/agent_prompt.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/summarize-video/SKILL.md"
-- ".claude/skills/summarize-video/agent_prompt.md"
-- ".claude/skills/summarize-video/summary_skeleton.rb"
-- ".claude/skills/summarize-video/visual_script_extractor.rb"
-- ".claude/skills/transcribe-audio/SKILL.md"
-- ".claude/skills/transcribe-audio/agent_prompt.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
@@ -103,7 +66,7 @@ files:
 - templates/settings_template.yaml
 homepage: https://github.com/andrewford/buttercut
 licenses:
-- MIT
+- Nonstandard
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -120,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,30 +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 (parent brief)
-
-Adds visual descriptions to a video's audio transcript by extracting JPG frames with ffmpeg and analyzing them.
-
-`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`.
-
-## Prerequisites
-
-Each video must already have an audio transcript. Run `transcribe-audio` first if any are missing.
-
-## Parallelism
-
-Launch at most **8 in parallel**. ffmpeg frame extraction is a brief CPU burst at the start; the rest of the runtime is LLM API calls. 8 is a comfortable middle ground that won't saturate older machines.
-
-## Inputs to gather and pass inline
-
-- `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
-
-After the agent returns, update `library.yaml` with `visual_transcript: <filename>.json`.
-
-## Next step
-
-Once all videos have visual transcripts, dispatch `summarize-video` (Haiku model) to produce summaries.

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

@@ -1,84 +0,0 @@
-# Analyze Video (sub-agent prompt)
-
-You are a sub-agent. Add visual descriptions to one video's audio transcript by extracting JPG frames with ffmpeg and analyzing them. **Never read the video file directly** — extract frames first.
-
-## Inputs (passed inline by the parent)
-
-- `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
-
-Do NOT read `library.yaml` or `settings.yaml`.
-
-## 1. Copy & clean audio transcript
-
-Don't read the audio transcript — just copy it, then prepare it via `prepare_visual_script.rb`. 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>
-```
-
-## 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:** start, middle, and end have different subjects, settings, 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 transcript JSON you created in step 1.
-
-**Read the JPG frames** from `tmp/frames/[video_name]/` using the Read tool, then **Edit** the file at `<visual_transcript_path>`. Do this incrementally — no script needed; just edit the JSON each time 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: 3 sentences max
-- First segment: detailed (subject, setting, shot type, lighting, camera style)
-- Continuing shots: brief if similar; up to 3 sentences if drastically different
-
-## 4. Cleanup & return
-
-```bash
-rm -rf tmp/frames/[video_name]
-```
-
-Return:
-```
-✓ [video_filename.mov] analyzed successfully
-  Visual transcript: <visual_transcript_path>
-  Video path: <video_path>
-```
-
-**Do NOT update library.yaml** — parent 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: Backs up user libraries and all their contents (external video excluded). 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/cut-planner/SKILL.md

@@ -1,74 +0,0 @@
----
-name: cut-planner
-description: Plans a cut (roughcut, sequence, or scene) from a library's clip summaries. Reads all clip summaries, then talks with the user and iteratively creates a plan markdown file until both agent and user are happy and understand the plan.
----
-
-# Skill: Cut Planner
-
-## Overview
-
-In the cut-planner skill, the main thread reads clip summaries from a library to understand footage coverage, then asks the user about the footage to confirm its understanding. It confirms who the characters and locations are, then updates the library.yaml's footage_summary and user_context as it learns more about the footage. If it determines summaries are wrong or missing details, it also updates the summary markdowns.
-
-After confirming its understanding of the footage, it works with the user to create a narrative plan markdown file.
-
-This skill runs in the main thread and does not use a sub-agent.
-
-## Cut Planner Process
-
-### 1. Verify all clips have visual transcripts and summaries
-Read `libraries/[library-name]/library.yaml`. Every clip must have `visual_transcript` and `summary` populated. If either is missing for any clip, stop and tell the user which clips still need processing — don't try to plan from incomplete footage. Then ask if they want to resume processing the library.
-
-### 2. Read summaries
-
-#### Sequences
-If the user explicitly says they want something short like a short sequence (60 seconds or less), consider asking them about what they want and then grepping through summaries to find the handful of files they might need.
-
-#### Rough Cuts
-If the user wants a full roughcut, read every `libraries/[library-name]/summaries/summary_*.md` file. This will give you full knowledge of the library.
-
-### 3. Confirm the footage knowledge and update incorrect summaries
-Tell the user what you've learned about the footage, then confirm you understand the Five W's of all the footage: Who, What, When, Where, Why.
-
-Don't tell them "Five W's" or label out Who, What, When, Where, Why, just talk with them conversationally like an assistant editor getting a grip on the footage.
-
-If they want a full roughcut, spend more time. If they just want a sequence, be brief.
-
-Talk with the user until you confirm you understand the footage. Update library.yaml based on the user's responses as you work through questions.
-
-Update footage_summary (locations, characters, narrative, dialogue, clips) and user_context (preferences, goals, etc.) as you iteratively learn more about the footage.
-
-Updating user_context and footage_summary helps future agents understand the footage and the user.
-
-For example, if a summary mentions a generic man or woman but you learn the person is actually the user, replace man/woman with the user's name. Ask the user's name if you don't know it already.
-
-### 4. Ask target length
-If available, use the `AskUserQuestion` tool or similar to ask the user what length of video they want to create. Use your judgement based on the footage — options like short sequence (30–60s), medium cut (5–8 min), or longer roughcut (9+ min) make good starting points. Podcast footage will likely require a longer option.
-
-### 5. If creating a roughcut, propose 2–3 concepts (titles only)
-Give the user 2–3 genuinely distinct narrative concepts. Keep this round short — it's about picking a direction, not approving a full plan. For each concept, write only:
-- **Title** — short, evocative
-- **Concept** — 1–2 sentences explaining the angle, tone, or arc
-
-Do **not** include beats, footage suggestions, runtime breakdowns, or format notes yet. Those come in step 6 once a direction is chosen.
-
-Make the options genuinely distinct — different angles, tones, or arcs. End with: "Which feels right, or want me to explore something different?"
-
-If the user just wants a short sequence, give them information about what the sequence will contain.
-
-### 6. Flesh out the chosen concept
-Once the user picks a direction for a full roughcut, expand it into a full plan and present that for approval. Now include:
-- **Format** — vlog, YouTube Short, long-form, documentary, etc.
-- **Beats** — 3–6 beats, each with editorial intent and a rough share of the runtime ("open with ~3 min of X", "montage of Y", "close on Z")
-- **Footage suggestions per beat** — name a few videos likely to feed each beat, ie DJI_123, panasonic_1234, etc. Include rough or specific dialogue if you think it will be helpful.
-- **Approx. duration**
-
-Iterate on the fleshed-out plan until the user explicitly signals go.
-
-If the user wants a short sequence, be brief, just a few sentences, including dialogue if that makes sense.
-
-### 7. Save the plan
-Copy `templates/plan_template.md` to `libraries/[library-name]/plans/plan_[short-name]_[YYYYMMDD_HHMMSS].md` and fill in every section. The template is the canonical structure — Concept, Format, Target Duration, Beats (with intent / approx. share / footage suggestions), Required Dialogue, Notes for the Build.
-
-The plan is direction. The build agent confirms specific clips inside each beat.
-
-Tell the user the plan is ready and confirm they want to move forward, then invoke the `roughcut` skill, passing the full plan path (`libraries/[library-name]/plans/plan_[short-name]_[YYYYMMDD_HHMMSS].md`) as a skill argument — `roughcut` hard-stops if it isn't given one.

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