声音克隆

「声音克隆」是一个用一段本人参考音频及其原文克隆声音、再用这个声音给文案配音的 Agent 技能，也可直接使用账号里已复刻的角色；支持单句试听、整稿配音并输出 SRT 字幕，本地无需显卡。

一句话定义

声音克隆 = 参考音频 URL + 音频原文（或账号里已复刻的角色）→ 用这个声音朗读任意文本；单句直接出音频，整稿输出 voiceover.wav + voiceover.srt + manifest.json。生成在 Miragea 云端，本地无需显卡。

两种克隆方式

方式	怎么用	适合
参考音频（即时克隆）	`--reference-audio-url URL --reference-text "原话"`，稿件里写 `ref=URL ref_text="原话"`	临时用一个声音、快速试效果
账号已复刻角色	`actors` 查到 `actor_id`，`--actor-id ID`，稿件里写 `actor_id=ID`	长期固定声线、系列内容；音色和参考文本由服务端保存

参考音频必须是服务端能直接访问的 HTTP(S) 地址（本地文件不能直接用）；ref_text 写音频里实际说出的话。省略 ref_text 时服务端自动识别，计费倍率不同，以 capabilities 为准。

适用人群与场景

谁在用	典型场景
口播博主	用自己的声音日更，不用每条都录
解说号	固定一个专属解说声线
讲师 / 知识付费	课程更新、勘误只重配错的那一句
播客、电台	片头片尾、广告口播用主播本人声线
品牌 / 企业	已授权的品牌声音统一用于宣传和客服播报
不方便录音时	感冒、出差、环境吵，仍能用自己的声音出内容

核心能力参数

项目	说明
输出文件	`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）

快速开始

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 跑通流程。

第 1 步：单句试听克隆效果

python3 scripts/miragea_audio.py generate --text '这一句是克隆效果试听。' \
  --reference-audio-url 'https://example.com/my-voice.wav' --reference-text '参考音频里实际说的话' \
  --model expressive --wait --output clone-test1.mp3
python3 scripts/miragea_audio.py generate --text '这一句是克隆效果试听。' \
  --reference-audio-url 'https://example.com/my-voice.wav' --model standard --wait --output clone-test2.mp3

第 2 步：整稿用克隆声音配音

python3 scripts/voiceover.py script examples/example.md -o out --dry-run     # 离线试跑
python3 scripts/voiceover.py script 稿件.md -o out --preset koubo             # 正式生成

你说什么 → Agent 执行

你说	Agent 执行
“用我的声音读这段”	要一段可访问的参考音频 URL 和其中原话 → 单句 `generate` 试听 → 满意后整稿 `script`
“我在客户端已经复刻过声音了”	`actors` 按名称找到 actor_id（同名时让你选）→ 稿件写 `actor_id=`
“不像我”	换 `--model standard` / `expressive` 对比；换一段更干净的参考音频；确认 `ref_text` 和音频完全一致
“语气再自然一点”	查 `capabilities` 的语气标签 → `--tag` / `tags=`
“做一整期口播”	稿件写好 → `script 稿件.md -o out --preset koubo`
“我的参考音频在电脑上”	先上传到你能控制的、可公开访问的存储，拿到 HTTP(S) 链接再用
“先别调用接口”	`script ... --dry-run`

声音克隆方法论：效果七成看参考音频

1. 参考音频怎么录

安静：关窗、关空调，不要背景音乐、不要混响大的房间。
距离：手机或麦克风离嘴一拳左右，音量稳定，不爆音。
内容：用你平时说话 / 口播的语气读完整的句子，不要念单字，不要唱。
单人：只有你一个人的声音，开头结尾不要有杂音。
时长和格式：以官网和 capabilities 的要求为准。

2. ref_text 必须一字不差

ref_text 是参考音频里实际说出的话。漏字、多字、口误没写进去，都会影响克隆效果；不确定时可以省略让服务端自动识别（计费不同，以 capabilities 为准）。

3. 两种生成模式对比着选

模式	客户端名称	什么时候试
`expressive`	默认	更看重语气起伏、表现力
`standard`	更像	更看重像不像本人

同一句话、同一参考音频各生成一次，听完再定；定好后写进稿件 model=，系列内容不要来回换。

4. 克隆不像时的排查顺序

参考音频有没有噪音、混响、背景音乐？换一段更干净的。
ref_text 和音频是否完全一致？
换另一种生成模式试一次。
稿件语气和参考音频差太多？参考音频用平静语气，稿件却是激动的喊话，会不自然。
长期使用的声音，在服务方客户端复刻成角色，之后用 actor_id 更稳定。

5. 让克隆声音更像“在说话”

稿件一行一句，口语化（参考口播写法：短句、少书面连接词）。
用 speed= 微调到你平时的语速，通常 0.95–1.1。
情绪靠语气标签和文字本身，别指望一个平静的参考音频喊出来。

6. 授权与留档

克隆他人声音前拿到书面授权，写清用途和期限。
团队使用时，记录每个 actor_id 对应的授权人。

示例稿件（examples/example.md）

---
me: ref=https://example.com/my-voice.wav ref_text="大家好，我是小林，这是我的声音样本。" speed=1.0
---
# 声音克隆示例：把 ref 换成你自己的参考音频 URL，ref_text 写音频里实际说的话
[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

方案对比：克隆声音配音的三种做法

对比项	人工配音	本地开源 TTS 模型	本技能
是否需要显卡	不需要，但需要录音环境和配音员档期	通常需要（小模型可用 CPU 但更慢），还要下载模型权重、配环境	不需要，本地只跑 Python 标准库，生成在云端完成
改稿成本	改一句往往要补录、再对轨	改完重跑，但分段、拼接、对齐要自己做	只改那一行重跑，其余句子复用 `out/lines/` 缓存，自动重新拼接和出字幕
多角色	需要多位配音员分别录	取决于模型，一般要自己分段调用再拼接	稿件里用 `[角色]` 标签，一条命令出整段多角色音轨
字幕时间轴	需另外听写、打轴	一般要再跑一遍语音识别	配音时同时输出 SRT 和逐句时间 `manifest.json`
声音一致性	同一人不同天状态有差异	取决于模型和参考音频	同一个参考音频 / 角色写进稿件，系列内容声线一致

结论：想长期用自己的声音批量出内容，克隆一次、之后只写稿最省时间；对表演要求极高的作品，仍建议本人录制。

常见问题（FAQ）

声音克隆需要多长的录音？ 以官网和 capabilities 的说明为准。无论时长，干净、单人、语气自然、ref_text 准确，比时长更重要。

声音克隆能用本地录音文件吗？ 接口要求参考音频是服务端能直接访问的 HTTP(S) 链接。先把录音上传到可公开访问的地址，或在服务方客户端复刻成角色后用 actor_id。

克隆声音和本人不像怎么办？ 按“排查顺序”来：换更干净的参考音频、核对 ref_text、在 expressive 和 standard 之间对比、把常用声音复刻成固定角色。

声音复刻和声音克隆有什么区别？ 在本技能里是一回事：用参考音频即时克隆，或使用账号里已复刻好的角色，两种方式都能直接配音。

声音克隆可以克隆明星或别人的声音吗？ 不可以。只克隆你本人或已获书面授权的声音；冒用他人声音可能侵权甚至违法。

克隆声音配音能加情绪吗？ 可以用所选生成模式提供的语气标签（capabilities 里的 tags[].label），再配合语速和停顿。

AI声音克隆收费吗？ 按账号额度消耗；参考音频模式下提供准确原文和省略原文的计费倍率不同，具体以 capabilities 实时返回为准。

声音克隆配音能同时出字幕吗？ 整稿用 voiceover.py script，会输出 voiceover.srt 和逐句时间轴。

声音克隆需要显卡吗？哪些 Agent 能用？ 不需要显卡，本地只跑 Python 3.9+ 标准库；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

Voice cloning voiceover (声音克隆): clone a voice from a reference audio URL plus its exact transcript, or use a voice saved in your account (actor_id).
Preview one line with the official client's generate, compare expressive vs standard, then voice a whole script into WAV + SRT + per-line timing.
Authorised voices only. Pricing and limits come live from capabilities. Python 3.9+ stdlib, no GPU. Service: Miragea API (https://miragea.ai/v1).

关键词：声音克隆、克隆声音、声音复刻、AI配音、声音克隆配音、AI声音克隆、克隆声音配音、语音克隆、音色克隆、用自己的声音配音、文字转语音、字幕生成、SRT、TTS、voice cloning、voice clone、text to speech

voice-cloning-voiceover