# Transcrição

> Transforme a fala de um clipe em texto com tempo por palavra, no seu computador, e gere legendas a partir dele.

Source: https://alexgalhardo.github.io/vukem-video/pt-br/docs/guide/transcription/

## O que você vai aprender

- como um clipe vira uma transcrição e a transcrição vira legendas;
- como usar as legendas automáticas no editor;
- onde o áudio é processado e como usar uma API de transcrição no lugar.

## A ideia

A **transcrição** é uma tarefa. Ela lê o áudio de uma mídia importada e armazena as palavras com os seus instantes de início e fim. A transcrição pertence à mídia, então um segundo clipe da mesma mídia a reaproveita. As **Legendas automáticas** agrupam então as palavras do trecho visível de um clipe em legendas em uma faixa de legendas e as ligam ao clipe.

Por padrão, a transcrição roda no seu computador com o whisper.cpp e um modelo que você instala uma única vez: `tiny`, `base`, `small` (o padrão) ou `large-v3-turbo`. O download é uma etapa explícita, anunciada com o seu tamanho e o servidor antes de começar, e nada é baixado em nenhum outro momento. Quando os arquivos estão ausentes, a tarefa falha com `E_TRANSCRIBE_UNAVAILABLE` e o editor oferece instalá-los.

Um operador pode apontar o servidor para uma API de transcrição compatível com a OpenAI com `VUKEM_VIDEO_TRANSCRIBE_URL`, `VUKEM_VIDEO_TRANSCRIBE_KEY` e `VUKEM_VIDEO_TRANSCRIBE_MODEL`. Então o áudio da mídia (e nada mais) é enviado a esse host, e a mensagem da tarefa diz qual host o recebe. Sem URL definida, nenhum áudio sai da máquina. Veja [Privacidade](/docs/self-hosting/privacy).

## Início rápido

No editor, selecione um clipe que tenha áudio e abra **Legendas automáticas** no inspetor:

1. Escolha a faixa de legendas, ou uma nova.
2. Defina as palavras por legenda, os caracteres por legenda e a pausa que inicia uma nova legenda.
3. Pressione **Gerar legendas**. Se a transcrição local não estiver instalada, o diálogo oferece instalá-la, ou mostra o comando a executar em um terminal.
4. Depois de reposicionar ou editar o clipe, pressione **Ressincronizar legendas** para acompanhá-lo.

**CLI**

```bash
vukem-video tools:install whisper --model small
vukem-video transcribe --project prj_7k2m9x4q1b --asset ast_3c5v8n2w6d --language en
vukem-video edit --project prj_7k2m9x4q1b caption.from_transcript \
  clip_item_id=itm_m1n2p3q4r5 track_id=trk_f6g7h8j9k0 max_words:=4
```

**MCP**

`job_start` com `{"project_id": "prj_7k2m9x4q1b", "kind": "transcribe", "args": {"asset_id": "ast_3c5v8n2w6d"}, "wait_ms": 25000}`, depois `media_inspect` com `"sections": ["transcript"]` para ler as palavras, depois `edit` com:

```json
{ "op": "caption.from_transcript", "args": {
  "clip_item_id": "itm_m1n2p3q4r5", "track_id": "trk_f6g7h8j9k0"
} }
```

O `caption.from_transcript` assume por padrão 5 palavras e 28 caracteres por legenda e uma pausa de 0,6 s. Com `replace` (o padrão), as legendas já ligadas ao clipe naquela faixa são removidas antes. O `caption.retime_from_clip` move as legendas ligadas depois que o clipe mudou. Estilize as legendas com `track.set_caption_style` e corrija uma palavra com `caption.edit_word`.

## Erros comuns

- Executar `caption.from_transcript` antes de a transcrição existir. Inicie antes a tarefa de transcrição e espere por ela.
- A transcrição fica na fila atrás de outras: `VUKEM_VIDEO_MAX_TRANSCRIBES` e `VUKEM_VIDEO_MAX_TRANSCRIBES_PER_KEY` limitam quantas rodam ao mesmo tempo.
- Uma origem mais longa que `VUKEM_VIDEO_MAX_TRANSCRIBE_SECONDS` (2 horas por padrão) é recusada.

## Próximos passos

- [Texto e legendas](/docs/guide/text-and-captions)
- [Tarefas e a fila](/docs/guide/jobs)
