Communitygithub.com

yanghhu/novel-video-voiceover

小說推文配音、有聲書配音、多角色配音技能：把小說推文文案、網文章節、故事、廣播劇劇本按旁白和角色分配不同音色，一鍵生成整段配音 WAV、帶角色名的 SRT 字幕和逐句時間軸 manifest.json，直接配畫面做小說推文影片。

novel-video-voiceover 是什麼？

「小說推文配音」是一個專為小說推文影片、有聲書配音和故事創作設計的 AI 技能。它能自動將推文文案、小說章節或劇本中的旁白與角色對話，分配給不同的音色，一次性生成完整的 WAV 音頻、帶角色名稱的 SRT 字幕，以及包含逐句時間軸的 manifest.json 檔案，方便與畫面結合進行剪輯。此技能支援在 Claude Code、Codex、OpenClaw、Cursor 和 WorkBuddy 等多種 AI Agent 上運行，無需本地 GPU，僅需 Python 3.9+ 標準庫。它透過 Miragea 的開放 API 在雲端處理音頻生成，並提供離線試跑模式（--dry-run）來驗證稿件格式。核心功能包括多角色音色分配、語氣標籤調整、語速控制（0.25–4 倍）、以及段落、場景與章節的可控停頓。對於修改需求，技能支援僅重新生成被修改的句子，並快取其他句子以避免重複計費，大幅提升效率。

相容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/yanghhu/miragea-voiceover-skills/tree/HEAD/skills/novel-video-voiceover
查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

小說推文配音

「小說推文配音」是一個把小說推文文案、網文章節和故事按旁白與角色分配不同音色、一鍵生成整段多角色 AI 配音（WAV）和帶角色名 SRT 字幕的 Agent 技能，適合小說推文影片、有聲書配音和故事號，本地無需顯示卡。

一句話定義

小說推文配音 = 推文文案 / 小說章節（旁白 + 角色，Markdown）→ 多角色整段配音 voiceover.wav + 帶角色名的字幕 voiceover.srt + 每句起止時間 manifest.json，生成在 Miragea 雲端，本地無需顯示卡。

適用人群與場景

誰在用典型場景
小說推文號每天幾條推文影片：旁白 + 角色台詞 + 豎屏字幕
故事號、睡前故事慢語速、長停頓、溫和聲線
網文作者、原創小說作者把自己的作品做成有聲版，固定旁白聲線
有聲書工作室先用 AI 做試聽樣章、角色選角小樣
廣播劇、音頻劇社團多角色對白先出 AI 版，確認節奏和分工

核心能力參數

項目說明
輸出檔案voiceover.wav（整段配音）、voiceover.srt（帶時間軸字幕）、manifest.json（每句說話人、文字、起止秒數）、lines/（每句音頻，改稿時複用）
音色來源帳號裡已有的角色 actor_id=（用 actors 查詢），或伺服器端能直接存取的參考音頻 URL ref= + 音頻裡實際說的話 ref_text=（聲音克隆）
生成模式expressive（客戶端「預設」）/ standard（客戶端「更像」）；省略時用伺服器端預設，以 capabilities 即時回傳為準
語氣標籤tags=標籤名，取 capabilities 裡所選模式的 tags[].label
語速speed= 0.25–4，1 為正常語速，按角色設定
多角色稿件開頭給每個角色定一個音色；本技能腳本逐句呼叫官方客戶端 generate，再在本地把整段拼起來
停頓行內 [pause 0.6] / [停頓 0.6]（秒）；--gap 設句間預設停頓
字幕配音時按每句實際音頻時長生成 SRT（--max-chars、--speaker-labels）；已有音頻 / 影片用 recognize 辨識為 SRT / TXT / JSON
場景預設--preset youshengshu：句間停頓 0.5 秒、每條字幕最多 20 字、字幕帶角色名；可再用 --gap / --max-chars 覆蓋
單句字數、檔案大小 / 時長上限、計費以 capabilities 即時回傳為準
本地依賴Python 3.9+ 標準庫，無需 pip 安裝、無需顯示卡
離線試跑--dry-run：不需要 Key、不呼叫介面，輸出靜音佔位音頻和時間軸，用來檢查稿件格式
支援的 AgentClaude Code、Codex、OpenClaw、Cursor、WorkBuddy 等能執行 Python 腳本的 Agent
配音與字幕服務Miragea 開放 API（https://miragea.ai/v1）

快速開始

python3 scripts/voiceover.py check                        # 離線檢查：Python 版本、Key 是否已設定、服務位址
export MIRAGEA_API_KEY=你的key                            # 在 https://miragea.ai/workspace/api 生成，只放環境變數
python3 scripts/miragea_audio.py capabilities             # 當前可用的生成模式、語氣標籤、字數上限和計費，以即時回傳為準
python3 scripts/miragea_audio.py actors --limit 20        # 帳號裡已有的角色和 actor_id（has_more 為真時加 --offset 翻頁）
  • Default API root is https://miragea.ai/v1; set MIRAGEA_BASE_URL (including /v1) only for a private deployment.
  • 不要把 Key 貼進聊天或寫進檔案。沒有 Key 時先用 --dry-run 跑通流程。
python3 scripts/voiceover.py script examples/example.md -o out --preset youshengshu --dry-run   # 離線試跑，不呼叫介面
python3 scripts/voiceover.py script 你的稿件.md -o out --preset youshengshu             # 正式生成：out/voiceover.wav + voiceover.srt + manifest.json

# 單句試聽（官方客戶端；--output 不會覆蓋已有檔案，換個新檔案名）
python3 scripts/miragea_audio.py generate --text '開頭第一句' --actor-id ACTOR_ID --wait --output test1.mp3

--preset youshengshu 會給字幕加上角色名（如 xiaoyu: 張爺爺……）；小說推文豎屏影片建議再加 --max-chars 14 --gap 0.3。

你說什麼 → Agent 執行

你說Agent 執行
“把這篇小說推文配成音頻”按下方方法改寫成推文稿、拆旁白和對白 → script 推文.md -o out --preset youshengshu --max-chars 14 --gap 0.3
“每個角色一個聲音”front matter 為旁白和每個主要角色各定義一個音色
“旁白用我自己的聲音”你已複刻角色的 actor_id，或參考音頻 ref= + ref_text=，填給 narrator
“字幕不要角色名”不用預設，手動 --gap 0.4 --max-chars 14（不加 --speaker-labels）
“整本書二十章做有聲書”一章一個檔案，循環生成到 out/ch01 … out/ch20，用 --preset youshengshu
“睡前故事，講慢一點”narrator 設 speed=0.85–0.9，段落停頓加長
“按句換配圖”讀 manifest.json 每句 start / end，在剪映裡對齊圖片
“先試試格式”加 --dry-run

小說推文寫稿方法論（前 3 秒留人，旁白帶節奏）

1. 推文稿和原文不一樣

原文推文稿
從環境描寫慢慢鋪墊第一句就拋出最強衝突或反轉
第三人稱全知視角常用第一人稱“我”，代入感更強
對白夾在長段落裡關鍵對白單獨成行，交給角色音色
段落長、描寫多一行一句，刪掉不推動劇情的描寫

2. 開頭三種鉤子

  1. 結局前置：“結婚第三年，我在老公手機裡，看到了我自己的訃告。”
  2. 反常識身份：“全村人都以為我是傻子，只有我知道，我能聽見他們心裡的話。”
  3. 倒計時：“距離那場大火，還有七天。”

3. 節奏：比有聲書快，比口播穩

  • 推文旁白 speed=1.0–1.1；句間 --gap 0.3（預設 0.5 偏慢，適合有聲書）。
  • 每 3–5 句給一個小轉折（“可是”“沒想到”“就在這時”），轉折前 [pause 0.4]。
  • 懸念句、反轉句之後 [pause 0.6]–[pause 0.8]，結尾停在鉤子上引導看下一集。

有聲書寫稿方法論（把“讀小說”變成“演小說”）

1. 先做選角表

角色定位音色建議speed
narrator（旁白）貫穿全書，最重要穩定、溫和、耐聽0.9–1.0
主角出場最多與旁白明顯區分（性別或年齡）1.0
重要配角每人一個音色與主角拉開差異按性格
次要角色出場少可以共用一個“路人”音色1.0

選角表寫進每章稿件的 front matter，整本書保持一致。角色太多時，只給有台詞份量的角色單獨音色。

2. 對白拆分規則

原文：小雨拉住他的衣角，小聲問：“張爺爺，燈塔裡是不是有人？”

拆成：

[narrator] 小雨拉住他的衣角，小聲問：
[xiaoyu]：張爺爺，燈塔裡是不是有人？
  • 引號裡的話交給角色；引號外的動作描寫留給旁白。
  • “他說”“她笑著說”這類提示語，如果角色音色已經能分辨是誰，可以刪掉，節奏更緊湊。
  • 一個段落裡有多句對白時，每句單獨一行，各自加標籤。

3. 三級停頓：段落、場景、章節

位置寫法作用
句與句之間預設自動 0.5 秒朗讀呼吸感
段落之間[pause 0.8]段落切換
場景 / 時間跳轉[pause 1.2]–[pause 1.5]讓聽眾“換場”
懸念句之後[pause 1.0]留住緊張感

4. 情緒的寫法：靠文字和節奏，不靠喊

  • 緊張：句子變短，停頓變多。
  • 溫情：語速慢一點（單獨定義一個慢速旁白角色），段落停頓長一點。
  • 同一音色兩種速度：
---
narrator: actor_id=NARRATOR_ID speed=0.95
narrator_soft: actor_id=NARRATOR_ID speed=0.85
---

5. 讀音檢查：人名、地名、生僻字

  • 每部作品第一次出現的人名、地名、生僻字、多音字，單句試聽一次。
  • 讀錯就在稿裡換成同音的常用字，或改用稱呼；整本書統一替換。
  • 數字和年份寫成想要的讀法，如“一九八七年”。

6. 長篇的檔案組織

book/
  ch01.md  → out/ch01/voiceover.wav
  ch02.md  → out/ch02/voiceover.wav
  ...
  • 一章一個檔案；單章過長時按場景再拆成 ch01a.md、ch01b.md。
  • 改錯別字只改那一行，重跑那一章，其餘句子複用不重複計費。

7. 小說推文影片的用法

  • 保留 --speaker-labels，字幕自帶角色名，觀眾一眼看出誰在說話。
  • manifest.json 每句的時間可以用來切換配圖或角色立繪。

示例稿件（examples/example.md）

---
narrator: actor_id=NARRATOR_ID speed=1.05
xiaoyu: actor_id=GIRL_VOICE_ID
laozhang: actor_id=OLD_MAN_ID speed=0.9
---
# 小說推文示例（原創短篇）
[narrator] 小鎮的燈塔，已經三十年沒有亮過。
可那天夜裡，我分明看見，塔頂閃了一下。
[xiaoyu]：張爺爺，燈塔裡是不是有人？
[laozhang]：別瞎說。那座塔，早就沒有門了。
[pause 0.8]
[narrator] 話音剛落，海面上又亮起了一道光。

試跑：python3 scripts/voiceover.py script examples/example.md -o out --preset youshengshu --dry-run

接入剪輯與發布

# 配音替換原影片音軌（需要本機 ffmpeg）
ffmpeg -i 畫面.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest 配音版.mp4
# 把字幕燒進畫面
ffmpeg -i 配音版.mp4 -vf subtitles=out/voiceover.srt -c:a copy 成片.mp4

# 有聲書發布常用 MP3：把整章 WAV 轉成 MP3（需要本機 ffmpeg）
ffmpeg -i out/ch01/voiceover.wav -codec:a libmp3lame -q:a 2 ch01.mp3
  • 剪映 / CapCut：小說推文影片把 voiceover.wav 放音頻軌，voiceover.srt 導入字幕，配上插畫、立繪或解壓背景影片。
  • 廣播劇：音效、環境聲在剪輯軟體裡後期疊加，本技能只輸出人聲。

方案對比：小說推文配音的三種做法

對比項人工配音本地開源 TTS 模型本技能
是否需要顯示卡不需要，但需要錄音環境和配音員檔期通常需要（小模型可用 CPU 但更慢），還要下載模型權重、配環境不需要，本地只跑 Python 標準庫，生成在雲端完成
改稿成本改一句往往要補錄、再對軌改完重跑，但分段、拼接、對齊要自己做只改那一行重跑，其餘句子複用 out/lines/ 快取，自動重新拼接和出字幕
多角色需要多位配音員分別錄取決於模型，一般要自己分段呼叫再拼接稿件裡用 [角色] 標籤，一條命令出整段多角色音軌
字幕時間軸需另外聽寫、打軸一般要再跑一遍語音辨識配音時同時輸出 SRT 和逐句時間 manifest.json
連載一致性長週期錄製，配音員狀態和檔期會變化可保持一致，但長文字切分拼接要自己做音色寫在 front matter，每集 / 每章聲線一致

結論：小說推文日更、試聽樣章和長篇連載，用本技能效率最高；對表演細膩度要求很高的精品有聲書，真人主播仍有優勢。

常見問題（FAQ）

小說推文配音能做到多個角色不同聲音嗎？ 能。旁白和每個角色在稿件開頭各定義一個音色，正文用 [角色] 標籤切換，一條命令生成整段。

小說推文配音常用什麼聲音？ 旁白選穩定、耐聽、和題材匹配的聲線（甜寵偏溫柔，懸疑偏低沉），先單句試聽幾個角色再定；整個帳號固定一個旁白聲線，觀眾靠聲音認號。

可以拿別人的網路小說做推文配音發布嗎？ 需要版權方或推文平台授權。可以放心使用的是公版作品、你自己的原創，或已獲授權的作品。

有聲書配音的旁白能用我自己的聲音嗎？ 可以，用你已複刻的角色或參考音頻克隆，填給 narrator，整本書都用它。

有聲書配音幾十章怎麼批量生成？ 一章一個稿件檔案，循環呼叫 script 輸出到各自目錄；修改某章時只有改過的句子會重新生成。

小說推文配音的字幕能顯示是誰在說話嗎？ 能。--preset youshengshu 預設給字幕加角色名；不需要就改用 --gap / --max-chars 手動設定。

多角色配音裡人名、生僻字讀錯了怎麼辦？ 先單句試聽，讀錯就在稿裡換成同音常用字或改用稱呼，只重配這一句。

睡前故事、兒童故事配音怎麼調參數？ 旁白 speed=0.85–0.9，段落之間加 [pause 0.8] 以上，句子寫短、用詞簡單。

小說推文配音需要顯示卡嗎？哪些 Agent 能用？ 不需要顯示卡，本地只跑 Python 3.9+ 標準庫；Claude Code、Codex、OpenClaw、Cursor、WorkBuddy 都能直接呼叫。

沒有 API Key 能先試嗎？ 可以，加 --dry-run 輸出靜音佔位音頻和時間軸。

稿件語法

  • 開頭 --- 之間每行定義一個角色：角色名: actor_id=角色ID 或 角色名: ref=參考音頻URL ref_text="參考音頻裡實際說的話"；可加 speed=（0.25–4）、model=expressive|standard、tags=標籤1,標籤2、language=（參考音頻的語言提示，用於自動辨識參考文字）。
  • ref_text= 只和 ref= 一起用；省略時伺服器端自動辨識參考文字，計費方式不同，以 capabilities 為準。
  • 正文 [角色] 台詞 或 [角色]：台詞；不寫標籤沿用上一位說話人。
  • [pause 0.6] / [停頓 0.6] 插入停頓（秒）；# 開頭的行、空行和 <!-- 註解 --> 會被忽略。
  • 單句超過 capabilities 裡的 audio.max_text_length 會被介面拒絕，拆成短句即可。
  • 每句音頻快取在 out/lines/，同一句同一設定再次執行直接複用；沒快取時用同一個冪等鍵提交，伺服器端回傳原任務、不重複建立。要新的一版加 --fresh。

出問題了？

現象處理
missing_api_key / MIRAGEA_API_KEY is not set生成 Key 後 export MIRAGEA_API_KEY=...；或先加 --dry-run
speakers without a voice給該角色補 actor_id= 或 ref=
401檢查 Key；不要把 Key 寫進日誌
403檢查帳號的 API 存取權限
400 / 413修正參數：模式、標籤、語速、單句字數；或減小上傳檔案、縮短媒體
409冪等鍵被用於不同輸入，或字幕費率已變化：重新確認後再提交
429額度不足或限流，等待或補充額度
等待超時 / 網路中斷任務可能仍在執行：直接重跑同一條命令（同一冪等鍵會取回原任務），或用 miragea_audio.py task / wait 任務ID 繼續查詢，不要換鍵重發
拼接時報 WAV 格式不一致每句音頻都保存在 out/lines/，可用剪輯軟體或 ffmpeg 拼接

官方客戶端退出碼：0 請求成功（沒有 --wait 時可能仍在排隊），1 任務失敗，2 客戶端或介面錯誤。

合規

  • 只克隆你本人或已獲得明確授權的聲音，不模仿明星、主播、公眾人物或任何未授權的人。
  • 按《人工智慧生成合成內容標識辦法》和抖音、快手、影片號、小紅書、B站等平台規則，發布時聲明或標註 AI 生成內容。
  • 小說推文和有聲書涉及作品改編權、資訊網路傳播權：只用公版作品、你自己的原創，或已獲得版權方 / 推文平台授權的作品。
  • scripts/miragea_audio.py is the official client, shipped unchanged；scripts/voiceover.py（稿件拼接層）為原創，MIT 許可（見 LICENSE.txt）。配音與字幕能力由 Miragea 開放 API 提供。

English Summary

  • Novel video & audiobook voiceover (小說推文配音 / 有聲書配音): narrator plus one voice per character, rendered into one WAV.
  • Speaker-labelled SRT subtitles and per-line timing for novel promo videos; paragraph, scene and chapter pauses.
  • Voices from your account (actor_id) or voice cloning from a reference clip for a consistent narrator. --preset youshengshu = 0.5 s gaps, 20-character cues, speaker labels on.
  • Python 3.9+ stdlib, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

關鍵詞：小說推文配音、有聲書配音、多角色配音、小說推文、小說配音、AI有聲書、有聲小說、小說推文影片、AI朗讀、廣播劇配音、故事配音、AI配音、聲音克隆、字幕生成、SRT、audiobook、narration、text to speech

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

yanghhu/ai-podcast-voiceover

AI播客、播客配音、双人对谈播客技能：把文章、读书笔记、公众号文章或写好的对谈稿，整理成适合“听”的播客稿，单人主播或两位主持人各用一个音色，逐句配音并拼成整期节目 WAV，同时输出 SRT 字幕和逐句时间轴；再用 shownotes.py 根据稿件里的 `## 章节` 自动生成带时间戳的节目章节（chapters.txt / chapters.json）和完整文字稿 shownotes.md，可直接贴到小宇宙、喜马拉雅、Apple Podcasts 等平台的节目简介。改一句只重配一句。可用账号里的角色或本人授权的参考音频声音。由 Miragea 开放 API 生成语音，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑；计费与限额以 capabilities 实时返回为准。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。AI podcast, podcast voiceover, two-host dialogue, show notes, chapters.

yanghhu/miragea-video-voiceover

AI配音、视频配音、文字转语音（TTS）、声音克隆与字幕生成技能：把口播稿、电影解说稿、小说推文、广告脚本、带货文案、有声书章节写成带 [角色] 标签的稿件，一条命令生成多角色配音 WAV、带时间轴的 SRT 字幕和逐句时间 manifest.json，直接导入剪映 / CapCut / Premiere / ffmpeg。音色可用账号已有角色，也可用参考音频 + 对应文本做声音克隆；支持语气标签、0.25–4 倍语速、停顿控制；已有音频 / 视频可识别成 SRT / TXT / JSON 字幕。内置口播、解说、带货、数字人、广告片、有声书 6 个节奏预设；改一句只重配一句。配音与字幕由 Miragea 开放 API 生成，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。AI voiceover, text to speech, voice cloning, multi-speaker dubbing and SRT subtitles.

相關技能

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community