auto-subtitle

AutoSubtitle AI - Guía de Automatización y Skill para Agentes

Esta skill te guía sobre cómo automatizar la extracción de subtítulos, la transcripción de voz a texto, la alineación forzada de letras (tubería Luna), la corrección local con LLM y el quemado de subtítulos en video con aceleración GPU, utilizando la CLI auto-subtitle y el backend FastAPI.

---

📌 Matriz de Decisión del Flujo de Trabajo

Elige el comando o la tubería adecuada según tus activos de entrada:

Escenario / Objetivo	Comando Recomendado	Argumentos Clave
Alineación de Canciones / Letras (Medio + letras .txt)	python src/cli/main.py luna (o align)	<media> <lyrics.txt> --llm local/api -o <dir>
Habla / Conversación / Video a Subtítulos (Sin guion)	python src/cli/main.py pipeline	<media> -d cuda -o <dir>
Extracción Solo de Audio	python src/cli/main.py extract	<video> -o <audio.wav> --sr 16000
Corregir Errores / Homófonos (con Edge LLM)	python src/cli/main.py proofread	<subtitles.srt> --gpu-layers -1
Quemar Subtítulos en Video (Hardsub)	python src/cli/main.py burn	<video> <subtitles.srt> --css "..."
Gestionar Fuentes (Instalar fuentes de código abierto/Windows)	python src/cli/main.py fonts	list, install <id/path/url>, remove <filename>
Iniciar Web Studio	python src/cli/main.py serve	--host 0.0.0.0 --port 8000

---

🛠️ Referencia de Comandos CLI

1. Tubería de Letras Luna (luna / align)

Ejecuta el pipeline de verificación dual de 5 pasos: extracción de características acústicas de Whisper + alineación stable-ts + auditoría con LLM Decision Brain + relleno de legibilidad de +0.16s:

python src/cli/main.py luna inputclip/test_video.mp4 inputclip/audio-org.txt \
    --llm local \
    --output-dir output_luna

Archivos de salida en --output-dir:

• lyrics.srt: Pista de subtítulos SRT estándar.
• lyrics.vtt: Formato WebVTT para reproductores web.
• lyrics.lrc: Formato LRC mejorado con marcas de tiempo en milisegundos para reproductores de música.
• lyrics.ass: Subtítulos ASS formateados listos para el quemado con FFmpeg.
• cue_evidence.json: Evidencia acústica completa y métricas de confianza por línea.
• review.csv: Informe detallado de líneas anómalas y decisiones de arbitraje del LLM.
• run_manifest.json: Hashes SHA-256 de integridad del medio fuente y las salidas.

2. Tubería de Habla de Extremo a Extremo (pipeline)

Pipeline automático de habla para programas de entrevistas, podcasts y conferencias:

python src/cli/main.py pipeline inputclip/test_video.mp4 \
    --device cuda \
    --prompt "Traditional Chinese" \
    --max-chars 16 \
    --pause 0.45 \
    --output-dir output/

3. Corrección con Edge LLM (proofread)

Ejecuta Qwen2.5-3B-Instruct GGUF local con descarga a GPU para corregir errores de reconocimiento de habla:

python src/cli/main.py proofread output/video.srt \
    --gpu-layers -1 \
    --batch-size 8 \
    --output output/video.proofread.srt

4. Quemado de Video Hardsub con GPU (burn)

Quema subtítulos ASS estilizados directamente en los fotogramas del video con aceleración GPU NVIDIA NVENC:

# Usando una cadena CSS inline (Soporta opacidad, contorno exterior, fuente, relleno de modelo de caja, colores)
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --css "font-family: 'Noto Sans CJK TC'; font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000; text-shadow: 2px 2px 3px #000; padding: 40px 40px 60px 40px;" \
    -o output/final_burned.mp4

# O usando una hoja de estilo CSS externa:
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --css-file styles/youtube_style.css \
    -o output/final_burned.mp4

# O usando banderas explícitas:
python src/cli/main.py burn inputclip/test_video.mp4 output/lyrics.srt \
    --font "jf-openhuninn-2.0" \
    --size 38 \
    --color "#FFFFFF" \
    --opacity 0.9 \
    --outline 3.0 \
    --outline-color "#000000" \
    --direction horizontal \
    --valign bottom \
    --halign center

5. Gestión de Fuentes (fonts)

# Listar todas las fuentes disponibles, instaladas y del sistema Windows
python src/cli/main.py fonts list

# Instalar fuentes populares de código abierto por ID predefinido:
# Opciones: openhuninn (粉圓體), lxgw-wenkai (霞鶩文楷), iansui (芫荽體), win-msjhbd (微軟正黑粗體)
python src/cli/main.py fonts install openhuninn

# Instalar desde URL o archivo local:
python src/cli/main.py fonts install https://example.com/font.ttf
python src/cli/main.py fonts install /path/to/custom_font.otf

---

🤖 Recetas de Automatización

Receta 1: Procesar por Lotes Todos los Videos en un Directorio (Bash)

#!/usr/bin/env bash
set -e
INPUT_DIR="./raw_videos"
OUTPUT_DIR="./dist_videos"
mkdir -p "$OUTPUT_DIR"

for video in "$INPUT_DIR"/*.mp4; do
  [ -f "$video" ] || continue
  filename=$(basename "$video")
  stem="${filename%.*}"
  lyrics="$INPUT_DIR/$stem.txt"
  
  echo "🚀 Procesando: $filename"
  
  if [ -f "$lyrics" ]; then
    # Pipeline con letras escritas
    python3 src/cli/main.py luna "$video" "$lyrics" --output-dir "$OUTPUT_DIR/$stem" --llm local
    sub_file="$OUTPUT_DIR/$stem/lyrics.srt"
  else
    # Pipeline de habla sin guion
    python3 src/cli/main.py pipeline "$video" -d cuda --output-dir "$OUTPUT_DIR/$stem"
    sub_file="$OUTPUT_DIR/$stem/$stem.srt"
  fi
  
  # Quemar hardsubs con estilo de marca
  python3 src/cli/main.py burn "$video" "$sub_file" \
    --css "font-size: 34px; color: #FFFFFF; opacity: 0.9; -webkit-text-stroke: 2.5px #000; text-shadow: 2px 2px #000;" \
    -o "$OUTPUT_DIR/${stem}_subtitled.mp4"
    
  echo "✔ Finalizado: $stem"
done

Receta 2: Script de Python para Generación de Subtítulos

from pathlib import Path
from src.core.luna_pipeline import run_luna_pipeline
from src.core.video_burner import burn_subtitles_to_video
from src.schemas.subtitle import SubtitleStyle

media_file = "inputclip/test_video.mp4"
lyrics_file = "inputclip/audio-org.txt"
out_dir = Path("output_automation")

# 1. Ejecutar el Pipeline de Verificación Dual Luna
track = run_luna_pipeline(
    audio_path=media_file,
    lyrics_source=lyrics_file,
    output_dir=str(out_dir),
    llm_provider="local"
)

# 2. Definir el estilo de subtítulos con opacidad y contorno exterior
style = SubtitleStyle.from_css(
    "font-size: 36px; color: #FFD700; opacity: 0.85; -webkit-text-stroke: 3px #000;"
)

# 3. Quemar subtítulos directamente con GPU NVENC
burned_mp4 = burn_subtitles_to_video(
    video_path=media_file,
    subtitles_source=str(out_dir / "lyrics.srt"),
    output_path=str(out_dir / "burned_output.mp4"),
    style=style,
    use_gpu=True
)
print(f"Video quemado creado: {burned_mp4}")

Receta 3: Integración con API REST (FastAPI)

El servidor se ejecuta en http://localhost:8000:

• Transcribir / Sin Guion: POST /api/ai/transcribe con campos de formulario media_path=..., auto_proofread=true
• Alinear / Pipeline Luna: POST /api/ai/align con JSON {"media_path": "...", "script_text": "...", "script_mode": "reference", "llm_provider": "local"}
• Analizar CSS: POST /api/style/parse-css con JSON {"css": "font-size: 36px; opacity: 0.8;"}
• Quemar Video: POST /api/burn con JSON {"video_path": "...", "subtitle_path": "...", "css": "..."}

---

🎨 Modelo de Caja CSS y Mapeo de Estilos ASS

Al diseñar estilos de subtítulos con --css:

Propiedad CSS	Traducción a Formato ASS	Notas
opacity: 0.85	Invertir alpha hex &H26FFFFFF&	Alpha = redondear((1 - opacidad) * 255). 0=opaco, 255=transparente.
-webkit-text-stroke: 4px #000	Outline: 2.0, OutlineColour: &H00000000&	Con paint-order: stroke fill;, el trazo crece solo hacia afuera.
text-shadow: 2px 2px 3px #000	Shadow: 2.0, BackColour: &H80000000&	Usa el desplazamiento absoluto del eje más grande; los CSS de ejes iguales no tienen deriva.
writing-mode: vertical-rl	Diseño de columnas verticales con saltos \N	Se ajusta automáticamente de derecha a izquierda cuando supera la altura de la ventana.
text-align: center/left/right	Mapeo a cuadrícula de 9 posiciones (1~9)	Centro-inferior = 2, Centro-superior = 8, Centro-medio = 5.
padding: 50px 40px 60px 40px	MarginV, MarginL, MarginR	Convertido a márgenes en píxeles ASS relativos a la resolución PlayRes.

---

⚠️ Notas de Implementación Importantes

1. Aceleración GPU:
   • Whisper: Toda la inferencia (con guion, sin guion y sincronización de línea de tiempo) utiliza Whisper large-v3-turbo nativo. El modelo y el backend son fijos; no pases opciones de modelo o tipo de cómputo.
   • Quemado de Video: Por defecto use_gpu=True intenta FFmpeg h264_nvenc. Usa la CLI --cpu para libx264 si NVENC no está disponible en tiempo de ejecución.
2. Cadenas de Varias Líneas de Letras vs. Rutas de Archivo:
   • run_luna_pipeline acepta tanto una ruta de archivo (.txt) como una cadena de letras sin procesar de varias líneas; la CLI toma una ruta TXT. Las cadenas de varias líneas se analizan directamente sin verificar la ruta del sistema de archivos.
3. Sin Sobrescritura de Subtítulos Fuente:
   • Al generar .srt o .vtt, las salidas se escriben en el directorio de salida destino o se sufijan con .generated.srt si ya existe un archivo con el mismo nombre.