AI播客

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、不呼叫介面，輸出靜音佔位音頻和時間軸，用來檢查稿件格式
支援的 Agent	Claude 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