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.
Como funciona
O que ela coleta
Atualizações
- 2.5.2 O
doctor passa a conferir a .venv contra as versões fixadas: código atualizado sem rodar o instalador de novo aparece em summary.missing (item venv). Mensagem do instalador diz se a falha foi rede, hash ou versão do Python.
- 2.5.1 Segurança:
certifi 2026.10.19 tira a raiz emSign ECC Root CA - G3 (GHSA-6q48-6c7w-9gw2) e os instaladores instalam o pip 26.2.2 e todas as dependências Python conferindo o sha256 de cada arquivo (--require-hashes). Rode o instalador de novo. Dependências atualizadas como um conjunto revisado.
- 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.
Comece aqui
0. Instale a stack inteira
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.
| Ferramenta | Para quê | Sem ela |
|---|
| Python 3.11+ | CLI, ledger, coleta do Instagram | nada roda |
FFmpeg + ffprobe com libfreetype (drawtext) | poster, contact sheet numerado, GIF, cortes | sem prévia; sem drawtext, o sheet sai sem número/timecode e o Storyboard mostra só a legenda |
| Node 22+ com npm/npx | Playwright CLI e runtime EJS do yt-dlp | YouTube e Instagram falham |
| curl | download dos pares de stream do Instagram | Instagram falha |
| Git | clonar e atualizar | instalação manual |
| yt-dlp e Playwright CLI | instalados pelo install.sh/install.ps1 no passo 2 | YouTube/TikTok e Instagram falham |
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).
1. Coloque a skill no seu agente
Instalação como plugin do Claude Code
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
Instalação como plugin do Codex e Outros
git clone https://github.com/engenheirodevideo/get-brolls.git
cd get-brolls
| Agente | Instalação pessoal | Dentro de um projeto | Como chamar |
|---|
| Codex | ~/.agents/skills/get-brolls/ | .agents/skills/get-brolls/ | $get-brolls |
| Claude Code | ~/.claude/skills/get-brolls/ | .claude/skills/get-brolls/ | /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.
2. Prepare o ambiente
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.
Primeiro B-roll em 5 minutos
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.
Checklist de onboarding — só pelo chat
Se você nunca abriu um terminal, esta é a lista inteira. Todos os passos são conversa com o agente; nada aqui pede comando.
- 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.
- 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.
- 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.
- Confira o brief. Ele devolve em cinco linhas o que entendeu e pergunta "fecho assim?". Corrija ali mesmo.
- 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.
- 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.
- 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.
- Receba. Os cortes saem em
entrega/, uma pasta por trecho, com um ORIGEM.md dizendo de onde veio cada um.
- Perdeu o fio? Peça
/get-brolls-status: ele diz em que pé está e qual é o próximo passo.
Comandos
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.
Destaques
- 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.
Storyboard
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.
| Na revisão | O que você faz |
|---|
| Quadro selecionado | Alterna entre imagem estática e GIF, mantendo a proporção original. |
| Contexto e origem | Consulta fala fornecida, intervalo, motivo da escolha, autor e link da fonte. |
| Decisão por trecho | Aprovar, Pedir ajuste (com comentário; dentro dele cabe "procure outro vídeo") ou Reprovar. |
| Salvar decisões | Baixa um JSON para o agente importar no projeto e mostra a instrução de voltar à conversa. |
| Imprimir / PDF | Gera uma versão estática com quadros, fontes e comentários. |
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.
Fontes
| Fonte | Como encontrar | Como obter |
|---|
| YouTube | Busca por palavras ou URL | yt-dlp + FFmpeg; sem API key. |
| Instagram | Reel encontrado no navegador | Captura de vídeo e áudio do mesmo Reel; coletor incluído une os canais. |
| TikTok | URL completa descoberta no navegador | yt-dlp + FFmpeg; sem API key. |
| Pexels / Pixabay | Busca nas APIs dos bancos | Chave do respectivo banco; download HTTPS. |
| Wikimedia Commons / NASA | Busca nas APIs públicas | Download HTTPS; sem chave. |
| Arquivo local | Vídeo, imagem ou captura fornecida | Importação local com origem e autoria, quando informadas. |
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.
Usar pelo terminal
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.
- URL específica:
resolve --url URL_REAL --shot insert-01 --project /caminho/meu-video.
- Arquivo local:
resolve --file /caminho/original.mp4 --source-url URL_REAL --creator "Autor" --shot insert-01 --project /caminho/meu-video. Use metadados reais; uma fonte sem URL pode omitir --source-url.
- Fala exata: acrescente
--narration à prévia quando houver roteiro fornecido.
- Regras do projeto:
init-rules --project /caminho/meu-video cria um RULES.md editável com formatos, fontes preferidas e bloqueios.
- Memória de escolhas:
remember registra referências aprovadas ou rejeitadas; references consulta o histórico daquele projeto.
- Imagens e notícias: importe o arquivo ou a captura com sua procedência. Veja tipos de mídia e capturas pelo navegador.
- GIF padrão: 360 px, 8 fps, 128 cores, até 10 segundos e 5 MB. Intervalo acima do limite de duração é recusado; tamanho excessivo gera prévia estática com aviso.
GB_PREVIEW_MODE=static usa poster e sequência de quadros.
--reference-only prepara uma referência estática sem obter mídia remota; um poster isolado não comprova movimento.- Os utilitários em
scripts/getbrolls/tools/youtube/ oferecem busca, quadros, cortes e verificação de YouTube por VIDEO_ID. Seus resultados precisam ser importados pela CLI para integrar o registro e a revisão do projeto.
Use python3 scripts/gb.py --help e python3 scripts/gb.py preview --help para consultar os argumentos. Fora da pasta da skill, use o caminho absoluto de scripts/gb.py.
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.
Limites e privacidade
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.
Documentação
| Entrada | Para que serve |
|---|
| README.md | Visão do produto e primeiro uso (este arquivo). |
| README.en.md | Product overview and first use in English. |
| AGENTS.md | Índice para agentes e mantenedores: mapa do repositório, instalação por agente e regras de manutenção. |
| docs/MANUAL.md | Manual + tutorial: cada comando explicado, formato da resposta, BRIEF/RULES/.env e automação. Comece por aqui se está chegando agora. |
| docs/GUIDE.md · SKILL.md | Manual completo e instruções de execução para o agente. |
| docs/QUALITY.md | Testes, evidências reais e limites conhecidos. |
| docs/RULES.md · .env.example.pt-BR | Regras editoriais e opções de configuração. |
| docs/SECURITY.md | Tratamento de dados privados e relato de vulnerabilidades. |
scripts/getbrolls/ | Núcleo único: CLI, provedores, Storyboard, coletor Instagram e utilitários YouTube. |
Para manter o projeto, comece por CONTRIBUTING e AGENTS. Consulte QUALITY, CHANGELOG e SECURITY para evidências, mudanças e tratamento de dados privados.
Autor
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.
