# kyanitelabs/kinocut architecture

> Architecture diagram of the GitHub repository kyanitelabs/kinocut, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kyanitelabs/kinocut
- Repository: https://github.com/kyanitelabs/kinocut

## Overview

Kinocut is a local-first video-editing MCP server, Python client, and CLI for agent-directed editing with validation, provenance, and quality/release checks. Its primary workflow turns local interview or podcast media into captioned vertical clips for human review or publishing. The README also documents repurposing packages, podcast cuts, and agent-driven workflows. Several subsystem paths are unsampled; those capabilities are represented from the README, while edges are limited to documented relationships or source-index references.

Main entry points: [`kinocut/client/media.py`](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/client/media.py) (Python client), [`kinocut_sound/mix/static_routing.py`](https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/mix/static_routing.py) (PCM routing), [`kinocut/projectstore/ingest.py`](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/projectstore/ingest.py) (Asset ingest), [`kinocut_sound/public/mix_worker.py`](https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/public/mix_worker.py) (Sound mixing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_mcp["MCP server<br/>[server.py]"]
  node_cli["CLI runner<br/>[runner.py]"]
  node_client["Python client<br/>[media.py]"]
end

subgraph group_media["Media processing"]
  node_ingest["Asset ingest<br/>[ingest.py]"]
  node_edit["Video editing<br/>[engine.py]"]
  node_transcribe["AI transcription<br/>[transcribe.py]"]
  node_subtitles["Subtitle rendering"]
  node_shorts["Shorts packages<br/>[shorts_package.py]"]
  node_hyperframes["Hyperframes"]
  node_revideo["Revideo bridge<br/>[revideo_engine.py]"]
end

subgraph group_governance["Review and provenance"]
  node_review["Review and verdicts<br/>[review.py]"]
  node_release["Release checkpoint"]
  node_receipts["Video receipts"]
  node_projectstore[("Project store<br/>[store.py]")]
end

subgraph group_sound["Audio capabilities"]
  node_soundmix["Sound mixing<br/>[mix_worker.py]"]
  node_soundrouting["PCM routing<br/>[static_routing.py]"]
  node_soundlimits["Sound limits<br/>[limits.py]"]
  node_mixerrors["Mix errors<br/>[_errors.py]"]
  node_wav["WAV handling<br/>[_wav.py]"]
end

subgraph group_foundation["Shared foundations"]
  node_validation["Input validation<br/>[validation.py]"]
  node_ffmpeg["FFmpeg helpers<br/>[ffmpeg_helpers.py]"]
  node_runtime["Runtime utilities"]
  node_probe["Media probing<br/>[engine_probe.py]"]
  node_models["Edit models<br/>[models.py]"]
  node_defaults["Shared defaults<br/>[defaults.py]"]
  node_limits["Resource limits<br/>[limits.py]"]
  node_contracts["Record contracts<br/>[_common.py]"]
end

node_agent(("Agent or editor"))

node_agent -->|"requests edits"| node_mcp
node_agent -->|"requests edits"| node_cli
node_agent -->|"requests edits"| node_client
node_client -->|"trims media"| node_edit
node_client -->|"transcribes clip"| node_transcribe
node_client -->|"adds captions"| node_subtitles
node_client -->|"checks export"| node_release
node_edit -->|"uses FFmpeg tools"| node_ffmpeg
node_release -->|"quality gates"| node_review
node_ingest -->|"writes asset records"| node_projectstore
node_ingest -->|"uses asset contract"| node_contracts
node_contracts -.->|"supports validation"| node_validation
node_ffmpeg -->|"resolves executables"| node_runtime
node_runtime -->|"probes media"| node_probe
node_soundmix -->|"routes audio"| node_soundrouting
node_soundmix -->|"reads and writes WAV"| node_wav
node_soundrouting -->|"decodes PCM"| node_wav
node_soundrouting -->|"enforces bounds"| node_soundlimits
node_soundrouting -->|"raises mix errors"| node_mixerrors

click node_mcp "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/server.py"
click node_cli "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/cli/runner.py"
click node_client "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/client/media.py"
click node_ingest "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/projectstore/ingest.py"
click node_edit "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/engine.py"
click node_transcribe "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/ai_engine/transcribe.py"
click node_subtitles "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/engine_subtitles.py"
click node_shorts "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/product/shorts_package.py"
click node_hyperframes "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/hyperframes_engine.py"
click node_revideo "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/revideo_engine.py"
click node_review "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/aivideo/review.py"
click node_release "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/aivideo/release_surfaces.py"
click node_receipts "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/receipts_ai_video.py"
click node_projectstore "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/projectstore/store.py"
click node_soundmix "https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/public/mix_worker.py"
click node_soundrouting "https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/mix/static_routing.py"
click node_soundlimits "https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/limits.py"
click node_mixerrors "https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/mix/_errors.py"
click node_wav "https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/mix/_wav.py"
click node_validation "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/validation.py"
click node_ffmpeg "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/ffmpeg_helpers.py"
click node_runtime "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/engine_runtime_utils.py"
click node_probe "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/engine_probe.py"
click node_models "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/models.py"
click node_defaults "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/defaults.py"
click node_limits "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/limits.py"
click node_contracts "https://github.com/kyanitelabs/kinocut/blob/master/kinocut/contracts/_common.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_cli,node_client toneBlue
class node_ingest,node_edit,node_transcribe,node_subtitles,node_shorts,node_hyperframes,node_revideo toneAmber
class node_review,node_release,node_receipts,node_projectstore toneMint
class node_soundmix,node_soundrouting,node_soundlimits,node_mixerrors,node_wav toneRose
class node_validation,node_ffmpeg,node_runtime,node_probe,node_models,node_defaults,node_limits,node_contracts,node_agent toneIndigo
```

## Components

### Agent interfaces

- [MCP server](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/server.py): `kinocut/server.py`
- [CLI runner](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/cli/runner.py): `kinocut/cli/runner.py`
- [Python client](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/client/media.py): `kinocut/client/media.py`

### Media processing

- [Asset ingest](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/projectstore/ingest.py): `kinocut/projectstore/ingest.py`
- [Video editing](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/engine.py): `kinocut/engine.py`
- [AI transcription](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/ai_engine/transcribe.py): `kinocut/ai_engine/transcribe.py`
- [Subtitle rendering](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/engine_subtitles.py): `kinocut/engine_subtitles.py`
- [Shorts packages](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/product/shorts_package.py): `kinocut/product/shorts_package.py`
- [Hyperframes](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/hyperframes_engine.py): `kinocut/hyperframes_engine.py`
- [Revideo bridge](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/revideo_engine.py): `kinocut/revideo_engine.py`

### Review and provenance

- [Review and verdicts](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/aivideo/review.py): `kinocut/aivideo/review.py`
- [Release checkpoint](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/aivideo/release_surfaces.py): `kinocut/aivideo/release_surfaces.py`
- [Video receipts](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/receipts_ai_video.py): `kinocut/receipts_ai_video.py`
- [Project store](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/projectstore/store.py): `kinocut/projectstore/store.py`

### Audio capabilities

- [Sound mixing](https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/public/mix_worker.py): `kinocut_sound/public/mix_worker.py`
- [PCM routing](https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/mix/static_routing.py): `kinocut_sound/mix/static_routing.py`
- [Sound limits](https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/limits.py): `kinocut_sound/limits.py`
- [Mix errors](https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/mix/_errors.py): `kinocut_sound/mix/_errors.py`
- [WAV handling](https://github.com/kyanitelabs/kinocut/blob/master/kinocut_sound/mix/_wav.py): `kinocut_sound/mix/_wav.py`

### Shared foundations

- [Input validation](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/validation.py): `kinocut/validation.py`
- [FFmpeg helpers](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/ffmpeg_helpers.py): `kinocut/ffmpeg_helpers.py`
- [Runtime utilities](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/engine_runtime_utils.py): `kinocut/engine_runtime_utils.py`
- [Media probing](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/engine_probe.py): `kinocut/engine_probe.py`
- [Edit models](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/models.py): `kinocut/models.py`
- [Shared defaults](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/defaults.py): `kinocut/defaults.py`
- [Resource limits](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/limits.py): `kinocut/limits.py`
- [Record contracts](https://github.com/kyanitelabs/kinocut/blob/master/kinocut/contracts/_common.py): `kinocut/contracts/_common.py`

### Other components

- **Agent or editor**

## Connections

- Agent or editor → MCP server: requests edits (evidence: `README.md`)
- Agent or editor → CLI runner: requests edits (evidence: `README.md`)
- Agent or editor → Python client: requests edits (evidence: `README.md`)
- Python client → Video editing: trims media (evidence: `README.md`)
- Python client → AI transcription: transcribes clip (evidence: `README.md`)
- Python client → Subtitle rendering: adds captions (evidence: `README.md`)
- Python client → Release checkpoint: checks export (evidence: `README.md`)
- Video editing → FFmpeg helpers: uses FFmpeg tools (evidence: `README.md`)
- Release checkpoint → Review and verdicts: quality gates (evidence: `README.md`)
- Asset ingest → Project store: writes asset records (evidence: `kinocut/projectstore/ingest.py`)
- Asset ingest → Record contracts: uses asset contract (evidence: `kinocut/projectstore/ingest.py`)
- Record contracts → Input validation: supports validation
- FFmpeg helpers → Runtime utilities: resolves executables (evidence: `kinocut/ffmpeg_helpers.py`)
- Runtime utilities → Media probing: probes media (evidence: `kinocut/engine_runtime_utils.py`)
- Sound mixing → PCM routing: routes audio (evidence: `kinocut_sound/public/mix_worker.py`)
- Sound mixing → WAV handling: reads and writes WAV (evidence: `kinocut_sound/public/mix_worker.py`)
- PCM routing → WAV handling: decodes PCM (evidence: `kinocut_sound/mix/static_routing.py`)
- PCM routing → Sound limits: enforces bounds (evidence: `kinocut_sound/mix/static_routing.py`)
- PCM routing → Mix errors: raises mix errors (evidence: `kinocut_sound/mix/static_routing.py`)
