yanghhu/miragea-video-voiceover

AI配音

«AI配音» es un skill de agente que convierte un guion de video en una locución multi-locutor (WAV) y subtítulos SRT con marcas de tiempo: utiliza voces guardadas en tu cuenta o clonación de voz a partir de una URL de audio de referencia, cubriendo locución directa, narración de películas, promoción de novelas, ventas con video, anuncios publicitarios y audiolibros. No requiere GPU local.

Definición en una frase

AI配音 = Un guion con etiquetas [rol] → Locución completa voiceover.wav + Subtítulos con marcas de tiempo voiceover.srt + Tiempos de inicio y fin por frase manifest.json, todo con un solo comando; cada frase se genera a través de la API abierta de Miragea, el equipo local solo necesita Python 3.9+, sin GPU ni paquetes de terceros.

Público objetivo y escenarios

Escenario	Necesidad típica	Preajuste recomendado
Locutor directo / Creador de contenido	Clonar tu propia voz para videos diarios, subtítulos verticales	--preset koubo
Narración de películas / series cortas	Voz en off + diálogos multi-tono, sincronizados con la línea de tiempo	--preset jieshuo
Promoción de novelas / audiolibros	Lectura multi-locutor, pausas entre párrafos, subtítulos con nombre del personaje	--preset youshengshu
Videos de ventas cortos	Locución rápida de puntos de venta, subtítulos grandes, pruebas de múltiples versiones	--preset daihuo
Humano digital / Avatar AI	Audio de voz limpio para conducción + línea de tiempo por frase	--preset shuziren
Anuncios / Videos promocionales	Espacios en blanco, pausas precisas, voz de marca fija	--preset guanggao
Añadir subtítulos a video existente	Reconocimiento de audio/video a SRT con marcas de tiempo	miragea_audio.py recognize

La misma serie incluye skills para métodos de escritura profundos por escenario: locución directa, narración de películas, promoción de novelas, texto a voz, clonación de voz, generación de subtítulos.

Parámetros de capacidad central

Elemento	Descripción
Archivos de salida	voiceover.wav (locución completa), voiceover.srt (subtítulos con marcas de tiempo), manifest.json (hablante, texto, segundos de inicio y fin por frase), lines/ (audio por frase, reutilizado al editar)
Origen de voz	ID de actor existente en cuenta actor_id= (consultar con actors), o URL de audio de referencia accesible por el servidor ref= + texto real en el audio ref_text= (clonación de voz)
Modo de generación	expressive (cliente «por defecto») / standard (cliente «más parecido»); si se omite, se usa el valor por defecto del servidor, según lo devuelto en tiempo real por capabilities
Etiquetas de tono	tags=nombre_de_etiqueta, tomar de tags[].label del modo seleccionado en capabilities
Velocidad	speed= 0.25–4, 1 es velocidad normal, se configura por rol
Multi-locutor	Definir un tono para cada rol al inicio del guion; este skill llama al cliente oficial por frase mediante generate, luego las une localmente
Pausas	[pause 0.6] / [停顿 0.6] en línea (segundos); --gap establece la pausa predeterminada entre frases
Subtítulos	Al locutar, se genera SRT según la duración real del audio de cada frase (--max-chars, --speaker-labels); audio/video existente se reconoce a SRT/TXT/JSON con recognize
Preajustes de escenario	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu (locución directa / narración / ventas / humano digital / anuncio / audiolibro), solo cambia pausas entre frases y longitud de subtítulos
Límite de caracteres por frase, límite de tamaño/duración de archivo, facturación	Según lo devuelto en tiempo real por capabilities
Dependencias locales	Biblioteca estándar de Python 3.9+, no requiere pip install, no requiere GPU
Prueba offline	--dry-run: no necesita Key, no llama a la API, genera audio silencioso de marcador de posición y línea de tiempo, para verificar el formato del guion
Agentes compatibles	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy y otros agentes que puedan ejecutar scripts de Python
Servicio de locución y subtítulos	API abierta de Miragea (https://miragea.ai/v1)

Límites de capacidad

Puede hacer	No hace
Voz en off individual, diálogos multi-locutor (un tono por rol, generación por frase y unión local)	No edita video, no sintetiza video (solo genera pista de audio y subtítulos, para luego importar a CapCut / Premiere /剪映 / ffmpeg)
Rol existente en cuenta (actor_id) o clonación de voz con URL de audio de referencia	No clona voces sin autorización explícita
Pausas, velocidad independiente por rol, modo de generación y etiquetas de tono	No escribe guiones automáticamente (el agente puede escribirlos siguiendo el método a continuación)
Reconocimiento de audio/video a SRT/TXT/JSON	No mezcla música de fondo, no traduce (la traducción la realiza el agente)
--dry-run prueba offline del flujo completo

Inicio rápido

python3 scripts/voiceover.py check                        # Verificación offline: versión de Python, si la Key está configurada, dirección del servicio
export MIRAGEA_API_KEY=tu_key                            # Generar en https://miragea.ai/workspace/api, solo en variable de entorno
python3 scripts/miragea_audio.py capabilities             # Modos de generación, etiquetas de tono, límite de caracteres y facturación disponibles actualmente, según lo devuelto en tiempo real
python3 scripts/miragea_audio.py actors --limit 20        # Roles existentes en cuenta y su actor_id (si has_more es verdadero, añadir --offset para paginar)

• La raíz de API predeterminada es https://miragea.ai/v1; establece MIRAGEA_BASE_URL (incluyendo /v1) solo para un despliegue privado.
• No pegues la Key en el chat ni la escribas en un archivo. Si no tienes Key, usa primero --dry-run para probar el flujo.

python3 scripts/voiceover.py script examples/movie-recap.md -o out --dry-run      # Prueba offline del ejemplo
python3 scripts/voiceover.py script guion.md -o out --preset koubo                 # Guion completo → out/voiceover.wav + voiceover.srt + manifest.json
python3 scripts/voiceover.py script guion.md -o out --gap 0.3 --max-chars 16 --speaker-labels --model standard
python3 scripts/miragea_audio.py generate --text 'Escucha una frase de prueba' --actor-id ACTOR_ID --wait --output test1.mp3
python3 scripts/miragea_audio.py recognize --file video_final.mp4 --wait --output video_final.srt

• --gap: pausa entre frases en segundos (predeterminado 0.25). --max-chars: número máximo de caracteres por subtítulo (predeterminado 18, para vertical se sugiere 12–16, para inglés 40).
• --preset configura de una vez la pausa entre frases y la longitud de subtítulos, pero se puede sobrescribir con --gap / --max-chars.

Lo que dices → Lo que ejecuta el agente

Dices	El agente ejecuta
«Convierte este guion de locución directa en audio»	Escribe guion.md (un solo rol) → script guion.md -o out --preset koubo
«Narración de película, voz en off más dos roles»	Definir en front matter narrador / tono de los roles → script ... --preset jieshuo
«Usa mi voz para la locución»	Usar actors para encontrar tu rol clonado con su actor_id; o proporcionar una URL de audio de referencia accesible por el servidor y el texto original en ella → ref= + ref_text=
«Que suene más alegre»	Consultar las etiquetas del modo seleccionado en capabilities → añadir tags=nombre_de_etiqueta al rol
«Solo lee una frase para probar»	miragea_audio.py generate --text "..." --actor-id ID --wait --output test1.mp3
«La quinta frase está mal»	Solo modificar esa línea y volver a ejecutar el mismo comando; el resto de frases se reutilizan de out/lines/
«Genera subtítulos para este video»	miragea_audio.py recognize --file video.mp4 --wait --output video.srt
«No gastes aún, prueba el flujo»	script ... --dry-run

Metodología general para escribir guiones de locución

Sea cual sea el escenario, la calidad de la locución AI depende en gran medida de si el guion está «escrito para los oídos».

1. Seis reglas generales

1. Una línea por frase, una idea por frase: en chino, una frase no debe exceder 20 caracteres; la locución suena más natural y los subtítulos caben justo en una pantalla.
2. Escribe como se leería: los números ambiguos, años, modelos, porcentajes deben escribirse en su forma leída en caracteres; las abreviaturas que se deletrean letra por letra deben separarse con espacios.
3. Sustituir lenguaje escrito por lenguaje oral: «por lo tanto» → «así que», «realizar ajustes» → «ajustar», dividir adjetivos largos en dos frases.
4. Las pausas solo se colocan antes y después de lo importante: 0.3 segundos antes de lo importante, 0.4–0.6 segundos para transiciones, 0.6–1.0 segundos para giros / cierre.
5. Un rol, una voz; una cuenta, una personalidad: el tono y la velocidad se escriben en el front matter, no cambiar para contenido en serie.
6. Primero escucha una frase, luego genera el guion completo: usa generate para una sola frase de prueba al inicio y palabras difíciles, luego ejecuta script.

2. Comparación de ritmo por escenario

Escenario	Pausa entre frases (preajuste)	Caracteres por subtítulo (preajuste)	Velocidad sugerida speed	Puntos clave al escribir
Locución directa	0.15 s	14	1.05–1.1	Dar la conclusión en los primeros 3 segundos, una idea por video
Narración de películas	0.3 s	16	0.95–1.05	Inicio con suspense, apodos de identidad, pausa antes del giro
Ventas con video	0.1 s	12	1.1–1.2	Problema → punto de venta visualizado → una sola instrucción
Humano digital	0.2 s	16	0.95–1.05	Solo voz humana, silencio al inicio y final, un clip por escena
Anuncio	0.4 s	14	0.9–1.0	Frases cortas con imágenes, espacios en blanco, nombre de marca + eslogan al final
Audiolibro	0.5 s (subtítulos con nombre de personaje)	20	0.9–1.0	Tabla de selección de voces, división de diálogos, pausas de tres niveles

3. La misma voz con dos velocidades

speed se configura por rol; cuando se necesita la misma voz para «hablar rápido en la introducción y lento en los puntos clave», define dos roles con el mismo actor_id:

---
narrator: actor_id=123 speed=1.05
narrator_slow: actor_id=123 speed=0.9
---
[narrator] Pensó que todo había terminado.
[pause 0.6]
[narrator_slow] Hasta que sonó ese teléfono.

4. Cómo hacer versiones en otros idiomas

1. Una vez fijado el guion en chino, pide al agente que lo reescriba en lenguaje oral del mercado objetivo (no traducción literal), localizando unidades y tratamientos.
2. Un archivo de guion por idioma; elige una voz de tu cuenta adecuada para ese idioma (cada rol en actors devuelve language), o cámbiala por un audio de referencia ref= en ese idioma, usando language= para sugerir el idioma del audio de referencia.
3. Subtítulos en otro idioma: --max-chars 40 aproximadamente.
4. Primero prueba una frase al inicio y las palabras difíciles, pide a un hablante nativo que escuche una muestra antes de generar el guion completo.

5. Lista de verificación de calidad antes de entregar

• ¿Se ha escuchado la primera frase? ¿El tono y la velocidad son correctos?
• ¿Números, inglés, nombres propios y caracteres polifónicos se leen correctamente?
• ¿La duración total en manifest.json cumple con los requisitos del video?
• ¿La longitud de cada subtítulo es adecuada para la relación de aspecto del video?
• ¿La voz está autorizada y se ha indicado que es generada por AI al publicar?

Sintaxis del guion

• Al inicio, entre ---, cada línea define un rol: nombre_del_rol: actor_id=ID_del_rol o nombre_del_rol: ref=URL_del_audio_de_referencia ref_text="texto real en el audio de referencia"; se puede añadir speed= (0.25–4), model=expressive|standard, tags=etiqueta1,etiqueta2, language= (sugerencia de idioma del audio de referencia, para reconocimiento automático del texto de referencia).
• ref_text= solo se usa junto con ref=; si se omite, el servidor reconoce automáticamente el texto de referencia, con distinta facturación, según capabilities.
• En el cuerpo: [rol] línea o [rol]：línea; si no se escribe etiqueta, se mantiene el último hablante.
• [pause 0.6] / [停顿 0.6] inserta una pausa (segundos); las líneas que empiezan con #, las líneas en blanco y <!-- comentarios --> se ignoran.
• Si una frase supera audio.max_text_length de capabilities, la API la rechazará; solo hay que dividirla en frases más cortas.
• El audio de cada frase se guarda en caché en out/lines/; si se vuelve a ejecutar con la misma configuración, se reutiliza directamente; si no hay caché, se envía con la misma clave de idempotencia y el servidor devuelve la tarea original sin crear una nueva. Para una nueva versión, añadir --fresh.

Ejemplo de guion (examples/movie-recap.md)

---
narrator: actor_id=TU_ACTOR_ID speed=1.05
hero: ref=https://ejemplo.com/tu-muestra.wav ref_text="texto real en el audio de referencia"
---
# Ejemplo de narración de película (cambia actor_id / ref por tus propias voces)
[narrator] Un repartidor normal encontró un teléfono que podía ver el futuro.
[pause 0.5]
[hero]：Si mañana aparezco en las noticias, ¿qué debería hacer hoy?
[narrator] Lo que no sabía es que cada vez que miraba el futuro, la realidad cambiaba un poco.

Integración con edición de video

# Reemplazar la pista de audio original del video con la locución (requiere ffmpeg local)
ffmpeg -i video_original.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest version_locutada.mp4
# Quemar los subtítulos en el video
ffmpeg -i version_locutada.mp4 -vf subtitles=out/voiceover.srt -c:a copy video_final.mp4

• 剪映 / CapCut / Premiere: Importa voiceover.wav a la pista de audio y voiceover.srt a la pista de subtítulos.
• Sincronización por frase: manifest.json tiene start / end en segundos para cada frase, útil para cortar escenas, añadir texto decorativo o alinear clips de humano digital.
• Herramientas de humano digital: voiceover.wav es solo voz, se puede usar directamente como audio de control; si se necesita MP3 o una frecuencia de muestreo específica, usa ffmpeg para convertir.

Comparación de soluciones: AI配音, locución humana y modelo local

Aspecto	Locución humana	Modelo TTS local de código abierto	Este skill
¿Requiere GPU?	No, pero necesita estudio de grabación y disponibilidad del locutor	Generalmente sí (modelos pequeños pueden usar CPU pero son más lentos), además descargar pesos y configurar entorno	No, solo ejecuta la biblioteca estándar de Python localmente; la generación se realiza en la nube
Costo de modificar el guion	Modificar una frase a menudo requiere regrabar y reajustar la sincronización	Tras modificar, se vuelve a ejecutar, pero la segmentación, unión y alineación hay que hacerlas manualmente	Solo se modifica esa línea y se vuelve a ejecutar; el resto de frases se reutilizan del caché out/lines/, y se reensamblan automáticamente
Multi-locutor	Requiere varios locutores grabando por separado	Depende del modelo; generalmente hay que segmentar y unir manualmente	Usa etiquetas [rol] en el guion; un solo comando genera toda la pista multi-locutor
Marcas de tiempo de subtítulos	Requiere transcripción y sincronización adicionales	Generalmente requiere ejecutar reconocimiento de voz por separado	Genera simultáneamente SRT y manifest.json con tiempos por frase
Interpretación emocional compleja	Un humano en un buen día sigue siendo el mejor	Depende del modelo y los parámetros	Consistente y estable, adecuado para transmisión de información y producción en masa; para interpretación emocional de alto nivel, aún se recomienda un humano

Conclusión: Para contenido de actualización diaria, múltiples versiones y modificaciones frecuentes, este skill ofrece la mayor ventaja en costo de modificación y marcas de tiempo de subtítulos; para piezas únicas que requieren una interpretación emocional excepcional, la locución humana sigue siendo valiosa.

Preguntas frecuentes (FAQ)

¿AI配音 necesita GPU o un modelo local? No. La generación se realiza en la nube de Miragea; localmente solo se necesita la biblioteca estándar de Python 3.9+, sin instalar ningún paquete con pip.

¿Cómo usar mi propia voz en AI配音? De dos formas: usando un rol ya clonado en tu cuenta (consultar actor_id con actors), o proporcionando una URL de audio de referencia accesible por el servidor y escribiendo el texto real que se dice en el audio (ref_text=). Los requisitos de muestra y la facturación se basan en capabilities y la documentación oficial.

¿Pueden hablar varias personas en un mismo video con AI配音? Sí. Al inicio del guion se definen varios roles, cada uno con su tono y velocidad; en el cuerpo se cambia con [rol]; el script genera las frases por separado y las une en una sola pista de audio, generando también los subtítulos.

¿Se puede ajustar el tono y la emoción en AI配音? Sí, con etiquetas de tono: primero consulta capabilities para ver las tags[].label del modo de generación seleccionado, y escribe tags=nombre_de_etiqueta en el rol. Además, se puede ajustar la velocidad con speed= y controlar las pausas con [pause].

¿Son precisas las marcas de tiempo de los subtítulos generados por AI配音? Los tiempos de inicio y fin de cada frase provienen de la duración real del audio generado, distribuyéndose dentro de la frase según el número de caracteres. Para una sincronización más precisa a nivel de palabra, se puede ejecutar recognize sobre el audio final.

Si modifico una frase del guion, ¿tengo que regenerar toda la locución? No. Solo modifica esa línea y vuelve a ejecutar el mismo comando; solo las frases modificadas se regenerarán, el resto se reutilizarán de out/lines/, y se reensamblarán automáticamente la pista de audio y los subtítulos.

¿AI配音 tiene costo? ¿Cuántos caracteres puedo generar de una vez? Se consume según el saldo de tu cuenta; el límite de caracteres por frase y las reglas de facturación se basan en lo devuelto en tiempo real por capabilities; --dry-run no llama a la API.

¿Los videos con AI配音 en Douyin (TikTok China) o WeChat Channels serán limitados? Ninguna herramienta puede garantizar tráfico. Es obligatorio indicar que el contenido es generado por AI según las reglas de la plataforma; el tráfico depende más del contenido en sí.

¿Puedo generar automáticamente subtítulos para un video ya grabado? Sí, con miragea_audio.py recognize --file video.mp4 --wait --output video.srt; añadiendo --subtitle-format txt se obtiene el texto plano.

¿Qué agentes AI son compatibles? Claude Code, Codex, OpenClaw, Cursor, WorkBuddy y otros agentes que puedan ejecutar scripts de Python.

¿Algún problema?

Síntoma	Solución
missing_api_key / MIRAGEA_API_KEY is not set	Genera una Key y luego export MIRAGEA_API_KEY=...; o añade --dry-run primero
speakers without a voice	Añade actor_id= o ref= a ese rol
401	Revisa la Key; no escribas la Key en los logs
403	Revisa los permisos de acceso API de la cuenta
400 / 413	Corrige los parámetros: modo, etiquetas, velocidad, caracteres por frase; o reduce el tamaño del archivo subido / acorta el contenido multimedia
409	La clave de idempotencia se usó para una entrada diferente, o la tarifa de subtítulos ha cambiado: confirma de nuevo antes de enviar
429	Saldo insuficiente o límite de tasa alcanzado; espera o recarga saldo
Timeout de espera / interrupción de red	La tarea podría seguir en ejecución: vuelve a ejecutar el mismo comando (la misma clave de idempotencia recuperará la tarea original), o usa miragea_audio.py task / wait ID_de_tarea para consultar, sin cambiar la clave y reenviar
Error de formato WAV al unir	El audio de cada frase se guarda en out/lines/, se puede unir con software de edición o ffmpeg

Códigos de salida del cliente oficial: 0 solicitud exitosa (puede estar aún en cola si no se usó --wait), 1 tarea fallida, 2 error de cliente o API.

Cumplimiento normativo

• Solo clona voces propias o de personas que hayan dado autorización explícita; no imites a celebridades, presentadores, figuras públicas ni a nadie sin autorización.
• De acuerdo con las «Medidas de Identificación de Contenido Generado por IA» y las reglas de plataformas como Douyin, Kuaishou, WeChat Channels, Xiaohongshu, Bilibili, etc., declara o etiqueta el contenido como generado por AI al publicar.
• scripts/miragea_audio.py es el cliente oficial, se distribuye sin cambios; scripts/voiceover.py (capa de ensamblaje de guiones) es original, con licencia MIT (ver LICENSE.txt). La capacidad de locución y subtítulos es proporcionada por la API abierta de Miragea.

English Summary

• AI voiceover & subtitles (AI配音) for agents: write a script with [speaker] tags, run one command, get voiceover.wav, timed voiceover.srt and manifest.json.
• Voices: saved voices in your account (actor_id) or voice cloning from a reference audio URL plus its transcript; generation modes, tone tags, speed 0.25–4.
• Multi-speaker scripts are rendered line by line through the official client's generate and joined locally; recognize turns existing audio/video into SRT/TXT/JSON.
• Limits and pricing come live from capabilities. Python 3.9+ standard library, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

关键词：AI配音、视频配音、声音克隆、字幕生成、文字转语音、文本转语音、语音合成、声音复刻、多角色配音、短视频配音、口播配音、电影解说配音、小说推文配音、广告配音、英文配音、AI旁白、SRT、TTS、voiceover、voice cloning、text to speech、subtitles