AI配音

AI配音 是做什麼的？

「AI配音」是一個把影片文字稿一鍵生成多角色配音（WAV）和帶時間軸 SRT 字幕的 Agent 技能：音色用帳號已有角色或參考音訊聲音複製，涵蓋口播、電影解說、小說推文、帶貨、廣告片和有聲書，本地無需顯示卡。

一句話定義

AI配音 = 一份帶 [角色] 標籤的文字稿 → 整段配音 voiceover.wav + 帶時間軸字幕 voiceover.srt + 每句起止時間 manifest.json，一條命令完成；每句由 Miragea 開放 API 生成，本地只需 Python 3.9+，無需顯示卡、無需安裝第三方套件。

適用人群與場景

場景	典型需求	推薦預設
口播 / 知識博主	自己的複製聲音日更口播，直式字幕	--preset koubo
電影 / 短劇解說	旁白 + 角色台詞多音色，按時間軸對畫面	--preset jieshuo
小說推文 / 有聲書	多角色朗讀、段落停頓、字幕帶角色名	--preset youshengshu
帶貨短影音	快節奏賣點配音、大字字幕、多版本測試	--preset daihuo
數字人 / AI 分身	乾淨人聲驅動音訊 + 逐句時間軸	--preset shuziren
廣告片 / 宣傳片	留白、精確停頓、固定品牌聲音	--preset guanggao
已有影片補字幕	音訊 / 影片辨識成帶時間戳 SRT	miragea_audio.py recognize

同系列還有按場景深入寫稿方法的技能：口播配音、電影解說配音、小說推文配音、文字轉語音、聲音複製、字幕生成。

核心能力參數

項目	說明
輸出檔案	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）

能力邊界

能做	不做
單人旁白、多角色對白（每個角色一個音色，逐句生成後本地拼接）	不剪輯畫面、不合成影片（輸出音軌和字幕，交給剪映 / Premiere / CapCut / ffmpeg）
帳號已有角色（actor_id）或參考音訊 URL 聲音複製	不複製未經本人授權的聲音
停頓、每個角色獨立語速、生成模式和語氣標籤	不自動寫稿（可以讓 Agent 按下方方法先寫稿）
音訊 / 影片辨識成 SRT / TXT / JSON	不做背景音樂混音、不做翻譯（翻譯由 Agent 完成）
--dry-run 離線試跑全流程

快速開始

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/movie-recap.md -o out --dry-run      # 離線試跑範例
python3 scripts/voiceover.py script 稿件.md -o out --preset koubo                 # 整稿 → out/voiceover.wav + voiceover.srt + manifest.json
python3 scripts/voiceover.py script 稿件.md -o out --gap 0.3 --max-chars 16 --speaker-labels --model standard
python3 scripts/miragea_audio.py generate --text '試聽一句' --actor-id ACTOR_ID --wait --output test1.mp3
python3 scripts/miragea_audio.py recognize --file 成片.mp4 --wait --output 成片.srt

• --gap：句間停頓秒數（預設 0.25）。--max-chars：每條字幕最多字數（預設 18，直式螢幕建議 12–16，英文建議 40）。
• --preset 一次設好句間停頓和字幕字數，仍可用 --gap / --max-chars 覆蓋。

你說什麼 → Agent 執行

你說	Agent 執行
“把這段口播稿配成音訊”	寫入 稿件.md（單角色）→ script 稿件.md -o out --preset koubo
“電影解說配音，旁白加兩個角色”	front matter 定義 narrator / 角色音色 → script ... --preset jieshuo
“用我的聲音配音”	用 actors 找到你已複製的角色 actor_id；或給一段伺服器能存取的參考音訊 URL 和其中的原話 → ref= + ref_text=
“語氣開心一點”	查 capabilities 裡所選模式的標籤 → 角色加 tags=標籤名
“只唸一句試聽”	miragea_audio.py generate --text "..." --actor-id ID --wait --output test1.mp3
“第五句說錯了”	只改那一行再跑同一條命令，其餘句子復用 out/lines/
“給這個影片生成字幕”	miragea_audio.py recognize --file 影片.mp4 --wait --output 影片.srt
“先別花錢，試一下流程”	script ... --dry-run

配音寫稿通用方法論

不論什麼場景，AI 配音好不好聽，大部分取決於稿子是不是“為耳朵寫的”。

1. 六條通用規則

1. 一行一句，一句一個意思：中文一句儘量不超過 20 字；配音更自然，字幕也剛好一屏。
2. 寫成要讀出來的樣子：有歧義的數字、年份、型號、百分比寫成漢字讀法；需要逐字母唸的縮寫用空格隔開。
3. 口語替換書面語：“因此”→“所以”，“進行調整”→“調一下”，長定語拆成兩句。
4. 停頓只放在重點前後：重點之前 0.3 秒，轉場 0.4–0.6 秒，反轉 / 落版 0.6–1.0 秒。
5. 一個角色一個聲音，一個帳號一個人物設定：音色和語速寫進 front matter，系列內容不要換。
6. 先試聽一句，再整稿生成：單句 generate 試開頭句和難讀的詞，確認後再跑 script。

2. 各場景節奏對照

場景	句間停頓（預設）	每條字幕字數（預設）	建議語速 speed	寫稿重點
口播	0.15 秒	14	1.05–1.1	前 3 秒給結論，一條只講一個觀點
電影解說	0.3 秒	16	0.95–1.05	懸念開場，身份代稱，反轉前停頓
帶貨	0.1 秒	12	1.1–1.2	痛點 → 賣點畫面化 → 一個指令
數字人	0.2 秒	16	0.95–1.05	純人聲、首尾留靜音、一段一鏡頭
廣告片	0.4 秒	14	0.9–1.0	意象短句、留白、品牌名 + slogan 落版
有聲書	0.5 秒（字幕帶角色名）	20	0.9–1.0	選角表、對白拆分、三級停頓

3. 同一個聲音兩種語速

speed 按角色設定；需要同一音色“快講鋪墊、慢講重點”時，用同一個 actor_id 定義兩個角色：

---
narrator: actor_id=123 speed=1.05
narrator_slow: actor_id=123 speed=0.9
---
[narrator] 他以為一切都結束了。
[pause 0.6]
[narrator_slow] 直到那通電話響起。

4. 外語版本怎麼做

1. 中文稿定稿後，讓 Agent 按目標市場口語改寫（不是逐字直譯），單位、稱呼本地化。
2. 每種語言一個稿件檔案；音色選帳號裡適合該語言的角色（actors 回傳每個角色的 language），或換成該語言的參考音訊 ref=，參考音訊的語言可用 language= 提示。
3. 外語字幕 --max-chars 40 左右。
4. 先單句試聽開頭和難讀的詞，請母語者抽聽後再整稿生成。

5. 交付前品質清單

• 開頭一句試聽過，音色和語速對嗎？
• 數字、英文、人名、多音字讀對了嗎？
• manifest.json 的總時長符合影片要求嗎？
• 字幕每條長度適合畫面比例嗎？
• 聲音已授權、發佈時標註了 AI 生成嗎？

稿件語法

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

範例稿件（examples/movie-recap.md）

---
narrator: actor_id=YOUR_ACTOR_ID speed=1.05
hero: ref=https://example.com/your-sample.wav ref_text="參考音訊裡實際說的話"
---
# 電影解說範例（把 actor_id / ref 換成你自己的音色）
[narrator] 一個普通的快遞員，撿到了一部能看見未來的手機。
[pause 0.5]
[hero]：如果明天的新聞裡有我，那今天我該做什麼？
[narrator] 他不知道的是，每看一次未來，現實就會悄悄改變一點。

接入剪輯

# 配音取代原影片音軌（需要本機 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 / Premiere：匯入 voiceover.wav 到音軌，voiceover.srt 匯入字幕軌即可。
• 按句卡點：manifest.json 每句有 start / end 秒數，用來切鏡頭、放花字、對齊數字人片段。
• 數字人工具：voiceover.wav 是純人聲，可直接作為驅動音訊；需要 MP3 或特定取樣率時用 ffmpeg 轉換。

方案對比：AI配音、人工配音和本地模型

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

結論：日更、多版本、頻繁改稿的內容，本技能在改稿成本和字幕時間軸上優勢最大；對情緒表演要求極高的單條精品，真人配音仍然值得。

常見問題（FAQ）

AI配音需要顯示卡或本地部署模型嗎？ 不需要。生成在 Miragea 雲端完成，本地只需 Python 3.9+ 標準庫，不用 pip 安裝任何套件。

AI配音怎麼用自己的聲音？ 兩種方式：用帳號裡已經複製好的角色（actors 查 actor_id），或提供一段伺服器能直接存取的參考音訊 URL，並寫上音訊裡實際說的話（ref_text=）。樣本要求和計費以 capabilities 和官網說明為準。

AI配音一段影片裡能有好幾個人說話嗎？ 能。稿件開頭定義多個角色，每個角色一個音色和語速，正文用 [角色] 切換；腳本逐句生成後拼成一條音軌，並同時出字幕。

AI配音能調語氣和情緒嗎？ 能用語氣標籤：先 capabilities 查看所選生成模式提供的 tags[].label，在角色上寫 tags=標籤名。另外可以用 speed= 調語速、用 [pause] 控制停頓。

AI配音生成的字幕時間準嗎？ 每句的起止時間來自真實生成的音訊長度，句內按字數分配。需要逐字更精確的時間軸，可對成品音訊再跑一次 recognize。

AI配音稿子改了一句，要整段重新生成嗎？ 不用。改那一行後重跑同一條命令，只有改過的句子會重新生成，其餘從 out/lines/ 復用，自動重新拼接音軌和字幕。

AI配音收費嗎？一次能配多少字？ 按帳號額度消耗，單句字數上限和計費規則以 capabilities 即時回傳為準；--dry-run 不呼叫介面。

抖音、影片號用 AI配音會限流嗎？ 沒有工具能保證流量。按平台規則標註 AI 生成內容是必須的；流量更多取決於內容本身。

已經錄好的影片能自動出字幕嗎？ 能，miragea_audio.py recognize --file 影片.mp4 --wait --output 影片.srt；加 --subtitle-format txt 得到純文字稿。

支援哪些 AI Agent？ Claude Code、Codex、OpenClaw、Cursor、WorkBuddy 等能執行 Python 腳本的 Agent。

出問題了？

現象	處理
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 voiceover & subtitles (AI配音) for agents: write a script with [speaker] tags, run one command, get voiceover.wav, timed voiceover.srt and manifest.json.
• Voices: saved voices in your account (actor_id) or voice cloning from a reference audio URL plus its transcript; generation modes, tone tags, speed 0.25–4.
• Multi-speaker scripts are rendered line by line through the official client's generate and joined locally; recognize turns existing audio/video into SRT/TXT/JSON.
• Limits and pricing come live from capabilities. Python 3.9+ standard library, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

關鍵詞：AI配音、影片配音、聲音複製、字幕生成、文字轉語音、文字轉語音、語音合成、聲音複製、多角色配音、短影音配音、口播配音、電影解說配音、小說推文配音、廣告配音、英文配音、AI旁白、SRT、TTS、voiceover、voice cloning、text to speech、subtitles