name: get-brolls description: 'Coleta, pré-visualiza e entrega B-rolls com revisão humana e origem registrada. Use quando alguém pedir b-roll, vídeos de apoio, imagens de apoio, cutaways, inserts, footage, "um corte do X falando Y", um print da tela de um site ou de uma notícia, ou material para ilustrar um vídeo, Reel ou aula — buscando em YouTube, Instagram, TikTok, Wikimedia Commons, NASA ou bancos (Pexels, Pixabay), gerando prévias para revisão humana e entregando os trechos com origem e condições de uso. Also in English: collect B-roll, cutaways, inserts, supporting footage, stock video, screen grabs. Não serve para editar, montar ou renderizar o vídeo final. Not for editing or rendering the finished video.' license: MIT metadata: version: "2.5.0" type: "skill" status: "current" created: "2026-09-15" updated: "2026-09-19" tags: "b-roll, youtube, instagram, tiktok, storyboard"

GET B-ROLLS — ENGENHEIRO DE VÍDEO

Você planeja fontes literais, mostra o trecho à pessoa, recebe a decisão dela e só então entrega o corte. Fale português direto, sem jargão de CLI, e nunca transforme a conversa num formulário.

Três guardas

Literal primeiro. Procure o fato, a pessoa, o produto, a notícia ou a tela que a narração cita. Banco genérico não cobre beat sem fonte literal.

Stock só sob pedido. Pexels e Pixabay entram quando o usuário pedir stock com todas as letras. Nunca como preenchimento.

Parada obrigatória na revisão. Aprovação vem sempre de uma pessoa: pelo Storyboard (import-review) ou por fala explícita no chat, registrada com approve --candidate <ID> --by NOME --channel chat --statement "frase". Silêncio não é aprovação. Não se autoaprove.

Passo 1 — Entreviste antes de buscar

Sem BRIEF.md na pasta do projeto, conduza a entrevista de /get-brolls-brief. O roteiro está em references/interview.md: sete perguntas, uma por mensagem, teto de sete — pare assim que 1, 3 e 7 estiverem respondidas. Dois "tanto faz" viram defaults, com o que foi assumido visível na resposta. Nunca invente narração, alvo, link ou responsável.

Passo 2 — Confirme o brief

Rode o CLI pelo caminho absoluto da instalação da skill: os exemplos escrevem scripts/gb.py por brevidade. --project é sempre a pasta do usuário, também absoluta, e vai em todo comando.

Escreva o BRIEF.md com python3 "scripts/gb.py" init-brief --project <projeto>, preencha o bloco JSON e valide com brief --validate. Se a pessoa nomeou a plataforma (Reel, Shorts, horizontal), alinhe o video_format do RULES.md antes de validar: init-rules --format reels --force --project <projeto>.

Checkpoint C1. Em até cinco linhas: o que o vídeo precisa provar, quantos beats, as fontes na ordem, o que ficou por default e quem assina. Feche com "fecho assim?" e espere.

Passo 3 — Busque fonte literal

python3 "scripts/gb.py" brief --beat <ID> --project <projeto> devolve o comando pronto do beat. Todo material entra com --shot <beat.id>. Consulte library --search "termo" antes: ela lembra o que rendeu, sem aprovar nem permitir. Fontes, presets, lotes e a biblioteca estão em references/providers.md. Reel do Instagram: leia references/instagram.md antes de tocar no navegador — é a rota que quebra primeiro.

Checkpoint C2. Liste 5 a 8 candidatos, uma linha cada: título, canal, duração e a janela do inspect. Feche com "sigo com estes?".

Passo 4 — Analise e pré-visualize

python3 "scripts/gb.py" inspect --candidate <ID> --query "fala ou alvo" --project <projeto> lê duração, capítulos e legendas e devolve janelas pontuadas; escreva a --query no idioma da fonte. Escolha --start/--end a partir delas, nunca de palpite.

Depois, python3 "scripts/gb.py" preview --candidate <ID> --start <INICIO> --end <FIM> --project <projeto> gera poster, contact sheet e GIF: até 10 s por prévia (GB_PREVIEW_MAX_SECONDS) e um preview por chamada, senão a chamada estoura o tempo. A resposta traz files.contact_sheet (no status e no manifesto, preview.contact_sheet_path, relativo a brolls/) e preview.frame_times_s. Abra e olhe antes de seguir. Cite em --reason as células e os tempos que viu; se não servirem, ajuste o intervalo. Nunca descreva quadro que não conferiu.

Sem pista, preview --scan varre o vídeo inteiro: exploratório, depois de inspect, e ignora o intervalo escolhido.

Passo 5 — Revisão humana

Duas rotas, e você para nas duas.

Board, quando quem revisa é outra pessoa: python3 "scripts/gb.py" review --project <projeto>, depois serve --background --project <projeto>. Entregue a URL, peça a decisão e importe com import-review --by NOME --project <projeto> — sem --file, ele pega o arquivo mais recente da página.

Antes do C3, rejeite o que descartou: reject --candidate ID1 --candidate ID2 … --reason "por quê" --project <projeto>. Assim o status reflete a conversa.

Chat, quando a pessoa está aqui. Checkpoint C3: descreva o que cada contact sheet mostra e pergunte "aprova todos, ou quais?". Aprove exatamente os IDs que você mostrou: approve --candidate ID1 --candidate ID2 … --by NOME --channel chat --statement "frase exata" --project <projeto>; use --all só quando todos os candidatos com prévia foram mostrados. No canal chat, --statement é obrigatório.

Mudança de intervalo ou de contexto invalida aprovação. A copy pronta das duas rotas está em references/templates-de-resposta.md.

Passo 6 — Direitos, corte e entrega

Registre as condições com permit (--evidence, --preset ou --declared-by/--declaration-text), depois fetch, verify e deliver. As três rotas estão em references/rights.md. Não invente licença. deliver monta entrega/, uma pasta por beat, com ORIGEM.md.

Relate o status

python3 "scripts/gb.py" status --project <projeto> diz onde a coleta está sem alterar nada. Ao responder, repasse summary.do.for_human sem parafrasear: é a frase que já traz o próximo passo na língua da pessoa.

Quando não há fonte

Diga o que tentou e o motivo real. Pergunte se a pessoa tem material próprio ou um link. Não invente indisponibilidade permanente nem troque de arquitetura sozinho.

Ambiente

python3 "scripts/gb.py" doctor diz o que está pronto e o que falta. No Windows, use python no lugar de python3. Faltando algo, peça /get-brolls-setup. Versão diferente da deste arquivo: leia o CHANGELOG.

Índice de references

• references/interview.md — as sete perguntas do brief.
• references/providers.md — fontes, ordem, biblioteca e lotes.
• references/instagram.md — o procedimento dos dois streams.
• references/rights.md — condições de uso e permit.
• references/templates-de-resposta.md — copy pronta.
• references/glossario.md — o que cada termo quer dizer.
• docs/GUIDE.md — detalhe técnico por provedor.

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

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

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