ZJU-REAL/Easel

Subtítulos automáticos (voz a subtítulos)

Convierte la voz de un archivo de audio/video en subtítulos. Basado en el script compartido skills/shared/scripts/asr.py (envoltura de faster-whisper), con parámetros deterministas y reproducibles, con segmentación de oraciones amigable para chino. Opcionalmente, puede incrustar los subtítulos en el video (reutilizando skills/shared/scripts/video_ops.py / filtro subtitles de ffmpeg).

Solo hace "voz → archivo de subtítulos (+ incrustación opcional)". Para edición general de video, consulta video-editing; para reducción de ruido pura, consulta audio-denoise; para cortes inteligentes de video largo con incrustación de subtítulos, consulta clipify.

Entrada

Campo	Obligatorio	Descripción
input_file	Sí	Ruta del archivo de audio o video (el video extrae automáticamente la pista de audio)
format	No	srt (predeterminado) / ass / txt / json
language	No	auto (predeterminado) o código ISO 639-1 como zh/en
model	No	tiny/base (predeterminado)/small/medium/large-v3, cuanto más grande, más preciso pero más lento
burn	No	Si se deben incrustar los subtítulos en el video (requiere entrada de video)

Soporta: audios mp3/wav/m4a/aac/flac; videos mp4/mkv/mov/webm.

Salida

• Archivos de subtítulos en outputs/nombre_del_tema/ (SRT/ASS/TXT/JSON)
• Si se incrusta: video con subtítulos duros (*-sub.mp4)
• Informe: idioma detectado, número de líneas de subtítulos, modelo utilizado, rutas de salida

Requisitos previos

• En la primera ejecución, descarga los modelos desde HuggingFace, se necesita proxy de internet. El script lee la variable de entorno EASEL_PROXY o http(s)_proxy como proxy; si ninguna está configurada, se conecta directamente. También se puede especificar con export https_proxy=... http_proxy=....
• En entornos CPU, usa por defecto --device cpu --compute-type int8.

Pasos de ejecución

Rutas de los scripts (relativas a la raíz del proyecto): skills/shared/scripts/asr.py, skills/shared/scripts/video_ops.py.

1. Generar archivo de subtítulos

# Video → SRT (extracción automática de pista de audio + detección automática de idioma)
python skills/shared/scripts/asr.py transcribe \
  -i input.mp4 -o outputs/nombre_del_tema/input.srt --language zh

# Video → ASS (con estilo, **tamaño de fuente/margen adaptativo según orientación del video**): para entrada de video, detecta automáticamente el ancho y alto
python skills/shared/scripts/asr.py transcribe \
  -i input.mp4 -o outputs/nombre_del_tema/input.ass --format ass --model small
# Solo audio → ASS: no puede detectar dimensiones, por defecto vertical 1080x1920; horizontal añadir --res 1920x1080
python skills/shared/scripts/asr.py transcribe \
  -i voice.mp3 -o outputs/nombre_del_tema/voice.ass --format ass --res 1920x1080

• El estilo ASS se adapta automáticamente a las dimensiones del video de destino: el tamaño de fuente se basa en el lado más corto (min(w,h)*0.05, adecuado tanto para vertical como horizontal), el margen inferior según la altura, los márgenes laterales según el ancho, y PlayRes = dimensiones reales. Para entrada de video, se detecta automáticamente; para solo audio, usa --res ancho x alto. Para subtítulos duros con estilo, es preferible usar este ASS (sección siguiente), es más cómodo y se adapta automáticamente en comparación con SRT plano + force_style manual.
• Chino: por defecto ~18 caracteres por línea, las líneas muy largas se dividen/separan automáticamente; se puede ajustar con --max-line-chars.
• Si no se da -o, se crea un directorio de proyecto basado en el nombre del archivo de entrada, por ejemplo, talk.mp4 produce salida en outputs/talk/talk.srt; para proyectos existentes, usar explícitamente -o outputs/nombre_del_tema/<nombre_archivo>.<formato>.
• Ver modelos/idiomas disponibles: python skills/shared/scripts/asr.py info.

2. (Opcional) Incrustar subtítulos en el video

Cuando el usuario solicite "subtítulos duros/incrustar en video", usa los filtros subtitles (SRT) o ass (ASS) de ffmpeg:

# Incrustar SRT (estilo personalizable)
ffmpeg -y -i input.mp4 \
  -vf "subtitles=outputs/nombre_del_tema/input.srt:force_style='FontName=Noto Sans CJK SC,FontSize=20,PrimaryColour=&H00FFFFFF,OutlineColour=&H80000000,BorderStyle=1,Outline=2'" \
  -c:a copy outputs/nombre_del_tema/input-sub.mp4

# Incrustar ASS (el estilo ya está en el archivo ASS, fiel)
ffmpeg -y -i input.mp4 \
  -vf "ass=outputs/nombre_del_tema/input.ass" \
  -c:a copy outputs/nombre_del_tema/input-sub.mp4

• Si la ruta contiene caracteres especiales, envuelve el valor de subtitles= entre comillas simples y escapa los dos puntos.
• Para subtítulos suaves (se pueden desactivar) en lugar de incrustados: ffmpeg -i in.mp4 -i sub.srt -c copy -c:s mov_text out.mp4.

3. Producto e informe

• Los archivos de subtítulos y el video incrustado se escriben en outputs/nombre_del_tema/.
• Informar al usuario: idioma detectado, número de líneas de subtítulos, modelo, rutas de archivos; sugerir que se puede re-ejecutar con --model/--max-line-chars.

Reglas

1. Extraer primero la pista de audio del video — el script usa ffmpeg automáticamente para extraer un wav mono de 16kHz, sin modificar el video original.
2. Segmentación de oraciones amigable para chino — divide líneas según puntuación/longitud, evitando líneas demasiado largas.
3. Nunca eliminar el archivo original — solo crea nuevos archivos en outputs/.
4. Selección de modelo — para rapidez usa base, para precisión usa small/medium; CPU usa int8.
5. Incrustación requiere entrada de video — solo audio no se puede incrustar, solo genera archivos de subtítulos.
6. Sin dependencia de perfil — la transcripción no necesita perfil de usuario.

Referencias

• SYSTRAN/faster-whisper — Inferencia Whisper acelerada con CTranslate2
• openai/whisper — Modelo Whisper original y método ASR
• Filtros subtitles / ass de FFmpeg (incrustación de subtítulos)