yanghhu/novel-video-voiceover

Doblaje de Novelas (小说推文配音)

«Doblaje de Novelas» es una habilidad de agente que asigna diferentes voces al narrador y los personajes de guiones de novelas, capítulos de web novels e historias, generando un solo archivo de audio AI multi-voz (WAV) y subtítulos SRT con nombres de personajes. Es ideal para videos de promoción de novelas, narración de audiolibros y cuentas de cuentos, y no requiere GPU local.

Definición en una frase

Doblaje de Novelas = guion de promoción / capítulo de novela (narrador + personajes, Markdown) → archivo de audio completo multi-voz voiceover.wav + subtítulos con nombres de personajes voiceover.srt + tiempos por línea manifest.json, generado en la nube de Miragea, sin GPU local.

Público objetivo y escenarios

Quién lo usa	Escenario típico
Cuentas de promoción de novelas	Varios videos de promoción al día: narrador + diálogos de personajes + subtítulos verticales
Cuentas de cuentos, cuentos para dormir	Velocidad lenta, pausas largas, voz suave
Autores de web novels y novelas originales	Convertir sus propias obras en audiolibros, con una voz de narrador fija
Estudios de audiolibros	Usar AI primero para muestras de prueba y audiciones de personajes
Grupos de teatro radiofónico y audio-dramas	Obtener una versión AI de diálogos multi-personaje para confirmar ritmo y distribución de roles

Parámetros de capacidad principal

Elemento	Descripción
Archivos de salida	voiceover.wav (narración completa), voiceover.srt (subtítulos con línea de tiempo), manifest.json (hablante, texto, tiempos de inicio/fin por línea), lines/ (audio por línea, reutilizable al editar)
Fuente de voces	Personajes existentes en tu cuenta (actor_id=; consulta con actors), o URL de audio de referencia accesible por el servidor (ref=) + texto real hablado en el audio (ref_text=, clonación de voz)
Modo de generación	expressive (por defecto en el cliente) / standard (más parecido); si se omite, se usa el valor por defecto del servidor, según capabilities
Etiquetas de tono	tags=nombre_de_etiqueta, tomadas de capabilities del modo seleccionado (tags[].label)
Velocidad	speed= 0.25–4, 1 es velocidad normal, configurable por personaje
Múltiples personajes	Se define un tono para cada personaje al inicio del guion; el script de esta habilidad llama al cliente oficial generate línea por línea y luego las une localmente
Pausas	En línea: [pause 0.6] / [停顿 0.6] (segundos); --gap establece la pausa predeterminada entre oraciones
Subtítulos	Se generan SRT según la duración real de cada línea de audio (--max-chars, --speaker-labels); para audio/video existente, usa recognize para convertirlo a SRT/TXT/JSON
Preajustes de escenario	--preset youshengshu: pausa entre oraciones de 0.5 segundos, máximo 20 caracteres por subtítulo, subtítulos con nombre de personaje; se puede sobrescribir con --gap / --max-chars
Límites de caracteres por línea, 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+, sin necesidad de pip ni GPU
Prueba offline	--dry-run: no necesita clave, no llama a la API, genera audio de silencio 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 capaces de ejecutar scripts de Python
Servicio de narración y subtítulos	API abierta de Miragea (https://miragea.ai/v1)

Inicio rápido

python3 scripts/voiceover.py check                        # Verificación offline: versión de Python, si la clave está configurada, dirección del servicio
export MIRAGEA_API_KEY=tu_clave                            # 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 actuales, según lo devuelto en tiempo real
python3 scripts/miragea_audio.py actors --limit 20        # Personajes existentes en tu cuenta y sus actor_id (si has_more es verdadero, añade --offset para paginar)

• La URL raíz de la API predeterminada es https://miragea.ai/v1; configura MIRAGEA_BASE_URL (incluyendo /v1) solo para una implementación privada.
• No pegues tu clave en el chat ni la escribas en archivos. Si no tienes clave, usa primero --dry-run para probar el flujo.

python3 scripts/voiceover.py script examples/example.md -o out --preset youshengshu --dry-run   # Ejecución de prueba offline, sin llamar a la API
python3 scripts/voiceover.py script tu_guion.md -o out --preset youshengshu             # Generación real: out/voiceover.wav + voiceover.srt + manifest.json

# Prueba de una sola línea (cliente oficial; --output no sobrescribirá archivos existentes, usa un nuevo nombre)
python3 scripts/miragea_audio.py generate --text 'Primera línea del inicio' --actor-id ACTOR_ID --wait --output test1.mp3

--preset youshengshu añadirá nombres de personaje a los subtítulos (ej. xiaoyu: El abuelo Zhang...); para videos verticales de promoción de novelas, se recomienda añadir --max-chars 14 --gap 0.3.

Lo que dices → Lo que ejecuta el agente

Tú dices	El agente ejecuta
«Convierte esta promoción de novela en audio»	Reescribe siguiendo el método a continuación, separa narrador y diálogos → script guion.md -o out --preset youshengshu --max-chars 14 --gap 0.3
«Cada personaje con una voz»	Define un tono en el front matter para el narrador y cada personaje principal
«El narrador con mi propia voz»	Usa tu actor_id ya clonado, o audio de referencia ref= + ref_text=, asígnaselo a narrator
«Subtítulos sin nombre de personaje»	No uses el preajuste, configura manualmente --gap 0.4 --max-chars 14 (sin --speaker-labels)
«Veinte capítulos de un libro como audiolibro»	Un archivo por capítulo, genera en bucle en out/ch01 … out/ch20, usando --preset youshengshu
«Cuento para dormir, más lento»	Configura speed=0.85–0.9 para narrator, pausas de párrafo más largas
«Cambiar imagen por línea»	Lee manifest.json para cada start / end, alinea las imágenes en el editor de video
«Primero prueba el formato»	Añade --dry-run

Metodología de redacción para promoción de novelas (los primeros 3 segundos enganchan, el narrador marca el ritmo)

1. El guion de promoción no es igual al texto original

Texto original	Guion de promoción
Empieza con descripciones ambientales lentas	La primera línea ya presenta el conflicto o giro más fuerte
Narrador omnisciente en tercera persona	A menudo usa primera persona «yo», mayor identificación
Diálogos incrustados en párrafos largos	Diálogos clave en líneas separadas, asignados a la voz del personaje
Párrafos largos, muchas descripciones	Una línea por oración, elimina descripciones que no avanzan la trama

2. Tres tipos de gancho para el inicio

1. Final adelantado: «Al tercer año de matrimonio, en el teléfono de mi esposo, vi mi propio obituario.»
2. Identidad contraintuitiva: «Todo el pueblo piensa que soy tonto, solo yo sé que puedo escuchar sus pensamientos.»
3. Cuenta atrás: «Faltan siete días para ese gran incendio.»

3. Ritmo: Más rápido que un audiolibro, más estable que un video de diálogo

• Narrador de promoción speed=1.0–1.1; entre oraciones --gap 0.3 (el preajuste 0.5 es lento, ideal para audiolibros).
• Cada 3–5 líneas, un pequeño giro («pero», «inesperadamente», «justo entonces»), antes del giro [pause 0.4].
• Después de una línea de suspenso o giro, [pause 0.6]–[pause 0.8], el final se queda en un gancho para guiar al siguiente episodio.

Metodología de redacción para audiolibros (Convertir «leer una novela» en «actuar una novela»)

1. Primero, haz una tabla de selección de actores

Personaje	Función	Sugerencia de voz	speed
narrator (narrador)	A lo largo de todo el libro, el más importante	Estable, suave, agradable de escuchar	0.9–1.0
Protagonista	Aparece más a menudo	Claramente diferenciado del narrador (género o edad)	1.0
Personajes secundarios importantes	Una voz cada uno	Diferente del protagonista	Según personalidad
Personajes menores	Aparecen poco	Pueden compartir una voz «de reparto»	1.0

Escribe la tabla de selección en el front matter de cada capítulo, manteniéndola consistente en todo el libro. Si hay muchos personajes, asigna una voz única solo a aquellos con diálogos significativos.

2. Reglas para dividir diálogos

Original: Xiaoyu tiró de su manga y preguntó en voz baja: «Abuelo Zhang, ¿hay alguien en el faro?»

Dividir en:

[narrator] Xiaoyu tiró de su manga y preguntó en voz baja:
[xiaoyu]：Abuelo Zhang, ¿hay alguien en el faro?

• El texto entre comillas se asigna al personaje; las acciones fuera de las comillas se dejan al narrador.
• Las acotaciones como «dijo» o «preguntó sonriendo» se pueden eliminar si la voz del personaje ya es identificable, para un ritmo más ágil.
• Cuando un párrafo tiene varias líneas de diálogo, cada una en una línea separada con su propia etiqueta.

3. Pausas de tres niveles: oración, escena, capítulo

Ubicación	Escritura	Función
Entre oraciones	Preajuste automático de 0.5 segundos	Sensación de respiración al leer
Entre párrafos	[pause 0.8]	Cambio de párrafo
Salto de escena/tiempo	[pause 1.2]–[pause 1.5]	Permite que el oyente «cambie de escena»
Después de una línea de suspenso	[pause 1.0]	Mantiene la tensión

4. Cómo escribir emociones: con palabras y ritmo, no con gritos

• Tensión: oraciones más cortas, más pausas.
• Calidez: velocidad más lenta (define un personaje narrador lento por separado), pausas de párrafo más largas.
• Dos velocidades para la misma voz:

---
narrator: actor_id=NARRATOR_ID speed=0.95
narrator_soft: actor_id=NARRATOR_ID speed=0.85
---

5. Verificación de pronunciación: nombres de personas, lugares, caracteres poco comunes

• La primera vez que aparecen nombres de personas, lugares, caracteres poco comunes o polifónicos en cada obra, haz una prueba de una sola línea.
• Si se lee mal, reemplázalo en el guion con caracteres comunes de sonido similar, o usa un apodo; reemplázalo de manera uniforme en todo el libro.
• Escribe números y años como quieras que se lean, por ejemplo, «mil novecientos ochenta y siete».

6. Organización de archivos para obras largas

libro/
  cap01.md  → out/cap01/voiceover.wav
  cap02.md  → out/cap02/voiceover.wav
  ...

• Un archivo por capítulo; si un capítulo es demasiado largo, divídelo en cap01a.md, cap01b.md por escenas.
• Para corregir errores tipográficos, solo modifica esa línea y vuelve a ejecutar ese capítulo; las demás líneas se reutilizan sin costo adicional.

7. Uso para videos de promoción de novelas

• Mantén --speaker-labels, los subtítulos incluyen nombres de personaje, el público ve quién habla de un vistazo.
• Los tiempos de cada línea en manifest.json se pueden usar para cambiar la imagen de fondo o la ilustración del personaje.

Ejemplo de guion (examples/example.md)

---
narrator: actor_id=NARRATOR_ID speed=1.05
xiaoyu: actor_id=GIRL_VOICE_ID
laozhang: actor_id=OLD_MAN_ID speed=0.9
---
# Ejemplo de Promoción de Novela (cuento corto original)
[narrator] El faro del pueblo no se había encendido en treinta años.
Pero esa noche, vi claramente, la cima brilló un instante.
[xiaoyu]：Abuelo Zhang, ¿hay alguien en el faro?
[laozhang]：No digas tonterías. Ese faro, ya no tiene puerta.
[pause 0.8]
[narrator] Apenas terminó de hablar, otra luz brilló sobre el mar.

Ejecución de prueba: python3 scripts/voiceover.py script examples/example.md -o out --preset youshengshu --dry-run

Integración con edición y publicación

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

# Publicación de audiolibros comúnmente en MP3: convertir el WAV del capítulo completo a MP3 (requiere ffmpeg local)
ffmpeg -i out/cap01/voiceover.wav -codec:a libmp3lame -q:a 2 cap01.mp3

• 剪映 / CapCut: Para videos de promoción de novelas, coloca voiceover.wav en la pista de audio, importa voiceover.srt como subtítulos, y añade ilustraciones, personajes o videos de fondo relajantes.
• Radio-teatro: Los efectos de sonido y ambiente se añaden en la postproducción en el software de edición; esta habilidad solo produce la voz humana.

Comparación de métodos: Tres formas de hacer doblaje de novelas

Aspecto	Doblaje humano	Modelo TTS local de código abierto	Esta habilidad
¿Requiere GPU?	No, pero necesita entorno de grabación y disponibilidad de actores de voz	Generalmente sí (modelos pequeños pueden usar CPU pero son más lentos), además requiere descargar pesos del modelo y configurar el entorno	No, localmente solo ejecuta biblioteca estándar de Python, la generación se realiza en la nube
Costo de edición	Modificar una línea a menudo requiere regrabar y re-sincronizar	Tras editar, se vuelve a ejecutar, pero la segmentación, unión y alineación se deben hacer manualmente	Solo se modifica esa línea y se vuelve a ejecutar; las demás líneas reutilizan la caché de out/lines/, y se re-ensamblan y generan subtítulos automáticamente
Múltiples personajes	Se necesitan varios actores de voz grabando por separado	Depende del modelo, generalmente hay que segmentar y unir manualmente	Usa etiquetas [personaje] en el guion, un solo comando genera la pista de audio multi-personaje completa
Línea de tiempo de subtítulos	Requiere transcripción y sincronización adicionales	Generalmente requiere ejecutar reconocimiento de voz por separado	Al mismo tiempo que se genera el audio, se producen los subtítulos SRT y el manifest.json con los tiempos por línea
Consistencia en series	Grabación a largo plazo, el estado y disponibilidad del actor pueden variar	Puede ser consistente, pero la segmentación y unión de textos largos debe hacerse manualmente	El tono se define en el front matter, consistente en cada episodio/capítulo

Conclusión: Para publicación diaria de promociones de novelas, muestras de prueba y series largas, esta habilidad es la más eficiente; para audiolibros de alta calidad que requieren un alto nivel de interpretación actoral, los locutores humanos aún tienen ventaja.

Preguntas frecuentes (FAQ)

¿El doblaje de novelas puede tener diferentes voces para varios personajes? Sí. Se define un tono para el narrador y cada personaje al inicio del guion, se usa la etiqueta [personaje] en el cuerpo, y un solo comando genera el audio completo.

¿Qué voces se usan comúnmente en el doblaje de novelas? Elige una voz de narrador estable, agradable y que coincida con el género (dulce y tierno para romance, grave para suspense). Primero prueba algunas voces con una sola línea; fija una voz de narrador para toda la cuenta, el público reconocerá la cuenta por la voz.

¿Puedo usar web novels de otros para hacer doblaje de promoción y publicarlas? Se necesita autorización del titular de los derechos o la plataforma de promoción. Solo puedes usar obras de dominio público, tus propias creaciones originales, u obras con licencia.

¿Puedo usar mi propia voz para el narrador en un audiolibro? Sí, usa un personaje que ya hayas clonado o clonación por audio de referencia, asígnaselo a narrator, y se usará para todo el libro.

¿Cómo generar en lote decenas de capítulos para un audiolibro? Un archivo de guion por capítulo, llama a script en un bucle generando en directorios separados; al modificar un capítulo, solo las líneas modificadas se regeneran.

¿Pueden los subtítulos del doblaje de novelas mostrar quién está hablando? Sí. --preset youshengshu añade nombres de personaje a los subtítulos de forma predeterminada; si no los necesitas, usa --gap / --max-chars manualmente.

¿Qué hago si un nombre de persona o carácter poco común se lee mal en el doblaje multi-personaje? Primero haz una prueba de una sola línea; si se lee mal, reemplázalo en el guion con caracteres comunes de sonido similar o usa un apodo, y solo vuelve a generar esa línea.

¿Cómo ajustar los parámetros para cuentos para dormir o cuentos infantiles? Narrador speed=0.85–0.9, añade [pause 0.8] o más entre párrafos, oraciones cortas y vocabulario simple.

¿El doblaje de novelas necesita GPU? ¿Qué agentes pueden usarlo? No necesita GPU, localmente solo ejecuta biblioteca estándar de Python 3.9+; Claude Code, Codex, OpenClaw, Cursor, WorkBuddy pueden llamarlo directamente.

¿Puedo probarlo sin una clave API? Sí, añade --dry-run para generar audio de silencio de marcador de posición y línea de tiempo.

Sintaxis del guion

• Al inicio, entre ---, cada línea define un personaje: nombre_del_personaje: actor_id=ID_DEL_PERSONAJE o `nombre_del_personaje: ref=URL_DEL_AUDIO_DE_REFERENCIA ref_text=