Communitygithub.com

reel

Ferramenta de criação e edição de vídeos para agentes de IA: vídeos promocionais, vídeos com locução, lyric videos, montagens com fotos e música, edição de material bruto, close-ups com zoom e vídeos de página web com destaque. A entrega deve seguir o fluxo reel check → reel deliver e produzir um recibo final.

O que é reel?

O **reel** é uma habilidade especializada para agentes de IA (como Claude Code) que atua como um sistema completo de produção e edição de vídeo, baseado no FFmpeg. Ele permite que o agente analise o material de origem, defina objetivos, escreva um plano de edição e, em seguida, use comandos específicos para renderizar e validar o vídeo final. A ferramenta suporta múltiplos formatos, incluindo vídeos promocionais, lyric videos (MV), montagens de fotos com locução e narração, e até mesmo vídeos de páginas web com elementos destacados em sincronia com a locução. O fluxo de trabalho é altamente estruturado e possui um sistema de 'portão de entrega' obrigatório: o agente deve registrar o brief, produzir uma amostra de voz aprovada, executar verificações técnicas (`reel check`), passar por uma revisão humana (`reel scrub`) e, finalmente, entregar o vídeo usando o comando `reel deliver`, que gera um recibo digital (`status: final`). Somente com esse recibo o agente pode declarar a tarefa como concluída. O reel também oferece suporte a renderização remota em GPU (NVIDIA), detecção de batidas musicais para sincronização, e um sistema de perfis de projeto para configurar resoluções, taxas de quadros e limites de áudio.

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

Perguntar na sua IA favorita

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

Documentação

reel — Ferramenta de criação/edição de vídeo para agentes

Ferramenta em camadas com FFmpeg como núcleo: o agente analisa o material, define objetivos e escreve um plano; o código cuida da geometria dos enquadramentos, renderização e validação. A proporção é configurável (padrão retrato 1080×1920). Comandos e detalhes de formato estão no README do motor e em docs/engine.zh.md; leia-os antes de começar.

Portão de entrega (obrigatório)

Regras que ninguém aplica são o mesmo que não existir. Cada passo abaixo tem código para impedir a entrega sem o recibo final.

  1. Escreva o brief antes de começar ($P/brief.json) e registre-o: reel register brief.json. Especifique o idioma de entrega, se é final ou amostra, o diretório de entrega e o que não pode ser alterado; se não souber, pergunte ao usuário. Após o registro, usar cp/mv/ffmpeg no Bash para escrever diretamente no diretório de entrega, ou usar reel … --out PATH / --out=PATH (o mesmo para --png, --sheet, --report, --check-png) apontando para o diretório de entrega, será rejeitado por hooks/guard_delivery.py. Este guard analisa o texto do comando e faz o possível: curingas, chaves, substituição de comandos, scripts internos e gravação remota podem escapar; não o trate como permissão, a entrega só é feita via reel deliver.
  2. Amostra de áudio primeiro: Não há áudio padrão fixo. Primeiro, produza uma amostra de 10–20 segundos para a pessoa ouvir. Após a aprovação, escreva a citação original, o caminho da amostra e o sha256 da amostra em brief.voice.approved; trocar de voz requer nova audição.
  3. Verificação após a renderização: reel check final.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|projeto.json]. Exit 1 = não pode entregar. Veja result.gate.blockers (falhas técnicas) e pending_review (itens que precisam de confirmação humana); not_covered lista itens não verificados — não diga "verificado".
  4. Revisão: Revise cada item em needs_review (reel scrub / extração de quadros), escrevendo uma observação com timestamp para cada um; assista ao vídeo completo e escreva final_watch, ouça o áudio completo e escreva final_listen.
  5. Entrega: reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json. Se as condições de final não forem atendidas, retorna DELIVERY_NOT_FINAL, só permitindo --sample, com o nome do arquivo contendo "amostra_pendente". O mesmo número de versão não pode ser entregue novamente; versões antigas não são deletadas ou sobrescritas.
  6. Condição para declarar "concluído": Obter o recibo com status: final (reel receipt <recibo> para verificar). Caso contrário, diga honestamente "não concluído / amostra pendente / aguardando audição". hooks/deliver_gate.py (Stop hook) bloqueará declarações de "concluído" sem recibo; o recibo deve corresponder à obra mencionada (quando nomear a obra e a versão, a correspondência é feita pelo nome da obra e versão). Este hook, por padrão, só monitora projetos registrados e turnos que chamaram reel; REEL_GATE_SCOPE=global para alcance em toda a máquina.
  7. Vídeos gerados por scripts de renderização próprios do projeto também seguem os passos 3–6.
  8. MV: Adicione --contract mv.json. A verificação da letra lê a camada de texto da letra declarada no contrato (cada frase tem texto na camada durante o canto, sem texto antes do início do canto), não lê os pixels da imagem final, portanto não se pode afirmar com base nisso que "a letra na tela foi verificada". song_level para coleções e policy: "trim" compara loudness e true peak faixa por faixa, com a mesma tolerância de uma faixa individual.
  9. Erros de parâmetro também geram saída JSON (ARG_INVALID, código de saída 2); --help exibe texto de ajuda. reel voice check verifica chinês (padrão --lang zh) e requer pypinyin (instalado no mesmo venv); se faltar, retorna BACKEND_UNAVAILABLE; reel words requer apenas whisper-cli e o modelo.

Exemplo de brief.json (para MV, adicione "kind": "mv"):

{"version": "reel.brief.v1", "name": "Vídeo Promocional", "language": "pt-BR", "deliverable": "final",
 "delivery_root": "~/Deliveries/<projeto>", "must_not_change": ["créditos finais"],
 "voice": {"mode": "tts", "voice_id": "pt-BR-AntonioNeural",
           "approved": {"voice_id": "pt-BR-AntonioNeural", "by": "user", "quote": "Esta voz está boa",
                        "sample": "voice_sample.mp3", "sample_sha256": "<resultado de shasum -a 256>"}},
 "profile": "default"}
  • Apenas os campos name, must_not_change e aqueles com chave text / title / caption / label no brief são escaneados para texto; language, delivery_root, voice.* não são escaneados.
  • Se não houver locução, escreva "voice": {"mode": "none"}; para gravação real, escreva "recorded". Para versão silenciosa, use um perfil de projeto: {"extends": "default", "audio": "silent"}.
  • Perfis: default (limiares genéricos), social-vertical (redes sociais retrato: 1080×1920 30fps, -16 LUFS); diferenças do projeto são escritas em um perfil de projeto (extends), com permanências intencionais registradas em allow com justificativa. O vocabulário de verificação de texto está na seção text do perfil: banned e extra_banned (substrings case-insensitive, falha se encontrar; palavras proibidas do projeto são adicionadas em extra_banned), banned_words (palavras inteiras maiúsculas com distinção de maiúsculas/minúsculas: TODO / TBD / FIXME, falha se encontrar), review (placeholder, lorem ipsum, palavras inteiras, aciona needs_review, exigindo um registro de revisão text_scan).

Início de cada bloco de chamada Bash

Cada chamada Bash do agente é um shell novo; as funções não são preservadas. Portanto, reel é um script no PATH (bin/reel), não uma função. Ele seleciona o interpretador na ordem: REEL_PYTHON → ~/.local/share/reel/venv/bin/python → python3. Se houver problemas de ambiente, execute primeiro reel doctor (lista dependências obrigatórias e opcionais e correções; se faltar obrigatória, sai com código 1):

command -v reel >/dev/null || export PATH="$HOME/.claude/plugins/reel/bin:$PATH"
P="$HOME/work/<projeto>"; mkdir -p "$P/preview" && cd "$P"   # artefatos no diretório do projeto, não em /tmp

Fluxo de trabalho padrão

  1. Prepare o material no diretório do projeto $P (material, observations.json, plan.json, previews, vídeo final — tudo no mesmo diretório; um diretório por plano, .reel-history/ para revisões).
  2. Analise o material, defina objetivos:
    reel inspect material/a.jpg material/b.mp4
    reel frame material/a.jpg --out "$P/preview/a_grid.png"          # Leia a imagem com grade 0–1, identifique os retângulos alvo
    reel observe --obs observations.json --src material --asset a.jpg --bbox x0,y0,x1,y1 --label "Alvo"
    reel locate  --obs observations.json --src material --asset b.mp4 --t 2 --query "copo vermelho" --check-png "$P/preview/chk.png"  # OWLv2, requer torch
    
  3. Escreva o plan.json (EditPlan v1): camera: [] para câmera realmente estática; zoom_to referencia uma observação para aproximar; track segue observações em múltiplos pontos no tempo; transition_out para transição. Os takes de vídeo não devem cruzar os pontos de corte identificados por inspect.
  4. Validação + pré-visualização: reel validate plan.json; reel compile plan.json; reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png", veja o mosaico para confirmar o movimento da câmera.
  5. Renderização: reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where mac. O áudio final é fixo em AAC 48 kHz; checks inclui a taxa de amostragem. Se todos os checks passarem, isso apenas indica que a renderização não quebrou; em seguida, siga os passos 3–6 do portão de entrega.

Linha do tempo e detecção de batidas

  • Visualizar: reel timeline plan.json --format text; reel timeline plan.json --png tl.png [--beats beats.json]; reel scrub plan.json --cuts --render final.mp4 --out diretório.
  • Editar: reel edit plan.json --op '{"op":"trim","id":"s3","duration":2.4}' (escreve após cada validação); reel undo plan.json --to r2; reel history plan.json.
  • Detecção de batidas: reel beats musica.mp3 --out beats.json → reel snap plan.json --beats beats.json --mode downbeat (--dry-run para ver o relatório primeiro).

Página web: navegação com destaque sincronizado

Quando o material é uma página web, não há OCR: a posição do texto é lida diretamente do DOM, e os enquadramentos e destaques são renderizados quadro a quadro pelo navegador.

  1. Escreva o roteiro com base no texto original da página (as frases a serem destacadas devem corresponder exatamente ao texto da página), e use TTS para gerar voice.mp3.
  2. reel words voice.mp3 --out words.json (whisper local para tempos palavra por palavra).
  3. No plano, use takes com kind: "web", camera: [{"op": "follow"}], highlight: [{"text": "texto original da página…", "sync": "voice"}], e audio.words apontando para words.json.
  4. TEXT_NOT_FOUND = a página não contém o texto original; TEXT_NOT_IN_VOICE = a locução não corresponde.

GPU remota (opcional)

  • Defina REEL_REMOTE=user@gpu-host (pode separar vários com espaço). Então, reel render --where 5090 / --where auto enviará a renderização para um host NVIDIA remoto (NVENC + libass), e o artefato será trazido de volta e validado novamente. Se não definido, usa apenas a máquina local.
  • VRAM padrão ≤ 80%, se exceder, retorna NEED_USER_APPROVAL; informe o usuário e só depois de obter consentimento adicione --allow-over-80. Utilização da GPU ≥ 50% retorna GPU_BUSY, não disputa. O flock remoto garante que apenas uma tarefa GPU do reel seja executada por vez.
  • reel remote probe para verificar o status; reel remote setup-vision para criar um venv independente na máquina remota (torch + OWLv2).

Habilidades Relacionadas