# kajisho5/ffmpeg-skill architecture

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

- Interactive diagram: https://gitdiagram.com/kajisho5/ffmpeg-skill
- Repository: https://github.com/kajisho5/ffmpeg-skill

## Overview

ffmpeg-skill is a local, agent-facing FFmpeg toolkit: an agent probes media, selects typed editing tools, then checks and verifies the result. The tools cover editing, captions and graphics, audio, synchronization, rendering, and delivery. Shared modules provide media probing, process execution, encoding decisions, and structured results; MCP exposes the tools, while the contract describes them. The workflow and feature links below follow README claims; source-index references support shared-module links. Unsampled tool internals are not inferred.

Main entry points: [`scripts/_common/probe.py`](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/probe.py) (Probe and measure), [`scripts/caption.py`](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/caption.py) (Captions and graphics), [`scripts/render.py`](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/render.py) (Project render), [`scripts/probe.py`](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/probe.py) (Probe media)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Agent interface"]
  node_mcp["MCP server<br/>[server.py]"]
  node_contract["Tool contract<br/>[_contract.py]"]
end

subgraph group_media["Media tools"]
  node_probe_tool["Probe media<br/>[probe.py]"]
  node_edit["Cut and join<br/>[cut.py]"]
  node_captions["Captions and graphics<br/>[caption.py]"]
  node_visual["Picture transforms<br/>[fit.py]"]
  node_audio["Audio processing<br/>[audio.py]"]
  node_sync["Sync and multicam<br/>[sync.py]"]
  node_analysis["Scene analysis<br/>[scenes.py]"]
end

subgraph group_delivery["Render and delivery"]
  node_render["Project render<br/>[render.py]"]
  node_batch["Batch folders<br/>[batch.py]"]
  node_export["Export delivery<br/>[export.py]"]
  node_check["Delivery checks<br/>[check.py]"]
  node_verify["Verify output<br/>[verify.py]"]
end

subgraph group_engine["Shared engine"]
  node_common_probe["Probe and measure<br/>[probe.py]"]
  node_decision["Encoding decisions<br/>[decision.py]"]
  node_runner["FFmpeg runner<br/>[runner.py]"]
  node_emit["Result documents<br/>[emit.py]"]
  node_asr["Local transcription<br/>[asr.py]"]
  node_timeline["Timeline helpers<br/>[timeline.py]"]
  node_text["Text and fonts<br/>[text.py]"]
  node_wrap["Caption wrapping<br/>[wrap.py]"]
  node_emoji["Emoji rendering<br/>[emoji.py]"]
  node_ass["ASS overlays<br/>[_ass_overlay.py]"]
  node_platforms["Platform profiles<br/>[_platforms.py]"]
end

node_agent(("Coding agent"))
node_ffmpeg["FFmpeg and ffprobe"]

node_agent -->|"calls tools"| node_mcp
node_agent -->|"probes media"| node_probe_tool
node_agent -->|"selects edits"| node_edit
node_agent -->|"selects captions"| node_captions
node_agent -->|"selects transforms"| node_visual
node_agent -->|"selects audio tools"| node_audio
node_agent -->|"selects sync tools"| node_sync
node_agent -->|"plans edit"| node_render
node_agent -->|"runs batch"| node_batch
node_agent -->|"checks delivery"| node_check
node_agent -->|"verifies output"| node_verify
node_mcp -->|"derives definitions"| node_contract
node_probe_tool -->|"measures media"| node_common_probe
node_edit -->|"reads probe"| node_common_probe
node_captions -->|"transcribes optionally"| node_asr
node_captions -->|"uses overlays"| node_ass
node_captions -->|"reads profiles"| node_platforms
node_captions -->|"formats text"| node_text
node_text -->|"uses wrapping"| node_wrap
node_text -->|"uses emoji"| node_emoji
node_render -->|"uses timeline"| node_timeline
node_render -->|"invokes batch"| node_batch
node_render -->|"invokes export"| node_export
node_export -->|"runs checks"| node_check
node_check -->|"reads specifications"| node_platforms
node_probe_tool -->|"uses ffprobe"| node_ffmpeg
node_edit -->|"runs FFmpeg"| node_ffmpeg
node_probe_tool -->|"emits results"| node_emit
node_common_probe -->|"runs ffprobe"| node_runner
node_runner -->|"provides execution state"| node_emit
node_decision -->|"selects encode arguments"| node_runner
node_asr -->|"runs optional engines"| node_runner
node_export -->|"uses encode choices"| node_decision
node_render -->|"absorbs stage results"| node_emit
node_analysis -->|"reads media facts"| node_common_probe
node_audio -->|"reads media facts"| node_common_probe
node_sync -->|"reads media facts"| node_common_probe

click node_mcp "https://github.com/kajisho5/ffmpeg-skill/blob/main/mcp/server.py"
click node_contract "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_contract.py"
click node_probe_tool "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/probe.py"
click node_edit "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/cut.py"
click node_captions "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/caption.py"
click node_visual "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/fit.py"
click node_audio "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/audio.py"
click node_sync "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/sync.py"
click node_analysis "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/scenes.py"
click node_render "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/render.py"
click node_batch "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/batch.py"
click node_export "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/export.py"
click node_check "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/check.py"
click node_verify "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/verify.py"
click node_common_probe "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/probe.py"
click node_decision "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/decision.py"
click node_runner "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/runner.py"
click node_emit "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/emit.py"
click node_asr "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/asr.py"
click node_timeline "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/timeline.py"
click node_text "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/text.py"
click node_wrap "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/wrap.py"
click node_emoji "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/emoji.py"
click node_ass "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_ass_overlay.py"
click node_platforms "https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_platforms.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_contract toneBlue
class node_probe_tool,node_edit,node_captions,node_visual,node_audio,node_sync,node_analysis toneAmber
class node_render,node_batch,node_export,node_check,node_verify toneMint
class node_common_probe,node_decision,node_runner,node_emit,node_asr,node_timeline,node_text,node_wrap,node_emoji,node_ass,node_platforms toneRose
class node_agent,node_ffmpeg toneIndigo
```

## Components

### Agent interface

- [MCP server](https://github.com/kajisho5/ffmpeg-skill/blob/main/mcp/server.py): `mcp/server.py`
- [Tool contract](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_contract.py): `scripts/_contract.py`

### Media tools

- [Probe media](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/probe.py): `scripts/probe.py`
- [Cut and join](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/cut.py): `scripts/cut.py`
- [Captions and graphics](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/caption.py): `scripts/caption.py`
- [Picture transforms](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/fit.py): `scripts/fit.py`
- [Audio processing](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/audio.py): `scripts/audio.py`
- [Sync and multicam](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/sync.py): `scripts/sync.py`
- [Scene analysis](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/scenes.py): `scripts/scenes.py`

### Render and delivery

- [Project render](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/render.py): `scripts/render.py`
- [Batch folders](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/batch.py): `scripts/batch.py`
- [Export delivery](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/export.py): `scripts/export.py`
- [Delivery checks](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/check.py): `scripts/check.py`
- [Verify output](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/verify.py): `scripts/verify.py`

### Shared engine

- [Probe and measure](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/probe.py): `scripts/_common/probe.py`
- [Encoding decisions](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/decision.py): `scripts/_common/decision.py`
- [FFmpeg runner](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/runner.py): `scripts/_common/runner.py`
- [Result documents](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/emit.py): `scripts/_common/emit.py`
- [Local transcription](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/asr.py): `scripts/_common/asr.py`
- [Timeline helpers](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/timeline.py): `scripts/_common/timeline.py`
- [Text and fonts](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/text.py): `scripts/_common/text.py`
- [Caption wrapping](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/wrap.py): `scripts/_common/wrap.py`
- [Emoji rendering](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_common/emoji.py): `scripts/_common/emoji.py`
- [ASS overlays](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_ass_overlay.py): `scripts/_ass_overlay.py`
- [Platform profiles](https://github.com/kajisho5/ffmpeg-skill/blob/main/scripts/_platforms.py): `scripts/_platforms.py`

### Other components

- **Coding agent**
- **FFmpeg and ffprobe**

## Connections

- Coding agent → MCP server: calls tools
- Coding agent → Probe media: probes media
- Coding agent → Cut and join: selects edits
- Coding agent → Captions and graphics: selects captions
- Coding agent → Picture transforms: selects transforms
- Coding agent → Audio processing: selects audio tools
- Coding agent → Sync and multicam: selects sync tools
- Coding agent → Project render: plans edit
- Coding agent → Batch folders: runs batch
- Coding agent → Delivery checks: checks delivery
- Coding agent → Verify output: verifies output
- MCP server → Tool contract: derives definitions (evidence: `mcp/server.py`)
- Probe media → Probe and measure: measures media
- Cut and join → Probe and measure: reads probe (evidence: `scripts/cut.py`)
- Captions and graphics → Local transcription: transcribes optionally (evidence: `scripts/caption.py`)
- Captions and graphics → ASS overlays: uses overlays (evidence: `scripts/caption.py`)
- Captions and graphics → Platform profiles: reads profiles (evidence: `scripts/caption.py`)
- Captions and graphics → Text and fonts: formats text (evidence: `scripts/_common/text.py`)
- Text and fonts → Caption wrapping: uses wrapping (evidence: `scripts/_common/text.py`)
- Text and fonts → Emoji rendering: uses emoji (evidence: `scripts/_common/text.py`)
- Project render → Timeline helpers: uses timeline (evidence: `scripts/render.py`)
- Project render → Batch folders: invokes batch (evidence: `scripts/render.py`)
- Project render → Export delivery: invokes export (evidence: `scripts/render.py`)
- Export delivery → Delivery checks: runs checks (evidence: `scripts/export.py`)
- Delivery checks → Platform profiles: reads specifications (evidence: `scripts/check.py`)
- Probe media → FFmpeg and ffprobe: uses ffprobe
- Cut and join → FFmpeg and ffprobe: runs FFmpeg
- Probe media → Result documents: emits results
- Probe and measure → FFmpeg runner: runs ffprobe (evidence: `scripts/_common/probe.py`)
- FFmpeg runner → Result documents: provides execution state (evidence: `scripts/_common/runner.py`)
- Encoding decisions → FFmpeg runner: selects encode arguments (evidence: `scripts/_common/decision.py`)
- Local transcription → FFmpeg runner: runs optional engines (evidence: `scripts/_common/asr.py`)
- Export delivery → Encoding decisions: uses encode choices (evidence: `scripts/export.py`)
- Project render → Result documents: absorbs stage results (evidence: `scripts/render.py`)
- Scene analysis → Probe and measure: reads media facts (evidence: `scripts/scenes.py`)
- Audio processing → Probe and measure: reads media facts (evidence: `scripts/audio.py`)
- Sync and multicam → Probe and measure: reads media facts (evidence: `scripts/sync.py`)
