boyingliu01/bilingual-video-subtitles

Bilingual Video Subtitles 培训视频双语字幕

La canalización completa se encuentra en scripts/pipeline.py (único punto de entrada, con caché por etapa y capacidad de reanudación).

Nota sobre el entorno anfitrión: Este skill se ha adaptado para múltiples entornos; el backend de transcripción se selecciona automáticamente (Omni Gateway original del sandbox / API compatible con OpenAI / puente Whisper). Si no hay Omni Gateway ni backend configurado, se utiliza el modo agente: las etapas de transcribe/translate se suspenden con código de salida 3 y generan un manifest; después de completar la transcripción/traducción correspondiente, se ejecuta build nuevamente para reanudar. Es obligatorio leer el protocolo de operación y la configuración del backend en references/host-adaptation.md. Si el pipeline sale con código 3, no es un error; complete el trabajo indicado en el manifest y vuelva a ejecutar.

Flujo de trabajo estándar

1. Obtener entrada: archivo de vídeo + documento(s) de normativas/referencia (.docx/.txt/.md).
2. Leer el documento de referencia y crear un glosario glossary.txt (cada línea: Chino = Inglés, de 10 a 40 entradas). El glosario determina la consistencia de la traducción en todo el vídeo; debe cubrir: nombres de normativas, roles y abreviaturas (ej. PM=Project Manager), formularios comerciales y nombres de sistemas internos.
3. Ejecutar la construcción (en primer plano, con tiempo de espera suficiente; un vídeo de 50 minutos tarda entre 15 y 25 minutos en completarse):

python3 scripts/pipeline.py build \
  --video <ruta_del_video> --doc <ruta_del_documento> \
  --work <directorio_de_trabajo> --out <directorio_de_salida> \
  --glossary <glossary.txt> \
  --hotwords "安全红线,需求单,变更单,PM,QA,SRE" \
  --preview 90

4. Orden de generación (cada paso tiene caché; si falla, volver a ejecutar el mismo comando reanuda): setup (dividir audio) → transcribe (transcripción palabra por palabra con Qwen3-Omni) → timing (línea de tiempo con Whisper) → align (alineamiento por pinyin) → clean (eliminar lenguaje oral/separar oraciones) → translate (traducción por lotes chino-inglés) → package (archivo de proyecto + SRT + ASS) → render (vista previa + versión completa).
5. Primero usar la salida de --preview para que el usuario confirme los resultados (se puede usar media-read para extraer fotogramas y verificar la representación de subtítulos), luego entregar la versión completa del vídeo, SRT y archivo de proyecto de subtítulos.

Descripción de los entregables

Archivo	Uso
<nombre>_中英双语字幕_完整版.mp4	Vídeo con subtítulos duros (texto chino en blanco arriba, texto inglés en azul claro abajo, ambos con fondo semitransparente negro, legible en cualquier fondo)
<nombre>_中英双语字幕.srt	Archivo de subtítulos bilingües (se puede importar a reproductores/plataformas)
<nombre>_字幕工程.json	Datos maestros: contiene todas las líneas de tiempo y texto chino-inglés. Para ajustes anuales, solo se modifica esto
Directorio --work	Caché de productos intermedios (transcripción, línea de tiempo de Whisper). Conservarlo evita retranscripciones

Ajuste anual (actualizar subtítulos tras revisión de normativas)

Cuando la modificación de normativas solo afecta a unas pocas frases, no es necesario retranscribir:

1. El usuario indica los períodos/contenidos que necesitan modificación, o edita directamente el texto zh/en en el archivo <nombre>_字幕工程.json del año anterior (no modificar start/end si la línea de tiempo no cambia).
2. Volver a renderizar:

python3 scripts/pipeline.py render --project <proyecto.json> [--video <nuevo_video>] [--srt-only]

Si el nuevo vídeo tiene oraciones agregadas o eliminadas en capítulos correspondientes: ejecutar build --stage transcribe en el nuevo vídeo para obtener una nueva transcripción, comparar manualmente y reemplazar las entradas correspondientes en el archivo del proyecto, luego renderizar.

División de vídeos cortos por tema/rol (aprendizaje fragmentado)

Se basa en el vídeo completo ya subtitulado (conserva los subtítulos bilingües).

1. Localizar los límites de los capítulos a partir de los datos de subtítulos: usar la lista de roles/capítulos del documento de referencia como palabras clave para buscar frases de transición en zh_lines.json (directorio de trabajo). Patrones típicos: "El enésimo rol es X", "Lo anterior son las responsabilidades de X, el requisito es", "La situación de incumplimiento de X es", etc. El tiempo de inicio de la frase de transición es el punto de división (dicha frase se incluye en el siguiente episodio).
2. Restricciones: cada episodio ≤ 10 minutos (límite superior estricto de 15 minutos); si un capítulo excede el límite, se divide internamente en puntos naturales (ej. entre "responsabilidades/incumplimientos/métodos de determinación"); no combinar diferentes roles.
3. Escribir un plan de división en JSON y ejecutar:

{"base": "nombre_del_video", "lead_in": 0.35,
 "chapters": [{"start": 0, "end": 288.4,
                "title": "01_开篇_目的与概述", "note": "Descripción del contenido"}]}

python3 scripts/pipeline.py split --plan plan.json \
  --video <video_completo_subtitulado.mp4> --out <directorio_de_salida>

4. Salida en <directorio_de_salida>/<nombre_del_video>_拆分视频/: episodios nombrados automáticamente + 00_拆分目录.txt (nombre del clip, intervalo de tiempo, duración, descripción del contenido).
5. Verificación por muestreo: extraer fotogramas del inicio de cada episodio (ffmpeg para capturar PNG y revisar) para confirmar que el punto de división cae exactamente en la oración de apertura del tema correspondiente.

Convenciones clave de implementación (no desviarse)

• El backend de qwen-omni debe inyectar el documento de referencia completo en el prompt como contexto terminológico, con --timeout 900 --max-tokens 8192 (ya incluido en el script); los backends de ASR dedicado (como mimo-asr) no aceptan prompt de texto, la corrección terminológica depende de la etapa clean que compara con el documento.
• Whisper se usa solo para la línea de tiempo; su texto reconocido se descarta siempre (la calidad del texto en chino es pobre, pero las marcas de tiempo son precisas).
• El alineamiento debe ser global usando cadenas de pinyin (los errores de homófonos se resuelven automáticamente a nivel de pinyin); el alineamiento codicioso oración por oración provoca desviaciones generales.
• Calidad del alineamiento: qual mean ≥0.75 en la salida de align es normal; si <0.6, verificar primero la cobertura de voz de Whisper (ver references/troubleshooting.md).
• Las tareas largas de CPU (whisper/render) deben tener en cuenta la política de limpieza de tareas en segundo plano del anfitrión; ejecutar en primer plano si es necesario.
• Limitaciones de red: HuggingFace requiere un espejo; el script ya incluye HF_ENDPOINT=hf-mirror.com y HF_HUB_DISABLE_XET=1, no eliminar.

Solución de problemas

Ver references/troubleshooting.md: escenarios como tiempo de espera de carga, transcripción de líneas largas únicas, baja calidad de alineamiento, caracteres ilegibles en fuentes, fallos de renderizado, etc.