CLAUDE.md

subtify

Genera subtítulos a partir de vídeos: descarga, extrae audio, transcribe, diariza, traduce e incrusta los subtítulos. Corre como Space de Hugging Face (Maximofn/subtify) sobre ZeroGPU.

Norma de documentación

Todo aprendizaje se documenta en este fichero. Si hay que investigar algo —una API, por qué falla un modelo, el formato raro que devuelve una librería— la conclusión se apunta aquí antes de seguir. El objetivo es no volver a investigar dos veces lo mismo.

Aplica también a los callejones sin salida: saber que algo no funciona y por qué ahorra tanto tiempo como saber qué funciona.

Objetivo del producto

Cuando hay varios hablantes, transcribir a cada uno por separado y pintar sus subtítulos en un color distinto.

A futuro, sobre esa misma base: traducir la transcripción, clonar la voz de cada hablante, generar TTS y hacer lipsync — es decir, a partir de un vídeo en un idioma, producir el vídeo en otro.

Por eso hacen falta timestamps por palabra, no solo por frase.

Arquitectura de modelos

Dos familias de modelos con papeles distintos:

• STT — transcribe con timestamps de palabra. Es la rejilla fina que necesitan la traducción, el TTS y el lipsync.
• STT+d — transcribe y diariza a la vez, devolviendo turnos de habla con etiqueta de hablante. Es lo que permite colorear por hablante.

Las dos salidas se cruzan por solapamiento temporal: cada palabra cae dentro del turno que la contiene.

Para la diarización no se confiará en un solo modelo: la idea es combinar varios métodos y contrastarlos.

Elección actual

Papel	Modelo	Por qué
STT principal	nvidia/parakeet-tdt-0.6b-v3	3-5× más rápido que Whisper turbo, hasta 5× menos VRAM, timestamps de palabra
STT fallback	openai/whisper-large-v3	Cubre los 99 idiomas; se usa cuando el idioma no está entre los 25 de Parakeet
Detección de idioma	openai/whisper-large-v3	Solo cuando el selector de idioma se deja vacío
STT+d	OpenMOSS-Team/MOSS-Transcribe-Diarize	Transcribe y diariza en una pasada con 2,4 GB

Benchmark de modelos STT (agosto 2026)

Medido sobre los vídeos del repo en ZeroGPU (H200). Spaces: Maximofn/subtify-stt-benchmark y Maximofn/subtify-stt-benchmark-qwen.

Podcast en español, 327 s, dos hablantes:

Modelo	Tiempo	RTFx	VRAM	Timestamps	Diariza
Cohere Transcribe	2,3 s	144×	4,9 GB	no	no
Parakeet TDT v3	22,1 s	14,8×	4,6 GB	palabra	no
Voxtral Mini 3B	24,9 s	13,1×	9,5 GB	no (ver abajo)	no
Qwen3-ASR 1.7B	35,9 s	9,1×	5,7 GB	palabra	no
MOSS-Transcribe-Diarize	46,4 s	7,0×	2,4 GB	frase	sí
Whisper large-v3-turbo	64,3 s	5,1×	24,2 GB	palabra	no
distil-whisper large-v3	66,5 s	4,9×	24,2 GB	palabra	no
Granite Speech 4.1 Plus	199,1 s	1,6×	4,3 GB	palabra	sí

Vídeo en inglés de 598 s: Parakeet 22,8 s frente a los 112,9 s de Whisper turbo — la ventaja crece con la duración, porque en clips cortos domina el arranque en frío.

distil-whisper/distil-large-v3 es solo inglés. Era el transcriptor por defecto y sobre audio en español no transcribía: traducía, y mal.

Trampas de cada modelo

Todas comprobadas en el benchmark; el código que las resuelve está en los Spaces.

Parakeet TDT v3

• El pipeline genérico de transformers no devuelve timestamps: es un transducer, no un seq2seq. Hay que usar AutoModelForTDT y processor.decode(sequences, durations=output.durations).
• Los timestamps son de subtoken BPE, no de palabra: 'Lo', 'ok', 'ing'. Hay que reagruparlos recorriendo el texto y consumiendo subtokens por longitud.
• Detecta el idioma automáticamente y no acepta que se lo fuercen.
• Cubre 25 idiomas europeos, no los 99 de Whisper.

MOSS-Transcribe-Diarize

• Su prompt por defecto está en chino. Sin pasarlo, el modelo no transcribe: se pone a traducir el audio a otro idioma.
• Sin add_generation_prompt=True ignora la instrucción de emitir timestamps y devuelve solo la etiqueta de hablante.
• Aguanta 90 minutos de una pasada. No trocear: al hacerlo, [S01] deja de referirse a la misma persona entre ventanas.
• Formato de salida: [inicio][Sxx]texto[fin].

Granite Speech 4.1 Plus

• En modo timestamps devuelve todo en minúsculas y sin puntuación. Hacen falta dos pasadas (una para el texto, otra para los tiempos) alineadas con SequenceMatcher.
• Los tiempos vienen en centisegundos módulo 1000: el contador se reinicia cada 10 segundos y hay que desenrollar el rollover.

Voxtral

• El modelo abierto vía transformers no da timestamps.
• La API de Mistral sí los da con timestamp_granularities=["word"], aunque entonces no admite fijar language a la vez. Son dos productos distintos.
• Hay una implementación funcionando en el proyecto del podcast (Welcome to La Secta, src/transcription/stt.py, clase VoxtralTranscriber).

Qwen3-ASR

• Su paquete qwen-asr fija transformers==4.57.6, incompatible con el 5.x que necesitan Parakeet y Cohere. Requiere un entorno aparte.
• El forced aligner devuelve objetos ForcedAlignItem, que no son indexables.
• El aligner cubre hasta 5 minutos: en audios más largos pierde palabras.

Descartados

• Canary-1B-v2: solo NeMo, dependencias incompatibles.
• Cohere Transcribe: el mejor texto y rapidísimo, pero sin timestamps.
• ARK-ASR-3B y Granite 4.1 2B a secas: sin timestamps.

ZeroGPU

• La GPU se presta solo mientras corre una función @spaces.GPU. El modelo hay que cargarlo dentro de la función, no al importar el módulo.
• Reserva crédito según el duration declarado, no según el uso real. Declarar 900 s aparta 900 s de cuota aunque se usen 20.
• No admite ejecuciones concurrentes: dos tareas a la vez agotan la asignación y fallan con «too many ZeroGPU credits allocated to running tasks».
• El wrapper cruza un proceso y solo propaga el nombre de la clase de excepción, sin traceback. Hay que capturar los errores dentro de la función decorada.
• El filesystem no sobrevive a un rebuild: los resultados hay que guardarlos fuera.
• Los modelos gated necesitan un secret HF_TOKEN en el Space.
• El decorador va en la función que calcula, no en la que construye la interfaz. En app.py estaba sobre subtify(), que solo monta los componentes de Gradio: la GPU se pedía al arrancar y se soltaba enseguida, así que las transcripciones corrían sin GPU. Ahora está sobre diarize() y trascribe_audio().

Descarga de vídeos

download.py importa pytube, que lleva años roto para YouTube. El módulo que funciona es youtube_download.py, con yt-dlp, y no siempre a la primera:

• El cliente por defecto puede dar 403 Forbidden.
• web, ios y tv a veces listan formatos que luego no sirven.
• Ningún cliente funciona siempre: en una prueba tiró mweb y en la siguiente hubo que caer a android. Por eso se recorre una lista de clientes en cascada.
• Para algunos vídeos solo queda el formato 18 (mp4 360p con audio incrustado); hay que bajarlo y extraer el audio con ffmpeg.

Desde el Space no se puede descargar de YouTube. Responde «Sign in to confirm you're not a bot»: es el bloqueo antibot contra IPs de centro de datos. La misma URL se descarga sin problema desde un ordenador de casa. En el Space, la vía que funciona es subir el fichero; la UI lo dice cuando detecta ese error.

Gradio

• El Space corre la versión que declara sdk_version en el README, no la de requirements.txt. Estaba en 5.13.2 (enero de 2025).
• Esa versión tiene un bug al convertir el esquema de los componentes: da TypeError: argument of type 'bool' is not iterable, tumba el endpoint /info y entonces todos los botones responden «No API found», aunque el evento esté bien registrado y la función jamás llegue a ejecutarse.
• app.py lo parchea en _patch_gradio_schema_bug(). La solución de fondo es subir sdk_version, y entonces el parche sobra.

Subida de ficheros al Space

Por API solo se aceptan ficheros .py. Los .md y .txt generan el commit pero llegan vacíos, sin aviso de error: por eso requirements.txt y este CLAUDE.md hay que editarlos a mano desde la web de Hugging Face.

Pendientes de investigar

• Modelo dedicado de identificación de idioma. Ahora se usa Whisper para detectar, lo que obliga a cargarlo (6-8 s) aunque luego transcriba Parakeet. Alternativa: speechbrain/lang-id-voxlingua107-ecapa (107 idiomas, ~25 M parámetros, milisegundos). Revisar cuando el pipeline esté funcionando.

• Inconsistencia de timestamps entre motores, para el lipsync. Whisper y Parakeet marcan el inicio de palabra de forma distinta: para «OpenAI», Whisper daba 0,00 s y Parakeet 0,16 s. Diferencias de 100-300 ms. Para subtítulos es irrelevante, pero el desfase audio-vídeo se percibe a partir de ~125 ms. Como un vídeo en español usaría Parakeet y uno en japonés Whisper, el sync tendría carácter distinto según el idioma, y una calibración del lipsync solo valdría para uno de los dos. Medir contra referencia antes de construir el doblaje.

• Diarización con más de dos hablantes. MOSS solo se ha probado con dos voces. Validar antes de apostar por él para sustituir a pyannote.