VideoCaptioner CLI
Subtitulación de video con IA: transcribe voz → optimiza subtítulos → traduce → incrusta en video con estilos atractivos.
Cuándo usarlo
- El usuario quiere agregar subtítulos a un video
- El usuario quiere transcribir audio/video a texto
- El usuario quiere traducir subtítulos a otro idioma
- El usuario quiere personalizar la apariencia de los subtítulos (colores, fuentes, fondos redondeados)
- El usuario quiere descargar y subtitular videos en línea
Antes de empezar
Siempre ejecuta videocaptioner <comando> --help primero para verificar las opciones y valores predeterminados más recientes antes de ejecutar un comando. Los ejemplos siguientes son patrones comunes, pero --help es la fuente de verdad.
- Instalación:
pip install videocaptioner - Se requiere FFmpeg para la síntesis de video (
brew install ffmpegen macOS) - Gratuito (sin clave API): transcripción (bijian/jianying), traducción (Bing/Google)
- Requiere clave API de LLM: optimización de subtítulos, resegmentación de subtítulos, traducción con LLM. Configurar mediante la variable de entorno
OPENAI_API_KEYo el flag--api-key
Escenarios comunes
1. Dar a un video en chino subtítulos en inglés (un solo comando, todo gratuito)
videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
--subtitle-mode hard --quality high -o output.mp4
2. Transcribir un video a SRT (gratuito)
videocaptioner transcribe video.mp4 --asr bijian -o output.srt
# Salida en formato JSON a un directorio
videocaptioner transcribe video.mp4 --asr bijian --format json -o ./subtitles/
3. Traducir subtítulos existentes
# Bing gratuito → Inglés, salida bilingüe con la traducción encima del original
videocaptioner subtitle input.srt --translator bing --target-language en --layout target-above -o translated.srt
# Google gratuito → Japonés, solo traducción (descarta el texto original)
videocaptioner subtitle input.srt --translator google --target-language ja --no-optimize --layout target-only -o output_ja.srt
# Traducción de alta calidad con LLM y modo reflexivo
videocaptioner subtitle input.srt --translator llm --target-language en --reflect \
--api-key $OPENAI_API_KEY -o output_en.srt
4. Proceso completo con subtítulos con estilo atractivo
# Subtítulos estilo anime (color cálido + contorno naranja), video de alta calidad
videocaptioner process video.mp4 --asr bijian --translator bing --target-language ja \
--subtitle-mode hard --style anime --quality high -o output_ja.mp4
# Subtítulos modernos con fondo redondeado
videocaptioner process video.mp4 --asr bijian --translator google --target-language ko \
--subtitle-mode hard --render-mode rounded -o output_ko.mp4
# Colores personalizados: texto blanco con contorno rojo, calidad ultra
videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
--subtitle-mode hard --quality ultra \
--style-override '{"outline_color": "#ff0000", "primary_color": "#ffffff"}' -o output_en.mp4
5. Solo subtítulos, salida en formato ASS (sin síntesis de video)
videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
--format ass --no-synthesize -o ./output/
6. Control paso a paso (transcribir → traducir → sintetizar por separado)
# Paso 1: Transcribir
videocaptioner transcribe video.mp4 --asr bijian -o video.srt
# Paso 2: Traducir (bilingüe, texto original encima de la traducción)
videocaptioner subtitle video.srt --translator bing --target-language en --layout source-above -o video_en.srt
# Paso 3: Incrustar en video con fondo redondeado y alta calidad
videocaptioner synthesize video.mp4 -s video_en.srt --subtitle-mode hard \
--render-mode rounded --quality high -o video_with_subs.mp4
7. Procesar archivo de audio (omite automáticamente la síntesis de video)
videocaptioner process podcast.mp3 --asr bijian --translator bing --target-language en -o ./output/
8. Transcribir otros idiomas (whisper-api)
videocaptioner transcribe french_video.mp4 --asr whisper-api \
--whisper-api-key $OPENAI_API_KEY --language fr -o french.srt
9. Solo optimizar subtítulos con LLM (corregir errores de ASR, sin traducción)
videocaptioner subtitle raw_subtitle.srt --no-translate --api-key $OPENAI_API_KEY -o optimized.srt
10. Estilo de fondo redondeado personalizado con fuente personalizada
videocaptioner synthesize video.mp4 -s subtitle.srt --subtitle-mode hard \
--style-override '{"text_color": "#ffffff", "bg_color": "#000000cc", "corner_radius": 10, "font_size": 36}' \
--font-file ./NotoSansSC.ttf --quality high -o styled_video.mp4
Referencia de comandos
| Comando | Propósito |
|---|---|
transcribe | Voz → subtítulos. Motores: bijian(gratuito) jianying(gratuito) whisper-api whisper-cpp |
subtitle | Optimizar (LLM) y/o traducir (LLM/Bing/Google) archivos de subtítulos |
synthesize | Incrustar subtítulos en video con estilos personalizables |
process | Proceso completo: transcribir → optimizar → traducir → sintetizar |
download | Descargar video de YouTube, Bilibili, etc. |
config | Gestionar ajustes (show set get path init) |
style | Listar todos los presets de estilo de subtítulos con parámetros |
Ejecuta videocaptioner <comando> --help para ver todas las opciones.
Estilos de subtítulos
Dos modos de renderizado para subtítulos atractivos:
Modo ASS (predeterminado) — estilo de contorno/sombra:
- Presets:
default(blanco+contorno negro),anime(cálido+contorno naranja),vertical(videos verticales) - Campos personalizables:
font_name,font_size,primary_color,outline_color,outline_width,bold,spacing,margin_bottom
Modo redondeado — cajas de fondo redondeadas modernas:
- Preset:
rounded(texto oscuro sobre fondo semitransparente) - Campos personalizables:
font_name,font_size,text_color,bg_color(#rrggbbaa),corner_radius,padding_h,padding_v,margin_bottom
Las opciones de estilo solo funcionan con --subtitle-mode hard.
Idiomas destino
Códigos BCP 47: zh-Hans zh-Hant en ja ko fr de es ru pt it ar th vi id y 23 más.
Variables de entorno
| Variable | Propósito |
|---|---|
OPENAI_API_KEY | Clave API de LLM |
OPENAI_BASE_URL | URL base de la API de LLM |
Códigos de salida
0 éxito · 2 argumentos incorrectos · 3 archivo no encontrado · 4 dependencia faltante · 5 error de ejecución
Consejos
- Usa
-qpara scripting (stdout = solo la ruta del resultado) - La traducción de Bing/Google es gratuita, no necesita clave API
- El ASR de
bijian/jianyinges gratuito pero solo admite chino e inglés - Ejecuta
videocaptioner stylepara ver todos los presets de estilo