How nhatvu148/video-transcriber-mcp-rs works
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)