Communitygithub.com

/reel: produção de vídeo para Claude Code

Mostra a um agente como planejar, construir ou editar um "reel" de modo que o resultado concreto seja um videoclipe finalizado. O procedimento passa por /reel: produção de vídeo para Claude Code, Ordem de trabalho: direção primeiro, depois edição, Portão de entrega (obrigatório). Use-o quando uma nova tarefa exigir esse ofício.

O que é reel: produção de vídeo para Claude Code?

O /reel é uma ferramenta em camadas construída sobre o ffmpeg, projetada para capacitar agentes de IA como o Claude Code a produzirem videoclipes de forma automatizada e controlada. O agente assume o papel criativo, decidindo quais tomadas usar, o assunto, os movimentos de câmera e o ritmo, enquanto o código lida com a geometria de enquadramento, renderização e verificações técnicas. O fluxo de trabalho segue uma ordem rigorosa: direção primeiro (criação de um briefing e storyboard), depois edição, e por fim uma etapa obrigatória de entrega que verifica conformidade técnica e revisão. A ferramenta suporta plataformas Linux e macOS, com uso opcional de GPU remota via SSH. O agente é chamado de `reel:director` e deve seguir o Procedimento Operacional Padrão (SOP.md) que inclui etapas como inventário de ativos, registro de briefing, audição de voz, verificação de renderização e revisão final. O sistema usa JSON para comunicação (todos os comandos retornam um objeto JSON) e impõe verificações rigorosas, como transcrição local via Whisper para validação de locução e restrições de escrita em pastas de entrega via hook Bash.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shuaige121/reel/tree/HEAD/skills/reel

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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.

  1. 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 escritas cp/mv/ffmpeg na pasta de entrega.
  2. 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 (--lang padrão en; 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 em brief.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 say do macOS é apenas para rascunhos internos, nunca para um vídeo entregue.
  3. 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) e result.gate.pending_review (itens que um revisor deve examinar).
    • Não confie apenas em ok. result.gate.not_covered lista o que não foi verificado (por exemplo, texto na tela, que não possui OCR); nunca diga que esses itens foram verificados.
  4. 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 assine final_watch (pelo menos um quadro por cena); ouça do início ao fim e assine final_listen (uma assinatura de agente precisa de observações com timecode; se o usuário ouviu, registre suas palavras exatas como quote). Quando você tiver assinado ambos, entregue como final: o recibo diz approved_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 de reviews.json está em docs/ENGINE.md.
  5. 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_FINAL e lista o motivo. Então apenas --sample é possível: o nome do arquivo carrega sample-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.
  6. 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.
  7. Vídeos feitos pelo próprio script de renderização de um projeto (build_*.py e 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), tts ou clone (estes dois também precisam de voice_id e um bloco approved escrito por reel voice check, ou uma aprovação humana com quote, sample e sample_sha256).
  • delivery_root deve 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) e vertical-strict (1080x1920 30 fps, -16 LUFS, estrito). Coloque diferenças do projeto em um perfil de projeto com extends; registre seguraças longas intencionais em allow com um motivo; adicione palavras proibidas (nomes de produtos antigos, texto de preenchimento) a text.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.

  1. Material em $P (assets, observations.json, plan.json, previews, renders e relatórios de verificação ficam todos lá; um plano por pasta).
  2. 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, aponte audio.voice para a faixa de música (ela é a âncora da linha do tempo).
  3. 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 observe para registrá-la, ou reel locate --query ... --check-png ... (OWLv2; olhe a imagem de verificação antes de usar uma detecção).
  4. Escreva plan.json (EditPlan v1): camera: [] mantém o quadro parado; zoom_to com um observation_id aproxima de um assunto registrado; use track quando o assunto se move em um vídeo; transition_out para transições. Não deixe uma tomada de vídeo cruzar um corte de cena relatado por inspect. audio.voice é obrigatório e é resolvido em relação a src_dir.
  5. 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.
  6. Renderize: reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local (use --where remote apenas 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 text ou uma imagem --png multitrilha), 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 com reel 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.mp3 fornece a temporização por palavra. Necessita de ./install.sh --web.
  • Projetos Shotcut: reel mlt project.mlt --video-only; --dupes encontra 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-80 apenas 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 probe relata o host; reel remote setup-vision instala 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.md no repositório): briefing, storyboard e revisão.
  • docs/ENGINE.md no repositório: comandos, EditPlan, briefing, revisões, recibos e perfis.

Habilidades Relacionadas