O que reel: produção de vídeo para Claude Code faz?
Uma ferramenta em camadas construída sobre o ffmpeg. Você (Claude) analisa o material, decide o que mostrar e escreve um plano; o código lida com a geometria de enquadramento, renderização e verificações. O tamanho da saída é configurável (padrão vertical 1080x1920).
Comandos e formatos de arquivo estão documentados em docs/ENGINE.md do repositório reel. Leia-o antes do primeiro comando: cat "$(reel --root)/docs/ENGINE.md". reel <comando> --help lista todas as opções. Cada comando imprime um objeto JSON ({"ok": true, "result": ...} ou {"ok": false, "error": {"code": ..., ...}}) e sai com código 1 em caso de falha.
Ordem de trabalho: direção primeiro, depois edição
Para qualquer vídeo que alguém que não o usuário irá ver, siga SOP.md: S0 recepção, S1 pacote de fontes, S2 inventário de ativos, S3-S4 um agente director escreve direction/BRIEF.md e um storyboard, depois edite imediatamente (a etapa de aprovação G1 não bloqueia por padrão), em seguida o portão de entrega abaixo. Na S7, um agente director separado revisa o corte em relação ao BRIEF. Instalado como plugin, o agente é nomeado reel:director.
- Dê ao diretor os caminhos do material original, não suas próprias conclusões sobre ele.
- Se existir um BRIEF aprovado e o propósito, público e escopo do material não tiverem mudado, siga-o.
- Se o usuário disser que o vídeo é chato ou sem sentido, volte para S3 e repense a peça; não apenas re-edite.
Portão de entrega (obrigatório)
Cada etapa é imposta por código: pule uma e você não poderá entregar um corte final.
- Escreva o briefing primeiro (
$P/brief.json, modelo abaixo) e registre-o:reel register brief.json. Idioma de entrega, final ou amostra, pasta de entrega e o que não deve mudar: se você não conseguir preencher estes campos, pergunte ao usuário. Uma vez registrado, o hook de guarda Bash recusa escritascp/mv/ffmpegna pasta de entrega. - Audicione a voz. Não há voz padrão. Escolha uma que se encaixe no briefing, renderize uma amostra de 10-20 s e execute
reel voice check sample.mp3 --script sample.txt --brief brief.json. O whisper local transcreve a amostra e compara com o texto (--langpadrãoen; para uma locução em chinês passe--lang zh, que compara por pinyin sem tons, então a ortografia homófona não conta como erro); apenas uma taxa de erro de 10% ou menos escreve a aprovação embrief.voice.approved(by: claude, com a transcrição como evidência). Se o usuário ouviu, registre suas palavras exatas.- STT prova que as palavras são lidas correta e claramente. Não prova que a voz se adequa à peça: diga em sua resposta que você escolheu a voz, e troque de voz na próxima versão se o usuário não gostar.
- Uma nova voz precisa de uma nova verificação. A voz
saydo macOS é apenas para rascunhos internos, nunca para um vídeo entregue.
- Verifique a renderização:
reel check final.mp4 --plan plan.json --brief brief.json [--profile vertical-strict|project-profile.json] [--text caption.txt].- Saída 1 significa que não pode ser entregue. Leia
result.gate.blockers(falhas técnicas: mesmo uma amostra não pode ser entregue) eresult.gate.pending_review(itens que um revisor deve examinar). - Não confie apenas em
ok.result.gate.not_coveredlista o que não foi verificado (por exemplo, texto na tela, que não possui OCR); nunca diga que esses itens foram verificados.
- Saída 1 significa que não pode ser entregue. Leia
- Revise. Olhe cada item
needs_review(reel scrub, capturas de quadro) e escreva um registro de revisão por item com observações com timecode. Assista ao corte inteiro você mesmo e assinefinal_watch(pelo menos um quadro por cena); ouça do início ao fim e assinefinal_listen(uma assinatura de agente precisa de observações com timecode; se o usuário ouviu, registre suas palavras exatas comoquote). Quando você tiver assinado ambos, entregue como final: o recibo dizapproved_by: agent, e sua resposta diz "corte final, revisado por Claude, ainda não visto por você". O feedback do usuário se torna a próxima versão. O formato dereviews.jsonestá emdocs/ENGINE.md. - Entregue:
reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json.- Se as condições finais não forem atendidas, falha com
DELIVERY_NOT_FINALe lista o motivo. Então apenas--sampleé possível: o nome do arquivo carregasample-pending-review, e você deve chamá-lo de amostra ao informar o usuário. - Um número de versão pode ser entregue uma vez; versões antigas nunca são deletadas ou sobrescritas. Apenas quando o usuário pedir explicitamente para remover versões antigas:
reel register brief.json --remove, delete, então registre novamente.
- Se as condições finais não forem atendidas, falha com
- Dizer "pronto" requer um recibo com
status: final(reel receipt <receipt.json>re-verifica). Caso contrário, informe o status real: "não finalizado", "amostra pendente de revisão", "voz não audicionada". O hook Stop bloqueia uma alegação de conclusão que não tenha um recibo correspondente. - Vídeos feitos pelo próprio script de renderização de um projeto (
build_*.pye similares), ou compostos em outra ferramenta e exportados, passam pelas etapas 3-6 também.
{"version": "reel.brief.v1", "name": "spring-promo", "language": "en", "deliverable": "final",
"delivery_root": "~/Videos/deliveries/spring-promo", "must_not_change": ["end card credit"],
"voice": {"mode": "recorded"}, "profile": "default"}
voice.mode:none(sem voz),recorded(uma gravação real),ttsouclone(estes dois também precisam devoice_ide um blocoapprovedescrito porreel voice check, ou uma aprovação humana comquote,sampleesample_sha256).delivery_rootdeve ser um caminho absoluto existente (ou começar com~). Não pode ser a pasta home, Desktop, Documents, Downloads, a raiz do iCloud Drive, a pasta do projeto ou um pai dela.- Uma versão silenciosa usa um perfil de projeto:
{"extends": "default", "audio": "silent"}. - Perfis:
default(limiares iniciais gerais) evertical-strict(1080x1920 30 fps, -16 LUFS, estrito). Coloque diferenças do projeto em um perfil de projeto comextends; registre seguraças longas intencionais emallowcom um motivo; adicione palavras proibidas (nomes de produtos antigos, texto de preenchimento) atext.extra_banned.
No topo de cada chamada Bash
Cada chamada Bash inicia um shell novo, então comece cada chamada com:
REEL_PROJECT=spring-promo # nome deste projeto
command -v reel >/dev/null || { echo "reel não está no PATH (habilite o plugin, ou execute ./install.sh --link)" >&2; return 1 2>/dev/null || exit 1; }
command -v ffmpeg >/dev/null || { echo "ffmpeg não encontrado" >&2; return 1 2>/dev/null || exit 1; }
P="${REEL_PROJECTS_DIR:-$HOME/reel-projects}/$REEL_PROJECT"; mkdir -p "$P/preview" && cd "$P"
Todas as saídas ficam em $P, nunca em uma pasta temporária; caminhos relativos abaixo são relativos a $P.
Fazendo o corte
Você toma as decisões (quais tomadas, qual assunto, movimentos de câmera, ritmo); percepção, geometria, renderização e verificações são feitas pelo código. A sintaxe completa dos comandos está em docs/ENGINE.md.
- Material em
$P(assets,observations.json,plan.json, previews, renders e relatórios de verificação ficam todos lá; um plano por pasta). - Roteiro e voz. Escreva o roteiro de locução, escolha uma voz que se encaixe no briefing e passe na audição (etapa 2 do portão). Produza
voice.mp3(ou.wav) e, se quiser legendas,voice.vtt. Para trabalhos publicados, prefira uma gravação real ou uma voz cuja licença cubra o uso; para uma peça apenas com música, aponteaudio.voicepara a faixa de música (ela é a âncora da linha do tempo). - Olhe e escolha alvos:
reel inspect(liste cada arquivo) →reel frame(Leia a imagem com a grade 0-1 e leia a caixa do assunto) →reel observepara registrá-la, oureel locate --query ... --check-png ...(OWLv2; olhe a imagem de verificação antes de usar uma detecção). - Escreva
plan.json(EditPlan v1):camera: []mantém o quadro parado;zoom_tocom umobservation_idaproxima de um assunto registrado; usetrackquando o assunto se move em um vídeo;transition_outpara transições. Não deixe uma tomada de vídeo cruzar um corte de cena relatado porinspect.audio.voiceé obrigatório e é resolvido em relação asrc_dir. - Valide e pré-visualize:
reel validate→reel compile→reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png, então Leia a folha de contato para julgar o movimento de câmera. - Renderize:
reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local(use--where remoteapenas se o usuário configurou uma GPU remota e pediu). Passar nas verificações de renderização significa apenas que o arquivo não está quebrado; continue com as etapas 3-6 do portão.
Outros pontos de entrada, cada um com uma seção em docs/ENGINE.md:
- Inspecione e altere a linha do tempo:
reel timeline(--format textou uma imagem--pngmultitrilha),reel scrub(quadros ao redor de cada corte),reel edit/undo/history,reel preview --range(pré-visualização de baixa resolução com som). - Corte na batida:
reel beats music.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat; então verifique cada corte comreel timeline --png --beats. Necessita de./install.sh --beats. - Narre uma página web com destaques: uma tomada com
kind: "web"; as posições do texto vêm do DOM (sem OCR), então uma frase destacada deve corresponder exatamente ao texto da página;reel words voice.mp3fornece a temporização por palavra. Necessita de./install.sh --web. - Projetos Shotcut:
reel mlt project.mlt --video-only;--dupesencontra metragem de origem usada duas vezes.
Disponível: montagem de plano, aproximações sub-pixel em uma caixa de assunto, seguimento de assunto em movimento, transições xfade, legendas queimadas, música de fundo, correção de cor e LUTs, tomadas web, pesquisa de assunto OWLv2, verificações técnicas, entreva com portão. Não construído: transições suavizadas, interpolação de quadros, clonagem de voz.
GPU remota (opcional)
As partes --where remote são impostas por código.
- Use-a apenas quando o usuário tiver configurado
REEL_REMOTE(um destino ssh) e pedir; caso contrário, renderize com--where local. - O uso de VRAM é limitado a 80% por padrão. Quando um trabalho precisar de mais, a ferramenta retorna
NEED_USER_APPROVAL: informe o usuário primeiro, e adicione--allow-over-80apenas com consentimento dele. Utilização de GPU de 50% ou mais significa que outra pessoa está usando; não a tome. - Um trabalho de GPU do reel por vez (bloqueio de arquivo remoto). Não altere limites de energia. Nunca reinicie ou desligue o host.
reel remote proberelata o host;reel remote setup-visioninstala um venv separado com torch e os pesos do OWLv2 no host remoto.
Arquivos complementares
SOP.md: fluxo de trabalho direção-primeiro, papéis, etapas e condições de saída.- O agente
director(agents/director.mdno repositório): briefing, storyboard e revisão. docs/ENGINE.mdno repositório: comandos, EditPlan, briefing, revisões, recibos e perfis.