# nhatvu148/video-transcriber-mcp-rs architecture

> Architecture diagram of the GitHub repository nhatvu148/video-transcriber-mcp-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nhatvu148/video-transcriber-mcp-rs
- Repository: https://github.com/nhatvu148/video-transcriber-mcp-rs

## Overview

##### Project Type and Purpose
- This is a command-line + MCP (Model Context Protocol) server written in Rust. Its primary purpose is to provide high-performance, offline video transcription via whisper.cpp bindings, using yt-dlp to fetch videos and FFmpeg to extract audio.
- It can be invoked directly as a CLI for local transcription or registered as an MCP server for Claude Code (an LLM client), exposing a simple RPC interface for transcription requests.

##### File Structure Analysis
- Top-level files:
- Cargo.toml, src/main.rs – Rust project entrypoint and metadata
- Dockerfile, install.sh, Taskfile.yml – deployment, automation, and CI
- scripts/download-models.sh – external model download
- src/ directory broken into three logical areas:
- mcp/ – implements the MCP server interface (server.rs, server_rmcp.rs, types.rs)
- transcriber/ – core transcription logic
– downloader.rs: wraps yt-dlp
– audio.rs: wraps FFmpeg
– whisper.rs: whisper.cpp integration via Rust bindings
– engine.rs: orchestrates download, audio processing, model inference
- utils/ – shared utilities, e.g., file-path management
- Configuration files (Taskfile.yml, Dockerfile) and scripts indicate deployment targets and external dependencies (yt-dlp, ffmpeg, cmake).

##### README Insights
- Describes the overall architecture: CLI + MCP server, offline transcription, multi-platform support, multiple model sizes, environment variable configuration.
- Highlights key dependencies and performance characteristics.
- Lists supported commands, deployment options, and integration steps for Claude Code.

##### Key Components to Model
a. Frontend / Client Layer
– CLI interface (main.rs)
– MCP RPC consumer (e.g., Claude Code via stdio/JSON-RPC)
b. MCP Server Layer
– server.rs / server_rmcp.rs: accepts incoming transcription requests, routes to engine
– types.rs: defines request/response payloads
c. Transcription Engine
– Downloader (yt-dlp wrapper)
– Audio Processor (FFmpeg wrapper)
– Model Inference (whisper.cpp bindings)
– Orchestrator (engine.rs) that sequences all steps
d. Data Storage & Caching
– Local model cache (~/.cache/video-transcriber-mcp/models)
– Output directory for transcripts (env-configured TRANSCRIPTS_DIR)
e. External Dependencies
– yt-dlp CLI
– FFmpeg CLI
– whisper.cpp C++ library
f. Utilities
– Path resolution (utils/paths.rs)
– Logging configuration (env RUST_LOG)

##### Relationships and Data Flow
- User/Client issues a “transcribe” command or MCP RPC call → MCP Server receives request → Transcription Engine:
1. Downloader fetches video URL → passes raw video file
2. Audio Processor extracts audio stream → passes audio buffer
3. Model Loader ensures required whisper model is present
4. whisper.cpp inference produces transcript segments
5. Engine aggregates segments into final format
- Engine outputs results to file system and returns JSON/Markdown/TXT via MCP response or CLI stdout.

##### Architectural Patterns and Principles
- Modular layering: clear separation between protocol interface (MCP), core logic (transcriber), and low-level utilities.
- Single responsibility: each module handles one piece (downloading, audio, inference).
- Dependency injection via environment and command-line args for model paths and logging.
- Offline-first design: no external online APIs required beyond video fetching.

##### Technologies and Frameworks
- Rust (1.85+), Cargo
- whisper.cpp (C++), whisper-rs bindings
- yt-dlp, FFmpeg CLIs
- JSON-RPC or MCP protocol over stdio (Model Context Protocol)
- Task for automation (Taskfile.yml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Protocol Layer
    subgraph "Protocol Layer"
        style PL fill:#d4f8d4,stroke:#2ecc71,stroke-width:2px
        CLI["CLI Interface"]:::protocol
        RPCConsumer["MCP RPC Consumer"]:::protocol
        MCPServer["MCP Server"]:::protocol
        RMCPServer["MCP RMCP Server"]:::protocol
        TypesRPC["MCP Request/Response Types"]:::protocol
    end

    %% Transcription Pipeline
    subgraph "Transcription Pipeline"
        style TP fill:#d0e7f9,stroke:#3498db,stroke-width:2px
        Engine["Engine Orchestrator"]:::pipeline
        Downloader["Downloader (yt-dlp)"]:::pipeline
        AudioProc["Audio Processor (FFmpeg)"]:::pipeline
        Inference["Model Inference (whisper.cpp)"]:::pipeline
        TypesTrans["Transcriber Shared Types"]:::pipeline
        TransMod["Transcriber Module Entry"]:::pipeline
    end

    %% External Services & Libraries
    subgraph "External Services & Libraries"
        style EL fill:#fce8c3,stroke:#e67e22,stroke-width:2px
        YTDLP["yt-dlp CLI"]:::external
        FFMPEG["FFmpeg CLI"]:::external
        CPP["whisper.cpp Library"]:::external
    end

    %% File System & Cache
    subgraph "File System & Cache"
        style FS fill:#ececec,stroke:#7f8c8d,stroke-width:2px
        Cache["Model Cache"]:::storage
        Transcripts["Transcripts Directory"]:::storage
    end

    %% Configuration & CI
    subgraph "Configuration & CI"
        style CI fill:#f3e5f5,stroke:#9b59b6,stroke-width:2px
        Scripts["Model Download Script"]:::config
        Tasks["Automation & CI Taskfile"]:::config
        DockerConf["Docker Deployment Config"]:::config
        Cargo["Project Metadata"]:::config
        ReleaseCI["Release CI Workflow"]:::config
    end

    %% Data Flow
    CLI -->|"transcribe cmd"| Engine
    RPCConsumer -->|"JSON-RPC"| MCPServer
    MCPServer -->|"RPC call"| Engine
    RMCPServer -->|"RMCP call"| Engine
    TypesRPC --> MCPServer

    Engine -->|"fetch URL"| Downloader
    Downloader -->|"video file"| AudioProc
    AudioProc -->|"audio buffer"| Inference
    Inference -->|"segments"| Engine
    TypesTrans --> Engine
    TransMod --> Engine

    Engine -->|"save transcript"| Transcripts
    Engine -->|"load model"| Cache

    Downloader --- YTDLP
    AudioProc --- FFMPEG
    Inference --- CPP

    Scripts --> Cache
    Tasks --> DockerConf
    Tasks --> Cargo
    ReleaseCI --> DockerConf

    %% Click Events
    click CLI "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/main.rs"
    click RPCConsumer "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/mcp/mod.rs"
    click MCPServer "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/mcp/server.rs"
    click RMCPServer "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/mcp/server_rmcp.rs"
    click TypesRPC "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/mcp/types.rs"
    click Engine "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/transcriber/engine.rs"
    click Downloader "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/transcriber/downloader.rs"
    click AudioProc "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/transcriber/audio.rs"
    click Inference "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/transcriber/whisper.rs"
    click TypesTrans "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/transcriber/types.rs"
    click TransMod "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/src/transcriber/mod.rs"
    click Scripts "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/scripts/download-models.sh"
    click Tasks "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/Taskfile.yml"
    click DockerConf "https://github.com/nhatvu148/video-transcriber-mcp-rs/tree/main/Dockerfile"
    click Cargo "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/Cargo.toml"
    click ReleaseCI "https://github.com/nhatvu148/video-transcriber-mcp-rs/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef protocol fill:#d4f8d4,stroke:#2ecc71,color:#2c3e50
    classDef pipeline fill:#d0e7f9,stroke:#3498db,color:#2c3e50
    classDef external fill:#fce8c3,stroke:#e67e22,color:#2c3e50
    classDef storage fill:#ececec,stroke:#7f8c8d,color:#2c3e50
    classDef config fill:#f3e5f5,stroke:#9b59b6,color:#2c3e50
```
