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.
- 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 usarreel … --out PATH/--out=PATH(o mesmo para--png,--sheet,--report,--check-png) apontando para o diretório de entrega, será rejeitado porhooks/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 viareel deliver. - 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. - 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. Vejaresult.gate.blockers(falhas técnicas) epending_review(itens que precisam de confirmação humana);not_coveredlista itens não verificados — não diga "verificado". - 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 escrevafinal_watch, ouça o áudio completo e escrevafinal_listen. - 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, retornaDELIVERY_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. - 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=globalpara alcance em toda a máquina. - Vídeos gerados por scripts de renderização próprios do projeto também seguem os passos 3–6.
- 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_levelpara coleções epolicy: "trim"compara loudness e true peak faixa por faixa, com a mesma tolerância de uma faixa individual. - Erros de parâmetro também geram saída JSON (
ARG_INVALID, código de saída 2);--helpexibe texto de ajuda.reel voice checkverifica chinês (padrão--lang zh) e requerpypinyin(instalado no mesmo venv); se faltar, retornaBACKEND_UNAVAILABLE;reel wordsrequer apenaswhisper-clie 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_changee aqueles com chavetext/title/caption/labelno 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 emallowcom justificativa. O vocabulário de verificação de texto está na seçãotextdo perfil:bannedeextra_banned(substrings case-insensitive, falha se encontrar; palavras proibidas do projeto são adicionadas emextra_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, acionaneeds_review, exigindo um registro de revisãotext_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
- 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). - 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 - Escreva o plan.json (EditPlan v1):
camera: []para câmera realmente estática;zoom_toreferencia uma observação para aproximar;tracksegue observações em múltiplos pontos no tempo;transition_outpara transição. Os takes de vídeo não devem cruzar os pontos de corte identificados porinspect. - 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. - 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;checksinclui a taxa de amostragem. Se todos oscheckspassarem, 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-runpara 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.
- 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. reel words voice.mp3 --out words.json(whisper local para tempos palavra por palavra).- No plano, use takes com
kind: "web",camera: [{"op": "follow"}],highlight: [{"text": "texto original da página…", "sync": "voice"}], eaudio.wordsapontando parawords.json. 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 autoenviará 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% retornaGPU_BUSY, não disputa. O flock remoto garante que apenas uma tarefa GPU do reel seja executada por vez. reel remote probepara verificar o status;reel remote setup-visionpara criar um venv independente na máquina remota (torch + OWLv2).