video-captioner — Pipeline de Subtítulos Animados
Transcribe el habla con Whisper e incrusta subtítulos animados palabra por palabra en videos. No realiza corrección de color — para mejora visual usa primero el skill video-enhancer.
Pipeline
video de entrada → transcripción Whisper → renderizado de subtítulos pycaps → video de salida con subtítulos
Estilos de subtítulos
Tres opciones:
- Predeterminado (sin flag) — estilo minimalista integrado de pycaps: texto blanco plano, sin efectos.
- Futurista (incluido) —
--css scripts/futuristic.css— subtítulos alternando oro/magenta con efecto brillo y fuente monoespaciada. Ideal para contenido tech, gaming o de alta energía. - Personalizado — el usuario puede proporcionar cualquier ruta de archivo CSS mediante
--css /ruta/a/personalizado.css.
Si el usuario no ha mencionado un estilo de subtítulos, pregunta si desea el aspecto predeterminado, el estilo futurista o un archivo CSS personalizado.
Subtítulos estáticos
Usa --caption para añadir texto predefinido en marcas de tiempo específicas en lugar de transcribir audio:
--caption "INICIO-FIN: TEXTO"
Formato:
- Las horas usan formato
M:SSoMM:SS(ej.,0:05= 5 segundos,1:30= 90 segundos) - Múltiples subtítulos: usa
--captionvarias veces - Si se proporcionan tanto subtítulos estáticos como transcripción, los estáticos tienen prioridad
Ejemplo:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hola mundo" \
--caption "0:10-0:20: Esto es una demo" \
--css scripts/futuristic.css
Estilizado de subtítulos
El estilizado se gestiona mediante archivos de configuración JSON. Al usar subtítulos estáticos, el estilo se aplica automáticamente.
Estilo predeterminado
Cuando no se especifica --style-config, se usa config.default.json:
- Fondo: blanco (
#FFFFFF) - Color de texto: azul (
#0066FF) - Fuente:
auto— usa primero una fuente de marca disponible etiquetada comocaption, luego recurre a Courier New - Padding:
10px 15px - Margen:
0
Usando una configuración de estilo
Cambia estilos pasando un archivo de configuración:
# Usar estilo modo oscuro
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hola" \
--style-config config.dark-mode.json
Configuraciones incluidas:
config.default.json— fondo blanco, texto azul, Courier New (predeterminado)config.dark-mode.json— fondo oscuro, texto blanco, fuente más grande
Creando configuraciones de estilo personalizadas
Copia config.default.json y modifica:
{
"caption_bg_color": "#000000",
"caption_color": "#FFFFFF",
"caption_font": "auto",
"caption_font_tag": "caption",
"caption_padding": "20px 30px",
"caption_margin": "10px",
"caption_font_size": 48
}
Luego úsalo:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Texto" \
--style-config mi-estilo-personalizado.json
Sobrescribiendo configuración con flags CLI
Los flags CLI tienen prioridad sobre los valores del archivo de configuración:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hola" \
--style-config config.dark-mode.json \
--caption-color "#00FF00" # Sobrescribe el color de texto de la configuración
Referencia de configuración de estilo
| Clave | Tipo | Descripción |
|---|---|---|
caption_bg_color | string | Color de fondo (hex o nombre de color CSS) |
caption_color | string | Color de texto (hex o nombre de color CSS) |
caption_font | string | auto, familia de fuente, o ruta a archivo .ttf, .otf, .woff, .woff2 |
caption_font_tag | string o null | Etiqueta de fuente de marca a preferir desde brand-manager (caption, body, heading, etc.) |
caption_padding | string | Padding CSS (ej., "10px 15px") |
caption_margin | string | Margen CSS (ej., "0") |
caption_font_size | integer o null | Tamaño de fuente en píxeles (null = autoescalado) |
Fuentes disponibles
Se pueden especificar fuentes del sistema por nombre:
DejaVu Sans/DejaVu Sans Bold/DejaVu SerifLiberation Sans/Liberation MonoCourier NewUbuntu Mono- Cualquier ruta de archivo TTF:
/ruta/a/fuente.ttf
O elegir entre fuentes de marca en skills/brand-manager/brand-assets/asset-manifest.json.
Cuando caption_font es auto, el skill lee el manifiesto de marca (o CLAW_BRAND_ASSETS_DIR si está configurado) y usa la primera fuente disponible etiquetada por caption_font_tag; si no existe dicha fuente, prueba fuentes de marca etiquetadas como caption, body, heading o bold, luego recurre a Courier New. Si la fuente de marca resuelta es una ruta de archivo, el CSS generado incluye una regla @font-face para que pycaps pueda renderizarla.
Cómo ejecutar
Instala dependencias (solo la primera ejecución):
cd "$SKILL_DIR" && uv sync
Nota: la primera ejecución será lenta (potencialmente varios minutos) porque pycaps descarga el modelo de reconocimiento de voz Whisper. Adviérteselo al usuario antes de comenzar.
Luego procesa videos:
cd "$SKILL_DIR" && uv run python scripts/caption_service.py \
--input <ruta/de/entrada> \
--output <ruta/de/salida> \
[--css scripts/futuristic.css]
Invocaciones comunes
# Subtítulos minimalistas predeterminados (transcripción Whisper)
uv run python scripts/caption_service.py --input ./input --output ./output
# Estilo futurista
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css scripts/futuristic.css
# CSS personalizado
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css /ruta/a/mi.css
# Subtítulos estáticos con estilo predeterminado (fondo blanco, texto azul, Courier New)
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Suscríbete para más" \
--caption "0:10-0:15: Síguenos en Instagram"
# Subtítulos estáticos con estilo modo oscuro
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hola mundo" \
--caption "0:10-0:20: Esto es una demo" \
--style-config config.dark-mode.json
# Subtítulos estáticos con configuración de estilo personalizada
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Texto personalizado" \
--style-config mi-estilo-personalizado.json
# Subtítulos estáticos con sobrescritura de flags CLI
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hola" \
--style-config config.dark-mode.json \
--caption-color "#00FF00"
# Modo vigilancia (sondea nuevos videos cada 10s)
uv run python scripts/caption_service.py --input ./input --output ./output --watch
Después de ejecutar
Informa al usuario:
- Cuántos videos se procesaron correctamente y cuántos fallaron.
- La ruta completa al directorio de salida.
- Si algún video falló, nómbralos explícitamente.
Casos extremos
- Si
ffmpegno está instalado: dile al usuario que lo instale (sudo pacman -S ffmpegen Arch/CachyOS,brew install ffmpegen macOS,sudo apt install ffmpegen Ubuntu) - Si
uvno está instalado: dirige a https://docs.astral.sh/uv/getting-started/installation/ - Si el directorio de entrada está vacío: repórtalo claramente en lugar de salir silenciosamente
- La primera ejecución descarga el modelo Whisper (~140 MB para
tiny, ~1.5 GB paralarge) — esto es solo una vez
Transcripción Remota
Este skill ahora soporta transcripción remota opcional mientras mantiene el renderizado pycaps local.
- El comportamiento predeterminado sigue siendo completamente local: transcripción Whisper dentro de pycaps + renderizado local
- El modo remoto solo reemplaza el paso de transcripción
- El renderizado de subtítulos, plantillas y manejo de CSS permanecen locales
Proveedores soportados
huggingfacereplicate
Claves de configuración / CLI
| Clave | Valor por defecto | Notas |
|---|---|---|
transcription_provider | null | null mantiene el flujo local Whisper-en-pycaps |
remote_model | null | Sobrescritura opcional del modelo de transcripción específico del proveedor |
hf_token_env | HF_TOKEN | Nombre de variable de entorno para autenticación HuggingFace |
replicate_api_key_env | REPLICATE_API_TOKEN | Nombre de variable de entorno para autenticación Replicate |
remote_timeout_seconds | 300 | Timeout de llamada remota |
Ejemplos
# Transcripción remota HuggingFace + renderizado pycaps local
export HF_TOKEN=hf_tu_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider huggingface
# Transcripción remota Replicate + renderizado pycaps local
export REPLICATE_API_TOKEN=r8_tu_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider replicate --remote-model <slug-del-modelo-replicate>
Notas
- No hay retroceso silencioso al modo local si falta autenticación/configuración remota
- El uso existente de CLI local sigue siendo válido
- Si no configuras
--transcription-provider, pycaps continúa usando su flujo Whisper integrado