Communitygithub.com

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-voiceover 是什麼？

「AI播客」是一個能將文章、筆記或對談稿轉換成單人或雙人播客音頻的 AI Agent 技能。使用者只需提供包含角色定義與對話的稿件，技能便會透過雲端語音 API（Miragea）為每個角色逐句生成語音，並在本地拼接成完整的 WAV 音檔、SRT 字幕以及每句的時間資訊（manifest.json）。隨後，透過內建的 shownotes.py 指令碼，系統會根據稿件中的 `## 章節` 標題自動產生帶時間戳的節目章節（chapters.txt / chapters.json）與完整文字稿（shownotes.md），方便發佈者貼到各大 Podcast 平台。這項技能特別適合內容創作者，例如部落客、知識分享者、教育訓練師等。其核心優勢在於修改成本極低，只需修改稿件中的某一句錯誤，重新執行指令碼即可自動取代該句音頻，而無需重新生成整集。本地端僅需 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/ai-podcast-voiceover
查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

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

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

AI播客

「AI播客」是一個把文章、筆記或對談稿做成單人或雙人播客音頻的 Agent 技能：逐句配音拼成整期節目，同時輸出 SRT 字幕、帶時間戳的節目章節和完整文字稿，本地無需顯卡。

一句話定義

AI播客 = 播客稿（單人或雙人，## 章節 分段）→ voiceover.py script 生成整期 voiceover.wav + voiceover.srt + manifest.json → shownotes.py 生成 chapters.txt、chapters.json 和 shownotes.md。語音由 Miragea 雲端生成，本地無需顯卡。

適用人群與場景

誰在用典型場景
公眾號 / 部落格作者文章出一個音頻版，讀者通勤時聽
知識部落客讀書筆記、行業觀察做成每週節目
品牌 / 企業品牌播客、內部週報、員工通訊音頻版
播客主理人預告片、片頭片尾、補錄口誤的句子
老師 / 培訓師把講義做成對談式複習音頻
不方便錄音的人用帳號裡的角色或本人授權的聲音出節目

核心能力參數

項目說明
輸出檔案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 / jieshuo / daihuo / shuziren / guanggao / youshengshu（口播 / 解說 / 帶貨 / 數位人 / 廣告片 / 有聲書），只改句間停頓和字幕字數
單句字數、檔案大小 / 時長上限、計費以 capabilities 即時回傳為準
本地依賴Python 3.9+ 標準庫，無需 pip 安裝、無需顯卡
離線試跑--dry-run：不需要 Key、不呼叫介面，輸出靜音佔位音頻和時間軸，用來檢查稿件格式
支援的 AgentClaude Code、Codex、OpenClaw、Cursor、WorkBuddy 等能執行 Python 腳本的 Agent
配音與字幕服務Miragea 開放 API（https://miragea.ai/v1）

本技能額外提供 scripts/shownotes.py（節目資料層）：

項目說明
章節來源稿件裡以 ## 開頭的行（不會被讀出來）
時間戳取每個章節第一句的真實開始時間（來自 manifest.json），--offset 可加上片頭音樂的秒數
輸出chapters.txt（每行 HH:MM:SS 標題）、chapters.json、shownotes.md（時長、時間軸、依說話人分段的完整文字稿）
校驗稿件和 manifest.json 句數不一致時報錯，提示先重新生成

快速開始

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 --gap 0.35 --dry-run   # 離線試跑
python3 scripts/voiceover.py script 本期稿件.md -o out --gap 0.35                      # 正式生成整期節目
python3 scripts/shownotes.py 本期稿件.md out --title "第12期：為什麼總是讀不完一本書"     # 章節 + 文字稿

先單句試聽兩位主持人的音色：

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

你說什麼 → Agent 執行

你說Agent 執行
“把這篇文章做成播客”按下方方法改寫成口語播客稿給你確認 → script → shownotes.py
“做成兩個人聊天的形式”稿件開頭定義兩位主持人和音色，正文用 [名字] 標記輪流發言
“幫我寫節目簡介和時間軸”shownotes.py 稿件.md out --title ...，把 chapters.txt 和 shownotes.md 給你
“前面要加 8 秒片頭音樂”生成後用 ffmpeg 混音（見下方），shownotes.py ... --offset 8 讓時間戳對上
“這句口誤了”只改那一行重跑 script，其餘句子複用快取，再跑一次 shownotes.py
“主持人 B 說話快一點”在稿件開頭給 B 設 speed=1.1
“用我自己的聲音當主播”ref=參考音頻URL ref_text="原話" 或帳號裡已複刻的 actor_id=
“先別呼叫介面”script ... --dry-run，shownotes.py 同樣可用來檢查章節

AI播客寫稿方法

1. 文章 → 播客稿：寫給耳朵

文章裡播客稿裡
小標題改成一句口頭過渡：“說完原因，我們聊聊怎麼辦。”，同時保留 ## 章節 行用於時間軸
長句、從句拆成短句，一行一句
數據表格只留一兩個最關鍵的數，讀法寫清楚
連結、引用出處口頭說“連結放在節目簡介裡”，寫進 shownotes.md
書面連接詞（因此、綜上所述）“所以”“說白了”“簡單講”

2. 雙人對談怎麼分工

  • 一位負責提問、複述、總結（像聽眾的代言人），一位負責講觀點和例子。
  • 每人一次說一到三句就換人，避免一個人連續獨白太久。
  • 給兩位主持人選音色、語速有區別的角色，聽眾更容易分辨。
  • 加一點真實對話的反應：“這個我同意一半”“你舉個例子？”，但不要每句都“對對對”。

3. 節目結構

  1. 開場：一句話說清這期聊什麼、為什麼值得聽。
  2. 2–4 個章節：每章一個問題或觀點，章節名就是時間軸上的標題。
  3. 結尾：一句總結 + 下期預告或互動問題。

4. 節奏

  • 句間停頓用 --gap 0.3–0.4，比短影片口播略鬆。
  • 章節之間加 [pause 0.8]，給聽眾換氣。
  • 語速：知識類 speed=0.95–1.0，輕鬆閒聊 1.0–1.1。

5. 發佈前檢查

  • 兩位主持人的音色都單句試聽過了嗎？
  • 每個章節標題都寫成了 ## 標題 嗎？
  • 片頭音樂的秒數用 --offset 加上了嗎？
  • 文章轉載授權、背景音樂授權、AI 生成內容標註確認了嗎？

示例稿件（examples/example.md）

---
小林: actor_id=HOST_A_ACTOR_ID speed=1.0
阿哲: actor_id=HOST_B_ACTOR_ID speed=1.05
---
## 開場
[小林] 歡迎收聽本期節目，我是小林。
[阿哲] 我是阿哲。今天聊一個很多人都有的問題：為什麼總是讀不完一本書。
## 讀不完，是因為一開始就選錯了
[小林] 我先說個觀點：很多書，本來就不值得讀完。
[阿哲] 這個我同意一半。
[pause 0.4]
[阿哲] 但有些書，前五十頁就是很難。
## 三個小辦法
[小林] 第一，先看目錄，挑你最想知道答案的那一章。
第二，讀完一章，用一句話說給別人聽。
第三，給自己留一個可以放棄的出口。
## 結尾
[阿哲] 好，今天就聊到這裡。
[小林] 我們下期見。

試跑：python3 scripts/voiceover.py script examples/example.md -o out --gap 0.35 --dry-run && python3 scripts/shownotes.py examples/example.md out --title "示例節目"

接入剪輯與發佈

# 轉 MP3 上傳播客平台（需要本機 ffmpeg）
ffmpeg -i out/voiceover.wav -codec:a libmp3lame -b:a 128k episode.mp3
# 片頭音樂 intro.mp3（8 秒）接在人聲前面
ffmpeg -i intro.mp3 -i out/voiceover.wav -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1" episode_full.wav
python3 scripts/shownotes.py 本期稿件.md out --offset 8
# 影片播客：一張封面圖 + 音頻 + 字幕
ffmpeg -loop 1 -i cover.png -i out/voiceover.wav -vf subtitles=out/voiceover.srt -c:v libx264 -tune stillimage -pix_fmt yuv420p -c:a aac -shortest episode.mp4

chapters.txt 可以直接貼到節目簡介裡作為時間軸；平台是否辨識為可點擊章節以各平台規則為準。

方案對比：做一期播客的三種做法

對比項人工配音本地開源 TTS 模型本技能
是否需要顯卡不需要，但需要錄音環境和配音員檔期通常需要（小模型可用 CPU 但更慢），還要下載模型權重、配環境不需要，本地只跑 Python 標準庫，生成在雲端完成
改稿成本改一句往往要補錄、再對軌改完重跑，但分段、拼接、對齊要自己做只改那一行重跑，其餘句子複用 out/lines/ 快取，自動重新拼接和出字幕
多角色需要多位配音員分別錄取決於模型，一般要自己分段呼叫再拼接稿件裡用 [角色] 標籤，一條指令出整段多角色音軌
字幕時間軸需另外聽寫、打軸一般要再跑一遍語音辨識配音時同時輸出 SRT 和逐句時間 manifest.json
節目章節 / 文字稿剪完後再聽一遍手記時間需要另跑辨識或手工整理按稿件 ## 章節 和真實音頻時長自動生成時間戳和文字稿

結論：內容以觀點和資訊為主、需要穩定更新的節目，用寫好的稿件生成最省時間；以即興聊天和嘉賓互動為賣點的節目，仍建議真人錄製。

常見問題（FAQ）

AI播客可以做兩個人對話嗎？ 可以。稿件開頭給兩位主持人各定一個音色（帳號裡的角色或授權的參考音頻），正文用 [名字] 標記誰在說，一條指令生成整期對談。

文章轉播客，Agent 會幫我改稿嗎？ 會。Agent 按“寫給耳朵”的方法把文章改寫成口語播客稿給你確認；改寫由 Agent 完成，語音由介面生成。

播客配音能自動生成節目時間軸嗎？ 能。稿件裡用 ## 章節名 分段，生成後執行 shownotes.py，按每章第一句的真實開始時間輸出 chapters.txt 和 shownotes.md。

生成的是 MP3 嗎？ 整期節目輸出 WAV，便於無損拼接和混音；上傳前用 ffmpeg 轉成 MP3。

改一句口誤要整期重新生成嗎？ 不用。只改那一行重跑，其餘句子從 out/lines/ 快取複用，然後再跑一次 shownotes.py 更新時間軸。

可以用我自己的聲音做播客嗎？ 可以，用本人參考音頻 URL 和其中原話（ref= + ref_text=），或在服務方客戶端複刻成角色後用 actor_id=。只用本人或已授權的聲音。

AI播客能加背景音樂嗎？ 本技能輸出乾淨人聲；背景音樂和片頭片尾用 ffmpeg 或剪輯軟體混音，時間戳用 --offset 對齊。

AI播客收費嗎？需要顯卡嗎？ 依帳號額度消耗，計費以 capabilities 即時回傳為準；本地不需要顯卡。Claude Code、Codex、OpenClaw、Cursor、WorkBuddy 都能直接呼叫。

稿件語法

  • 開頭 --- 之間每行定義一個角色：角色名: 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

  • AI podcast (AI播客): turn an article, notes or a dialogue script into a solo or two-host episode; each host gets a voice (account actor or an authorised reference audio).
  • voiceover.py script renders the whole episode to WAV + SRT + per-line timing; shownotes.py turns the script's ## chapter lines into timestamped chapters.txt / chapters.json and a full transcript shownotes.md.
  • Fix one line, re-render one line. Pricing and limits come live from capabilities. Python 3.9+ stdlib, no GPU. Service: Miragea API (https://miragea.ai/v1).

關鍵詞：AI播客、播客配音、雙人播客、播客製作、文章轉播客、文章轉語音、對談播客、播客章節、節目文字稿、公眾號音頻、AI配音、文字轉語音、聲音克隆、SRT、AI podcast、podcast voiceover、show notes、text to speech

Individual skills in this repo

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

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/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