Video Transcribe
Executa o pipeline deste repositório de forma headless: legendas da plataforma quando disponíveis (em segundos), Whisper local como fallback, depois otimiza -> traduz -> resume.
Antes de executar
O comando deve ser executado a partir da raiz do repositório AI Video Transcriber e precisa do
virtualenv do projeto e do ffmpeg. Verifique uma vez por sessão:
ls venv/bin/python && command -v ffmpeg
- Sem venv: execute
./install.sh, oupython3 -m venv venv && venv/bin/pip install -r requirements.txt. - Sem ffmpeg: instale primeiro com
brew install ffmpegno macOS ousudo apt install ffmpegno Debian/Ubuntu. Não prossiga sem ele; a extração de áudio falhará.
Executar
venv/bin/python transcribe.py "<URL ou caminho do arquivo>" --json
Sempre use --json: ele coloca a saída legível por máquina no stdout e mantém o progresso
no stderr. Analise o JSON em vez de extrair linhas de log.
Flags úteis:
| Flag | Quando usar |
|---|---|
-l, --summary-language <código> | Idioma do resumo: en, zh, es, fr, de, it, pt, ru, ja, ko, ar. Padrão en |
--no-llm | Nenhuma chave de API disponível, ou o usuário só quer a transcrição bruta. Ignora otimizar/traduzir/resumir |
--no-video | O usuário não deseja manter o vídeo fonte |
--whisper-model small | A precisão importa mais que a velocidade. De tiny a large, padrão base |
-o <dir> | Escrever o Markdown em outro lugar que não ./temp |
As etapas de LLM precisam de uma chave compatível com OpenAI via OPENAI_API_KEY e opcionalmente
OPENAI_BASE_URL. Sem uma, o pipeline ainda transcreve, mas usa formatação básica;
prefira --no-llm quando o usuário só precisar da transcrição.
Configurações do provedor:
export OPENAI_API_KEY="sua_chave_api_aqui"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_TRANSLATION_MODEL="gpt-4o" # opcional
Para uma execução única, transcribe.py também aceita --api-key, --base-url, e
--model. Prefira variáveis de ambiente quando possível para que as chaves de API não sejam
gravadas no histórico do shell.
Lendo o resultado
{
"title": "...",
"no_speech": false,
"detected_language": "en",
"files": { "raw": "...", "transcript": "...", "summary": "...", "translation": "..." },
"media": { "path": "...", "kind": "video", "size_bytes": 2243691 }
}
Leia os caminhos transcript e summary para obter o conteúdo. translation está
presente apenas quando o idioma fonte difere do idioma do resumo.
Crítico: no_speech
Quando "no_speech": true, a fonte não contém fala. Não há transcrição, resumo,
ou tradução. O pipeline deliberadamente ignora o LLM para que nada seja inventado.
Se você vir isso, informe ao usuário que o vídeo não tem fala. Não adivinhe o conteúdo, infira a partir do título ou descreva o que o vídeo provavelmente diz.
Modos de falha
- Código de saída
2: entrada inválida, como arquivo ausente, extensão não suportada ou arquivo de texto vazio. Informe a mensagem e corrija o argumento. - Código de saída
1: falha no download/transcodificação, geralmente URL inacessível, vídeo bloqueado por região/privado ou ffmpeg ausente. Informe o erro real. - Primeira execução baixa os pesos do Whisper, então pode parecer travado por um minuto.
- Vídeos longos são lentos no modo Whisper. Avise o usuário antes de começar se não houver legendas da plataforma disponíveis.