align-captions
Alinea texto de guion existente con audio para generar subtítulos al estilo karaoke. Utiliza Qwen3-ForcedAligner-0.6B (precisión de ~30 ms) y jieba para segmentación de palabras en chino (agrupa caracteres en palabras naturales).
Pipeline
Script + Audio
↓
Qwen3-ForcedAligner (marcas de tiempo a nivel de carácter)
↓
Segmentación de palabras con Jieba (caracteres → palabras chinas)
↓
Emparejamiento de frases basado en posición (palabras → frases)
↓
Salida: frases con marcas de tiempo de palabras incrustadas
Uso
# Alinear guion con audio (salida a nivel de frase con marcas de tiempo de palabras)
python skills/align-captions/align.py voiceover.wav --script "当全世界都在追AI的时候..."
# Guardar en archivo
python skills/align-captions/align.py voiceover.wav --script "..." --output captions.json
# Solo nivel de palabra (sin agrupación en frases)
python skills/align-captions/align.py voiceover.wav --script "..." --word-level
Formato de salida
Diseñado para renderización de karaoke en Remotion:
{
"segments": [
{
"text": "当全世界...",
"startMs": 240, "endMs": 2080,
"words": [
{"text": "当", "startMs": 240, "endMs": 400},
{"text": "全世界", "startMs": 400, "endMs": 880}
]
}
],
"word_segments": [...],
"language": "Chinese",
"model": "Qwen3-ForcedAligner-0.6B"
}
Uso programático
from align import align_captions
# Obtener frases con marcas de tiempo de palabras incrustadas
resultado = align_captions(
"voiceover.wav",
script="当全世界都在追AI的时候...",
language="Chinese"
)
# Cada frase tiene un array 'words' para resaltado tipo karaoke
for frase in resultado["segments"]:
print(f"{frase['text']}: {len(frase['words'])} palabras")
Integración con make-video
El script make_video.py utiliza automáticamente align-captions cuando:
- Existe un archivo de voiceover
- Se proporciona un guion en project.json
caption_modees "auto" o "asr"
La salida se pasa al componente RollingCaption de Remotion para renderización de karaoke.
Recuperación de errores
- Archivo de audio no encontrado: Verifica que la ruta exista antes de llamar. El script lanzará
FileNotFoundError— revisaproject.jsonpara la ruta correcta del voiceover. - Fallo en descarga del modelo: Qwen3-ForcedAligner (~1GB) se descarga en la primera ejecución. Si falla (problemas de red/disco), reintenta o descarga manualmente en el caché de HuggingFace (
~/.cache/huggingface/). - jieba no instalado: Ejecuta
pip install jieba. Sin él, el texto en chino vuelve a marcas de tiempo a nivel de carácter (sin agrupación de palabras).
Notas
- Soporta 11 idiomas: chino, inglés, cantonés, francés, alemán, italiano, japonés, coreano, portugués, ruso, español.