ElevenLabs TTS Skill para Podcasts em Chinês
DuoDuo25/elevenlabs-tts-skill
Converta scripts em podcasts chineses com timestamps de caractere para karaokê
Ver no GitHubSkill Python para Claude Code que integra a API da ElevenLabs para gerar podcasts em chinês com qualidade profissional, incluindo sincronização de karaokê em nível de caractere. Documenta sistematicamente os problemas reais de produção (pronúncia de números/datas, controle de velocidade, merge de chunks, compatibilidade de streaming) e fornece soluções testadas em produção.
Instalação
npx convez-ai DuoDuo25/elevenlabs-tts-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Produção de podcasts de entrevista em chinês com sincronização de legendas
- Geração de áudio narrativo multilíngue com controle granular de entonação
- Criação de conteúdo de mídia com sincronização de karaokê em tempo real
- Automação de workflows de criação de conteúdo com IA
Veredito

Skill altamente especializado e bem documentado para um caso de uso concreto (podcasts em chinês com karaokê). O material do 'cookbook' reflete experiência de produção real, mas a curva de aprendizado é íngreme e o escopo é restrito a usuários que dominam chinês e têm necessidades específicas de sincronização de mídia. Recomendado apenas para quem trabalha com conteúdo de áudio em chinês em larga escala.
README
A tradução para o português deste README ainda está na fila.
elevenlabs-tts
一个 Claude Code Skill:让 Claude 帮你把脚本 → 中文播客音频 + 字符级时间戳,能直接喂给前端做 karaoke 同步字幕。
这是嗨妮好(Hinihao)做的一个 Claude Code Skill 彩蛋,从一档真实跑过的 17 分钟、5 幕中文访谈播客里磨出来的 —— 开源送给愿意一起折腾 AI 内容创作工作流的粉丝朋友 :)
它解决什么问题
ElevenLabs 是当前公开 API 里中文 TTS 质量天花板(v3 模型能给具体情绪、能控速、能给字符级时间戳),但直接对着官方文档撸出一档能听的中文播客非常痛:
- 不知道用 v2 还是 v3;不知道 v3 没有
speed参数要用[quickly]tag 控速 - 中文数字 / 字母评级 / 日期 / 口语缩略写错就被念错(
B+念成 "B 加号"、25 年念成 "二十五年"、早九晚十一半干脆吞掉) - 主持人 tag 一不小心就咄咄逼人(
[sharp][probing]配上短反问 = AI 审讯) - 长稿要分 chunk 跑(不然超时),但 chunk 怎么拼时间戳 / 怎么合并 MP3 不踩浏览器 seek 的坑
- 部署到静态 CDN 后 seek 突然不工作(CDN 不响应 HTTP Range)
- karaoke 同步字幕跟不上音频(
timeupdate事件只有 ~4Hz)
这个 Skill 把这些坑全踩完了,每一条都有「现象 → 原因 → 修法」沉淀在 references/v3-podcast-cookbook.md 里。装上之后,让 Claude 跟你说一句「先读 cookbook 再开工」就行。
它能做什么
| 命令 | 用途 |
|---|---|
scripts/tts.py | 一句话朗读 → MP3 |
scripts/dialogue.py | 多角色对话脚本 (.txt / .json) → 拼接好的播客 MP3 + 每行时间戳 |
scripts/dialogue_timestamps.py | 同上,但调 v3 with-timestamps 端点,返回字符级时间戳 + voice_segments(karaoke 必用) |
scripts/merge_chunks.py | 把多个 chunk 的 MP3 + timing.json 正确合并成一集(避开 Xing header / -c copy 坑) |
scripts/list_voices.py | 列出你账号里所有音色 |
外加两份文档:
SKILL.md— Claude 的入口(命令速查 + 模型/参数选择表 + 反模式清单)references/v3-podcast-cookbook.md— 真金白银换来的踩坑笔记,写 cookbook 这件事本身花的时间比写代码还多references/voices.md— premade 音色目录 + 中文播客 HOST/GUEST 推荐搭配
安装
前置:macOS / Linux(Windows 也能跑,路径自己换)、Python 3.8+、ffmpeg(用
dialogue.py/merge_chunks.py时需要)、一个 ElevenLabs 账号。
1. clone 到 Claude Code 的 skills 目录
git clone https://github.com/DuoDuo25/elevenlabs-tts-skill.git \
~/.claude/skills/elevenlabs-tts
# 验证文件落到了正确位置
ls ~/.claude/skills/elevenlabs-tts/
# 应该能看到 SKILL.md、scripts/、references/
2. 配置 API key(绝不要写进任何会被 commit 的文件)
mkdir -p ~/.config/elevenlabs && \
printf '%s' "<YOUR_ELEVENLABS_API_KEY>" > ~/.config/elevenlabs/api_key && \
chmod 600 ~/.config/elevenlabs/api_key
或者用环境变量:
export ELEVENLABS_API_KEY=<YOUR_ELEVENLABS_API_KEY>
key 在 ElevenLabs 网站 → Profile → API Keys 里拿。
3. 装 ffmpeg(如果还没有)
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt install ffmpeg
只有 dialogue.py 拼接和 merge_chunks.py 合并步骤需要 ffmpeg;tts.py 和 dialogue_timestamps.py 不需要。
4. 验证
在 Claude Code 里跟 Claude 说一句:
用 elevenlabs-tts skill 帮我把「你好世界,这是一段测试。」用 rachel 念出来,输出到 /tmp/hello.mp3
Claude 应该会执行:
python3 ~/.claude/skills/elevenlabs-tts/scripts/tts.py \
--voice rachel \
--text "你好世界,这是一段测试。" \
--out /tmp/hello.mp3
听一下 /tmp/hello.mp3。能听就说明全链路 OK。
一档真实播客的完整流程
以做一档 ~15 分钟、双人访谈、带 karaoke 字幕的中文播客为例:
1. 跟 Claude 描述选题,让它先生成一版 ~30s 的 cold open 脚本(json 格式)
── 用 eleven_v3 + settings.stability=0.0 + 双 voice_id
── 写脚本时务必让 Claude 先读 cookbook §4(中文 literacy)
2. 用 dialogue_timestamps.py 生成第一段 + timing.json
── 听一下:音色对吗?情绪对吗?语速对吗?
── 不对就改 tag / 改标点 / 调 stability,绝不要继续往下做
3. cold open 通过后,把全本拆成 N 个 ~500-800 字符的 chunk
── 并发跑:限 3 并发,2 + 2 安全
4. 全部 chunk 跑完后,merge_chunks.py 合成单集 mp3 + 单份 timing.json
── 自动用 libmp3lame 重编码(避开 Xing header 坑)
── 自动时移每个 chunk 的时间戳到全局时间线
5. 前端用 timing.json 做 karaoke 同步
── audio 用 Blob URL(避开 CDN Range 坑)
── 高亮用 requestAnimationFrame 驱动(避开 timeupdate 4Hz 坑)
每一步可能踩的坑都在 cookbook 里有对应章节。
命令速查
单段朗读
python3 scripts/tts.py \
--voice rachel \
--text "你好世界" \
--out /tmp/out.mp3
简单对话播客(无字符时间戳)
script.txt:
HOST: 今天的嘉宾,<嘉宾>。
GUEST: 谢谢主持人。
python3 scripts/dialogue.py \
--script script.txt \
--voices "HOST=antoni,GUEST=rachel" \
--out /tmp/podcast.mp3
v3 带字符时间戳(karaoke 必用)
script.json:
{
"model_id": "eleven_v3",
"settings": {"stability": 0.0},
"language_code": "zh",
"inputs": [
{"voice_id": "ErXwobaYiN019PkySvjV", "text": "[curious, warmly] 第一个问题。"},
{"voice_id": "21m00Tcm4TlvDq8ikWAM", "text": "[matter-of-factly] 我的回答。"}
]
}
python3 scripts/dialogue_timestamps.py script.json /tmp/chunk_01
# 输出:/tmp/chunk_01.mp3 + /tmp/chunk_01.timing.json
合并多 chunk
python3 scripts/merge_chunks.py \
/tmp/episode \
/tmp/chunk_01 /tmp/chunk_02 /tmp/chunk_03 /tmp/chunk_04
# 输出:/tmp/episode.mp3 + /tmp/episode.timing.json
列出账号里的音色
python3 scripts/list_voices.py --category premade --page-size 50
python3 scripts/list_voices.py --search "Chinese"
已知限制
- v3 中文还在 beta 阶段:能听,但偶尔会把某个字念错,或对某个 tag 反应不出来。Cookbook §3 的「Tag 起不来的征兆」章节有修法。
- 音色市场(library voices)需要付费计划:免费账号只能用 premade(默认库)+ 自己 clone 的音色,调付费市场音色会 402。
references/voices.md列了所有 premade。 with-timestamps端点偶尔会超时(>5min):urllib 会 stuck 住,kill 重跑就行。脚本不会自动 retry —— 故意的,免得静默烧钱。- 依赖 ffmpeg:合并和拼接必装。
想贡献?
欢迎 PR / Issue。特别欢迎:
- 别的非中文语言的 literacy 坑表(日文 / 韩文 / 西语 ……)
- 别的端点的封装(streaming / sound-effects / dubbing API)
- 别的前端框架的 karaoke 同步组件示例
- Cookbook 的英文翻译
致谢
这个 Skill 是在做一档真实的中文访谈播客时一点一点踩坑磨出来的。每一条 cookbook 规则背后都对应一次「这段为什么听起来怪 → 一定要重跑 → 找到根因 → 写进文档」的循环。如果它能帮你少跑几次 ElevenLabs(每次都要钱啊),那这份文档就值了。
姊妹 Skill:codex-bridge —— 让 Claude Code 把 Codex.app 当子代理用。
License
MIT —— 详见 LICENSE。你可以自由使用、修改、再分发,包括商用。