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 valorou--opção=valor.--encerra as opções. --versionmostraopen-whispere a versão, comoopen-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ção | Valores | Padrão | O que faz |
|---|---|---|---|
--format | txt, srt, vtt, json | txt | O formato da saída (veja abaixo). |
--on-device | nenhum | desligada | Para 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. |
--words | nenhum | desligada | Só com --format json: cada segmento ganha uma lista de palavras com os seus tempos. Legendas não trazem tempo por palavra. |
--prompt | texto | nenhum | Uma 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. |
--numbers | written, spoken | written | spoken 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. |
--model | small-q5_1, base, medium-q5_0, large-v3-turbo-q5_0 | o modelo de vídeo definido no app | O modelo desta chamada. Precisa já estar baixado: o comando nunca baixa (código 4). |
--quality | fast, balanced, accurate | a velocidade de vídeo definida no app | A velocidade desta chamada. |
--lang | pt, en, es, fr, de, it, nl, ru, zh, ja, ko, ar, hi, pl, tr, uk, ou auto | o Idioma definido no app | O 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
| Formato | O que você recebe |
|---|---|
txt | Texto 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. |
srt | Legendas (SRT), sem cabeçalho. |
vtt | Legendas (WebVTT), com o cabeçalho num bloco NOTE. |
json | Um 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.
| Campo | O que traz |
|---|---|
app | name e version. |
input | kind (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.model | O id do modelo e a origin: preferences ou override (você passou --model). |
settings.quality | value e origin. |
settings.language | requested, origin e detected (o idioma ouvido). |
settings.prompt | value e origin: override, video_metadata ou none. |
settings.numbers | value e applied: true quando transcrito neste computador, false para legendas. |
transcript.provenance | on_device, manual_captions ou automatic_captions. |
transcript.language | O idioma da transcrição. |
transcript.repetition_flagged | true quando trechos repetidos em excesso foram reduzidos. |
transcript.segments | Cada um com start_ms, end_ms, text; words com --words; suspect: true numa linha que parece despedida de canal. |
transcript.text | O texto inteiro. |
transcript.empty_reason | no_speech, só quando não sobra nenhum segmento. O código continua 0. |
transcript.suppressed | Segmentos 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_timestamps | Com --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ódigo | Quer dizer | O que fazer |
|---|---|---|
| 0 | A transcrição está na saída padrão. Também quando nenhuma fala foi encontrada (veja empty_reason). | Leia a saída padrão. |
| 1 | Erro interno. | Relate com a linha da saída de erro. |
| 2 | Erro 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. |
| 3 | O yt-dlp está faltando ou é antigo demais (só links). | Instale ou atualize o yt-dlp: veja Solução de problemas. |
| 4 | O modelo não está baixado. | Use --model small-q5_1, ou baixe o modelo no app. |
| 5 | Formato 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. |
| 6 | O 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. |
| 7 | O link não tem legendas utilizáveis e você não passou --on-device. | Rode de novo com --on-device. |
| 8 | Erro 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. |
| 9 | A transcrição ficou pronta, mas a saída padrão fechou antes de recebê-la. | Rode de novo. |
| 130 | Interrompido (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