# MCP Tools Reference

kino's development tip exposes **203 registered MCP tools / 177 CLI commands** across video editing, governed AI-video review and salvage, project-backed deterministic inspection, dedicated rescue, post-rescue planning, the agent workflow engine, PUSHING CREATION-style planning, Hyperframes and Revideo video authoring, repurposing packages, audio, effects, analysis, and image workflows. Published 1.16.0 exposes **203 MCP tools / 177 CLI commands**. All return structured JSON with `success` and operation metadata. On failure, they return `{"success": false, "error": {...}}` with operation-specific diagnostics and suggestions when available.

---

## Project-backed Inspection (3 tools)

These operations share one adapter with the Python client and CLI. Only ingest accepts a
host source path. Later operations resolve the active stored record by `asset_id`; they do
not accept a caller-supplied record or an arbitrary media path.

| Tool | Description |
|------|-------------|
| `video_ingest` | Copy source bytes into a content-addressed private project and return the authoritative asset record |
| `video_preflight` | Persist one technical, loudness, color, and full-decode report for a stored asset |
| `video_inspect_temporal` | Persist sampled frames, a motion strip, frame differences, deterministic findings, explicit optional-provider availability, and the complete inspection manifest |

`video_preflight` and `video_inspect_temporal` require an existing project. Optional visual
providers are not contacted or downloaded implicitly; the default result explicitly marks
both visual capabilities unavailable.

## Durable Intent and Recipe Tools (3 tools)

These tools operate on an existing project, edit project, and immutable revision. Semantic
search stays local and revision-bound. Recipe export verifies that caller-supplied operation
descriptors compile to the selected revision, then emits a canonical artifact containing
digest placeholders and typed parameters—not host paths. Replay requires explicit source
digest bindings and appends a new revision; it never overwrites the source or publishes.

| Tool | Description |
|------|-------------|
| `video_find_moments` | Persist or query a bounded, revision-owned semantic index in projectstore CAS |
| `video_project_recipe_export` | Export a verified revision path as a path-free, policy-carrying portable recipe |
| `video_project_recipe_replay` | Bind recipe source slots to explicit CAS digests and replay into a durable revision |

The guarded recipe flow is: review the source revision and policies, export, distribute the
JSON artifact, bind every `cas_digest` slot in the destination project, then replay. A recipe
is not release authority: review gates remain metadata that the receiving workflow must
satisfy, and no tag, package upload, directory submission, or publish action occurs.

## Governed AI-video Review and Salvage (4 tools)

These operations share one validated boundary with the Python client and CLI. Protection
has no force or bypass parameter; authorization accepts only stored human decision ids.
The end-to-end sequence and stop conditions are in
[AI_VIDEO_REVIEW_AND_SALVAGE.md](AI_VIDEO_REVIEW_AND_SALVAGE.md).

| Tool | Description |
|------|-------------|
| `video_verdict` | Persist exact-asset analysis; approved dispositions require an active exact human decision and requirement-level evidence |
| `video_acceptance_eval` | Resolve active stored spec/verdict ids and derive acceptance without creating an approval |
| `video_body_swap` | Require a project and two active stored inputs, then replace video while preserving approved audio |
| `video_salvage` | Create one content-addressed, lineage-bound salvage derivative with a fresh non-approved review slot |

---

## Meta / Discovery (1 tool)

| Tool | Description |
|------|-------------|
| `search_tools` | Rank registered MCP tools by exact name, keyword, or supported task phrases such as `remove filler words`, `resume render`, and `keep face in frame`. Returns matching names, descriptions, and required parameters; planning tools remain plans and discovery does not verify optional backends. An empty query returns no matches. Clients that eagerly load all MCP tools still receive the full registry. |

**Python Client:**
```python
from kinocut import Client
editor = Client()
results = editor.search_tools("subtitle")
# Returns matching tool metadata: {success, query, count, tools}.
```

---

## Visual review evidence

Published 1.16.0 `video_record_motion_acceptance` and CLI `record-motion-acceptance`
join Python `Client.record_motion_acceptance`. Supply the exact `report`,
`input_path`, `reviewer_id`, `source_sha256`, `report_sha256`, complete
`watched_intervals`, flagged-interval `dispositions`, and `verdict` (`accept` or
`reject`). CLI requires either inline `--report-json JSON` or bounded
`--report-file PATH` (UTF-8 JSON, sized for bounded longform producer output).
Watched intervals and dispositions likewise accept mutually exclusive inline
`--watched-intervals-json` / `--dispositions-json` or bounded
`--watched-intervals-file` / `--dispositions-file` inputs. Use files when these
artifacts exceed OS argument limits; file caps derive from producer/evidence
counts while inline JSON keeps its 1 MiB cap. The result nests the content-hashed `receipt`. This is an explicit
caller attestation: `attestation_verified_by_system=false`, not authenticated
proof of viewing or release approval. Agents must never invent the human inputs.

`video_qc_vision` prepares retained keyframes for human visual review. It reports
`sampling_status` separately from `assessment_status`; preparing frames does not
establish visual quality. With no executable VLM scorer, complete sampling returns
`verdict="not_evaluated"` and incomplete sampling returns `"inconclusive"`.
Setting `require_vlm=true` returns `verdict="fail"` and `blocked=true`. Installing
a provider SDK alone does not make visual assessment available. Explicitly setting
`KINOCUT_VISION_MODEL` and `ANTHROPIC_API_KEY` opts into one paid Anthropic request
for the sampled frames. The request runs in an isolated worker with an elapsed
deadline and byte ceilings; malformed or incomplete responses fail closed. This
does not approve the whole film or establish model accuracy. See
[quality evidence](QUALITY_EVIDENCE.md) for waveform, objective visual measurement
and perceptual voice limits.

Published controls also include `video_convert(two_pass=true,
target_bitrate=KBPS)` for MP4/MOV, `video_fade(crf=...)`, and
`video_add_audio(mix=true, duration_policy="loop_audio")`. Mixed `pad_audio`
remains unsupported. `video_hls_segment` now has CLI `hls-segment`; it writes
local playlists/segments and does not host them. `video_estimate_operation`,
CLI `estimate`, and `Client.estimate_operation` share the local heuristic:
`estimated_cost_units` is dimensionless and `currency` is null.

---

## Cinematic Creation (4 tools)

Plan video generation like a director of photography before rendering. These tools implement a PUSHING CREATION-compatible pre-production workflow: project scaffold, STYLE_/NEG_ blocks, storyboard tables, and prompt expansion.

| Tool | Description |
|------|-------------|
| `video_project_create` | Scaffold `projects/<slug>/style.md`, `storyboard.md`, and `refs/` using cinematic starter templates |
| `style_pack_read` | Parse STYLE_/NEG_ blocks, including one parenthesized heading annotation; malformed or duplicate declared headings fail |
| `storyboard_read` | Parse storyboard rows from `storyboard.md` or a project directory |
| `shot_prompt_render` | Expand camera/lens direction and style blocks into generic positive/negative prompts; `model_dialect_compiled=false`, no provider execution |

---

## Agent Workflow Engine (4 tools)

Plan, validate, render, recover, and prove a multi-step local video job from one JSON
job-spec over a small allowlisted op set (`probe | trim | resize | convert | crop | merge |
add_text | composite_layers | burn_in`). Every op maps 1:1 to a vetted engine function; params are introspected from
the engine signature; media references are symbolic and workspace-confined. Full schema,
`@ref` grammar, variants, resume, and cleanup are in [WORKFLOWS.md](WORKFLOWS.md); receipt
shapes are in [VIDEO_RECEIPT.md](VIDEO_RECEIPT.md).

| Tool | Description |
|------|-------------|
| `video_workflow_validate` | Fail-closed structural gate for a job-spec (op allowlist, `@ref` resolution, backward-reference-only ordering, per-op param introspection, workspace-confined path safety); renders nothing |
| `video_workflow_plan` | Dry-run plan artifact (`receipt_kind: workflow_plan`): ordered op graph, per-source ffprobe + sha256 hashes where the file exists, output intents, variant summary; renders zero media (`save_plan`, `variant`) |
| `video_workflow_render` | Execute allowlisted ops sequentially and emit a `workflow` provenance receipt (per-step input/output hashes, cleanup manifest, determinism caveat); supports `resume_receipt`, `save_receipt`, `keep_intermediates`, `variant`, `all_variants`, `save_receipt_dir` |
| `video_workflow_inspect` | Summarize any receipt this project emits — `workflow`, `workflow_plan`, or `layer_plan` (v2 or legacy v1 without `receipt_kind`) — with a read-only integrity re-check, human-review pointers, and known limitations |

---

## Dedicated Video Rescue (3 tools)

The rescue tools form one review-first local pipeline. Plan and inspect before render; pass
only IDs from the plan's `safe_repairs`; inspect the final receipt before trusting the
package. Full contracts and examples are in [RESCUE.md](RESCUE.md).

| Tool | Description |
|------|-------------|
| `video_rescue_plan` | Analyze one local video without rendering; return evidence, previews, policy-classified safe/recommended/unavailable/blocked work, package intents, and an estimate |
| `video_rescue_render` | Apply approved safe repair IDs from an immutable reviewed plan; fail closed on staleness, dependency drift, cancellation, or verification failure |
| `video_rescue_inspect` | Inspect a plan or receipt and re-check promoted artifact hashes, verification, privacy, resume, and cleanup state without modifying media |

---

## Post-Rescue Planning (8 tools)

These JSON-compatible tools are side-effect-free planners and verifiers. They do not render,
download models, contact providers, or submit jobs. See
[POST_RESCUE_FEATURES.md](POST_RESCUE_FEATURES.md) for operations and guardrails.

| Tool | Description |
|------|-------------|
| `video_semantic_timeline` | Build a source-time semantic timeline from supplied analyzer evidence |
| `video_semantic_query` | Query local source-backed spans without invented descriptions |
| `video_timeline_edit_plan` | Build an EDL, approval binding, visible diff, and verification |
| `video_visual_transform_plan` | Plan analysis, subject-aware reframing, or stabilization |
| `video_restoration_plan` | Plan or evaluate evidence-gated restorative work |
| `video_composition_plan` | Build manifests, selections, compositions, previews, compiled plans, and checks |
| `video_creative_autopilot_plan` | Coordinate declared proven local planners or abstain |
| `video_remote_egress_plan` | Plan explicit remote egress and fake-adapter receipts without network I/O |

---

## Core Editing (35 tools)

| Tool | Description |
|------|-------------|
| `video_info` | Get metadata: duration, resolution, codec, fps, file size |
| `video_info_detailed` | Extended metadata with scene detection and dominant colors |
| `video_trim` | Trim by finite start time + duration or absolute end; `accurate=true` selects frame-accurate seeking; staged output preserves the destination on render/result failure |
| `video_merge` | Concatenate clips with optional per-pair transitions; warns on resolution/FPS/audio mismatches and rejects transitions longer than the shortest clip |
| `video_add_text` | Overlay text with positioning, font, color, shadow |
| `video_add_texts` | Overlay multiple text elements in a single FFmpeg pass; auto-detects overlaps and distributes stacked texts at the same named position |
| `video_add_audio` | Add, replace, or mix audio tracks with fade effects; validates volume and warns on timing/sample-rate risks |
| `video_resize` | Change resolution or apply preset aspect ratios (16:9, 9:16, 1:1, etc.) |
| `video_convert` | Convert between mp4, webm, gif, mov, hevc, av1, prores (two-pass encoding); validate a staged output before publication so failures preserve an existing destination |
| `video_speed` | Speed up or slow down (0.5x = slow-mo, 2x = time-lapse), with staged output publication |
| `video_reverse` | Reverse video and audio playback |
| `video_fade` | Fade in/out over the bounded primary-picture window, preserving delayed origins rather than using longer container/audio duration |
| `video_crop` | Crop in upright display pixels, including rotation-tagged phone video; explicit odd dimensions reject, percentage dimensions become even, pixel offsets stay exact |
| `video_rotate` | Rotate 90/180/270 and flip horizontal/vertical |
| `video_filter` | Apply bounded visual/audio filters; Ken Burns defaults to one frame per input at source fps, noise reduction uses -50 dB by default with explicit `noise_level` override |
| `video_chroma_key` | Remove solid color background (green screen) with bounded similarity/blend parameters |
| `video_stabilize` | Stabilize shaky footage (requires FFmpeg with vidstab) |
| `video_subtitles` | Burn `.srt`/`.vtt`/authored `.ass` subtitles into video; optional `style` force_style override (omit to preserve authored ASS PlayRes/styles/positions). SRT/VTT are rendered dimension-aware via a synthesized ASS whose PlayResX/Y match the probed display size |
| `video_subtitles_styled` | Burn subtitles with custom styling (font, size, color, outline) |
| `video_generate_subtitles` | Create SRT from text entries, optionally burn in |
| `video_watermark` | Add image watermark with validated opacity and positioning |
| `video_overlay` | Picture-in-picture overlay with opacity and timing guardrails |
| `video_composite_layers` | Spec-driven ordered image/video layer compositing with explicit straight/premultiplied input alpha, transforms, timing windows, masks/mattes, full-canvas and allowlisted positioned blend modes, rotation/pivot, named layer/mask/mask-edge `effect-noise` routes, dry-run plans, and deterministic `layer_plan` v2 receipts (video-only output) |
| `video_split_screen` | Side-by-side or top/bottom layout with duration/FPS/audio mismatch warnings |
| `video_edit` | Full timeline-based edit from JSON DSL, or sequence shortcut (`clips` + optional `transitions` / `transition_duration`) |
| `video_create_from_images` | Create video from image sequence |
| `video_export_frames` | Export video as individual image frames |
| `video_extract_frame` | Extract a frame; omitted `timestamp` uses smart sampling when available, otherwise 10% of duration; explicit `timestamp=0` means the first frame, matching CLI/Python |
| `video_extract_audio` | Extract audio as mp3, wav, aac, ogg, or flac |
| `video_export` | Render with quality and format settings; optional C2PA signing for final MP4 exports via `c2pa_manifest_path` |
| `video_normalize_audio` | Normalize audio/video loudness; `target_lufs`, `lra`, `true_peak_dbtp`, `fade_seconds` set delivery controls. WAV uses PCM16, supported M4A/video uses AAC with staged codec/full-decode validation |
| `video_batch` | Apply the same operation to multiple video files |
| `video_cleanup` | Remove Kinocut-managed intermediate files |
| `video_hls_segment` | Segment video into HLS format with multi-quality variants |
| `video_template_preview` | Preview social/video template operations before rendering |
| `video_validate_text_layout` | Validate text overlays for overlap, low contrast, unsafe positioning, and missing shadows before rendering |

Non-`normal` blends support opacity and `start`/`duration` windows in two geometries: full-canvas at `{0,0}` without explicit sizing, or a positioned rectangle with both positive integer `width` and `height` and an integral nonnegative in-canvas position. RGB blending avoids applying color arithmetic to subsampled chroma planes. Scale, rotation/pivot, mask/matte, fractional positions and out-of-canvas rectangles remain deferred and fail closed with `unsupported_blend_geometry`. Video layers and video masks start playing from their declared layer `start`; a timing window does not merely hide footage already playing from the canvas origin. File sources and masks must resolve inside the spec directory; place the spec in a common parent of its media.
Layer `alpha_mode` is `straight` by default; `premultiplied` image/video inputs are explicitly unpremultiplied before transforms and compositing. Top-level `passes` route `effect-noise` through `layer:<id>`, `layer:<id>.mask`, or `layer:<id>.mask.edge`. Unknown targets, effects, route/argument fields, and mask routes without a mask fail closed with stable validation errors.

---

## AI-Powered (11 tools)

| Tool | Description | Dependencies |
|------|-------------|--------------|
| `video_analyze` | Comprehensive video analysis: transcript, metadata, scenes, audio, quality, chapters, and colors | FFmpeg; optional Whisper/image extras |
| `video_ai_remove_silence` | Auto-remove silent sections with configurable threshold | FFmpeg |
| `video_ai_transcribe` | Speech-to-text with timestamp alignment | [openai-whisper](https://pypi.org/project/openai-whisper/) |
| `video_intent` | Route ~10 semantic intent verbs to a plan (no silent media mutation). Optional `goal=` compiles a reviewable cutfile. A 360/desk/table/`x4` `goal` plus `source=` also attaches a `360_assembly_plan` (`next_action: review_then_sphere_render`). See [360_ASSEMBLY.md](360_ASSEMBLY.md). | — |
| `video_propose_broll` | Transcript-keyed b-roll proposals; **human review required**, never silent insert | — |
| `video_translate_captions` | Translate SRT with honest coverage (EN→ES offline map first) | — |
| `video_language_coverage` | Honest per-surface matrix for transcribe / translate / dub | — |
| `video_review_run` | Watching guardrail: offline metric floor under a review policy | FFmpeg |
| `video_review_decide` | Human accept/reject/revise on a `review_run` artifact. If `review_run.artifact_kind` is `360_assembly_plan`, `approve`/`accept`/`reject` that plan and optionally render when `output_path` is set. | — |
| `video_ai_scene_detect` | ML-enhanced scene change detection (perceptual hashing) | [imagehash](https://pypi.org/project/imagehash/), Pillow |
| `video_ai_stem_separation` | Isolate vocals, drums, bass, other instruments | [demucs](https://pypi.org/project/demucs/), Torch, TorchAudio, TorchCodec |
| `video_ai_upscale` | AI super-resolution upscaling (2x or 4x) | [opencv-contrib-python](https://pypi.org/project/opencv-contrib-python/); Real-ESRGAN/BasicSR where supported |
| `video_ai_color_grade` | Color grading with style presets, reference matching or an explicit `lut_path` | FFmpeg |
| `video_quality_check` | Check brightness, contrast, saturation, audio levels, color balance |
| `video_design_quality_check` | Full design quality analysis: layout, typography, color, motion, composition |
| `video_fix_design_issues` | Auto-fix brightness, contrast, saturation, and audio level issues |
| `video_release_checkpoint` | Hard quality gate plus thumbnail/storyboard artifacts before publishing |

Install only the AI dependencies you need:

```bash
pip install "kinocut[transcribe]"  # Whisper transcription
pip install "kinocut[ai-scene]"    # perceptual scene hashing
pip install "kinocut[stems]"       # Demucs stem separation
pip install "kinocut[upscale]"     # OpenCV upscaling; Real-ESRGAN/BasicSR where supported
pip install "kinocut[ai]"          # all AI extras, kept for compatibility
pip install yt-dlp                   # only for downloading platform URLs (YouTube/Vimeo/...)
```

AI upscaling checks both estimated and actual extracted frame counts before
model initialization, stages final output, and rejects input/output aliases.
Failed frame writes and source-audio extraction abort instead of publishing
shortened or silent media.
The default test suite verifies these admission and publication controls with
native media and simulated inference. It does not establish model execution or
equivalent quality between OpenCV and Real-ESRGAN. BasicSR 1.4.2 retains an
unpatched advisory in its unused distributed initializer and a legacy import
incompatibility with modern TorchVision; consult [fleet upgrade guidance](FLEET_UPGRADE.md)
before enabling optional backends.

---

## Hyperframes — HTML-Native Video (18 tools)

Relative render and requested still output paths resolve from the caller working
directory. A requested still output is atomically copied independently of mutable
snapshots and contains PNG bytes; changing its extension does not transcode it.
Without an explicit output, the existing snapshot path may be replaced by a later
snapshot. Missing still artifacts are errors.


Create videos programmatically using [Hyperframes](https://hyperframes.io/) — an HTML-native framework for video (Apache 2.0). Hyperframes owns HTML-video authoring, catalog blocks, website capture, local TTS, transcription import, background removal, layout inspection, diagnostics, benchmarking, and rendering; Kinocut wraps those operations for MCP-safe orchestration and FFmpeg post-processing.

| Tool | Description |
|------|-------------|
| `hyperframes_init` | Scaffold a new Hyperframes project (blank, warm-grain, swiss-grid templates; optional media bootstrap, Tailwind, and resolution preset flags) |
| `hyperframes_render` | Render a Hyperframes composition to video (MP4/WebM/MOV/PNG sequence; optional composition, resolution preset, and runtime `variables` / `variables_file` flags; arbitrary width/height pairs are rejected instead of silently ignored) |
| `hyperframes_snapshot` | Capture actual PNG snapshot paths written by Hyperframes with optional runtime `variables` / `variables_file` data |
| `hyperframes_still` | Backward-compatible single-frame snapshot helper with optional runtime `variables` / `variables_file` data |
| `hyperframes_inspect` | Inspect rendered layout for overflow and visual issues |
| `hyperframes_info` | Read project metadata |
| `hyperframes_catalog` | Browse catalog blocks/components, including social overlays and caption styles |
| `hyperframes_capture` | Capture a website as editable Hyperframes components |
| `hyperframes_tts` | Generate speech audio with local Hyperframes TTS or list available voices |
| `hyperframes_transcribe` | Transcribe media to word-level timestamps or import transcripts |
| `hyperframes_remove_background` | Cut a person (default `u2net_human_seg`) or a product/object (`model="birefnet-general"`, `kinocut[object-matte]`) out of a still or video. `info=true` lists models without downloading. No new tool name. Guide: [PRODUCT_MATTE.md](PRODUCT_MATTE.md) |
| `hyperframes_doctor` | Run Hyperframes environment diagnostics |
| `hyperframes_benchmark` | Compare render speed and output size, with configurable run count |
| `hyperframes_compositions` | List all compositions in a project |
| `hyperframes_preview` | Launch Hyperframes preview studio |
| `hyperframes_validate` | Check project structure and run lint |
| `hyperframes_add_block` | Install a block from the Hyperframes catalog, with optional clipboard suppression |
| `hyperframes_to_mcpvideo` | Pipeline: render with Hyperframes, then post-process with Kinocut |

---

## Revideo — guarded local code video (4 tools)

| Tool | Purpose |
| --- | --- |
| `revideo_materialize` | Copy Kinocut's pinned bridge template and write a validated job. |
| `revideo_install` | Run bounded `npm ci` against the committed lockfile. |
| `revideo_render` | Render a verified materialized project and atomically publish its output. |
| `revideo_render_job` | Run materialize, install, render, decode verification, and receipt generation. |

`npm ci` can access the npm registry; rendering then runs on the local machine.
A supplied `scene_source` is trusted executable TypeScript. Kinocut rejects altered
control files, symlinks below the project root, malformed jobs, invalid timeouts,
and unverified output. Each render uses a fresh private project output, verifies
counted frames plus a full decode, and updates prior project and final outputs
only after validation. Render responses include output and exact on-disk job-file
SHA-256 digests, observed dimensions, fps, frame count, duration, render time,
and project directory. `.mp4`, `.webm`, and `.mov` select pinned MP4, WebM,
and ProRes 4444 exporter modes, with encoded format checks before publication. Run a
quality check and human visual review before publication. Local concurrent path
replacement, process crashes, and trusted scene behavior remain outside this
bounded in-process rollback guard. The job file is capped at one MiB; its
pre/post render binding is byte-exact, so formatting-only mutation also rejects
publication.

## Repurposing (2 tools)

Create local YouTube/social media packages from one source video. Publishing and scheduling are intentionally out of scope for v1; the tools produce files, manifests, thumbnails, storyboards, and optional release-checkpoint artifacts for a human or downstream publisher to review.

| Tool | Description |
|------|-------------|
| `video_repurpose_plan` | Dry-run a platform manifest with vertical, horizontal, and square output variants |
| `video_repurpose` | Render platform-ready assets plus thumbnails, storyboards, release-checkpoint artifacts, and `repurpose_manifest.json` |

---

## Stream shorts (saved-plan stages, 4 tools)

Local-only review → render → package over a persisted shorts plan. No posting.
See [STREAM_SHORTS.md](STREAM_SHORTS.md).

| Tool | Description |
|------|-------------|
| `shorts_plan_show` | Load a saved plan and return source-free proposals for review |
| `shorts_review` | Append one human decision (`approve` / `reject` / trim / title / sensitivity) |
| `shorts_render` | Render platform drafts for an approved candidate; cache unchanged digests |
| `shorts_package` | Write portable packages (video, SRT, thumbnail, metadata, manifest) |

---

## Sound public operations

Bounded local-first sound discovery and invoke via `kinocut_sound.public`. This is **not** full-episode sonic-world completion. Results are JSON-safe and fail closed on hostile/privacy boundaries.

| Tool | Description |
|------|-------------|
| `sound_capabilities` | Discover the bounded public sound operation set (local-first, non-TTY JSON) |
| `sound_plan_validate` | Validate a supplied SoundPlan, including typed state; explicit invalid plans fail. Omission retains the minimal example. See [input validation](SOUND_INPUT_VALIDATION.md). |
| `sound_voice_batch` | Retain local EN/ES caption speech with `request` + `project_root`, including V2 [dry/distance profiles](SOUND_SPEECH_SPATIAL.md); legacy `plan` mode is a labelled synthetic demo. See [caption speech](SOUND_DUB_REQUESTS.md). |
| `sound_mix_render` | Assemble supplied WAVs with [routing](SOUND_ROUTING_REQUESTS.md), [automation](SOUND_AUTOMATION_REQUESTS.md), [sends](SOUND_SEND_REQUESTS.md), [final sidechains](SOUND_SIDECHAIN_REQUESTS.md), [layers/loop fill/ducking](SOUND_LAYER_REQUESTS.md) and V4 [source-rate conversion](SOUND_RATE_CONVERSION.md). Takes a persisted request and project root. No-argument labelled demo remains available. See [request contract](SOUND_MIX_REQUESTS.md). |
| `sound_qa_loudness` | Measure the first audio stream of hashed supported local audio/video containers with FFmpeg and report actual policy compliance; omit inputs for a labelled demo. See [meter request](SOUND_LOUDNESS_REQUESTS.md). |
| `sound_master_render` | Retain a mono/stereo two-pass master ZIP only after measuring final audio against its policy. Requires `request` and `project_root`; see [master request](SOUND_MASTER_REQUESTS.md). |
| `sound_qa_asr` | Recognize hashed local audio and retain reference comparison. Requires `request` and `project_root` ([contract](SOUND_ASR_REQUESTS.md)) |

---

<a id="audio-synthesis-9-tools"></a>

## Audio Synthesis (10 tools)

Plain-file `Client.mix_audio` and `Client.duck_audio` also have published CLI
adapters `mix-audio` and `duck-audio`. The published 1.16.0 MCP addition is
`video_mix_audio`; `video_duck_audio` already existed. See
[audio mixing](AUDIO_MIXING.md) for engine behavior.

Generate audio from code — no external audio files needed. Pure NumPy, no extra dependencies.

| Tool | Description |
|------|-------------|
| `audio_synthesize` | Generate waveforms: sine, square, sawtooth, triangle, noise. With envelopes, reverb, filtering. |
| `audio_preset` | 15 pre-configured sounds: UI blips, ambient drones, notification chimes, data sounds |
| `audio_sequence` | Compose timed audio events into a layered track |
| `audio_compose` | Mix multiple WAV tracks with individual volume control |
| `audio_effects` | Apply effects chain: lowpass, reverb, normalize, fade |
| `video_add_generated_audio` | Generate audio and add it to a video in one call |
| `video_audio_spatial` | 3D spatial audio positioning (azimuth + elevation) |
| `video_mix_audio` | Mix `sounds` (track array or JSON array with `path`, `start`, `volume`, `fade_in`, `fade_out`) using one AAC encode and picture stream copy; `keep_source` and `audio_bitrate` controls. Gains sum and may clip; no automatic loudness normalization or governed audio-bed receipt |
| `video_duck_audio` | Mix background music under a video's voice with automatic sidechain ducking; music dips while speech plays and recovers in pauses |
| `video_audio_bed` | Governed one-shot audio-bed: duck a music bed under a voice track, normalize to EBU R128 `target_lufs`, optionally loop with crossfade, and emit a deterministic edit-receipt (`AudioBedReceipt`, `operation: "audio_bed"`, fixed `keep_video` duration policy). The receipt lands at top-level `result["receipt"]`; no authorization, duration-policy, or duration-tolerance parameter is exposed. |

---

## Visual Effects (8 tools)

| Tool | Description |
|------|-------------|
| `effect_vignette` | Darken edges for cinematic focus |
| `effect_chromatic_aberration` | RGB color separation (glitch aesthetic) |
| `effect_scanlines` | Retro CRT scanline effect with flicker |
| `effect_noise` | Film grain and digital noise |
| `effect_glow` | Bloom/glow for highlights |
| `video_apply_mask` | Apply image mask with edge feathering |
| `video_luma_key` | Mask out dark regions based on luminance (brightness) |
| `video_shape_mask` | Circle, rounded_rect or oval mask; default MOV retains alpha, explicit MP4 composites over black; static masks loop for video duration |

---

## Transitions (3 tools)

| Tool | Description |
|------|-------------|
| `transition_glitch` | RGB shift + noise for digital distortion |
| `transition_pixelate` | Block dissolve with configurable pixel size |
| `transition_morph` | Mesh warp transition |

---

## Glitch Effects (12 tools)

CPU-based glitch effects run entirely through FFmpeg. GPU-accelerated effects (marked below) require Node.js, the `MCP_VIDEO_CRUSH_PATH` environment variable pointing to the [CRUSH](https://github.com/pushingsquares/crush) shader sources, and the `canvas` npm package — install it once with `npm install` inside `kinocut/_crush_shader/`. The tools report exactly which piece is missing.

| Tool | Description |
|------|-------------|
| `glitch_rgb_shift` | Shift red and blue channels in opposite directions for a chromatic split look; optional per-frame noise for jitter |
| `glitch_scanline_jitter` | Displace random horizontal rows of pixels for a CRT malfunction look |
| `glitch_screen_tearing` | Create horizontal tear bands at varying Y positions that shift left/right over time |
| `glitch_vhs_tracking` | Simulate VHS tape tracking errors with color bleed, rolling bands, and analog noise |
| `glitch_macroblocking` | Simulate codec artifacting with downscale/upscale pixelation and color posterization |
| `glitch_datamoshing` | Simulate P-frame corruption where displacement drifts across frames then periodically resets |
| `glitch_cmyk_split` | Shift RGB channels at 90-degree intervals to simulate four-plate offset print registration errors |
| `glitch_turbulent_displacement` | Layered sin/cos noise approximating fractal Brownian motion for organic-looking displacement |
| `glitch_digital_feedback` | Iterative frame feedback with scale/rotation transform, creating ghostly trails and recursive patterns (requires Node.js + GPU) |
| `glitch_slit_scan` | Sample each row/column from a different past frame for a time-smeared slit-scan effect (requires Node.js + GPU) |
| `glitch_depth_splatting` | Extract pseudo-depth from luminance and render the image as scattered points in 3D (requires Node.js + GPU) |
| `glitch_point_cloud` | Sample the image as scattered points in a 3D-rotated grid with depth-based displacement (requires Node.js + GPU) |

---

## Layout & Motion Graphics (6 tools)

| Tool | Description |
|------|-------------|
| `video_layout_grid` | Grid layout for multiple videos (2x2, 3x1, etc.) with clip-count and duration mismatch warnings |
| `video_layout_pip` | Picture-in-picture with border and positioning |
| `video_text_animated` | Animated text overlays (fade, slide, typewriter) with color, timing, and overflow guardrails |
| `video_mograph_count` | Animated number counter video |
| `video_mograph_progress` | Progress bar/circle/dots animation |
| `video_auto_chapters` | Auto-detect scenes and create chapter timestamps |

---

## Analysis (8 tools)

| Tool | Description |
|------|-------------|
| `video_detect_scenes` | Auto-detect scene changes with threshold control |
| `video_thumbnail` | Extract a single frame (thumbnail / frame grab) at any timestamp |
| `video_preview` | Generate fast low-res preview |
| `video_storyboard` | Extract key frames as a grid for review |
| `video_compare_quality` | Compare PSNR/SSIM quality metrics between videos |
| `video_read_metadata` | Read video metadata tags |
| `video_write_metadata` | Write video metadata tags |
| `video_audio_waveform` | Measure first-stream RMS dBFS bins and silence regions; distinguish real measurements from `synthetic=true` fallback. [Evidence contract](QUALITY_EVIDENCE.md#audio-waveform) |

---

## Image Analysis (3 tools)

| Tool | Description |
|------|-------------|
| `image_extract_colors` | Extract dominant colors from an image or video frame via K-means clustering (1-20 colors) |
| `image_generate_palette` | Generate color harmony palette from an image or video frame |
| `image_analyze_product` | Analyze a product image or video frame — extract colors + optional AI description (Claude Vision) |

## Still / plate editor (5 tools)

See [STILL_PLATES.md](STILL_PLATES.md) for order-of-ops, signal LUTs, and cohesion gate policy.

| Tool | Description |
|------|-------------|
| `still_match` | Match a package of stills to a hero with one shared WB/exposure gain; receipt + no source overwrite |
| `still_grade` | Ordered grade correct→match→look; optional 3D LUT last; signal-mode near-extrema logging |
| `still_gate` | Fail-closed cohesion gate (luma spread, shadow green/cyan) + contact sheet |
| `image_edit` | Free establish-locked still edit with plan/receipt; paid gen off by default |
| `still_package` | Full package job: edit beats → match → grade → gate |