tts

¿Qué hace tts?

Convierte cualquier texto en audio de voz. Soporta dos motores backend (Kokoro local, Noiz en la nube), dos modos (simple o con sincronización de tiempos) y control de voz por segmento.

Disparadores

• text to speech / tts / speak / say
• voice clone / dubbing (clonación de voz / doblaje)
• epub to audio / srt to audio / convert to audio (epub a audio / srt a audio / convertir a audio)
• 语音 / 说 / 讲 / 说话

Modo Simple — texto a audio

speak es el modo predeterminado; el subcomando se puede omitir:

# Uso básico (speak está implícito)
python3 skills/tts/scripts/tts.py -t "Hola mundo"          # añade -o ruta para guardar
python3 skills/tts/scripts/tts.py -f articulo.txt -o salida.mp3

# Clonación de voz — ruta de archivo local o URL
python3 skills/tts/scripts/tts.py -t "Hola" --ref-audio ./ref.wav
python3 skills/tts/scripts/tts.py -t "Hola" --ref-audio https://ejemplo.com/mi_voz.wav -o clon.wav

# Formato de mensaje de voz
python3 skills/tts/scripts/tts.py -t "Hola" --format opus -o voz.opus
python3 skills/tts/scripts/tts.py -t "Hola" --format ogg -o voz.ogg

La integración con terceros (Feishu/Telegram/Discord) está documentada en ref_3rd_party.md.

Modo de Línea de Tiempo — SRT a audio con tiempos sincronizados

Para sincronización precisa por segmento (doblaje, subtítulos, narración de videos).

Paso 1: Obtener o crear un archivo SRT

Si el usuario no tiene uno, generarlo a partir del texto:

python3 skills/tts/scripts/tts.py to-srt -i articulo.txt -o articulo.srt
python3 skills/tts/scripts/tts.py to-srt -i articulo.txt -o articulo.srt --cps 15 --gap 500

--cps = caracteres por segundo (por defecto 4, bueno para chino; ~15 para inglés). El agente también puede escribir el SRT manualmente.

Paso 2: Crear un mapa de voces

Archivo JSON que controla la configuración de voz predeterminada y por segmento. Las claves segments soportan un índice único "3" o un rango "5-8".

Mapa de voces para Kokoro:

{
  "default": { "voice": "zf_xiaoni", "lang": "cmn" },
  "segments": {
    "1": { "voice": "zm_yunxi" },
    "5-8": { "voice": "af_sarah", "lang": "en-us", "speed": 0.9 }
  }
}

Mapa de voces para Noiz (añade soporte para emo, reference_audio). reference_audio puede ser una ruta local o una URL (audio propio del usuario; solo Noiz):

{
  "default": { "voice_id": "voice_123", "target_lang": "zh" },
  "segments": {
    "1": { "voice_id": "voice_host", "emo": { "Joy": 0.6 } },
    "2-4": { "reference_audio": "./refs/invitado.wav" }
  }
}

Segmentación Dinámica de Audio de Referencia: Si estás traduciendo o doblando un video y deseas que cada oración use automáticamente el audio del video original en la misma marca de tiempo como su audio de referencia, usa el argumento --ref-audio-track en lugar de configurar reference_audio en el mapa:

python3 skills/tts/scripts/tts.py render --srt entrada.srt --voice-map vm.json --ref-audio-track video_original.mp4 -o salida.wav

Consulta examples/ para ejemplos completos.

Paso 3: Renderizar

python3 skills/tts/scripts/tts.py render --srt entrada.srt --voice-map vm.json -o salida.wav
python3 skills/tts/scripts/tts.py render --srt entrada.srt --voice-map vm.json --backend noiz --auto-emotion -o salida.wav

Cuándo Elegir Cuál

Necesidad	Recomendado
Simplemente leer texto en voz alta, sin complicaciones	Kokoro (predeterminado)
Audiolibro EPUB/PDF con capítulos	Kokoro (soporte nativo)
Mezcla de voces ("v1:60,v2:40")	Kokoro
Clonación de voz desde audio de referencia	Noiz
Control de emociones (parámetro emo)	Noiz
Duración exacta por segmento en el servidor	Noiz

Cuando el usuario necesita control de emociones + clonación de voz + duración precisa juntos, Noiz es el único backend que soporta los tres.

Modo Invitado (sin clave API)

Cuando no hay una clave API configurada, tts.py cae automáticamente en modo invitado — un endpoint limitado de Noiz que no requiere autenticación. El modo invitado solo soporta --voice-id, --speed y --format; no están disponibles la clonación de voz, emociones, duración ni renderizado de línea de tiempo.

# Modo invitado (detectado automáticamente cuando no hay clave API)
python3 skills/tts/scripts/tts.py -t "Hola" --voice-id 883b6b7c -o hola.wav

# Sobrescribir explícitamente el backend para usar kokoro en su lugar
python3 skills/tts/scripts/tts.py -t "Hola" --backend kokoro

Voces de invitado disponibles (15 incorporadas):

voice_id	nombre	idioma	género	tono
063a4491	販売員（なおみ）	ja	M	喜び
4252b9c8	落ち着いた女性	ja	F	穏やか
578b4be2	熱血漢（たける）	ja	H	怒り
a9249ce7	安らぎ（みなと）	ja	H	穏やか
f00e45a1	旅人（かいと）	ja	H	穏やか
b4775100	悦悦｜社交分享	zh	F	Alegre
77e15f2c	婉青｜情绪抚慰	zh	F	Calmada
ac09aeb4	阿豪｜磁性主持	zh	H	Calmado
87cb2405	建国｜知识科普	zh	H	Calmado
3b9f1e27	小明｜科技达人	zh	H	Alegre
95814add	Science Narration (Narración Científica)	en	H	Calmado
883b6b7c	The Mentor (Alex)	en	H	Alegre
a845c7de	The Naturalist (Silas)	en	H	Calmado
5a68d66b	The Healer (Serena)	en	F	Calmada
0e4ab6ec	The Mentor (Maya)	en	F	Calmada

Seguridad y divulgación de datos

Esta habilidad realiza las siguientes operaciones de archivos y red en tiempo de ejecución:

• Almacenamiento de credenciales: Cuando ejecutas config --set-api-key, la clave se guarda en ~/.config/noiz/api_key (permisos 0600). La variable de entorno NOIZ_API_KEY también es compatible como alternativa.
• Migración de clave heredada: Si ~/.noiz_api_key existe y ~/.config/noiz/api_key no existe, la clave se copia (no se elimina) a la nueva ubicación. Se imprime un mensaje; el archivo antiguo no se modifica para que lo elimines manualmente.
• Llamadas de red (backend Noiz): El texto y el audio de referencia opcional se cargan a https://noiz.ai/v1/ para la síntesis. No se envían datos a menos que invoques un comando de Noiz.
• Descarga de audio de referencia: Cuando --ref-audio es una URL, el archivo se descarga en un archivo temporal, se utiliza para la llamada API y luego se elimina. Si no se proporciona voice-id ni ref-audio, se descarga un audio de referencia predeterminado desde storage.googleapis.com o noiz.ai.
• Archivos temporales: Se pueden crear archivos temporales de audio/texto durante la síntesis y se limpian después de su uso.
• ffmpeg: Se invoca solo en el modo de renderizado de línea de tiempo para ensamblar el audio final.

No se modifican archivos fuera de la ruta de salida y ~/.config/noiz/. El backend Kokoro funciona completamente sin conexión, sin acceso a la red.

Requisitos

• ffmpeg en PATH (solo para modo de línea de tiempo)
• Paquete requests: uv pip install requests (necesario para el backend Noiz)
• Obtén tu clave API en Noiz Developer, luego ejecuta python3 skills/tts/scripts/tts.py config --set-api-key TU_CLAVE (el modo invitado funciona sin clave pero tiene funciones limitadas)
• Kokoro: si ya está instalado, pasa --backend kokoro para usar el backend local

Autenticación de la API de Noiz

Usa solamente la clave API codificada en base64 como Authorization—sin prefijo (por ejemplo, sin APIKEY ni Bearer ). Cualquier prefijo resulta en un error 401.

Para detalles del backend y la referencia completa de argumentos, consulta reference.md.