Skip to main content
Glama
Sign In
audio-story-mcp

audio-story-mcp

by cuonghv0298
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

audio-story-mcp

MCP server + plugin Claude Code: link YouTube truyện audio → chép lời → Claude đổi tên nhân vật, viết lại tình tiết → đọc bằng một giọng thuyết minh tiếng Việt (VieNeu-TTS) → story.mp3.

Tool MCP không gọi LLM — Claude Code viết lại truyện; server tải, chép lời, kiểm (sót tên cũ, % trùng bản gốc), đọc TTS và ghép. Plan: docs/plan.md · tiến độ: docs/status.md.

Cài

Cần: Claude Code · uv. ffmpeg và yt-dlp đi kèm gói Python, không cần cài hệ thống.

/plugin marketplace add https://github.com/cuonghv0298/audio-story-mcp.git
/plugin install audio-story@audio-story

Gõ /mcp → plugin:audio-story:audio-story ✔ connected (lần đầu uv cài thư viện ~30 s).

VieNeu-TTS (giọng đọc, chạy trên máy, Apache-2.0): skill tự nhắc khởi động khi cần. Chạy tay:

scripts/vieneu.sh run          # http://127.0.0.1:8165 — lần đầu cài ~1–2 phút + tải model

Đặt VIENEU_URL nếu chạy VieNeu ở máy khác (vd. máy có GPU).

Chép lời (STT) — một trong:

  • phụ đề tiếng Việt có sẵn trên video (tự dùng, miễn phí);

  • OPENAI_API_KEY (model gpt-4o-transcribe, nhanh, tốn phí);

  • whisper tại máy: uv sync --extra whisper (miễn phí, chậm trên CPU; model đặt bằng AUDIO_STORY_WHISPER_MODEL).

Related MCP server: youtube-content

Dùng

Làm truyện audio mới từ https://www.youtube.com/watch?v=…  — đổi hết tên nhân vật, viết lại tình tiết

Skill audio-story đi qua: fetch_source → transcribe → Claude viết story_bible.json, cast.json, script.json → check_script → anh duyệt script.md + nghe thử giọng → tts_render → assemble_audio → out/story.mp3.

Mọi file nằm trong thư mục run ./audio-story-runs/<slug>-<ngày>-<id>/ (đổi gốc bằng AUDIO_STORY_RUNS_DIR).

Tool MCP

Tool

Làm gì

fetch_source

Link YouTube (audio + metadata + phụ đề vi) hoặc file audio/.vtt/.srt/.txt → run mới

transcribe

captions · text · openai · whisper · auto → transcript/transcript.txt

split_chapters

Tách transcript dài theo «Chương N» → transcript/chapters/chuong-XXXX.txt

run_status · list_runs

Run đang ở bước nào

check_script

Kiểm cast.json + script.json: sót tên gốc (cả không dấu), thiếu giọng, đoạn rỗng; cảnh báo % trùng bản gốc, đoạn quá dài

list_voices · tts_preview

25 giọng VieNeu, nghe thử một câu

tts_render

Đọc từng đoạn (bỏ qua đoạn đã đọc → chạy tiếp được khi bị ngắt)

qa_audio

STT nghe lại từng đoạn, CER → đoạn cần đọc lại

assemble_audio

Ghép + khoảng nghỉ + chương → story.wav / story.mp3 (−16 LUFS)

doctor

Kiểm ffmpeg, yt-dlp, STT, VieNeu

CLI (không qua Claude — cho bước dài)

uv run audio-story doctor
uv run audio-story fetch <url|file>
uv run audio-story transcribe <run> --engine whisper
uv run audio-story chapters <run>
uv run audio-story check <run>
uv run audio-story render <run> [--limit 3]
uv run audio-story assemble <run>

Phát triển

uv sync                 # + --extra whisper nếu cần
uv run pytest           # không gọi mạng
uv run ruff check src tests
uv run python scripts/smoke_stdio.py   # gọi server qua MCP stdio thật

Mở Claude Code trong repo này là dùng được server luôn (.mcp.json ở gốc). Truyện mẫu: examples/demo/.

Available Tools

12 tools
assemble_audioA

Ghép các đoạn theo thứ tự kịch bản, chèn khoảng nghỉ pause_after_ms (+1,5 s giữa chương) → out/story.wav và out/story.mp3 (chuẩn hoá âm lượng -16 LUFS). allow_missing=true: ghép bản nháp dù còn đoạn chưa đọc.

Inputs: run (required), format, loudnorm, allow_missing. Returns: object

check_scriptA

Kiểm tất định story/cast.json + script/script.json → script/check.json, và dựng lại script/script.md để duyệt. Lỗi (chặn tts_render): schema, old_name_leak (còn tên gốc — so cả không dấu), voice_missing (chưa chọn giọng thuyết minh), empty_text. Cảnh báo: high_overlap (% cụm 6 từ trùng bản gốc > max_overlap), segment_too_long, new_name_collision, voice_unknown (khi server TTS đang chạy).

Inputs: run (required), max_overlap, max_segment_chars. Returns: object

doctorA

Kiểm môi trường: ffmpeg, yt-dlp, engine STT có sẵn, server VieNeu, thư mục run.

Inputs: no named parameters. Returns: object

fetch_sourceA

Tạo thư mục run mới từ link YouTube (tải audio + metadata + phụ đề tiếng Việt nếu có) hoặc từ file trên máy (audio .mp3/.m4a/.wav…, phụ đề .vtt/.srt, hay transcript .txt/.md). Trả run_dir để dùng cho các tool sau. with_audio=false: chỉ lấy metadata + phụ đề (nhanh, khi chắc chắn phụ đề đủ tốt).

Inputs: source (required), title, with_audio. Returns: object

list_runsB

Liệt kê các run gần nhất dưới thư mục gốc ($AUDIO_STORY_RUNS_DIR, mặc định ./audio-story-runs).

Inputs: limit. Returns: result

list_voicesA

Danh sách giọng của server VieNeu-TTS (id dùng làm narrator.voice trong cast.json) + tình trạng server.

Inputs: no named parameters. Returns: object

qa_audioB

Nghe lại các đoạn đã đọc bằng STT (openai | whisper), tính CER so với chữ đưa vào TTS → qa/report.json. Trả các đoạn CER > max_cer để sửa phát âm (pronunciation.json) rồi đọc lại.

Inputs: run (required), limit, engine, max_cer, +1 more. Returns: object

run_statusB

Trạng thái một run: nguồn, file đã có, lịch sử bước, bước kế tiếp nên làm.

Inputs: run (required). Returns: object

split_chaptersA

Tách transcript dài thành từng chương theo mốc «Chương <số>» → transcript/chapters/chuong-XXXX.txt (kèm số ký tự, mốc thời gian, ước lượng phút audio). Dùng khi truyện dài nhiều chương: đọc/viết lại từng chương thay vì cả file.

Inputs: run (required). Returns: object

transcribeA

Chuyển audio của run thành chữ → transcript/transcript.txt (bản đọc, có mốc thời gian) + transcript.json. engine: auto | captions (phụ đề YouTube) | text (file .txt có sẵn) | openai (cần OPENAI_API_KEY) | whisper (faster-whisper tại máy). Sau đó đọc transcript.txt bằng công cụ đọc file (có thể dài — đọc theo phần).

Inputs: run (required), engine, language. Returns: object

tts_previewA

Đọc thử một câu bằng một giọng → file WAV (áp pronunciation.json của run nếu có). Dùng để chọn giọng / thử cách đọc tên trước khi đọc cả truyện. Không có run thì ghi vào ./audio-story-runs/_preview/.

Inputs: text (required), voice (required), run, name. Returns: object

tts_renderA

Đọc kịch bản bằng VieNeu → audio/seg_XXXXX.wav, cả truyện một giọng thuyết minh (cast.narrator.voice). Chỉ chạy khi check_script mới nhất không còn lỗi. Đoạn đã đọc với cùng chữ + giọng thì bỏ qua → gọi lại để chạy tiếp. limit: chỉ đọc N đoạn (làm thử); segment_ids: đọc lại đúng các đoạn này; workers>1 khi server có GPU.

Inputs: run (required), force, limit, workers, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool maps to a distinct pipeline stage: setup (doctor), ingest (fetch_source), transcribe, split, inspect (run_status/list_runs), validate (check_script), preview/render TTS, QA, and assemble. The only near-neighbors—run_status vs list_runs and fetch_source vs transcribe—are clearly differentiated by scope (single run vs listing; source acquisition vs speech-to-text). No two tools appear to do the same thing.

    Naming Consistency4/5

    The set is predominantly snake_case with verb_noun naming (list_voices, split_chapters, fetch_source, check_script, tts_preview, tts_render, qa_audio, assemble_audio). Minor deviations exist: bare verbs/nouns (doctor, transcribe) and a noun-first tool (run_status), but overall it reads consistently.

    Tool Count5/5

    Twelve tools cleanly cover a multi-stage audio-story pipeline, with each tool earning its place as a discrete workflow step. The count is well-scoped—no redundant or filler tools and none obviously missing from the pipeline.

    Completeness4/5

    The surface covers the full lifecycle from ingest through transcription, chapter splitting, script validation, TTS rendering, QA, and final assembly, with a preview step for voice selection. Gaps are minor: there are no dedicated tools for building/editing cast.json, script.json, or pronunciation.json, and no run cleanup/deletion, though these can be handled via file editing.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers