zaddy99999/captions

¿Qué hace captions?

Transcripción local a nivel de palabra, estilizado de subtítulos para formato corto e incrustación.

Los scripts están en scripts/:

Script	Función
transcribe.py	faster-whisper con word_timestamps=True a words.json (en caché)
make-captions.mjs	words.json a ASS (estilizado, resaltado de palabra activa) y SRT
burn.mjs	incrusta ASS/SRT con libass (filtro ass / subtitles)
snap-to-words.mjs	mueve los puntos de corte al espacio más cercano entre palabras

Flujo de trabajo

1. Transcribir (una vez por fuente; el resultado se guarda en caché):

   pip install faster-whisper            # una vez
   python3 scripts/transcribe.py --input clip.mp4 --out edit/clip.words.json --model small --language en
   

   La primera ejecución descarga el modelo desde Hugging Face. Si está bloqueado, el script termina con código 4 y un mensaje JSON fix en lugar de un traceback; nunca escribe una transcripción falsa. Apunta --model a una carpeta de modelo CTranslate2 local para trabajar sin conexión.
2. Generar subtítulos:

   node scripts/make-captions.mjs --words edit/clip.words.json --out-ass edit/clip.ass --out-srt edit/clip.srt
   

   El estilo proviene del paquete de marca (bloque captions: tamaño, margen, contorno, resaltado; colors.accent es el color de la palabra activa).
3. Incrustar como el último paso visual:

   node scripts/burn.mjs --input edit/clip-hook.mp4 --subs edit/clip.ass --out edit/clip-captioned.mp4
   

   Usa --fonts-dir cuando la fuente del subtítulo sea un archivo en lugar de una fuente instalada.
4. Verificar con una hoja de prueba render-qc: legible, dentro del área segura, sin superponerse a la placa de enganche.

Reglas

• Nunca cortes dentro de una palabra. Antes de dividir el habla, ajusta los cortes a los espacios entre palabras: node scripts/snap-to-words.mjs --words edit/clip.words.json --markers edit/cuts.json --out edit/cuts.json
• Los subtítulos van al final: después de cortes, superposiciones y color. Si recortas el clip después de transcribir, pasa --offset -<segundos recortados> a make-captions.mjs.
• De 1 a 3 palabras por fragmento para videos cortos (maxWords, maxChars). Los fragmentos se dividen por puntuación y pausas.
• Mantén los subtítulos fuera del ~15% inferior (interfaz de plataforma) y alejados de la placa de enganche: ajusta captions.marginV.
• Las transcripciones se almacenan en caché: vuelve a ejecutar con --force solo cuando el audio haya cambiado.
• Verifica las palabras contra el audio; whisper puede malinterpretar nombres y jerga. Corrige words.json manualmente si es necesario.

Sin ffmpeg libass

Si burn.mjs informa que no hay filtro ass, la compilación de ffmpeg carece de libass. Instala una compilación completa (la mayoría de los gestores de paquetes incluyen una), o sube el SRT como una pista de subtítulos separada en lugar de incrustarlo.