yanghhu/ai-voiceover

AI Voiceover (Locución por IA)

Usa el CLI voiceover (paquete ai-voiceover-studio, Python 3.9+) para generar locuciones.

Verificación de configuración

1. voiceover --version — si falta: pip install -e "<repo>[edge]" ([edge] = voces gratuitas, [yaml] = voices.yaml).
2. Ejecuta voiceover doctor --json y corrige cualquier fail que reporte (nunca imprime claves).
3. Motores: sin claves se usa el motor gratuito edge (requiere internet, sin cuenta). MIRAGEA_API_KEY cambia el predeterminado a Miragea (clonación de voz, modelos expresivos); OPENAI_API_KEY habilita --provider openai. Nunca pidas al usuario que pegue una clave en el chat, nunca la repitas, nunca la escribas en archivos.
4. La salida MP3 y el video necesitan ffmpeg (con libass para subtítulos incrustados).

Flujo de trabajo: poner voz a un guion

1. Prepara el guion (Markdown o TXT). Una etiqueta de orador por línea o párrafo:

   [NARRATOR]: Línea de apertura.
   Las líneas sin etiqueta continúan con el orador actual.
   
   [ALEX](tags=excited, speed=1.1): Un personaje diferente.
   [pause 1]
   

   Los encabezados, comentarios HTML, bloques de código y tablas se ignoran.
2. Voces (opcional). Sin un archivo de voces cada orador recibe automáticamente su propia voz, elegida del idioma del guion. Para elegir: voiceover voices --json (añade --provider edge --filter en-GB para voces Edge como en-GB-SoniaNeural; para Miragea voice_id = id del actor). Si dos voces comparten nombre, pregunta al usuario cuál usar. Con Miragea una voz también puede ser una URL pública de audio de referencia más su transcripción exacta (reference_text). Solo clona voces que el usuario posea o tenga permiso para usar.
3. Escribe voices.json si el usuario eligió voces (claves en mayúsculas):

   {"NARRATOR": {"actor_id": "en-US-AndrewNeural"}, "ALEX": {"actor_id": "en-US-AvaNeural", "speed": 1.05}}
   

4. Simulación (sin conexión, valida oradores y tiempos): voiceover script script.md -o out/ --dry-run --json
5. Genera: voiceover script script.md [--voices voices.json] -o out/ --json Produce out/voiceover.mp3, out/voiceover.srt, out/manifest.json, out/segments/.
6. Informa las rutas guardadas y la duración. No declares éxito a menos que el comando termine con código 0.

Otros comandos

• Una línea: voiceover say "texto" [--voice <id de voz|https://ref.wav>] [--ref-text "..."] [--lang es] -o linea.mp3
• Video sin rostro: voiceover video [--images slides/] --script script.md -o video.mp4 [--style clean|box|bold|minimal] [--size 1080x1920] [--speaker-labels] [--subtitles burn|sidecar|none] Los subtítulos se incrustan por defecto. Una imagen por segmento da una sincronización exacta de diapositivas; sin --images se usa un fondo degradado. Para Shorts usa --size 1080x1920 --style bold.
• Subtítulos desde reconocimiento de voz en lugar de sincronización (Miragea): añade --subtitles recognize (una llamada API extra).
• Reanudar una tarea tras un tiempo de espera: voiceover task <task_id> --wait -o salida.mp3.

Reglas

• Volver a ejecutar el mismo comando es seguro: los segmentos sin cambios vienen de caché y las solicitudes remotas usan claves de idempotencia. Usa --fresh solo cuando el usuario quiera una nueva toma.
• Ante un tiempo de espera, conserva el task_id reportado y reanuda con voiceover task; no vuelvas a enviar.
• Códigos de salida: 0 correcto, 1 falló la tarea del proveedor, 2 error de uso/configuración/API. Con --json, los errores son {"error": {"code", "message", "http_status", "retryable"}, "task_id"?}.
• 401: clave rechazada → el usuario verifica la variable de clave. 403: la cuenta no tiene acceso a la API. 429: límite de cuota/tasa → espera, no hagas bucle. 400: corrige texto/voz/velocidad/etiquetas.
• proxy_unsupported (edge): configura VOICEOVER_EDGE_PROXY o desactiva HTTPS_PROXY para el comando.
• Idiomas: edge cubre 75 idiomas; Miragea cubre chino, inglés, japonés, coreano, alemán, francés, ruso, portugués, español, italiano (con clonación de voz).