// Backs up user libraries and all their contents (external video excluded). This skill can also be useful when you need to restore a library.
| 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. |
Backups default to ~/Documents/buttercut-video-editor-backups. Each library gets its own subdirectory there, and each run drops a timestamped archive of just that one library — so adding a new clip to one library only writes that library's archive, not a full duplicate of everything.
~/Documents/buttercut-video-editor-backups/
wedding/
wedding_20260520_140000.aar
programmer-story-vlog/
programmer-story-vlog_20260520_140000.aar
Read backups_dir from libraries/settings.yaml. If the key is missing, ask the user with AskUserQuestion whether to use the default (~/Documents/buttercut-video-editor-backups, recommended) or a custom folder, and save the answer to libraries/settings.yaml under backups_dir. If libraries/settings.yaml doesn't exist yet, create it from templates/settings_template.yaml first.
When invoked from another skill that must stay non-interactive (e.g. process-library auto-backup) and backups_dir isn't set, skip the prompt and use the default — the user can change it later.
Default to backing up just the library you've been working on — that's almost always what "run a backup" means. Only back up everything when the user explicitly asks for "all libraries" or you're doing a one-time cleanup pass.
# Back up the one library you just touched (the usual case)
ruby lib/buttercut/backup_libraries.rb --library <library-name>
# Back up every library (only when the user explicitly asks)
ruby lib/buttercut/backup_libraries.rb
The script reads backups_dir from libraries/settings.yaml (falling back to the default). Pass --backups-dir <path> to override for one run.
Apple Archive (.aar) is used when the macOS aa CLI is available — hardware-accelerated on Apple Silicon, Finder handles double-click extract. Falls back to .zip otherwise.
After a successful backup_all run, the script removes the legacy in-project backups/ directory (the old single-archive layout) if it still exists and the resolved backups_dir is somewhere else. Per-library runs leave it alone.
Extract the per-library archive back into libraries/:
# Apple Archive — restores into libraries/<library-name>/
aa extract -i ~/Documents/buttercut-video-editor-backups/<library>/<library>_<timestamp>.aar -d libraries/<library>
# Zip — already contains the <library>/ folder
unzip ~/Documents/buttercut-video-editor-backups/<library>/<library>_<timestamp>.zip -d libraries/
Skill for processing footage (video clips, sounds, photos, etc). Use this when creating a new library, adding new footage (videos) to an existing library, or resuming processing on an existing library.
Build a cut from a library — scene, selects, roughcut, or custom task. Starts by asking what kind of cut the user wants, then works with them to determine what they want to create. Always exports a file for Final Cut, Premiere, or Resolve at the end. Use when the user asks for a "roughcut", "sequence", "scene", "selects", or any other cut-shaped output.
Full footage analysis pipeline — audio transcripts, contact sheets, and Sonnet-written summaries. Produces every artifact the cut skill reads. Orchestrated from the main thread.
Builds a contact sheet from a video clip — evenly spaced frames laid out in a single grid image, each with its hh:mm:ss timestamp burned in. Use when the user asks for a "contact sheet", "grid", "film strip", or wants a one-image overview of part of a clip.
Exports all dialogue from every clip in a library into a single text file. One clip per block — filename, then its spoken words. Use when the user asks for a "full transcript", "full script", or wants all the dialogue from a library in one place.
Reset a library's visual analysis (contact sheets, summaries, legacy visual_transcripts) and re-run the current analyze-video pipeline on it. Keeps audio transcripts, cuts, plans, and library metadata. Use when a library was processed under the older pipeline and the user wants to bring it onto the contact-sheet-based one.