Open Whisper Ajuda

Anexo A3 Referência do comando

Leitura · 7 min

O comando open-whisper transcribe completo: cada opção, os formatos, as duas saídas, os campos do JSON e cada código de saída.

Esta é a referência completa do comando open-whisper. Para começar a usar e para colocá-lo no PATH, veja Linha de comando. As opções, as saídas, os campos do JSON e os códigos de saída são estáveis: podem surgir novos, mas os que existem nunca mudam de nome nem de número.

Sinopse

open-whisper transcribe <ENTRADA> [--format txt|srt|vtt|json] [--on-device] [--words] [--prompt <texto>]
                        [--numbers written|spoken] [--model <id>] [--quality fast|balanced|accurate]
                        [--lang <código>|auto]
open-whisper --help | -h
open-whisper --version
  • <ENTRADA> é um arquivo de mídia ou um link de vídeo por chamada. Um caminho que existe é um arquivo; qualquer outra coisa tem que ser o link de um único vídeo do YouTube. Ponha entre aspas um caminho com espaços.
  • As opções podem vir antes ou depois da entrada, como --opção valor ou --opção=valor. -- encerra as opções.
  • --version mostra open-whisper e a versão, como open-whisper 0.1.0.
  • O comando lê as preferências que você definiu no app e nunca as altera.

Mac

Sem argumentos, open-whisper abre o app da barra de menus.

Windows

Sem argumentos, open-whisper termina com erro de uso (código 2): o app em si abre pelo menu Iniciar. O comando funciona no Prompt de Comando e no PowerShell.

Opções

OpçãoValoresPadrãoO que faz
--formattxt, srt, vtt, jsontxtO formato da saída (veja abaixo).
--on-devicenenhumdesligadaPara um link: pula as legendas e transcreve o áudio neste computador. Esta opção é o seu consentimento, nunca presumido. Um arquivo é sempre transcrito neste computador.
--wordsnenhumdesligadaSó com --format json: cada segmento ganha uma lista de palavras com os seus tempos. Legendas não trazem tempo por palavra.
--prompttextonenhumUma dica de vocabulário (nomes, jargão) para esta chamada. Num link, substitui a dica tirada do título e do canal. Um valor vazio quer dizer sem dica.
--numberswritten, spokenwrittenspoken escreve os números por extenso, como foram ditos, sem nenhum algarismo. Numerais romanos são letras e podem ficar. Vale só para o que é transcrito neste computador, não para legendas.
--modelsmall-q5_1, base, medium-q5_0, large-v3-turbo-q5_0o modelo de vídeo definido no appO modelo desta chamada. Precisa já estar baixado: o comando nunca baixa (código 4).
--qualityfast, balanced, accuratea velocidade de vídeo definida no appA velocidade desta chamada.
--langpt, en, es, fr, de, it, nl, ru, zh, ja, ko, ar, hi, pl, tr, uk, ou autoo Idioma definido no appO idioma desta chamada. Um código desconhecido dá código 2. Fixar o idioma costuma dar resultado melhor que auto.

small-q5_1 é o modelo embutido. Os outros são baixados uma vez no app: veja Modelos.

Formatos de saída

FormatoO que você recebe
txtTexto puro, com um cabeçalho (título, canal, data de publicação, duração, link ou arquivo, idioma, origem) e uma quebra de parágrafo onde a fala pausa por mais de 2 segundos.
srtLegendas (SRT), sem cabeçalho.
vttLegendas (WebVTT), com o cabeçalho num bloco NOTE.
jsonUm documento JSON com a transcrição, os segmentos e como ela foi feita (veja abaixo).

txt, srt e vtt são idênticos, byte a byte, ao que Copiar e Salvar entregam na janela de vídeo.

As duas saídas

  • A saída padrão leva só o resultado, em UTF-8 com quebras de linha \n. Ela é escrita inteira, e então o comando termina com código 0. Em qualquer falha ela fica vazia, então um script nunca confunde uma mensagem com uma transcrição.
  • A saída de erro leva todo o resto, para pessoas: uma linha antes de qualquer uso de rede (só links), o progresso e uma linha explicando uma falha. Essas linhas podem mudar; não dependa delas num script.
  • A entrada padrão é ignorada.

Algumas linhas da saída de erro que você pode ver:

open-whisper: buscando o vídeo na rede — a transcrição em si continua nesta máquina
open-whisper: legenda encontrada (manual, pt) — usando-a; passe --on-device para transcrever o áudio
open-whisper: transcrevendo no dispositivo com small-q5_1 (accurate)
open-whisper: nenhuma fala detectada
open-whisper: interrompido; nada foi entregue

O envelope JSON

Com --format json, a saída padrão traz um documento JSON. Com o tempo surgem campos novos, mas nenhum é removido nem renomeado, então ignore os campos que você não conhece.

CampoO que traz
appname e version.
inputkind (file ou url), reference (o caminho ou o link), title, duration_secs e, para um arquivo, audio (taxa de amostragem, canais, faixa, contêiner, codec).
settings.modelO id do modelo e a origin: preferences ou override (você passou --model).
settings.qualityvalue e origin.
settings.languagerequested, origin e detected (o idioma ouvido).
settings.promptvalue e origin: override, video_metadata ou none.
settings.numbersvalue e applied: true quando transcrito neste computador, false para legendas.
transcript.provenanceon_device, manual_captions ou automatic_captions.
transcript.languageO idioma da transcrição.
transcript.repetition_flaggedtrue quando trechos repetidos em excesso foram reduzidos.
transcript.segmentsCada um com start_ms, end_ms, text; words com --words; suspect: true numa linha que parece despedida de canal.
transcript.textO texto inteiro.
transcript.empty_reasonno_speech, só quando não sobra nenhum segmento. O código continua 0.
transcript.suppressedSegmentos deixados de fora por não serem fala, cada um com start_ms, end_ms, text e reason (silence, subtitle_credit ou no_speech). Só aparece quando há algum.
transcript.word_timestampsCom --words: se há tempo por palavra. Para legendas, available: false com reason: captions.

Cada item de words tem start_ms, end_ms, text e probability. As palavras, em ordem, são o texto do segmento separado nos espaços. Cada uma dura pelo menos 40 ms, as palavras nunca se sobrepõem e ficam dentro do seu segmento. probability vai de 0 a 1 e é relativa, não uma nota calibrada.

Códigos de saída

CódigoQuer dizerO que fazer
0A transcrição está na saída padrão. Também quando nenhuma fala foi encontrada (veja empty_reason).Leia a saída padrão.
1Erro interno.Relate com a linha da saída de erro.
2Erro de uso: opção ou valor desconhecido, entrada faltando ou sobrando, --lang ou --model desconhecido, uma entrada sem transcribe, um link que não é de um único vídeo do YouTube.Corrija o comando. open-whisper --help mostra o uso.
3O yt-dlp está faltando ou é antigo demais (só links).Instale ou atualize o yt-dlp: veja Solução de problemas.
4O modelo não está baixado.Use --model small-q5_1, ou baixe o modelo no app.
5Formato não suportado. A mensagem diz o codec ou o contêiner.Exporte como MP4 ou M4A com AAC, ou como MP3, FLAC ou WAV.
6O arquivo não pode ser lido: nada nesse caminho, uma pasta, sem permissão, vazio ou truncado, sem faixa de áudio, ou mais longo que 3 horas.Corrija a entrada.
7O link não tem legendas utilizáveis e você não passou --on-device.Rode de novo com --on-device.
8Erro do vídeo: indisponível, privado ou removido, com restrição de idade, fora da sua região, transmissão ao vivo, acessos limitados, sem rede, falha ao decodificar ou transcrever, falha não reconhecida, ou outro vídeo já em andamento.Vale tentar de novo mais tarde quando for limite de acessos ou falta de rede.
9A transcrição ficou pronta, mas a saída padrão fechou antes de recebê-la.Rode de novo.
130Interrompido (CtrlC). O comando para em até 2 segundos e não entrega nada.Nada a fazer.

Mac

Veja o código no Terminal com echo $?.

Windows

Veja o código com echo %ERRORLEVEL% no Prompt de Comando, ou $LASTEXITCODE no PowerShell.

Garantias

  • O comando nunca grava arquivo, aconteça o que acontecer. Redirecione a saída padrão para guardar o resultado.
  • O arquivo de entrada é lido onde está. O tamanho e a data de modificação não mudam.
  • Um arquivo do seu computador não faz nenhuma requisição de rede. Um link usa a rede só para buscar o vídeo.
  • Ele nunca altera as suas preferências, e o ditado continua funcionando enquanto ele roda.
  • Uma entrada por chamada. Não há pastas, curingas nem playlists: percorra os arquivos no seu próprio script.
  • Ele não lê faixas de legenda de dentro de um arquivo, não escolhe faixa de áudio, não entrega saída parcial aos poucos, não traduz nem resume.

Num Mac com Apple Silicon, o modelo embutido transcreve cerca de 20 a 25 vezes mais rápido que o tempo real: uma hora de áudio leva uns 3 minutos, mais um ou dois segundos para carregar o modelo. No Windows, a velocidade depende do processador. Num script, espere pelo menos um décimo da duração da gravação mais 60 segundos antes de desistir.

 open-whisper transcribe "aula.mov" --format srt > aula.srt
 open-whisper transcribe "https://youtu.be/ID_DO_VIDEO" --on-device --format json > video.json