/kinocut

name: kinocut
description: Use when an agent must edit local video safely. Kinocut guards planning, FFmpeg operations, subtitles, audio, analysis, quality gates, receipts, repurposing, and Hyperframes via MCP, Python, or CLI.

Kinocut

Use Kinocut when an agent needs a structured video-editing surface instead of hand-writing FFmpeg commands. It exposes MCP tools, a Python client, and a CLI for editing, analysis, subtitles, audio, Hyperframes, layered compositing, and local repurposing workflows.

Published 1.16.1 and the matching development checkout have 203 MCP tools / 177 CLI commands; inspect the installed schemas before using development additions. Desktop-local execution is available; native Android/iOS clients and a complete browser processing application remain unimplemented. Recommended service/client work is described in `docs/PLATFORM_PARITY.md`.

Default path (do this first)

1. `kino doctor` then `kino --format json info <file>`. 2. For an unfamiliar task, call `search_tools` with the user's task (for example, "remove filler words" or "keep face in frame"), then inspect the returned tool's required inputs. Plan with `video_intent` for supported intents (optional `goal=` compiles a cutfile; a 360/desk/table/`x4` goal also proposes a `360_assembly_plan`). Check that the proposal actually satisfies the request before rendering. 3. Render (`video_cutfile_render`, `video_edit`, workflow, or a single engine tool). For 360: `video_review_decide` approve/reject on that plan, then render — never render a `proposed` plan. `.insv` is rejected; need a stitched 360 MP4. Guide: `docs/360_ASSEMBLY.md`. 4. `video-quality-check` / `assert_quality`. Sync `repurpose` and `shorts-package` fail-closed at score 80 unless skipped/`allow_fail`. 5. Human visual/audio review. Never treat a receipt as published.

Depth (rescue, salvage, composite, Hyperframes, thin sound S12): `docs/TOOLS.md`, `docs/RESCUE.md`, `docs/WORKFLOWS.md`. Workflow allowlist: probe, trim, resize, convert, crop, add_text, merge, composite_layers, burn_in.

Load the relevant guide when needed. Use source evidence for editorial choices; preserve names, numbers, negation, and qualifications. Report missing evidence or unsupported actions instead of inventing source claims, timestamps, or capabilities. A planning tool proposes an edit; its existence does not mean the required detector or model has run. Code owns timing, transforms, validation, and execution; human review remains separate from model judgment.

Revideo local code-video flow (published 1.16.1)

Use `revideo_materialize`, `revideo_install`, and `revideo_render` when the caller needs an inspectable staged project. Use `revideo_render_job` for the same guarded steps in one call. A supplied scene is trusted executable TypeScript: inspect it before use and never run untrusted scene code. Dependency installation may access npm; rendering runs locally against Kinocut's pinned template. The render receipt binds observed media and output bytes to the exact bounded on-disk job-file digest. `.mp4`, `.webm`, and `.mov` select pinned MP4, WebM, and ProRes 4444 exporter modes and are verified before publication. Verify the receipt against the output bytes, run `video_quality_check` and `video_release_checkpoint`, then require human visual review.

Start Here

• Read `../../README.md` for install and the safety contract.
• Run `kino doctor` before FFmpeg / Hyperframes / AI extras.

Choose A Surface

• MCP: best for Claude Code, Cursor, Codex-style clients, and other agent hosts. Configure `uvx --from kinocut kino`.
• CLI: best for direct local edits, quick diagnostics, `composite-layers --dry-run`, batch jobs, and CI-friendly JSON output.
• Python client: best for repeatable pipelines that need structured results, output paths, and saved layer-plan receipts.

360 dual-cam assembly (published 1.14.0)

Use when the source is a **stitched equirect 360 MP4** from any camera (Insta360, Ricoh Theta, GoPro MAX, DJI Osmo 360, …) and the ask is two virtual cameras as split / switch / PiP / single.

1. `video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH)` or `Client.propose_360_assembly(...)`. 2. Show cameras, layout, and storyboard stills. Do not invent yaw/pitch. 3. `video_review_decide` / `Client.decide_360_assembly` with `approve` or `reject`. 4. Render only an approved plan (`Client.render_360_assembly` or `video_review_decide` + `output_path`).

There is no `video_360_*` MCP tool and no `kino 360` command. In published 1.16.1, `kino intent reformat_vertical --goal "desk 360 split 9:16" --source PATH` also proposes a nested `sphere_plan`. Save that plan as its own JSON artifact; after actual human review, `kino review-decide PLAN.json accept --output OUTPUT` approves and renders it. `reject` never renders; changed source identity blocks rendering. Director hooks accept an injected JSON proposer; a configured model name alone does not execute a model. Cloud proposals require `allow_cloud`; directors never write pixels.

Published 1.16.1 operator parity

• Timed audio: `video_mix_audio`, CLI `mix-audio --sounds JSON`, and

`Client.mix_audio` use one AAC encode and copy the picture. Gains can clip; listen before delivery. CLI `duck-audio` joins existing `video_duck_audio` and `Client.duck_audio`; neither provides governed audio-bed receipts or automatic delivery loudness normalization.

• Encoding: `trim --accurate`; `convert --two-pass --target-bitrate KBPS`

(MP4/MOV); `fade --crf`; and `add-audio --mix --duration-policy loop_audio` map to shared controls. Mixed `pad_audio` remains unsupported. `normalize-audio --lufs --lra --true-peak-dbtp --fade-seconds` exposes loudness and boundary-fade controls; verify the resulting soundtrack and delivery spec.

• Frame extraction: omitted timestamps use smart sampling when available,

otherwise 10% of duration. Pass explicit zero for the first frame.

• HLS: CLI `hls-segment`