engenheirodevideo/get-brolls

Português · English

GET B-ROLLS

Da ideia ao trecho certo para a sua edição.

Encontre imagens de apoio, veja o movimento e revise cada escolha
antes de receber os cortes finais com suas fontes.

Comece aqui · Destaques · Documentação · Manual e tutorial · Guia completo

Get B-rolls é uma skill para coletar os vídeos e imagens que apoiam uma fala, ilustram uma ideia ou mostram exatamente a pessoa, o produto e o acontecimento citados no roteiro. Você descreve o que precisa; o agente pesquisa, prepara as prévias e reúne as escolhas em um storyboard para sua revisão.

• Escolha com contexto. Cada trecho pode reunir fala, motivo da escolha, intervalo, autor e fonte original.
• Veja antes de decidir. GIFs e sequências de quadros ajudam a avaliar ação, enquadramento e textos sobrepostos.
• Receba uma coleta organizada. Os cortes finais ficam junto de um registro de origem, revisão e condições de uso.

O agente procura a fonte literal do que você cita: o fato, a pessoa, o produto, a notícia ou a tela reais. Bancos de vídeo entram somente quando você pedir stock explicitamente. Um único insert funciona sem roteiro completo: basta explicar o que precisa aparecer.

A prévia pode baixar mídia de trabalho para mostrar o movimento. A entrega final depende da decisão humana e do registro das condições de uso da fonte. Se o intervalo ou o contexto mudar, o trecho volta para revisão.

• 2.5.0 Log por projeto em brolls/getbrolls.log (GB_LOG_LEVEL, GB_LOG_STDERR): comandos, trilha de aprovação, subprocessos e rede, sem nomes, frases de aprovação nem URLs. reject zera o output, verify confere todos os clipes e desmarca o que foi alterado, e deliver pula clipe rejeitado ou reprovado e lista em skipped. Storyboard local endurecido (só review.html, previews/ e clips/, cabeçalhos contra embutir a página). ~/.getbrolls/RULES.md ilegível passa a parar o comando em vez de ser ignorado.
• 2.4.3 Portão único de release (scripts/preflight.sh), versão escrita numa passada (scripts/bump_version.py) e espelho do SKILL.md gerado (scripts/gen_skill_mirror.py). GB_CACHE_DIR passa a valer no .env; GETBROLLS_CACHE_DIR continua funcionando. Sem mudança no fluxo de coleta.
• 2.4.2 Frontmatter do SKILL.md válido como YAML (a description ganha aspas; o GitHub não renderizava o arquivo).
• 2.4.1 Correção do workflow de release (FFmpeg no runner) e registro do ensaio ao vivo do Instagram. Sem mudança de comportamento na CLI.
• 2.4.0 Entrevista de intake e BRIEF.md por projeto (init-brief/brief), aprovação pelo chat (approve --all --by NOME --channel chat --statement "..."), biblioteca de aprendizados entre projetos (learn/library), análise da fonte antes de coletar (inspect, preview --scan), pasta entrega/ por beat (deliver), Storyboard que salva as decisões dentro do projeto, próximo passo pronto em status.summary.do, search --shot/--dry-run e init-rules --format.
• 2.3.8 Fila com ritmo para lotes sociais (queue), instagram_pairs --pace/--max-per-run/--continue-on-error, pausas do yt-dlp e respeito a Retry-After, erros legíveis com stderr redigido, cache por intervalo/NASA/drawtext, e comando serve para o Storyboard local.
• 2.3.7 Comando status --project ("onde estamos?"), CLI autoexplicativa com --version, comando de plugin /get-brolls-setup, quickstart "Primeiro B-roll em 5 minutos", caminhos de ferramentas fixáveis via GB_*_PATH e AGENTS.md como hub do repositório.
• 2.3.6. Instalação como plugin do Claude Code — o próprio repositório é o marketplace da skill.
• 2.3.5. Primeira release oficial no GitHub, endurecimento de rede (HTTPS/DNS) e dependências fixadas.

Histórico completo no CHANGELOG.md.

A skill só funciona completa com todas as ferramentas abaixo instaladas antes do passo 2. Sem uma delas, a coleta roda parcialmente e o Storyboard sai sem prévia ou sem contact sheet numerado.

macOS (Homebrew):

brew install python ffmpeg node git curl

Windows (winget, PowerShell 5.1 já serve):

winget install Python.Python.3.13 Gyan.FFmpeg OpenJS.NodeJS.LTS Git.Git

Ubuntu/Debian:

sudo apt install python3 python3-venv ffmpeg nodejs npm curl git

Depois do passo 2, python3 scripts/gb.py doctor é o gate: summary.missing vazio e contact_sheet.labels: true. Se aparecer drawtext em summary.optional, seu FFmpeg veio sem libfreetype: reinstale pelo comando acima (no macOS, brew reinstall ffmpeg).

No Claude Code, você também pode instalar a skill como plugin, sem clonar manualmente:

/plugin marketplace add engenheirodevideo/get-brolls
/plugin install get-brolls@engenheirodevideo

git clone https://github.com/engenheirodevideo/get-brolls.git
cd get-brolls

Ao copiar uma pasta de desenvolvimento, exclua .venv/, .tools/, caches, projetos e arquivos privados. skills/ e .claude-plugin/ são artefatos do plugin do Claude Code e podem ser omitidos ao copiar para o Codex. Instale as dependências no destino final e abra uma nova sessão do agente. Veja instalação, atualização e compatibilidade.

Na pasta instalada da skill, use o instalador do seu sistema.

macOS:

bash scripts/install.sh --check
bash scripts/install.sh
python3 scripts/gb.py doctor

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -Check
powershell -ExecutionPolicy Bypass -File scripts/install.ps1
python scripts/gb.py doctor

O instalador cria os ambientes locais e obtém as versões registradas de yt-dlp/EJS e Playwright CLI. --check só valida pré-requisitos (Python, FFmpeg/ffprobe, Node, curl, Git) e não instala nada; rode-o antes do instalador completo para saber o que falta. doctor confere a disponibilidade das ferramentas depois de instaladas; o acesso a cada fonte depende da URL e, quando necessário, da sua sessão de navegador.

Quer cada comando explicado, passo a passo? Veja o manual + tutorial.

A sequência mais curta pelo terminal, usando uma fonte sem chave (NASA). Troque /caminho/meu-video pelo seu projeto e <ID> pelo identificador devolvido pela busca — mantenha as aspas, porque identificadores podem conter espaços.

python3 scripts/gb.py search --provider nasa --query "Artemis launch" --limit 3 --intent literal --project /caminho/meu-video
python3 scripts/gb.py preview --candidate "<ID>" --start 0 --end 4 --project /caminho/meu-video
python3 scripts/gb.py review --project /caminho/meu-video
python3 scripts/gb.py serve --background --project /caminho/meu-video

Abra o storyboard local pela URL que o comando devolveu na hora, decida os trechos e exporte o JSON — abrir a página por file:// pode desativar o salvamento local, então exporte antes de fechar.

python3 scripts/gb.py import-review --by "Seu nome" --project /caminho/meu-video
python3 scripts/gb.py serve --stop --project /caminho/meu-video
python3 scripts/gb.py permit --candidate "<ID>" --evidence "Condições de uso reais dessa fonte" --project /caminho/meu-video
python3 scripts/gb.py fetch --candidate "<ID>" --project /caminho/meu-video
python3 scripts/gb.py verify --project /caminho/meu-video

No fim, verify responde "count": 1 e o clipe aprovado está em /caminho/meu-video/brolls/clips/, com origem, autor e decisão registrados em brolls/credits.md. Trocar nasa por commons segue o mesmo fluxo.

Se você nunca abriu um terminal, esta é a lista inteira. Todos os passos são conversa com o agente; nada aqui pede comando.

1. Instale uma vez. Peça /get-brolls-setup. Ele instala tudo e responde em uma linha se está pronto. Repita depois de cada /plugin update.
2. Diga o que você precisa. /get-brolls preciso de vídeos de apoio pro meu Reel sobre X — e diga também em que pasta o projeto vai ficar.
3. Responda à entrevista. O agente faz no máximo sete perguntas, uma por vez. "Tanto faz" é resposta válida: ele assume um padrão e mostra o que assumiu. Se preferir chamar direto, use /get-brolls-brief.
4. Confira o brief. Ele devolve em cinco linhas o que entendeu e pergunta "fecho assim?". Corrija ali mesmo.
5. Olhe a shortlist. Antes de baixar qualquer coisa, ele lista de 5 a 8 candidatos com título, autor e o trecho exato. Diga quais servem.
6. Aprove as prévias. Ou pelo chat ("aprovei todos", ou nomeando quais), ou pelo Storyboard: peça /get-brolls-review, ele te manda um link, você clica em Aprovar / Pedir ajuste / Reprovar e em Salvar decisões, e volta para dizer que salvou. Sem essa etapa, nada é baixado.
7. Diga de quem é o material. O agente registra as condições de uso com o que você informar. Quem responde pelas condições é você; ele só registra o que foi dito e de onde veio cada arquivo.
8. Receba. Os cortes saem em entrega/, uma pasta por trecho, com um ORIGEM.md dizendo de onde veio cada um.
9. Perdeu o fio? Peça /get-brolls-status: ele diz em que pé está e qual é o próximo passo.

Na ordem de uso, do primeiro contato à entrega:

1. Instale o ambiente (uma vez, na pasta do plugin ou do clone):

/get-brolls-setup   # instala as dependências e roda o doctor

2. Chame a skill com o que você precisa:

/get-brolls <seu pedido>   # Claude Code — descreva os inserts e a pasta do projeto
$get-brolls <seu pedido>   # Codex — mesma coisa
/get-brolls-brief          # entrevista e escreve o BRIEF.md do vídeo
/get-brolls-review         # monta o Storyboard, te manda o link e importa as decisões
/get-brolls-status         # diz em que pé está a coleta e qual é o próximo passo

3. Confira o ambiente quando algo não funcionar:

python3 scripts/gb.py doctor   # verifica ferramentas e diz o que falta

4. Pesquise e escolha (o agente executa por você, mas dá pra rodar na mão):

python3 scripts/gb.py search ...    # pesquisa candidatos na fonte escolhida
python3 scripts/gb.py preview ...   # gera GIF/contact sheet do intervalo
python3 scripts/gb.py review ...    # monta o storyboard brolls/review.html
python3 scripts/gb.py serve ...     # sobe o storyboard em http://localhost:8767/review.html

4b. Lotes sociais com ritmo (opcional, para vários Reels/vídeos de uma vez):

python3 scripts/gb.py queue --action add|next|mark|status ...   # enfileira, dá o próximo no ritmo certo e fecha o item

5. Decida e receba:

python3 scripts/gb.py import-review ...   # importa suas decisões do storyboard
python3 scripts/gb.py reject --candidate ID --reason "por que saiu"   # descarta e guarda o porquê
python3 scripts/gb.py permit ...          # registra as condições de uso da fonte
python3 scripts/gb.py fetch ...           # baixa o corte final aprovado
python3 scripts/gb.py verify ...          # confere a entrega no projeto

--reason é opcional e fica gravado no candidato como rejection.reason; o status mostra esse texto em items[].rejection_reason, então quem abrir o projeto meses depois lê por que aquele trecho saiu sem precisar perguntar a ninguém.

6. Se perdeu? Pergunte onde o projeto está:

python3 scripts/gb.py status --project /caminho/meu-video   # resumo por etapa, só leitura

Cada subcomando aceita help; a sintaxe completa está em Usar pelo terminal.

• Storyboard local. review gera brolls/review.html: uma página para alternar entre imagem estática e GIF, ver fala, intervalo, motivo da escolha, autor e fonte, e aprovar, pedir ajuste ou sugerir outra fonte por trecho. Detalhes do storyboard.
• Seis fontes cobertas. YouTube e TikTok sem API key via yt-dlp/FFmpeg, Instagram pelo navegador autorizado com coletor de pares vídeo/áudio incluído, Pexels e Pixabay com chave própria, Wikimedia Commons e NASA sem chave, e importação de arquivos locais. Veja fontes e transportes.
• Estado do projeto a qualquer momento. status --project resume candidatos, prévias, decisões, permissões e entregas, com o próximo passo sugerido, sem alterar o projeto. Veja uso pelo terminal.
• Lotes sociais com ritmo. queue enfileira URLs de Instagram/TikTok/YouTube e só devolve o próximo item quando o intervalo e os tetos por hora/dia permitem — a CLI nunca dorme, ela diz quanto esperar. serve sobe o Storyboard local em http://localhost:8767/review.html sem comando solto de http.server.
• Registro de origem. Cada trecho entregue carrega fonte, autor, intervalo e condições de uso — a aprovação editorial é sempre sua.
• Rede protegida. O coletor aceita somente URLs públicas HTTPS sem credenciais, rejeita resolução para redes locais e não segue redirecionamentos.
• Nativo em macOS e Windows. Instaladores próprios para os dois sistemas; os helpers Bash de YouTube são opcionais.
• Instalável como plugin do Claude Code. O próprio repositório é seu marketplace de plugin, com /get-brolls-setup configurando a pasta do plugin e uma skill espelhada que resolve caminhos via ${CLAUDE_PLUGIN_ROOT}. O fluxo clone-como-skill continua idêntico para Codex.

O comando review gera brolls/review.html: uma página local para avaliar a coleta, navegar entre os trechos e devolver decisões ao agente.

A galeria permanece estática; a animação acontece no quadro selecionado e respeita a preferência por movimento reduzido. Um print opcional da pessoa serve de contexto e permanece estático. Para avaliar uma composição pronta do mesmo insert, use GB_GIF_SCOPE=full com --full-preview-file.

Compartilhe a pasta brolls/ completa, para manter as imagens e os GIFs acessíveis. Para continuar editando ou regenerar prévias, preserve também os originais e .getbrolls-sources/. Detalhes da revisão.

Pexels e Pixabay são rota opcional: o agente recorre a bancos somente quando você pede stock explicitamente. O padrão é a fonte literal do que a narração cita.

Para Instagram, o agente opera o navegador autorizado e entrega os dois streams ao coletor; o script não captura a sessão sozinho. O guia Instagram cobre seleção dos pares, download, áudio e recuperação. Instagram e TikTok dependem da descoberta da URL no navegador; não há busca global por palavra-chave na CLI.

O coletor aceita somente URLs públicas HTTPS sem credenciais, rejeita resolução para redes locais, fixa o download no endereço validado e não segue redirecionamentos. Arquivos indicados por output= permanecem dentro de --config-output-root; outputs em lote ficam no diretório escolhido e arquivos existentes não são sobrescritos.

Os ensaios registrados incluem aquisição real de YouTube, Instagram, TikTok, Pexels e Pixabay. Para Commons/NASA, a evidência cobre busca e disponibilidade do arquivo, sem download integral naquele ensaio. Consulte os resultados e seus limites em Qualidade e evidências.

Execute os exemplos abaixo na pasta da skill. Troque /caminho/meu-video pelo seu projeto e <ID> pelo identificador retornado na busca — mantenha as aspas, porque os identificadores podem conter espaços.

python3 scripts/gb.py status --project /caminho/meu-video
python3 scripts/gb.py rules --project /caminho/meu-video
python3 scripts/gb.py references --project /caminho/meu-video
python3 scripts/gb.py search --provider youtube --query "NASA Artemis launch" --limit 3 --intent literal --project /caminho/meu-video
python3 scripts/gb.py preview --candidate "<ID>" --start 0 --end 5 --reason "Mostrar a decolagem citada no vídeo" --project /caminho/meu-video
python3 scripts/gb.py review --project /caminho/meu-video
python3 scripts/gb.py serve --background --project /caminho/meu-video

Abra o storyboard local pela URL que o comando devolveu na hora, revise os trechos e exporte as decisões — abrir por file:// pode desativar o salvamento local, então exporte antes de fechar.

python3 scripts/gb.py import-review --by "Nome de quem revisou" --project /caminho/meu-video
python3 scripts/gb.py serve --stop --project /caminho/meu-video
python3 scripts/gb.py permit --candidate "<ID>" --evidence "Evidência real das condições de uso" --project /caminho/meu-video
python3 scripts/gb.py fetch --candidate "<ID>" --project /caminho/meu-video
python3 scripts/gb.py verify --project /caminho/meu-video

Substitua o nome e a evidência pelos dados reais. Repita permit e fetch para cada candidato aprovado. approve também pode registrar uma decisão explícita já recebida. verify confere integridade e decodificação dos arquivos; a avaliação editorial é sua.

status responde onde a coleta está a qualquer momento — candidatos, prévias, decisões, permissões e entregas, com o próximo passo sugerido — e não altera o projeto. Os comandos do fluxo também devolvem um campo summary com uma linha dizendo o que acabou de acontecer. Detalhes do estado e do progresso.

Ao atualizar para 2.3.5, regenere o Storyboard e exporte uma revisão atual. JSONs baseados em decisões anteriores ou sem reviewEpoch são recusados. Veja a migração.

Os arquivos de projeto e os originais importados ficam locais. Pesquisa e aquisição remotas se conectam aos provedores escolhidos. Guarde chaves, sessão do navegador, configs Instagram e URLs assinadas em ambiente privado; esses dados não pertencem à pasta distribuída da skill.

O storyboard é destinado a projetos locais confiáveis e não possui autenticação de revisor. Compartilhe apenas o material necessário à revisão. As condições de uso pertencem a cada fonte; o registro de uma decisão não verifica automaticamente sua licença. A responsabilidade pelas condições de uso do material é de quem produz o vídeo; a skill responde pela fidelidade da fonte e pelo registro da origem de cada asset.

A resolução final depende da fonte: prefira 1080p quando disponível e confira as dimensões reais. A ferramenta preserva a proporção e sinaliza incompatibilidades de formato. Ela não monta automaticamente o vídeo completo, não faz busca de imagens via API nem entrega áudio isolado como asset final.

Execute um comando por projeto de cada vez. Preserve originais, cache e histórico de eventos. Se o registro for salvo e a geração da página falhar, execute review novamente. A CLI e o instalador são nativos em macOS e Windows; os helpers Bash de YouTube são opcionais e têm equivalentes no fluxo principal da CLI. Veja compatibilidade.

Para manter o projeto, comece por CONTRIBUTING e AGENTS. Consulte QUALITY, CHANGELOG e SECURITY para evidências, mudanças e tratamento de dados privados.

Criado e mantido por Bruno Moreira — Engenheiro de Vídeo. Instagram: @zbrunomoreira.

Código sob licença MIT. Dependências externas mantêm suas próprias condições, descritas nos avisos de terceiros.