agent-caption

agent-caption — SKILL

Eres un agente de subtitulado de IA. Este repositorio añade subtítulos precisos y perfectamente sincronizados a cualquier video o audio, en cualquier idioma (inglés por defecto), tanto para voz como música, con soporte de primera clase para Hinglish / cambio de código. Funciona en Windows, macOS y Linux.

Repositorio: https://github.com/ahkamboh/agent-caption — clonar: git clone https://github.com/ahkamboh/agent-caption Este archivo, en bruto (para que agentes de chat lo obtengan): https://raw.githubusercontent.com/ahkamboh/agent-caption/master/SKILL.md

Principio fundamental: las palabras provienen del reconocimiento de voz, pero el TIEMPO proviene de la alineación forzada en la forma de onda — nunca de marcas de tiempo ASR sin procesar. Así los subtítulos nunca se adelantan o atrasan, incluso si la transcripción tiene errores ortográficos.

Configuración única (Windows / macOS / Linux)

Requiere: Python 3.10+, ffmpeg, ~4 GB de disco. (torch proporciona ruedas hasta 3.14; si whisperx carece de una rueda en una versión nueva de Python, usa 3.11–3.12).

python setup.py        # multiplataforma: crea ./.venv-whisperx e instala todo
# macOS/Linux conveniencia: bash setup.sh      ·     Windows conveniencia: setup.bat

ffmpeg: macOS brew install ffmpeg · Ubuntu sudo apt install ffmpeg · Windows winget install ffmpeg. Los modelos (Whisper large-v3 — el predeterminado — MMS_FA, whisperX) se descargan automáticamente al primer uso.

Ruta más fácil — el envoltorio de un solo comando (PREFIERE ESTO)

Para solicitudes de "subtitular este video", simplemente ejecuta el envoltorio de nivel superior. Hace: transcribir → alinear → quemar con subtítulos de proporción automática (tamaño/espaciado/alineación correctos para cualquier resolución), y en caso de que el ffmpeg del usuario no tenga soporte de subtítulos, recurre a un renderizador sin libass (Pillow + overlay):

python caption.py <video>                                  # Inglés, limpio, proporcionado -> <video>.captioned.mp4
python caption.py <video> --hinglish --style tiktok        # Hinglish + caja TikTok
python caption.py <video> --lang ur --pos center --size 6  # otro idioma / colocación / tamaño
python caption.py <video> --srt                            # solo escribe un .srt (sin quemar)
python caption.py <video> --from-srt FILE                  # quema un .srt existente, proporcionado

15 estilos (fuentes incluidas): clean (predeterminado) bold hormozi green beast impact bebas tiktok pill boxed yellow neon gradient minimal subtitle. Recurre a los scripts individuales a continuación solo cuando necesites la transcripción sin procesar, renderizado personalizado o traducción.

Modelo: large-v3 es el PREDETERMINADO (mejor precisión) — no se necesita indicador; setup.py lo precarga. ¿Quieres velocidad en inglés limpio? añade --fast (modelo pequeño). --accurate aún existe pero ahora es redundante. La ruta Hinglish siempre usa large-v3.

Estilo personalizado — construye CUALQUIER aspecto que el usuario describa. Asigna las palabras del usuario a estos indicadores (anulan --style):

• --font <nombre|ruta> — una fuente incluida (Poppins-Bold, Poppins-Black, Anton-Regular, BebasNeue-Regular, ArchivoBlack-Regular) o cualquier ruta .ttf
• --fill #hex (color del texto) · --outline #hex · --box #hex|#hexAA|none (fondo detrás del texto)
• --caps / --no-caps · --gradient "#hex,#hex,#hex" · --glow · --ow N (grosor del contorno)
• --size <pct> (altura) · --pos bottom|center|top

Ejemplo — el usuario dice "mayúsculas rosa intenso en una caja oscura redondeada, grande, fuente Anton" →

python caption.py v.mp4 --fill "#ff3da6" --box "#10141ae0" --caps --font Anton-Regular.ttf --size 6

Para hacer permanente un nuevo estilo con nombre, añade una entrada al diccionario STYLES en caption.py.

Precisión — elimina palabras mal escuchadas (gratuito, sin tokens, sin revisión humana)

La alineación forzada hace que la temporización sea correcta por construcción. Lo único que no puede corregir es si una palabra fue escuchada correctamente ("su" en lugar de "sur", nombres, jerga). Tres palancas gratuitas acercan eso a cero:

• --glossary "..." — proporciona nombres/marcas/jerga (una lista o una ruta .txt). Influye en la pista inicial de ASR para que los nombres propios dejen de ser malinterpretados. El mayor beneficio con nombres. Lista única.

  python caption.py talk.mp4 --glossary "Xaibridge, Hinglish, Xotion, Kamboh"
  

• --script ARCHIVO — si las palabras correctas ya existen (letras, un guion), pásalas. La herramienta salta el ASR por completo y solo alinea a la fuerza las palabras dadas → precisión del contenido del 100%.

  python caption.py song.mp4 --script lyrics.txt
  

• --grammar — pasada local de homófonos/gramática sobre los subtítulos ("su" → "sur", "tu" → "tú"). Ejecuta LanguageTool localmente (sin subida, sin tokens); nunca afecta la temporización. Dependencia opcional — actívala una vez con python setup.py --grammar (necesita Java/JRE 8+); se salta limpiamente si está ausente.

  python caption.py talk.mp4 --accurate --glossary names.txt --grammar    # apíla los
  

Orden relación calidad-precio: --glossary (nombres) → --script (cuando el texto existe) → --grammar (homófonos). El modelo base ya es large-v3 por defecto. El único residuo que estos no pueden capturar necesita un humano o un LLM — ese es el único costo que vale la pena gastar tokens, y solo en las palabras marcadas, no en toda la transcripción.

Canciones — aísla la voz primero (--content)

Para música, separar la pista vocal antes del ASR hace que la transcripción de letras sea mucho más limpia (Whisper deja de luchar contra la pista de acompañamiento). Es condicional — inútil/lento en voz limpia — por lo que está controlado:

python caption.py song.mp4 --content music                 # fuerza el aislamiento vocal (demucs)
python caption.py clip.mp4                                  # --content auto (predeterminado): detecta música, aísla solo entonces
python caption.py podcast.mp4 --content speech              # nunca aislar (o --no-isolate)
python caption.py song.mp4 --content music --script lyrics.txt   # canciones más limpias: palabras conocidas, temporizadas en la pista vocal

auto ejecuta un sondeo rápido de música/voz y aísla SOLO cuando detecta música — así los podcasts/entrevistas nunca se ralentizan. La quema siempre usa el video original; solo transcribimos/alineamos la pista. Necesita demucs (instalado por python setup.py); recurre al audio original si está ausente.

Siempre ejecuta los scripts con el python del entorno virtual — escrito aquí como PY:

• macOS / Linux: PY = ./.venv-whisperx/bin/python
• Windows: PY = .venv-whisperx\Scripts\python

Los scripts

• transcribe.py — Whisper → transcripción a nivel de palabra (inglés predeterminado; --lang xx para otros idiomas).
• align.py — alineación forzada para temporización precisa por fotograma. --code-switch para Hinglish/mixto.
• cs_transcribe.py — reconocimiento de palabras robusto para cambio de código (identificación de idioma por segmento).
• mms_align.py — alineador forzado universal MMS_FA (más de 1100 idiomas, cualquier escritura).
• validate_timing.py — verificación de cordura de temporización utilizada por la ruta de cambio de código.
• export-subs.py — transcripción → .srt + .vtt.
• multilang-subs.py — traduce subtítulos a muchos idiomas, sin conexión.
• grammar_fix.py — corrección local de homófonos/gramática en un .srt (temporización preservada); utilizado por --grammar.
• isolate_vocals.py — aislamiento vocal Demucs para canciones + un sondeo de música vs voz; utilizado por --content.
• qa.py — puerta de control de calidad determinista rápida (verificación de cordura de señal + salida de ffprobe) → work/<base>.qa.json. Se ejecuta automáticamente después de cada quema; --strict hace que una salida defectuosa salga con código de error distinto de cero.
• footprint.py — renderiza <base>.footprint.svg: un mapa de salud de subtítulos de un vistazo (cada palabra coloreada por la confianza de alineación forzada + marcadores de espacio + veredicto). Se ejecuta automáticamente después de cada subtítulo; --no-footprint para omitir.
• benchmark.py — mide la ganancia real de precisión: WER del antiguo predeterminado (pequeño) vs el nuevo predeterminado (large-v3 [+ Demucs]) contra una transcripción de referencia. PY scripts/benchmark.py CLIP --ref truth.txt [--music] [--hinglish].
• caption.py — subtítulos estilizados integrales (karaoke/palabra/línea; Hormozi/TikTok/neon…) → captions.js animado.

Subtitular un video (la tarea principal) — idioma predeterminado = Inglés

Para otro idioma, pasa --lang <código>. Para Hinglish / mixto usa --code-switch.

1) Temporizaciones de palabra precisas por fotograma

Voz (charla, podcast, UGC):

PY scripts/align.py INPUT --lang en --out work/transcript.json

Hinglish / hindi-inglés mixto (o cualquier audio con cambio de código):

PY scripts/align.py INPUT --code-switch --dual hi en --out work/transcript.json

Cualquier otro idioma (urdu, español, árabe, chino, …):

PY scripts/align.py INPUT --lang ur --out work/transcript.json

2a) Subtítulos (.srt / .vtt) + quemar en el video

PY scripts/export-subs.py work/transcript.json --out work/subs
ffmpeg -i INPUT -vf "subtitles=work/subs.srt" -c:a copy captioned.mp4

El .srt también es perfecto para subir directamente a YouTube (seleccionable + SEO).

2b) Subtítulos estilizados / animados (Hormozi, TikTok, karaoke — formato corto)

PY scripts/caption.py INPUT --lang en --content speech --style karaoke --preset hormozi --out out/

Preajustes: hormozi, beast, pill, neon, gradient, minimal, tiktok. Usa --content music para canciones/letras. Consulta docs/caption-styles.md.

3) Traducir subtítulos a cualquier idioma (opcional)

PY scripts/multilang-subs.py work/subs.srt --to "hi,ur,es,fr,ar,de" [--burn INPUT]

Reglas (integradas — no anular)

• La temporización es SIEMPRE alineación forzada, nunca marcas de tiempo ASR sin procesar (sin adelanto/retraso).
• Idioma predeterminado de los subtítulos = Inglés; pasa --lang para cualquier otro.
• Música/canto → --content music; voz/charla → --content speech.
• Ejecuta cada script con PY (el python del entorno virtual) para que tenga whisperx/torch.
• Antes de entregar, verifica rápidamente algunos subtítulos en sus inicios de palabra para confirmar la sincronización.

Códigos de idioma

en (predeterminado), hi, ur, pa, es, fr, de, pt, ar, zh, ja, ko, ru, it, tr, id, nl, pl, uk, … — Whisper admite ~99 idiomas; MMS_FA alinea más de 1100.