convez.ai
SkillIntegração & APIsAvançado
DuoDuo25

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 GitHub
InicialPluginScore · de 0 a 100

Skill 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-skill

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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。你可以自由使用、修改、再分发,包括商用。


作者:嗨妮好(Hinihao) 关注我:小红书 · 抖音

Ver o original no GitHub

Bom para

Relacionados