memex-lab/product-launch-video-skill

Texto a Voz con Gemini

Genera voz natural y expresiva a partir de texto usando Google Gemini TTS. Soporta más de 70 idiomas, 30 voces predefinidas y control de estilo mediante indicaciones en lenguaje natural y etiquetas de audio.

Requisitos: Node.js 18+, ffmpeg, paquete npm @google/genai, variable de entorno GEMINI_API_KEY.

Scripts Disponibles

• scripts/generate-tts.mjs — Generador TTS completo con consistencia en una sola solicitud, división basada en silencios y recorte automático.

Inicio Rápido

Texto único a voz

npm install @google/genai
GEMINI_API_KEY=tu-clave node scripts/generate-tts.mjs \
  --text "¡Hola, bienvenido a nuestro producto!" \
  --output-dir public/vo \
  --voice Kore

Voiceover multi-segmento (voz consistente)

Crea un archivo segments.json:

[
  { "id": "intro", "text": "Bienvenido al lanzamiento de nuestro producto." },
  { "id": "features", "text": "Estas son las tres características que te encantarán." },
  { "id": "close", "text": "Comienza hoy mismo en nuestro sitio web." }
]

Ejecuta:

GEMINI_API_KEY=tu-clave node scripts/generate-tts.mjs \
  --segments segments.json \
  --output-dir public/vo \
  --voice Kore \
  --director-notes "Tono: Cálido, seguro, inspirador. Estilo: Narrador profesional con sonrisa vocal. Acento: Inglés americano neutro. Ritmo: Moderado."

Salida (JSON a stdout):

{
  "success": true,
  "segments": [
    { "id": "intro", "file": "public/vo/vo-intro.mp3", "duration": 3.25 },
    { "id": "features", "file": "public/vo/vo-features.mp3", "duration": 4.10 },
    { "id": "close", "file": "public/vo/vo-close.mp3", "duration": 2.80 }
  ],
  "totalDuration": 10.15,
  "fullAudioFile": "public/vo/vo-full.wav"
}

Opciones del Script

Banderas	Por Defecto	Descripción
--segments FILE	—	Archivo JSON con definiciones de segmentos [{id, text}]
--text TEXT	—	Texto único a generar (alternativa a --segments)
--output-dir DIR	—	Directorio de salida para archivos de audio (requerido)
--voice NAME	Kore	Nombre de voz predefinida (ver tabla de Voces)
--model NAME	gemini-3.1-flash-tts-preview	ID del modelo Gemini TTS
--director-notes TEXT	—	Guía de interpretación: estilo, ritmo, acento, respiración, articulación. No controla género/edad (usa --voice para eso).
--retries N	3	Máximo de reintentos para errores de API
--trim / --no-trim	--trim	Recortar silencios de los bordes de los segmentos
--format FORMAT	mp3	Formato de salida: mp3 o wav

Códigos de Salida

Código	Significado
0	Éxito
1	Faltan argumentos requeridos o variables de entorno
2	Error de API después de agotar reintentos
3	ffmpeg no instalado o error de procesamiento
4	Error de E/S de archivos

Cómo Funciona (Multi-Segmento)

Gemini TTS NO garantiza consistencia de voz entre solicitudes API separadas. El script lo resuelve:

1. Combinando todos los segmentos en UNA sola indicación con marcadores de [pausa de 3 segundos] entre ellos
2. Generando un único archivo de audio continuo en una sola llamada a la API
3. Detectando pausas de silencio con ffmpeg silencedetect usando umbrales adaptativos (comienza en noise=-35dB, d=1.5s, y se relaja progresivamente). Si se encuentra una coincidencia exacta, la usa directamente. Si ocurre un salto de umbral (demasiado pocos → demasiados silencios), regenera el audio con un ritmo de habla más rápido para hacer las pausas entre segmentos más distintivas, y luego reintenta la detección.
4. Dividiendo en los puntos medios de los silencios para crear archivos de segmentos individuales
5. Recortando el silencio residual (~1.5s por lado) de cada segmento, manteniendo 0.15s de espacio para respirar

Modelos

Modelo	Mejor Para
gemini-3.1-flash-tts-preview	Último, más controlable, más de 200 etiquetas de audio (por defecto)
gemini-2.5-flash-preview-tts	Rápido, buena calidad, uso general
gemini-2.5-pro-preview-tts	Máxima calidad, interpretaciones complejas

Voces

30 voces predefinidas:

Voz	Género	Carácter	Tono
Achernar	Femenina	Suave	Más agudo
Achird	Masculina	Amigable	Medio bajo
Algenib	Masculina	Grave	Más grave
Algieba	Masculina	Suave	Más grave
Alnilam	Masculina	Firme	Medio bajo
Aoede	Femenina	Aireada	Medio
Autonoe	Femenina	Brillante	Medio
Callirrhoe	Femenina	Tranquila	Medio
Charon	Masculina	Informativa	Más grave
Despina	Femenina	Suave	Medio
Enceladus	Masculina	Entre cortada	Más grave
Erinome	Femenina	Clara	Medio
Fenrir	Masculina	Emocionable	Medio bajo
Gacrux	Femenina	Madura	Medio
Iapetus	Masculina	Clara	Medio bajo
Kore	Femenina	Firme	Medio
Laomedeia	Femenina	Optimista	Más agudo
Leda	Femenina	Juvenil	Más agudo
Orus	Masculina	Firme	Medio bajo
Puck	Masculina	Optimista	Medio
Pulcherrima	Masculina	Directa	Medio
Rasalgethi	Masculina	Informativa	Medio
Sadachbia	Masculina	Animada	Más grave
Sadaltager	Masculina	Erudita	Medio
Schedar	Masculina	Pareja	Medio bajo
Sulafat	Femenina	Cálida	Medio
Umbriel	Masculina	Tranquila	Medio bajo
Vindemiatrix	Femenina	Gentil	Medio
Zephyr	Femenina	Brillante	Más agudo
Zubenelgenubi	Masculina	Casual	Medio bajo

Notas del Director (--director-notes)

Guía de interpretación para la voz seleccionada. Define solo lo que importa: especificar demasiado limita la creatividad del modelo y puede empeorar los resultados.

Las tres direcciones más comunes son Estilo, Ritmo y Acento, pero puedes incluir cualquier instrucción personalizada relevante para la interpretación.

• Estilo — Calidad emocional y carácter de la entrega. Sé descriptivo: "Entusiasmo contagioso: el oyente debe sentirse parte de algo emocionante" funciona mejor que solo "enérgico". Puedes superponer características y usar términos profesionales de locución como "sonrisa vocal".
• Ritmo — Velocidad general y variación rítmica. Puede ir desde "Habla lo más rápido posible" hasta "Increíblemente lento y líquido, las palabras se funden entre sí, cero urgencia".
• Acento — Sé específico. "Inglés británico como se escucha en Croydon, Inglaterra" funciona mucho mejor que "Acento británico".

--director-notes "Estilo: Entusiasta y descarada YouTuber de belleza GenZ. Ritmo: Extremadamente rápido, entrega acelerada como influencers de video corto. Acento: Chica del valle del sur de California de Laguna Beach."

Etiquetas de Audio

Usa [corchetes] dentro del texto del segmento para control palabra por palabra. Anula las notas del director localmente.

[susurros] [gritos] [emocionado] [serio] [pausa corta] [risas] [muy rápido] [muy lento] [sarcástico] [curioso]

También funcionan etiquetas creativas: [como drácula], [susurrando conspirativamente]

Ejemplo: "[emocionado] ¡Esto lo cambia todo! [pausa corta] Déjame mostrarte cómo."

Referencias

• Guía de Indicaciones — Ingeniería de indicaciones avanzada para estilo, emoción y acento