Traductor de Subtítulos de YouTube
Descarga videos de YouTube, extrae y procesa subtítulos (corrección + puntuación + traducción), luego los incrusta en el video. Maneja tanto subtítulos generados automáticamente como cargas manuales, con respaldo de ASR cuando no hay subtítulos.
Reglas Estrictas
- Usa un máximo de 3 subagentes concurrentes para el procesamiento de fragmentos de subtítulos. Cuando haya más de 3 fragmentos, ejecútalos en oleadas e inicia el siguiente fragmento solo después de que un subagente termine.
- El número de fragmentos no es concurrencia. Puedes dividir en 10 fragmentos, pero no debes iniciar 10 procesos/subagentes de Codex a la vez; ejecuta un máximo de 3 trabajadores activos en cualquier momento.
- Siempre descarga solo la pista de subtítulos fuente: inglés cuando esté disponible, de lo contrario el idioma original del video. No descargues los subtítulos traducidos automáticamente por YouTube; traduce desde el subtítulo fuente.
- Nunca uses una pista de subtítulos en el idioma de destino proporcionada por YouTube como atajo, incluso para videos largos y aunque
zh-Hansu otro idioma de destino esté listado enautomatic_captions. - La descarga de video por defecto es 1080p. Si 1080p no está disponible, descarga la mejor versión disponible por debajo de 1080p.
- La traducción debe ser realizada por subagentes sobre archivos de fragmentos. No uses ayudas de modelo local para la traducción.
- Antes de escribir SRT/ASS, elimina caracteres ilegales de subtítulos del texto, especialmente barras invertidas sueltas (
\) que se renderizan visiblemente en el video.
Resumen del Flujo de Trabajo
Fase 1: Descargar → Obtener info del video, descargar video, extraer subtítulos
Fase 2: Preparar → Si no hay subtítulos: extraer audio → ejecutar ASR
Fase 3: Procesar → Dividir en fragmentos → corrección de agente paralela + traducir
Fase 4: Fusionar → Combinar fragmentos → generar archivos SRT/ASS
Fase 5: Renderizar → Incrustar subtítulos en el video usando ffmpeg
Fase 1: Descargar
1.1 Obtener Información del Video
Usa la herramienta MCP de YouTube para obtener metadatos:
youtube_get_video_info(videoId="...", detail="standard")
Registra: título, duración, canal, si hay subtítulos disponibles.
1.2 Crear Directorio de Salida
Nombra el directorio según el título del video. Sanitiza para el sistema de archivos:
mkdir -p "/ruta/salida/<Título del Video>"
1.3 Descargar Video
youtube_download(videoId="...", outputPath="<dir>/video.mp4", quality="1080p", force=true)
Si usas yt-dlp, prefiere 1080p y recurre al mejor formato por debajo de 1080p:
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]/best" --merge-output-format mp4 \
-o "<dir>/video.%(ext)s" "<url>"
1.4 Extraer Solo Subtítulos Fuente
youtube_get_transcript(videoId="...", language="<idioma-fuente>")
Si el resultado excede los límites de tokens, se guarda en un archivo de resultados de la herramienta; léelo en fragmentos.
Esta es una política de subtítulos fuente no negociable:
- Prefiere subtítulos/captions en inglés cuando estén disponibles.
- Si el inglés no está disponible, usa el idioma hablado original del video.
- Ignora
zh-Hans,zh-Hanty cualquier otra pista de subtítulos en el idioma de destino mostrada por YouTube, incluyendo pistas traducidas automáticamente. - No solicites, reintentes, combines o renderices una pista de subtítulos en el idioma de destino proporcionada por YouTube.
- Los subtítulos en el idioma de destino deben producirse solo mediante traducción de subagentes a partir del subtítulo fuente.
Si una herramienta devuelve una lista como en-orig, zh-Hans, elige solo en-orig. No incluyas zh-Hans en ningún comando de descarga.
Si usas yt-dlp, escribe solo el subtítulo fuente:
yt-dlp --skip-download --write-auto-subs --write-subs \
--sub-langs "en.*" --sub-format srt --convert-subs srt \
-o "<dir>/video.%(ext)s" "<url>"
Incorrecto, no ejecutes:
yt-dlp --write-auto-subs --sub-langs "en-orig,zh-Hans" ...
Si la descarga del subtítulo en inglés/original tiene éxito pero la solicitud del idioma de destino falla con HTTP 429, no reintentes la solicitud del idioma de destino. Esa solicitud no debería haberse realizado; continúa con el subtítulo fuente y tradúcelo a través de la Fase 3.
Si existen subtítulos: Guarda los segmentos sin procesar como JSON, continúa a la Fase 3. Si NO hay subtítulos (404/error): Continúa a la Fase 2 (respaldo de ASR).
Guarda los datos sin procesar:
raw_segments.json— todos los segmentos con texto/desplazamiento/duraciónraw_subtitles.srt— conversión SRT inicial
Fase 2: Respaldo ASR (Sin Subtítulos Disponibles)
Cuando el video no tiene captions/transcripciones:
-
Extraer audio del video usando ffmpeg:
ffmpeg -i video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav -
Ejecutar ASR — el usuario especificó qwen3-asr pero cualquier modelo compatible con whisper funciona:
qwen3-asr audio.wav --output-format srt > raw_subtitles.srtO usa el enfoque integrado a través del comando transcribe de la habilidad hyperframes-media.
-
Analiza la salida SRT de nuevo al formato JSON de segmentos esperado por la Fase 3.
Fase 3: Corrección y Traducción Paralela
Este es el paso que más tiempo consume para videos largos. La estrategia: dividir en fragmentos y procesarlos con subagentes, con un límite estricto de 3 subagentes concurrentes.
Haz esta fase incluso para videos muy largos. La longitud no es una razón para descargar o usar los subtítulos automáticos en el idioma de destino de YouTube. El atajo correcto para videos largos es la división en fragmentos más la concurrencia de 3 subagentes, no la reutilización de subtítulos de destino.
3.1 Dividir Segmentos en Fragmentos
Usa la lógica inversa de scripts/merge-chunks.py — divide raw_segments.json en N archivos de fragmentos:
# Dividir en fragmentos del tamaño adecuado para revisión/traducción.
n = len(segments)
chunk_count = min(10, max(1, (n + 75) // 76))
chunk_size = n // chunk_count + 1
for i in range(0, n, chunk_size):
save_chunk(i, segs[i:i+chunk_size])
Guarda como chunk_00.json, chunk_01.json, etc. Cada uno contiene {"chunk_id", "start_idx", "end_idx", "segments": [...]}.
3.2 Iniciar Agentes Paralelos
Para cada fragmento, inicia un subagente en segundo plano. No inicies más de 3 subagentes al mismo tiempo. Si hay 10 fragmentos, inicia primero los fragmentos 00, 01 y 02; cuando uno termine, inicia el siguiente fragmento pendiente. Nunca inicies los 10 fragmentos a la vez. Dale a cada agente:
- La ruta a su
chunk_XX.json - Instrucciones para leer references/subtitle-proofreading.md para la especificación completa
- Ruta de salida:
result_XX.jsonen el mismo directorio
El agente debe:
- Leer cada segmento en su fragmento
- Corregir el inglés (corregir errores de ASR, añadir puntuación)
- Traducir a chino simplificado natural (mantener términos técnicos en inglés)
- Guardar como un array JSON con
{index, start, end, en, zh}por segmento - Eliminar caracteres ilegales de subtítulos de
enyzh, especialmente barras invertidas sueltas (\), caracteres de control y llaves de anulación de ASS sin procesar.
Importante: La concurrencia máxima es de 3 subagentes/procesos. Si hay más de 3 fragmentos, ejecútalos en oleadas. No inicies 10 procesos hijos de Codex para 10 fragmentos.
3.3 Esperar a la Finalización
Monitorea qué archivos result_XX.json aparecen. No continúes hasta que todos los fragmentos estén completos.
Fase 4: Fusionar y Generar Archivos de Salida
Ejecuta el script de fusión:
python3 scripts/merge-chunks.py <directorio_salida>
Esto descubre automáticamente todos los archivos result_*.json y produce:
| Archivo | Contenido |
|---|---|
final_subtitles.json | JSON fusionado, ordenado por marca de tiempo |
subtitles_bilingual.srt | Líneas en inglés + chino |
subtitles_zh.srt | Solo chino |
subtitles_en.srt | Solo inglés |
4.2 Validar la Calidad de los Datos
Antes de renderizar, siempre valida los datos fusionados. El procesamiento de agente paralelo puede producir corrupción de marcas de tiempo:
# Verificar duraciones anormales (>120s = casi con toda seguridad corruptas)
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
mals = [s for s in segs if s['end'] - s['start'] > 120]
print(f'Duraciones anormales: {len(mals)} / {len(segs)}')
for s in mals: print(f' [{s[\"index\"]}] {s[\"start\"]:.1f}->{s[\"end\"]:.1f} ({s[\"end\"]-s[\"start\"]:.0f}s)')
"
Si se encuentra alguna, corrígelas (limita end a start + 6) y regenera SRT/ASS. Tanto merge-chunks.py como srt-to-ass.py incluyen detección automática y corrección automática para este problema.
Verifica la salida: comprueba que las primeras y últimas entradas tengan marcas de tiempo correctas y texto legible.
También verifica la sanitización del texto:
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
mals = [s for s in segs if '\\\\' in s.get('en','') or '\\\\' in s.get('zh','')]
print(f'Artefactos de barra invertida: {len(mals)}')
for s in mals[:10]: print(s['index'], s.get('en',''), s.get('zh',''))
"
Fase 5: Renderizar Subtítulos en el Video
Aquí es donde las cosas se complican. NO uses el ffmpeg del sistema directamente — consulta los Obstáculos a continuación.
5.1 Ejecutar el Script de Renderizado
bash scripts/render-subtitles.sh <video.mp4> <subtitles_bilingual.srt> [output.mp4]
El script maneja todo:
- Detecta/construye ffmpeg nativo para ARM64 con soporte libass
- Convierte SRT → ASS con configuración de fuentes CJK adecuada
- Copia archivos a /tmp para evitar problemas de rutas con caracteres especiales
- Renderiza con el filtro ass de ffmpeg
- Valida la salida
5.2 Verificar la Salida
Comprueba que:
- El archivo de salida existe y tiene más de 10MB (no solo audio)
- La duración coincide con el video original (usa ffprobe)
- Reproduce el primer y último minuto para confirmar que aparecen los subtítulos
Obstáculos y Lecciones Aprendidas
Estas son lecciones ganadas con esfuerzo del uso real. Síguelas para evitar perder horas.
Discordancia de Arquitectura de ffmpeg (CRÍTICO)
Problema: El ffmpeg de Homebrew en macOS está compilado SIN libass, libfreetype y fontconfig. Los filtros ass, subtitles y drawtext simplemente no existen.
Peor: Las compilaciones estáticas de ffmpeg de evermeet.cx son binarios x86_64 (Intel). En Macs con Apple Silicon se ejecutan a través de la emulación Rosetta 2, aproximadamente 8-10 veces más lento. Un video de 1.5h tardó más de 2 horas.
Solución: Usa scripts/ensure-ffmpeg.sh. Detecta estos problemas y compila ffmpeg nativo para ARM64 desde el código fuente con todas las bibliotecas necesarias. La primera compilación toma ~5 minutos; las reconstrucciones posteriores son instantáneas (archivos de objetos en caché).
Indicaciones de configuración requeridas para soporte completo de subtítulos:
--enable-libass --enable-libfreetype --enable-fontconfig --enable-libdav1d
Falta de Decodificación AV1
Problema: Muchos videos modernos de YouTube están codificados en AV1 (codec_name: av1). Un ffmpeg compilado sin --enable-libdav1d fallará con errores de "Función no implementada" durante la decodificación, produciendo un archivo de solo audio de 68MB.
Solución: Incluye siempre --enable-libdav1d al compilar ffmpeg.
Caracteres Especiales en Rutas Rompen los Filtros de ffmpeg
Problema: Cuando la ruta del video o del subtítulo contiene caracteres como guiones largos (—), comillas inteligentes o caracteres no ASCII, el analizador de filtros de ffmpeg falla con errores como "No option name near...". Esto sucede incluso con comillas de shell adecuadas.
Solución: Copia los archivos de subtítulos a /tmp/subs_<pid>.ass antes de pasarlos a ffmpeg. El script de renderizado hace esto automáticamente.
Conflictos en la API de TextClip de moviepy (EVITAR)
Problema: TextClip de moviepy 2.x tiene conflictos de parámetros entre argumentos posicionales y kwargs (font aparece dos veces internamente). Múltiples variantes de error, ninguna obvia a partir del mensaje de error.
Recomendación: No uses moviepy para la renderización de subtítulos en producción. Usa el filtro ass de ffmpeg en su lugar: es más rápido, más confiable y maneja fuentes CJK correctamente a través de libass/fontconfig.
SRT vs ASS para ffmpeg
Problema: El filtro subtitles de ffmpeg (que lee SRT directamente) también sufre problemas de análisis de rutas en algunas compilaciones. El filtro ass es más confiable.
Solución: Convierte SRT → ASS primero usando scripts/srt-to-ass.py, luego usa el filtro ass. El formato ASS también te da control fino sobre fuente, tamaño, posicionamiento y estilo.
Caracteres Ilegales en Subtítulos
Problema: El texto de los subtítulos sin procesar o traducidos puede contener barras invertidas sueltas (\) o caracteres de anulación de ASS. En la renderización ASS, una barra invertida literal puede aparecer en pantalla o interactuar accidentalmente con la sintaxis de escape de ASS.
Solución: Sanitiza el texto de los subtítulos antes de escribir SRT/ASS:
- Elimina las barras invertidas del texto visible del subtítulo
- Elimina los caracteres de control, excepto los espacios en blanco normales
- Elimina las llaves
{y}sin procesar del texto del subtítulo - Deja que
srt-to-ass.pyañada solo las secuencias de control ASS que le pertenecen, como\Nentre líneas bilingües
Duraciones Anormales de Subtítulos por Procesamiento de Agente Paralelo
Problema: Al procesar subtítulos en fragmentos paralelos (Fase 3), los agentes individuales pueden producir entradas con marcas de tiempo corruptas, específicamente, valores de end que son mucho más grandes que start (por ejemplo, duración de 2600s o 4800s en lugar de ~6s). Esto hace que esas líneas de subtítulos permanezcan visibles en pantalla durante la mayor parte del video, superponiéndose con todo el otro contenido.
Causa raíz: Los agentes a veces asignan mal los tiempos de finalización al consolidar segmentos de ASR fragmentados a través de los límites de los fragmentos. El problema está a nivel de datos, no es un problema de renderizado, por lo que no será detectado por errores de ffmpeg.
Solución: Tres capas de defensa:
scripts/srt-to-ass.pydetecta automáticamente entradas con duración > 120s y las limita a 6s con una advertencia- Validación de la Fase 4: Después de fusionar fragmentos, siempre busca entradas donde
(end - start) > 120segundos - Verificación previa a la renderización: Antes de ejecutar ffmpeg, busca en el archivo ASS líneas de Diálogo sospechosamente largas
# Verificación rápida previa a la renderización: encuentra cualquier subtítulo que dure más de 2 minutos
python3 -c "
import json, sys
segs = json.load(open('final_subtitles.json'))
mals = [s for s in segs if s['end'] - s['start'] > 120]
if mals: print(f'ADVERTENCIA: ¡{len(mals)} duraciones anormales encontradas!'); sys.exit(1)
else: print('Verificación de duración superada')
"
Ajuste del Tamaño de Fuente
Problema: Los tamaños de fuente predeterminados (16-20px) pueden ser demasiado pequeños en videos de alta resolución 1080p+, especialmente cuando se ven en pantallas más pequeñas o desde una distancia.
Solución: Usa la bandera --font-size para ajustar. Tamaños base recomendados:
- Video 1080p:
--font-size 24(bilingüe) o--font-size 28(idioma único) - Video 4K:
--font-size 36o más grande - El script
render-subtitles.shpasa esto asrt-to-ass.py
Dependencias
- Herramientas MCP de YouTube:
mcp__plugin_youtube_youtube__*(descarga de video, transcripción, información) - ffmpeg: Compilado automáticamente por
scripts/ensure-ffmpeg.sh - Python 3 con: scipy, tqdm, moviepy (solo para soporte de vista previa)
- Herramientas de línea de comandos: curl, git (para compilación de ffmpeg)
- Subagentes: Se requiere capacidad de spawn de procesos (Codex, Claude Code)
Referencias
- references/subtitle-proofreading.md — especificación completa de la tarea del subagente
scripts/merge-chunks.py— fusión de fragmentos y generación de SRTscripts/srt-to-ass.py— conversión de SRT a ASS con configuración CJKscripts/render-subtitles.sh— script de renderizado ffmpeg todo en unoscripts/ensure-ffmpeg.sh— compilación de ffmpeg optimizado para ARM64
Nota sobre el Estado Actual
03/2025: Todas las fases están verificadas como funcionales. La fase de renderizado ahora maneja correctamente la compilación de ffmpeg ARM64 con libass, la conversión SRT→ASS y la validación. Se han incorporado los obstáculos de la Fase 5 como comprobaciones automáticas. El problema de subtítulos "falta la última línea" está resuelto. Se debe agregar detección de subtítulos existentes y operación de solo edición de SRT.