kinocut

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.5 serves 205 MCP tools / 177 CLI commands with `KINOCUT_TOOLS=all`; the default registration is a curated 20-tool core. Inspect the installed schemas before using 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.

## Vision review and network permission (1.16.5)

Keep `KINOCUT_VISION_MODE=off` (the default). Prepare images with `video_thumbnail`
or `video_qc_vision`, then use the host's configured vision model to inspect them.
Use `image_analyze_product(use_ai=false)` for local colors. The host owns local or
hosted inference and fallback; Kinocut's MCP process does not inherit that routing.
Keep host observations separate from Kinocut's unevaluated semantic QC status.
Do not invent a visual pass when no model or human has inspected the frames.

The optional legacy product adapter requires explicit operator `local` or
`remote` mode and speaks the Anthropic-compatible Messages protocol. Local mode
requires a loopback endpoint and never enables the separate fixed cloud QC
worker. Credentials and tool arguments cannot override `off`. See
[the vision and network policy](https://github.com/KyaniteLabs/kinocut/blob/v1.16.5/docs/VISION_PRIVACY.md) before enabling either adapter.

Hyperframes telemetry and passive update checks default off. Kinocut removes known
provider credentials from its child environment and disables implicit capture/snapshot
model analysis. With telemetry off, previews require verified CLI 0.8.104 or 0.8.140.
Docker rendering and other preview versions require explicit operator telemetry consent;
do not enable consent on the operator's behalf. These controls do not sandbox project
assets or requested network access. See the vision/network policy for the limits.

## Revideo local code-video flow (published 1.16.5)

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. Telemetry defaults off; only explicit operator
`KINOCUT_REVIDEO_TELEMETRY=true` enables it. 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 runtime requirements, network disclosures, and the safety contract.
- Run `kino doctor` before FFmpeg / Hyperframes / AI extras.

## Choose A Surface

- MCP: use the pinned server that the host already starts from this plugin's `mcp.json`. Do not install a second copy or modify another host's configuration.
- 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.5, `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.5 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` joins `video_hls_segment`/`Client.hls_segment` for local
  packaging; it does not publish or host a stream.
- Estimates: `video_estimate_operation`, CLI `estimate`, and
  `Client.estimate_operation` return local heuristics, dimensionless cost units,
  and no billing currency. Do not present them as measured cloud latency/cost.

## Product / object matte (published in 1.15.1; current in 1.16.5)

The optional object-matte extra is available in published 1.16.5. Use the **existing** `hyperframes-remove-background` / `hyperframes_remove_background` command. Default model is people. For catalog SKUs, jewelry, bottles, shoes, packaging, or anything that is not a person:

1. `hyperframes_remove_background(info=true)` — lists models, no download.
2. The optional extra belongs in the server's uvx arguments, pinned to the same version as `mcp.json`: replace its `kinocut==1.16.5` argument with `kinocut[object-matte]==1.16.5`. Installing the extra in a separate Python environment does not affect the uvx server. Have the operator configure this extra before using `model="birefnet-general"`.
3. Optional `--mask-interval 3` on product video. Optional equipment overlay for leftover turntable/stand/tripod/sweep.
4. Composite onto a shop plate with `composite-layers`. Keep every `src` inside the spec directory.

Do **not** invent `video_product_matte`; this is not a new MCP tool. Do **not** fall back to the people model when the object extra is missing. Guide: `docs/PRODUCT_MATTE.md`. Example: `examples/product-matte/`.

## Dedicated Video Rescue

Use `video_rescue_*`, `rescue-*`, or `Client.rescue_*` when the request is to fix one local
clip while preserving its source, story, and timeline.

From KyaniteLabs/kinocut, Apache-2.0.

More from KyaniteLabs/kinocut