LucasLBrito/narracao-voz

Narración con voz neural

Rutas: ${CLAUDE_PLUGIN_ROOT} es la raíz de este plugin. Si la variable no está definida, la raíz queda dos carpetas arriba del "Base directory" de esta skill (<raiz>/skills/<skill>). Si las skills se copiaron sueltas a ~/.claude/skills, use ~/.claude/skills en lugar de ${CLAUDE_PLUGIN_ROOT}/skills.

Script: ${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py. Necesita pip install edge-tts e internet: el texto se envía al servicio de voz de Microsoft (gratis y sin clave). No ponga en el guion nada que el usuario no quiera enviar fuera.

Uso

N=${CLAUDE_PLUGIN_ROOT}/skills/narracao-voz/scripts/narracao.py
python $N <carpeta>                    # audio/escena01.mp3 ... + escena01.json (tiempos de palabras)
python $N <carpeta> --mostrar          # muestra el texto YA con los reemplazos de pronunciación (sin generar)
python $N <carpeta> --solo 3 7         # regraba solo las escenas 3 y 7
python $N <carpeta> --tiempos 3         # "  2.41s  clave" ... para sincronizar la animación
python $N <carpeta> --voz pt-BR-FranciscaNeural --rate +0%
python $N --voces                      # lista las voces en portugués

Entrada: <carpeta>/guion.json, una lista de strings (un parlamento por escena). La voz y la velocidad pueden estar en video.json ("voz", "rate"). Predeterminado: pt-BR-AntonioNeural, +8%.

Parlamento suelto (víñeta, aviso, mensaje, prueba de voz), sin carpeta ni guion:

python $N --texto "¡Hola a todos! Hoy el tema es Docker." --salida C:/tmp/vinheta.mp3
python $N --texto "..." --salida C:/tmp/f.mp3 --voz pt-BR-FranciscaNeural --rate +0%

El mapa de pronunciación base también aplica aquí. Para varios parlamentos sueltos, prefiera una carpeta con guion.json: sale un MP3 por parlamento.

Voces pt-BR útiles: pt-BR-AntonioNeural (masc., la de los vídeos), pt-BR-FranciscaNeural (fem.), pt-BR-ThalitaMultilingualNeural (fem., maneja mejor términos en inglés). Lista completa: --voces. También hay voces de Portugal (pt-PT-...) y de otros idiomas.

Escribir para ser hablado

El guion es leído por una máquina. Escriba como se habla, no como se escribe:

En pantalla / escritura	En el guion
1995	mil novecientos noventa y cinco
puerto 22	puerto veintidós
SCP, AWS (siglas deletreadas)	S C P, A W S (letras separadas)
git push -u origin main	git push, guión u, origin main
feat/login	feat barra login
.gitignore, .env	punto gitignore, punto env
~/.ssh/known_hosts	el archivo known hosts
<, >, =	menor que, mayor que, igual a

• Frases cortas. La coma es pausa: úsela para dar ritmo ("Conexión, intercambio de claves, y autenticación.").
• Tono de conversación: "vamos a entender", "¿saben aquello...?", "y lo mejor:", "resumiendo:".
• 25–45 palabras por escena (10–16 s al +8%).
• Evite paréntesis y guiones largos: la voz no sabe qué hacer con ellos.

Pronunciación de términos en inglés

La voz pt-BR lee el inglés como portugués. La corrección consiste en reemplazar el término por una grafía que suene correcta, solo en el audio (el guion y la pantalla siguen con la palabra original).

• Mapa base con ~70 términos de desarrollo: scripts/pronuncia_base.json (git, commit, push, GitHub, branch, Docker, deploy, API, JSON, frontend, Python, npm...).
• Términos del proyecto: <carpeta>/pronuncia.json, en el mismo formato. Prevalece sobre el mapa base. Para desactivar un reemplazo del mapa base, mapee el término a sí mismo: {"status": "status"}.
• El reemplazo es por palabra completa, sin distinguir mayúsculas, y los términos más largos se reemplazan primero ("Pull Request" antes de "pull").

Cómo encontrar la grafía correcta:

1. Escriba como un brasileño lo leería en voz alta, con acento en la sílaba fuerte: commit → "comít", push → "púch", GitHub → "guít-râb", release → "rilís", cache → "kéch".
2. Use guion para separar partes: "és-és-êitch" (SSH), "ci-él-ái" (CLI).
3. Genere solo esa escena (--solo N), escuche y ajuste. Si el usuario dice que algo sonó mal, corríjalo en el pronuncia.json del proyecto. Si es un término común de desarrollo, agréguelo también en pronuncia_base.json, así los próximos vídeos ya salen correctos.

Sincronizar con la animación

Cada audio/escenaNN.json tiene [{"t": 2.41, "palabra": "clave"}, ...], en segundos desde el inicio de la escena. Use ese t (o 0,2 s antes) como tiempo de entrada del elemento que representa la palabra. La palabra aparece ya con la grafía reemplazada ("comít"), lo cual es normal.

Problemas comunes

Síntoma	Causa / solución
No module named edge_tts	python -m pip install edge-tts
Error de conexión / 403	sin internet, o Microsoft cambió algo: pip install -U edge-tts
Voz demasiado rápida o lenta	--rate +0% (más lenta) o +15% (más rápida)
Término leído incorrectamente	pronuncia.json (arriba)
Escena demasiado larga (> 20 s)	divida el parlamento en dos escenas