roughcut-skill

Showcase only — no license, all rights reserved. This repository is publicly viewable but is not open source. Viewing or forking it does not grant permission to use, copy, modify, distribute, or publish the code or skill. Default copyright applies. No LICENSE file is provided deliberately.

A small Agent Skills-compatible workflow and typed Python CLI for making first-pass cuts from one continuous Hebrew talking-head recording. It prepares one cached ElevenLabs Scribe v2 word-timed transcript, gives a model a compact phrase view and an editorial profile, validates two independent edit lists, and renders ordinary H.264/AAC rough MP4s.

The default both mode creates ordered short candidates and one cleaned continuous recording. shorts and clean modes render only their selected output. These are review artifacts, not final or approved content.

Prerequisites

• Python 3.11–3.13
• uv
• FFmpeg and ffprobe on PATH
• An ElevenLabs account and ELEVENLABS_API_KEY for real transcription only
• Authority to send the recording's audio to ElevenLabs

Install and inspect

git clone https://github.com/mocraimer/roughcut-skill.git
cd roughcut-skill
uv sync --all-groups --locked
uv run roughcut --help
uv run roughcut prepare --help
uv run roughcut validate --help
uv run roughcut render --help
uv run roughcut profile-check profiles/educational.json

The repository is intentionally not published to a package registry.

Offline demo

No API key or network transcription is needed. The script generates a six-second synthetic video, prepares it from the technical transcript and plan fixtures under tests/fixtures/, and renders both, shorts, and clean outputs. The public plans under examples/ are longer editorial examples and are not renderable against this technical fixture.

uv run python scripts/demo.py

The demo prints the exact three manifest paths under .demo/outputs/. Each run creates fresh both, shorts, and clean child directories. .demo/ is ignored.

Real workflow

read -rsp 'ElevenLabs API key: ' ELEVENLABS_API_KEY && export ELEVENLABS_API_KEY && printf '\n'
uv run roughcut profile-check profiles/educational.json
uv run roughcut prepare /path/to/recording.mp4 --work-dir .roughcut

prepare prints the exact cache paths. Give transcript.md and the profile to an agent using SKILL.md. The agent writes a plan under the strict schema. Then run:

uv run roughcut validate .roughcut/plan.json \
  --metadata .roughcut/cache/SOURCE_HASH/source.json \
  --output .roughcut/plan.normalized.json \
  --mode both

uv run roughcut render /path/to/recording.mp4 .roughcut/plan.normalized.json \
  --metadata .roughcut/cache/SOURCE_HASH/source.json \
  --output-dir outputs \
  --mode both

Use --mode shorts or --mode clean on both validation and rendering when requested. --output-dir is one output root. Every render reserves a fresh child such as outputs/roughcut-both-1a2b3c4d, and the CLI prints that child's exact manifest.md path after completion. A completed child contains the selected MP4 outputs, manifest.json, and manifest.md; it has no .roughcut-incomplete marker. The source is read only.

Each render reserves its visible child atomically with mkdir, immediately adds a .roughcut-incomplete marker, and renders directly there. After FFmpeg finishes, it checks the source hash, writes both manifests, then removes the marker last. Unique names make concurrent renders to one root independent, and a name collision always selects another name rather than replacing even an empty existing child. Existing root contents are never replaced, scanned, cleaned, or recovered. A caught failure removes only its own reserved child. Process death can leave a visible, clearly marked incomplete child; it is honest partial output, never a completed render, and must be inspected or removed manually.

Install the Agent Skill

Install the CLI environment first. Then link or copy this repository directory into an Agent Skills search path, keeping SKILL.md, docs/, and profiles/ together. For a common per-user path:

mkdir -p ~/.agents/skills
ln -s "$(pwd)" ~/.agents/skills/roughcut-skill

If your harness uses another Agent Skills directory, use that path instead. Invoke the skill with a source video and profile; the work directory defaults to .roughcut, and the skill asks for an output root only before rendering. It asks for one missing input at a time, validates before rendering, reports the fresh child path and uncertainty, and stops before publishing or approval.

Design and boundaries

Automated render verification uses two declared media tolerances. A decoded video source boundary may differ from its planned time by at most 2 frames at 25 fps (80 ms). A rendered video stream, audio stream, or MP4 container duration may differ from the sum of its planned ranges by at most 2 video frames plus 1 AAC-LC packet of 1024 samples at 48 kHz, rounded up to a 120 ms ceiling. The fixture embeds a decodable source-frame identity in every frame: identity checks prove source mapping at every short and cleaned-concat boundary, while separate stream-duration checks bound AAC padding and container timing.

• Architecture: deterministic CLI versus editorial model/profile work
• Plan schema: strict dual outputs, modes, normalization, and validation
• Profiles: generic educational and unaffiliated House Finance examples
• Privacy, security, and cost: exact upload and local-data boundaries

Real preparation extracts compact mono audio locally and uploads only that audio to ElevenLabs. It preserves fillers and false starts (no_verbatim=false), requests Hebrew word timestamps, and disables diarization for one speaker. Source inspection hashes before ffprobe and again after probing and stat so metadata cannot combine file versions. The cache is keyed by source-content SHA-256. Preparation checks the source again after extraction and before cache publication; a mutation publishes no valid cache. Concurrent preparations publish complete staging by atomic rename: one complete cache wins and the others return cache hits. A nonempty incomplete canonical cache is preserved unchanged and causes an actionable error naming the exact path to inspect or remove before retry. Process death may leave only hidden staging, which never hides a complete canonical cache. The local cache includes sensitive audio, transcript, and absolute source path and is not encrypted.

ElevenLabs quota or charges can apply to real transcription. Smaller mono audio reduces transfer size, not necessarily duration-based cost. This project does not request zero-retention mode; check provider terms and account settings. See the privacy document before use.

No real House Finance footage was tested. The House profile uses only public positioning from https://www.house-finance.co.il/about, is not affiliated with or approved by House Finance, and is not legal or financial approval. Hebrew accuracy, real cut edges, claims, permissions, and legal compliance require human review.

Out of scope: captions, reframing, grading, B-roll, motion graphics, social copy or posting, NLE project files, local speech recognition, multiple-take comparison, hosted services, and automatic final approval.

Troubleshooting

• Missing FFmpeg/ffprobe: install FFmpeg and ensure both programs are on PATH.
• Missing key: set ELEVENLABS_API_KEY, or use --fixture-transcript only for offline test data.
• No audio or unsupported media: transcode the source to a normal video with one audio stream, then prepare the new file (it will have a new source identity).
• Scribe failure: check account access, quota, provider limits, network access, and extracted audio; incomplete calls do not create a valid canonical cache. Hidden staging from process death may be removed manually.
• Incomplete cache: inspect the exact cache path reported by the CLI. Roughcut preserves any nonempty incomplete canonical cache; remove that exact entry yourself only when its contents are no longer needed, then retry.
• Plan rejected: use the exact prepared source ID, keep all required fields, and fix the specific bounds, overlap, mode, or type error before rendering.
• Cannot write: choose work and output directories with free space and write permission.
• FFmpeg render failure: check source compatibility, stream presence, disk space, and FFmpeg encoder availability. A caught failure removes its own reserved child. After process death, a visible child containing .roughcut-incomplete is partial and must not be treated as complete; inspect or remove it manually.
• Source changed: retry prepare or render only after the source file is stable. Mutation checks prevent publication under a stale source identity.
• Output root refused: choose a missing or existing real directory. Files, symlinks, and broken symlinks are refused; arbitrary existing directory contents are left untouched.

Contributing and verification

Contributions can be discussed, but without a license you receive no general permission to reuse this work. From a clean checkout:

rm -rf .venv
uv sync --all-groups --locked
uv run skills-ref validate "$(pwd)"
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -m "not e2e"
uv run pytest -m e2e
uv run python scripts/demo.py

CI runs the same Agent Skills validation, format, lint, type, unit, and fixture-E2E gates on Python 3.11, 3.12, and 3.13 with read-only repository permissions and no API key.