# Editor de Vídeo

Uma skill para o **Claude Code** e para o **Codex** que edita vídeos falados gravados no celular,
só conversando. Feita para quem grava criativo de anúncio, Reels e TikTok olhando para a câmera.

Você entrega a pasta com as gravações e conversa. A IA:

- ouve tudo e escolhe as melhores tomadas;
- tira pausas, erros, gaguejadas e repetições;
- monta o corte na ordem que funciona para anúncio (gancho, problema, virada, prova, chamada);
- depois coloca legenda animada, texto de gancho, tela dividida com imagem, zoom nos cortes,
  efeitos sonoros, trilha, botão de chamada e, se você pedir, aviso de resultado;
- faz tela verde sem pano verde: recorta você do fundo da gravação e te coloca no canto ou no meio, na
  frente de um print, uma foto ou um vídeo (bom para comentar uma página, reagir a um vídeo ou mostrar um
  produto). As imagens e vídeos da edição passam no fundo, sem tela dividida, e o print aparece inteiro acima
  de você. O recorte roda no seu computador e leva uns 3 minutos por minuto de vídeo na primeira vez;
- anima textos e números que a IA de vídeo não desenha certo: lista com check, lista riscada, passo a
  passo, etiqueta de preço, contador, gráfico, palavra de impacto e "comenta a palavra", no segundo em
  que você fala, sem cobrir o seu rosto;
- escolhe entre 24 efeitos sonoros prontos pelo sentido da fala (notificação na venda, erro, contagem
  de números, grave na revelação, teclado, rebobinar...), que você também pode pedir pelo nome em
  português;
- guarda as suas músicas de fundo por clima (animada, triste, tensa...) para você só dizer
  "trilha triste" na próxima edição;
- se você quiser, limpa o ruído de fundo da voz (chiado, ventilador, rua);
- confere o próprio trabalho (som, cortes, textos na tela, rosto livre) antes de te mostrar.

Tudo roda no seu computador. Você acompanha num **preview** com player e linha do tempo, marca o
que quer mudar e aprova em dois momentos: o corte e o vídeo final.

## Do que você precisa

- **Mac com chip Apple** (M1, M2, M3, M4) com **macOS 13 (Ventura) ou mais novo**. No macOS 14 ou mais
  novo a transcrição usa a placa gráfica e fica bem mais rápida.
- **Mac com processador Intel** com **macOS 14 (Sonoma) ou mais novo**. Funciona, mas a transcrição
  é mais lenta.
- **Windows 10 ou 11 de 64 bits** com processador Intel ou AMD.
- Não funciona em Windows com processador ARM (como Snapdragon), nem em Mac com sistema mais antigo
  que os de cima: algumas bibliotecas não existem para eles. O instalador avisa e não instala nada.
- **8 GB de memória** (16 GB deixa tudo mais folgado).
- **Uns 5 GB livres** no disco: cerca de 1 GB de programas, 1,6 GB do modelo de voz e o espaço
  dos seus vídeos.
- **Claude Code** (app ou terminal) ou o **app do Codex**, já com login feito.
- Internet na instalação e na primeira transcrição. Depois disso, cortar e legendar funciona sem
  internet (só a busca de imagens precisa).

## Instalação

### 1. Instale o uv e o ffmpeg

**Mac:** abra o app Terminal e rode:

```
brew install uv ffmpeg
```

Se aparecer `command not found: brew`, instale o Homebrew antes, seguindo as instruções de
https://brew.sh, e rode o comando de novo.

**Windows:** abra o PowerShell e rode:

```
winget install astral-sh.uv Gyan.FFmpeg
```

Se o seu Windows não aceitar os dois de uma vez, rode um de cada vez:
`winget install astral-sh.uv` e depois `winget install Gyan.FFmpeg`.

### 2. Feche e abra o terminal

Feche todas as janelas do Terminal ou do PowerShell e abra de novo. Sem isso o computador ainda
não enxerga o que você acabou de instalar.

### 3. Rode o instalador

Descompacte a pasta `editor-video` que você recebeu e abra o terminal dentro dela:

- **Mac:** no Terminal, digite `cd ` (com espaço), arraste a pasta para a janela e aperte Enter.
- **Windows:** clique com o botão direito na pasta e escolha **Abrir no Terminal**.

Depois rode:

```
uv run --no-project python install.py
```

O instalador:

1. confere se o computador é compatível;
2. acha o Claude Code e o Codex no seu computador e copia a skill para cada um
   (`~/.claude/skills/editor-video` e `~/.codex/skills/editor-video`);
3. baixa as bibliotecas que a skill usa (na primeira vez leva alguns minutos);
4. confere se o ffmpeg está instalado;
5. mostra um resumo. Quando aparecer **Pronto!**, deu tudo certo.

Depois **feche e abra o Claude Code ou o Codex** para a skill aparecer.

Opções do instalador (para casos especiais):

| Opção | Para que serve |
|---|---|
| `--dry-run` | Mostra o que faria, sem mudar nada. |
| `--dest PASTA` | Instala só nessa pasta (pode repetir). |
| `--no-sync` | Copia os arquivos sem baixar as bibliotecas. |
| `--dev` | Cria um atalho para a pasta em vez de copiar (para quem mexe no código). |

## Primeiro uso

Coloque os vídeos brutos numa pasta só, por exemplo `Filmes/criativo-bolsa`. No Mac, evite Mesa,
Documentos e Downloads na primeira vez (o macOS pode bloquear o acesso; veja "Problemas comuns").

### No Claude Code

1. Abra o Claude Code na pasta dos vídeos. No app, escolha a pasta ao começar a conversa. No
   terminal, entre na pasta e rode `claude`.
2. Peça em português normal, por exemplo:
   *"Edita os vídeos dessa pasta para um anúncio de uns 30 segundos."*
   Se quiser chamar a skill pelo nome, digite `/editor-video`.
3. O preview abre ao lado da conversa. Responda as perguntas, aprove o corte, escolha o estilo e
   aprove o final.

### No app do Codex

1. Abra o Codex e escolha a pasta dos vídeos como projeto.
2. Peça, por exemplo: *"Use $editor-video para editar os vídeos desta pasta."*
3. O Codex abre o preview no navegador do app. Se não abrir, entre no endereço que ele mostrar
   (normalmente `http://127.0.0.1:4830`).
4. Quando o Codex pedir permissão para rodar comandos ou abrir o preview, aprove.
5. **Importante no Codex:** depois de clicar em Aprovar, Salvar marcações ou Salvar estilo, mande
   uma mensagem na conversa (pode ser só "pronto"). O Codex só vê o clique quando você escreve.

### Como é o caminho

1. **Conversa rápida:** produto, para onde vai o clique, duração.
2. **Corte:** a IA transcreve, escolhe as tomadas e te conta o plano antes de cortar.
3. **Você assiste o corte** no preview. Gostou, clica em **Aprovar**. Quer mudar, marca o trecho
   (tecla `I` no começo, `O` no fim), escreve o que quer e clica em **Salvar marcações**.
4. **Estilo:** na aba Estilo você escolhe o tipo de edição (limpa, tela dividida ou tela verde, com a
   posição: canto esquerdo, canto direito ou meio), legenda, gancho, cor, elementos e a trilha de fundo (um
   clima da sua biblioteca, um arquivo da pasta ou sem trilha), vendo amostras no seu próprio vídeo.
   O elemento **Motion** liga as animações de texto e número: a IA sugere onde elas cabem pela sua
   fala e só coloca as que você aprovar.
5. **Final:** a IA monta o vídeo completo. Você aprova ou marca de novo.
6. O vídeo pronto fica em `edit/final.mp4`, dentro da pasta dos vídeos. Seus arquivos originais
   nunca são alterados.

Atalhos do player: `Espaço` toca e pausa, setas andam 1 quadro, `Shift` + setas andam 1 segundo.

## Biblioteca de trilhas

Você pode guardar músicas de fundo prontas, separadas por clima, e usar em qualquer edição sem
gerar nada de novo. Na conversa, é só dizer *"trilha triste"* ou *"põe uma trilha animada"*, ou
escolher o clima na aba Estilo do preview.

Os climas prontos são: **Animada** (energia, oferta, novidade), **Inspiradora** (conquista, virada de
vida), **Triste** (dor, problema, desabafo), **Tensa** (segredo, alerta, erro comum), **Calma**
(explicação, tutorial, confiança), **Épica** (revelação, resultado, grande virada), **Divertida**
(humor, bastidor) e **Luxo** (produto premium). Você pode criar os seus.

**Onde fica.** Fora da pasta da skill, para não se perder quando você atualiza ou reinstala:

- Mac: `~/.editor-video/trilhas` (pasta `.editor-video` dentro da sua pasta de usuário)
- Windows: `%USERPROFILE%\.editor-video\trilhas`

Dentro dela há uma pasta por clima (`animada`, `triste`...), a lixeira `_lixeira` (música removida vai
para lá, nada é apagado) e o índice `trilhas.json`, com duração, volume e energia de cada música. A
pasta só é criada quando a primeira música entra. O instalador nunca mexe nela.

**Como pôr as suas músicas.** Peça na conversa, por exemplo *"guarda esta música como trilha
animada: /Users/ana/Músicas/pop.mp3"*. A IA copia o arquivo (o original fica onde está), mede e
anota tudo. Use só música que você tem direito de usar em anúncio: feita por você, comprada com
licença comercial ou de um banco que libera uso comercial. Diga de onde veio para ficar anotado.
Também dá para marcar a favorita de cada clima: é ela que entra primeiro.

**Músicas feitas com IA na sua conta ElevenLabs** também podem ir para a biblioteca (peça, por
exemplo, *"gera uma trilha tensa e guarda na biblioteca"*). Elas seguem as regras da ElevenLabs
logo abaixo: plano pago certo na hora de gerar, uso só nos seus vídeos, sem repassar, vender ou
juntar em pacote. A biblioteca é sua: não mande a pasta para outras pessoas.

## Chaves opcionais

Nada disso é necessário. Sem chave, as imagens vêm do Wikimedia Commons (grátis) e a trilha é um
arquivo seu ou da sua biblioteca de trilhas (ou fica sem trilha).

| Chave | Para que serve |
|---|---|
| `PEXELS_API_KEY` | Buscar fotos no Pexels (grátis, precisa de cadastro no site do Pexels). |
| `OPENROUTER_API_KEY` | Gerar imagem com IA pelo OpenRouter (pago por imagem). |
| `ELEVENLABS_API_KEY` | Gerar trilha (música de fundo) ou um efeito sonoro com IA na sua conta ElevenLabs (pago por uso). Para usar em anúncio, a conta precisa de plano pago. |

**Trilha e efeito com IA (ElevenLabs):** são gerados na sua própria conta, com a sua chave, e ficam
só na pasta `edit` do seu vídeo. Nenhuma música gerada vem junto com a skill. Antes de gerar, a IA
mostra o custo em créditos e pede o seu ok. Regras da ElevenLabs (lidas em 16/09/2026; elas mudam,
então confira os termos no site dela antes de anunciar):

- Para usar em anúncio, a sua conta precisa estar num plano pago na hora de gerar. No plano grátis
  o uso comercial não é permitido.
- Pessoa física pode usar do plano Starter para cima. Empresa precisa do Scale (menos de 10
  funcionários), do Business (menos de 50) ou do Enterprise.
- Vale para anúncio e post na internet. TV, rádio e cinema ficam de fora.
- O arquivo é só para os seus vídeos: não repasse, não venda e não monte pacote de músicas ou de
  sons com ele.
- No pedido, nada de nome de artista, banda, compositor, música, álbum, gravadora, filme ou marca,
  nem trecho de letra.
- A chave é só sua: não mande para ninguém.

**Jeito mais fácil:** peça na conversa, por exemplo *"quero usar imagem com IA, minha chave do
OpenRouter é ..."* ou *"quero trilha com IA, minha chave da ElevenLabs é ..."*. A IA grava a chave
no arquivo certo para você, sem você mexer em pasta escondida. Faça isso uma vez no Claude Code e
uma vez no Codex, se usar os dois: cada app tem a sua cópia da skill.

Para fazer na mão: crie um arquivo chamado `.env` dentro da pasta da skill
(`~/.claude/skills/editor-video/.env` e/ou `~/.codex/skills/editor-video/.env`) com uma chave por
linha:

```
PEXELS_API_KEY=cole_sua_chave_aqui
OPENROUTER_API_KEY=cole_sua_chave_aqui
ELEVENLABS_API_KEY=cole_sua_chave_aqui
```

Não mande esse arquivo para ninguém. O instalador mantém o `.env` quando você atualiza, mesmo se a
atualização falhar no meio.

## Atualizar

Baixe a versão nova, abra o terminal dentro da pasta dela e rode o mesmo comando:

```
uv run --no-project python install.py
```

Suas chaves no `.env` continuam lá, e a biblioteca de trilhas também (ela fica fora da skill). Feche e
abra o Claude Code ou o Codex.

## Desinstalar

Apague a pasta `editor-video` dentro de `~/.claude/skills` e/ou `~/.codex/skills`. A biblioteca de
trilhas (`~/.editor-video/trilhas`) continua no computador; apague só se não quiser mais as músicas.

## Problemas comuns

**`command not found: uv` ou "uv não é reconhecido"**
Feche e abra o terminal. Se continuar, instale de novo (Mac: `brew install uv`; Windows:
`winget install astral-sh.uv`) e feche todas as janelas do terminal antes de tentar.

**`'ffmpeg' não encontrado`**
Mac: `brew install ffmpeg`. Windows: `winget install Gyan.FFmpeg`. Depois feche e abra o terminal
e também o Claude Code ou o Codex.

**O instalador diz "Este computador não é compatível"**
A skill funciona em Mac com chip Apple no macOS 13 ou mais novo, em Mac Intel no macOS 14 ou mais novo
e em Windows 64 bits com Intel ou AMD. Num Mac com macOS antigo, atualize o sistema e rode o instalador de novo.

**O instalador diz que não achou o Claude Code nem o Codex**
Abra o Claude Code ou o Codex pelo menos uma vez (isso cria a pasta de configuração) e rode o
instalador de novo.

**A skill não aparece**
Feche e abra o app. Confira se existe o arquivo `SKILL.md` em `~/.claude/skills/editor-video` ou
`~/.codex/skills/editor-video`. Se não existir, rode o instalador de novo.

**A primeira transcrição demora muito**
Na primeira vez a skill baixa o modelo de voz (cerca de 1,6 GB). Aparece "baixando o modelo...
(só na primeira vez)". Deixe terminar com a internet ligada. Das próximas vezes é rápido.

**No Windows a transcrição é lenta**
No Windows ela roda no processador, sem a aceleração do chip da Apple. É normal levar mais tempo.
Feche programas pesados enquanto isso.

**Mac: erro de permissão, "Operation not permitted" ou o preview diz que não consegue gravar**
O macOS protege as pastas Mesa, Documentos, Downloads e discos externos. Duas saídas:
1. Libere: **Ajustes do Sistema > Privacidade e Segurança > Arquivos e Pastas** e ative o acesso
   para o app que você usa (Claude, Codex ou Terminal). Para disco externo, ative "Volumes
   removíveis". Se não resolver, use **Acesso Total ao Disco**. Depois feche e abra o app.
2. Ou mova os vídeos para outra pasta, como `Filmes`.

**O preview não abre**
Abra no navegador o endereço que a IA mostrou (normalmente `http://127.0.0.1:4830`). Se outra
edição já estiver aberta, a porta pode ser outra, como 4831. O endereço certo fica anotado em
`edit/preview_cache/server.json`.

**Cliquei em Aprovar e nada aconteceu (Codex)**
Mande uma mensagem na conversa, por exemplo "pronto". O Codex só vê o que você fez no preview
quando você escreve.

**Cores estranhas em vídeo de iPhone**
Vídeo gravado em HDR pode ficar com a cor diferente depois do corte. Para os próximos vídeos,
desligue em **Ajustes > Câmera > Gravar Vídeo > Vídeo HDR**.

**O disco está enchendo**
Depois de terminar um vídeo, você pode apagar as pastas `clips`, `renders` e `preview_cache` dentro
de `edit`. Elas são só arquivos temporários e a skill recria se precisar.

**O instalador falhou no "uv sync"**
Leia a linha de ERRO do instalador: ela diz se é internet (confira a conexão e rode de novo) ou se
uma biblioteca não existe para este computador (veja "Do que você precisa").

## Privacidade

O corte, a transcrição, o recorte da tela verde e a montagem acontecem no seu computador. Só sai para a internet: o download
do modelo de voz na primeira vez, a busca de imagens (Wikimedia Commons ou Pexels) e, se você
quiser, o pedido de imagem com IA ao OpenRouter e o pedido de trilha ou efeito à ElevenLabs, na sua
conta. Nesses pedidos vai só o texto que descreve a imagem ou o som, nunca o seu vídeo.

O preview só aceita conexões deste computador e só grava cliques feitos na própria página do
preview (outro site aberto no navegador não consegue aprovar nem ler a sua edição).

## Licença

Uso restrito a quem tem acesso ao produto. Veja `LICENSE.md`. Partes de código aberto, fontes, o
modelo de detecção de rosto, o modelo de recorte da pessoa (tela verde) e os efeitos sonoros incluídos estão
listados em `THIRD_PARTY_NOTICES.md`.

Os 24 efeitos sonoros prontos (`whoosh`, `pop`, `click`, `tick`, `rise`, `cash`, `coin`,
`notification`, `success`, `error`, `count`, `keyboard`, `snap`, `mouse_click`, `bass_drop`,
`metal_hit`, `synth_hit`, `flash`, `charge`, `metal_riser`, `wind`, `rewind`, `gears`, `data`) são CC0
ou de domínio público, ou feitos pelo código do próprio editor, então eles vão junto e você pode usar
nos seus vídeos, inclusive comerciais, sem pagar e sem dar crédito a ninguém. O comprovante de licença de
cada som (página de origem, autor, licença, a frase da licença e a data em que ela foi lida) fica em
`assets/sfx/licencas/`.