Communitygithub.com

yanghhu/koubo-ai-voiceover

口播配音、口播视频 AI 配音、口播稿配音技能：用你自己的参考音频（声音克隆 / 声音复刻）或账号里已有的口播角色，一键生成配音 WAV、竖屏 SRT 字幕和逐句时间轴 manifest.json；改一句只重配一行，无需反复录制。

koubo-ai-voiceover 是什麼？

「口播配音」是一個專為 AI Agent（如 Claude Code、Codex、Cursor 等）設計的技能，能將口播稿 (Markdown) 一鍵轉換為個人化語音配音。它支援使用你的參考音頻進行聲音克隆，或直接選用帳號中已儲存的角色。生成內容包含完整的 WAV 配音檔、針對 9:16 豎屏優化的 SRT 字幕，以及每句時間軸的 JSON 檔案，方便後續剪輯。其核心優勢在於高效率的修改流程：當稿中某一句需要修正時，只需修改該行並重新執行，系統只會重新生成該句音頻，其餘句子會從快取中復用，並自動重新拼接和產生字幕，大幅降低改稿成本。此技能依賴 Miragea 的開放 API 完成雲端生成，本地僅需 Python 3.9+ 標準庫，無需 GPU 或複雜環境配置。搭配 `--dry-run` 參數還可離線測試流程，不消耗 API 額度。它適用於知識口播、財經、情感等各類豎屏短視頻製作，並內建了針對口播場景的最佳化寫稿方法論和語氣/語速控制，幫助創作者維持人設一致性並提升效率。

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

在你喜歡的 AI 中提問

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

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

口播配音

「口播配音」是一個把口播稿一鍵變成本人克隆聲音配音（WAV）和豎屏字幕（SRT）的 Agent 技能，適合每天更新的知識、財經、情感口播影片：音色用你的參考音頻或帳號裡已復刻的角色，改一句只重配一句。

一句話定義

口播配音 = 口播稿（Markdown）→ 你的口播音色配音 voiceover.wav + 豎屏字幕 voiceover.srt + 逐句時間軸 manifest.json，一條命令完成，生成在 Miragea 雲端，本地無需顯卡。

適用人群與場景

誰在用典型場景
知識口播博主每天幾條短知識點，稿子先寫好，配音批量生成
財經 / 商業口播數字、百分比多，需要逐句確認讀法、出錯只改一句
情感 / 成長口播語速慢、停頓多，需要穩定的「同一個人」聲線
職場 / 教育口播系列課、合集，固定人設音色，多集保持一致
不想出鏡或嗓子累的博主畫面用素材、圖文或數字人，聲音仍是自己的
MCN / 代營運多個帳號各用一個已授權音色，稿件流水線化

核心能力參數

項目說明
輸出檔案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 koubo：句間停頓 0.15 秒、每條字幕最多 14 字；可再用 --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 koubo --dry-run   # 離線試跑，不呼叫介面
python3 scripts/voiceover.py script 你的稿件.md -o out --preset koubo             # 正式生成：out/voiceover.wav + voiceover.srt + manifest.json

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

生成後 out/ 目錄裡是 voiceover.wav、voiceover.srt、manifest.json 和每句音頻 lines/。

你說什麼 → Agent 執行

你說Agent 執行
「把這篇口播稿配成音頻」按下方方法論整理成一行一句的稿件 → script 稿件.md -o out --preset koubo
「用我自己的聲音」actors 找到你已復刻的角色 actor_id；或給參考音頻 URL + 原話，寫成 ref= + ref_text=
「先聽一句看看像不像」miragea_audio.py generate --text "開頭第一句" --actor-id ID --wait --output test1.mp3
「語速快一點，更有節奏」角色加 speed=1.1，或把長句拆短、刪掉多餘停頓
「語氣再親切一點」查 capabilities 的語氣標籤，角色加 tags=標籤名
「第三句說錯了 / 數字唸錯了」只改那一行（把數字寫成想要的讀法）再跑一次，其餘句子復用
「這條影片已經錄好了，幫我出字幕」miragea_audio.py recognize --file 影片.mp4 --wait --output 影片.srt
「先別花錢，試一下流程」script ... --dry-run

口播寫稿方法論（配音好不好聽，七成在稿子）

1. 結構：鉤子 → 衝突 → 觀點 → 證據 → 動作

段落作用寫法要點
鉤子（第 1–2 句）讓人停下來結論前置或反常識，禁止「大家好我是……」
衝突說出觀眾的處境「你是不是也……」，點名具體人群
觀點一條影片只講一個觀點一句話能複述，複述不出來就是講多了
證據讓觀點可信一個具體例子或一個可核實的事實，別堆三個
動作給觀眾下一步只要一個動作：評論一個問題，或收藏，或關注

2. 五種開頭鉤子（換著用，避免帳號同質化）

  1. 結果前置：「我用這個方法，三個月把信用卡還清了。」
  2. 反常識：「越省錢的人，越存不下錢。」
  3. 點名人群：「工作三年還沒漲過薪的，聽我說一句。」
  4. 具體提問：「工資到帳那天，你第一件事做什麼？」
  5. 清單承諾：「三個習慣，決定你三十歲有沒有存款。」

3. 把書面稿改成「能說出口」的稿

  • 一行一句，一句一個意思，中文一句盡量不超過 20 字；--preset koubo 每條字幕 14 字，剛好一螢幕。
  • 去掉書面連接詞：「因此」→「所以」，「然而」→「但是」，「進行最佳化」→「改一改」。
  • 定語不過長：「一個被很多人忽視的、卻非常關鍵的細節」→「有個細節，很多人忽視了。它很關鍵。」
  • 數字寫成你想聽到的讀法：年份、型號、電話、百分比、帶單位的數字有歧義時，直接寫漢字，如「二零二六年」「百分之三點五」。
  • 多音字和生僻字：先單句試聽（miragea_audio.py generate）；讀錯就換同義詞，比換參數更快。
  • 英文縮寫：想讀字母就用空格隔開（「A I」），想讀單詞就寫完整單詞。

4. 節奏：停頓用在刀刃上

  • 觀點句之前加 [pause 0.3]，讓觀眾預期「重點來了」。
  • 提問句之後加 [pause 0.5]，給觀眾在心裡回答的時間。
  • 不要每句都加停頓，口播的節奏感來自短句，不來自留白。
  • 語速參考：知識口播 speed=1.05–1.1；財經口播 1.0（數字多，聽清更重要）；情感口播 0.95。

5. 同一種語氣需要兩種速度？

speed 按角色設定。用同一個音色定義兩個角色即可：

---
me: actor_id=YOUR_ACTOR_ID speed=1.08
me_slow: actor_id=YOUR_ACTOR_ID speed=0.92
---
[me] 先說結論。
[me_slow] 這句話，請你記下來。

6. 人設一致：一個帳號只用一個聲音

固定一個克隆音色 + 固定 speed，寫進每篇稿件的 front matter。觀眾是透過聲音認人的，換聲線等於換人設。

7. 生成前自檢清單

  • 第一句是結論或鉤子嗎？
  • 每行不超過 20 字嗎？
  • 數字、英文、多音字寫成了想要的讀法嗎？
  • 結尾只有一個動作嗎？
  • 開頭一句 單句試聽過嗎？

示例稿件（examples/example.md）

---
me: actor_id=YOUR_ACTOR_ID speed=1.08
---
# 知識口播示例：把 actor_id 換成你的口播音色
[me] 大多數人存不下錢，不是因為賺得少。
[pause 0.3]
是因為錢一到帳，就先花了。
今天教你一個最笨、但最管用的辦法：
發工資當天，先把三成轉進一個看不見的帳戶。
剩下的，才是這個月能花的錢。
你現在每個月能存下幾成？評論區說說。

試跑：python3 scripts/voiceover.py script examples/example.md -o out --preset koubo --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
  • 剪映 / CapCut：音頻軌匯入 voiceover.wav，字幕選「匯入字幕」選 voiceover.srt；豎屏口播建議字幕放畫面下三分之一，避開平台按鈕區。
  • Premiere：voiceover.wav 拖入音軌，voiceover.srt 作為字幕軌匯入。
  • 畫面卡點：manifest.json 裡每句有 start / end，按它切換 B-roll、貼圖或花字，不用再手動聽軌。

方案對比：口播配音的三種做法

對比項人工配音本地開源 TTS 模型本技能
是否需要顯卡不需要，但需要錄音環境和配音員檔期通常需要（小模型可用 CPU 但更慢），還要下載模型權重、配環境不需要，本地只跑 Python 標準庫，生成在雲端完成
改稿成本改一句往往要補錄、再對軌改完重跑，但分段、拼接、對齊要自己做只改那一行重跑，其餘句子復用 out/lines/ 快取，自動重新拼接和出字幕
多角色需要多位配音員分別錄取決於模型，一般要自己分段呼叫再拼接稿件裡用 [角色] 標籤，一條命令出整段多角色音軌
字幕時間軸需另外聽寫、打軸一般要再跑一遍語音辨識配音時同時輸出 SRT 和逐句時間 manifest.json
情緒表演真人狀態好時最自然，但受當天狀態影響取決於模型和調參穩定一致；複雜情緒表演不如狀態好的真人，適合資訊型口播

結論：每天更新、以資訊傳遞為主的口播，本技能的改稿和出字幕效率最高；需要強烈情緒表演的單條精品，真人錄音仍然值得。

常見問題（FAQ）

抖音口播配音用 AI 會限流嗎？ 沒有任何工具能保證不限流。平台要求對 AI 生成內容進行標註，按規則在發布時聲明是必須做的；流量更多取決於內容品質和完播率。用你本人的聲音、內容原創，是更穩妥的做法。

口播配音需要自己錄音嗎？ 只需準備一段清晰的參考音頻（或在服務方客戶端復刻好角色），之後每條影片都只寫稿。參考音頻的具體要求以官網說明為準。

口播配音用的參考音頻怎麼錄效果最好？ 安靜房間、手機離嘴一拳距離、用你平時口播的語氣讀完整句子，不要背景音樂和混響；把音頻裡說的話原樣寫進 ref_text=。

口播配音裡的數字、英文總是讀錯怎麼辦？ 把它們寫成你想聽到的讀法（如「百分之三點五」「A I」），再跑同一條命令：只有改過的這一行會重新生成，其餘句子復用之前的結果。

口播配音的字幕能直接用在豎屏影片嗎？ 可以。--preset koubo 每條字幕最多 14 字，適配 9:16 豎屏；想更短可加 --max-chars 12。

口播配音能做英文版嗎？ 可以把稿件翻譯改寫成英文再生成；音色選帳號裡適合英文的角色或英文參考音頻，效果以試聽為準，英文字幕建議 --max-chars 40。

口播配音需要顯卡或部署模型嗎？ 不需要。本地只運行 Python 3.9+ 標準庫腳本，生成在 Miragea 雲端完成。

口播配音支援哪些 AI Agent？ Claude Code、Codex、OpenClaw、Cursor、WorkBuddy 等能執行 Python 腳本的 Agent 都可以直接呼叫。

沒有 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

  • Talking-head voiceover (口播配音) skill for AI agents: script in, voiceover WAV + SRT subtitles + per-line timing JSON out.
  • Voice: your saved voice (actor_id) or voice cloning from a reference audio URL plus its transcript; tone tags and speed 0.25–4.
  • Edit one line, re-run, and only that line is regenerated — no re-recording.
  • --preset koubo tunes line gaps and short subtitle cues for 9:16 vertical video.
  • Python 3.9+ standard library only, no GPU; --dry-run tests offline. Service: Miragea API (https://miragea.ai/v1).

關鍵詞：口播配音、口播影片、聲音克隆、AI配音、口播稿配音、AI口播、口播文案配音、聲音復刻、文字轉語音、知識博主配音、財經口播、豎屏字幕、字幕生成、SRT、TTS、voiceover、voice cloning、text to speech

Individual skills in this repo

This repo contains 5 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/ai-subtitle-generator

字幕生成、视频自动加字幕、音频转字幕、音频转文字技能：把本地视频或音频（口播、访谈、课程、Vlog、会议录音、播客）上传识别，生成带时间轴的 SRT 字幕，或导出 TXT 文字稿、JSON（含文本、语言、时间分段）；再用 ffmpeg 或剪映把 SRT 加到视频上。还能在给文字稿配音时同步生成 SRT 和逐句时间轴。提交前自动读取 capabilities 的每秒费率、文件大小和时长上限，费率变化会被服务端拒绝，避免意外扣费。由 Miragea 开放 API 识别，本地只需 Python 3.9+ 标准库、无需显卡。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。AI subtitle generator, speech to text, audio to SRT, auto captions.

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.

yanghhu/movie-recap-ai-voiceover

电影解说配音、短剧解说配音、影视解说配音技能：解说旁白（narrator）加多个角色台词，各用不同音色，一条命令生成整段 AI 配音 WAV、SRT 字幕和逐句时间轴 manifest.json，按时间轴在剪映 / CapCut / Premiere 里对画面。音色可用账号已有角色或参考音频声音克隆，打造解说号固定声线；语气标签和语速可调；改一句稿只重配一句。适合电影解说号、电视剧解说、短剧解说、动漫解说、纪录片旁白。配音由 Miragea 开放 API 完成，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。Movie recap AI voiceover, multi-voice narration, voice cloning, SRT subtitles.

yanghhu/novel-video-voiceover

小说推文配音、有声书配音、多角色配音技能：把小说推文文案、网文章节、故事、广播剧剧本按旁白和角色分配不同音色，一键生成整段配音 WAV、带角色名的 SRT 字幕和逐句时间轴 manifest.json，直接配画面做小说推文视频；段落、场景、章节停顿可控。适合小说推文号、故事号、网文作者有声化、睡前故事和广播剧小样。音色可用账号已有角色或参考音频声音克隆，固定旁白声线；语气标签和语速可调；改一句只重配一句。由 Miragea 开放 API 生成，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。Novel video voiceover, audiobook narration, multi-voice, 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