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.

Atualizações

• 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.

Como funciona

O que ela coleta

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

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 --project /caminho/meu-video

Abra o storyboard local, decida os trechos e exporte o JSON — abrir a página por file:// pode desativar o salvamento local, então exporte antes de fechar. Depois, em outro terminal:

python3 scripts/gb.py import-review --file /caminho/revisao.json --by "Seu nome" --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.

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

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 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

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	Aprova, pede ajuste com comentário ou sugere outra fonte.
Exportar revisão	Salva um JSON para o agente importar no projeto.
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 --project /caminho/meu-video

Abra o storyboard local, revise os trechos e exporte as decisões — abrir por file:// pode desativar o salvamento local, então exporte antes de fechar. Depois, em outro terminal na pasta da skill:

python3 scripts/gb.py import-review --file /caminho/revisao.json --by "Nome de quem revisou" --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, o arquivo exportado 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.

URLs, arquivos locais e configurações

• 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/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	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.
assets/	Logo, estilos e scripts usados pelo Storyboard gerado.
agents/ · schemas/	Apresentação no agente e contrato de dados.
tests/ · .github/workflows/	Testes e automação de qualidade.

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.