Transcripción de Video
Ejecuta el pipeline de este repositorio sin interfaz gráfica: subtítulos de la plataforma cuando estén disponibles (en segundos), Whisper local como respaldo, luego optimiza -> traduce -> resume.
Antes de ejecutar
El comando debe ejecutarse desde la raíz del repositorio AI Video Transcriber y necesita
el virtualenv del proyecto y ffmpeg. Verifica una vez por sesión:
ls venv/bin/python && command -v ffmpeg
- Sin venv: ejecuta
./install.sh, opython3 -m venv venv && venv/bin/pip install -r requirements.txt. - Sin ffmpeg: instálalo primero con
brew install ffmpegen macOS osudo apt install ffmpegen Debian/Ubuntu. No continúes sin él; la extracción de audio fallará.
Ejecútalo
venv/bin/python transcribe.py "<URL o ruta de archivo>" --json
Usa siempre --json: coloca la salida legible por máquina en stdout y mantiene el
progreso en stderr. Analiza el JSON en lugar de leer las líneas de log.
Banderas útiles:
| Bandera | Cuándo usarla |
|---|---|
-l, --summary-language <código> | Idioma del resumen: en, zh, es, fr, de, it, pt, ru, ja, ko, ar. Por defecto en |
--no-llm | No hay clave API disponible, o el usuario solo quiere la transcripción cruda. Omite optimizar/traducir/resumir |
--no-video | El usuario no quiere conservar el video fuente |
--whisper-model small | La precisión importa más que la velocidad. Desde tiny hasta large, por defecto base |
-o <dir> | Escribir el Markdown en otro directorio que no sea ./temp |
Los pasos con LLM necesitan una clave compatible con OpenAI a través de OPENAI_API_KEY y opcionalmente
OPENAI_BASE_URL. Sin ella, el pipeline aún transcribe pero usa formato básico;
prefiere --no-llm cuando el usuario solo necesita la transcripción.
Configuración del proveedor:
export OPENAI_API_KEY="tu_clave_api_aqui"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_TRANSLATION_MODEL="gpt-4o" # opcional
Para una ejecución única, transcribe.py también acepta --api-key, --base-url y
--model. Prefiere las variables de entorno cuando sea posible para no escribir claves API
en el historial del shell.
Lectura del resultado
{
"title": "...",
"no_speech": false,
"detected_language": "en",
"files": { "raw": "...", "transcript": "...", "summary": "...", "translation": "..." },
"media": { "path": "...", "kind": "video", "size_bytes": 2243691 }
}
Lee las rutas transcript y summary para obtener el contenido. translation está
presente solo cuando el idioma fuente difiere del idioma del resumen.
Crítico: no_speech
Cuando "no_speech": true el origen no contiene voz. No hay transcripción, resumen
o traducción. El pipeline omite deliberadamente el LLM para que no se invente nada.
Si ves esto, dile al usuario que el video no tiene voz. No adivines el contenido, no lo infieras del título ni describas lo que probablemente dice el video.
Modos de fallo
- Código de salida
2: entrada incorrecta, como un archivo faltante, extensión no soportada o archivo de texto vacío. Informa el mensaje y corrige el argumento. - Código de salida
1: fallo de descarga/transcodificación, generalmente una URL inaccesible, video bloqueado por región o privado, o falta de ffmpeg. Informa el error real. - La primera ejecución descarga los pesos de Whisper, por lo que puede parecer que se queda colgado durante un minuto.
- Los videos largos son lentos en modo Whisper. Advierte al usuario antes de comenzar si no hay subtítulos de la plataforma disponibles.