🗃️ Conheça os tipos de fonte
Na trilha 1 você escreveu o ESCOPO.md: o domínio numa frase e a lista de fontes. Agora essa lista vira arquivo. Cada fonte tem um tipo, e cada tipo tem um coletor próprio no kit. O resultado de todos eles cai no mesmo lugar: a pasta raw/, com uma linha nova no manifesto para cada item. O mentor nunca lê a internet na hora de ensinar — ele lê o que você coletou.
🆕 Novo aqui?
- Acervo é o conjunto de tudo o que o especialista publicou e que você escolheu usar: lives, artigos, guias, repositórios.
- raw ("cru", em inglês) é a pasta onde o acervo fica exatamente como foi coletado. Ninguém edita nada ali depois.
- Coletor é um script Python do kit (pasta tools/) que busca um tipo de fonte e grava o texto em raw/.
- Manifesto é o arquivo raw/MANIFESTO.json: a lista de tudo que foi coletado, com tamanho e uma "impressão digital" de cada arquivo. O módulo 2.2 abre esse arquivo por dentro.
Como ler: cada tipo de fonte (esquerda) tem o seu coletor (meio), mas todos desembocam na mesma caixa iluminada. Repare que nada sai do raw/ sem passar pelo manifesto, e que até a falha tem destino escrito. É isso que torna o acervo conferível depois.
| Tipo | Coletor | Vai para | No piloto do Nei |
|---|---|---|---|
| Vídeo, live, aula | coletar_video.py | raw/videos/ | 14 lives |
| Guia, artigo, blog | coletar_web.py --tipo guia | raw/guia/ | 8 guias |
| Repositório | coletar_repo.py | raw/repos/ | não usado |
| Posts, notas, export | coletar_arquivo.py --tipo posts | raw/posts/ | não usado |
✓ Entra no acervo
- ✓Conteúdo público em que a pessoa explica como faz e por quê
- ✓Material longo, com raciocínio em voz alta (lives são ótimas)
- ✓Guias e documentos em que o método aparece passo a passo
- ✓Só fontes listadas no ESCOPO.md, com o tipo certo
✗ Fica de fora
- ✗Opiniões pessoais e políticas, vida privada
- ✗Qualquer coisa que faça o mentor parecer a própria pessoa
- ✗Fonte "achada no caminho" que não está no escopo
- ✗Conteúdo atrás de login pago coletado por API sem autorização
💬 Use a legenda antes da transcrição
Quase todo vídeo publicado já tem uma legenda automática: o texto que a própria plataforma gera a partir da fala, com marcas de tempo. Baixar só essa legenda é questão de segundos e não exige baixar o vídeo. Transcrever o áudio na sua máquina dá um texto parecido, mas custa minutos de GPU por vídeo. Por isso o coletor de vídeo segue uma ordem fixa.
🆕 O que é yt-dlp?
yt-dlp é um programa de linha de comando que lê páginas de vídeo. Com a opção --skip-download ele não baixa o vídeo: só pega título, ID e, se você pedir, as legendas. VTT e SRT são os dois formatos de arquivo de legenda mais comuns; ambos guardam "de tal segundo a tal segundo, este texto".
Legenda que já existe
Pede as legendas manuais e automáticas nos idiomas de idiomas_legenda do config, sem baixar o vídeo. Teto de 300 segundos.
Seu transcritor, se configurado
Só roda se não houver legenda e se transcrever_cmd estiver preenchido. Teto de timeout_video_s (3600 s no padrão).
Relatório de falhas
Se nada deu texto, o vídeo vira uma linha em raw/RELATORIO-FALHAS.md com o motivo ("sem legenda", "timeout na legenda"…). O coletor segue com os outros.
Como ler: a barra de cima é o lote inteiro de 13 lives buscado por legenda; a de baixo é uma única live sem legenda, transcrita na máquina. A de baixo é quase cinco vezes mais longa para um vigésimo do texto. É por isso que o transcritor é o plano B, nunca o plano A.
🔎 O comando que o coletor roda por baixo
Objetivo: ver com os próprios olhos se um vídeo tem legenda, antes de pôr ele no ESCOPO. Nada é baixado além do arquivo de legenda.
mkdir -p /tmp/teste-legenda yt-dlp --skip-download --write-subs --write-auto-subs \ --sub-langs pt,pt-orig --sub-format "vtt/srt/best" \ -o "/tmp/teste-legenda/%(title)s.%(ext)s" "<URL do vídeo>" ls /tmp/teste-legenda
Como verificar: se aparecer um .vtt ou .srt, o coletor vai resolver esse vídeo em segundos. Pasta vazia = esse vídeo vai cair no transcritor (tópico 3) ou no relatório de falhas.
💡 Dica do piloto
No mentor do Nei, idiomas_legenda ficou ["pt", "pt-orig"]: "pt-orig" é a legenda automática na língua original da fala. Das 14 lives do escopo, 13 tinham legenda e saíram de uma vez; 1 não tinha e foi parar no relatório de falhas, exatamente como desenhado.
🎙️ Plugue o seu transcritor
O kit não traz um transcritor embutido de propósito: cada máquina tem o seu (Whisper local, faster-whisper, o pipeline que você já usa). Em vez disso, ele aceita qualquer comando em transcrever_cmd, dentro do mentor.config.json. O coletor só exige uma coisa do seu comando: deixar um .txt, .srt ou .vtt dentro da pasta que ele indicar.
🆕 Novo aqui?
Transcritor é o programa que ouve o áudio e devolve o texto falado. Whisper é um modelo de transcrição que roda na sua própria máquina, sem custo por minuto. Placeholder é um marcador no texto do comando que o coletor troca por um valor real: aqui são dois, {url} (o link do vídeo) e {saida} (uma pasta temporária).
⚙️ O formato no mentor.config.json
Objetivo: ligar o plano B. Troque a parte entre < > pelo seu comando; mantenha {url} e {saida} exatamente assim.
{
"idiomas_legenda": ["pt", "pt-orig"],
"transcrever_cmd": "<seu transcritor> --url {url} --saida {saida}",
"timeout_video_s": 3600
}
Como verificar: rode o coletor num vídeo que você sabe que não tem legenda (tópico 2). A linha de saída deve terminar em (transcrição local) em vez de (legenda).
No piloto, o comando do Nei encadeia dois scripts que ele já tinha (um que baixa só o áudio e outro que transcreve com Whisper large-v3). O detalhe que importa não é o programa, é a moldura em volta:
"transcrever_cmd": "cd ~/projetos/inemavox && systemd-run --user --scope -q -p MemoryMax=24G -- python3 baixar_v1.py --url {url} --outdir {saida} --quality audio && systemd-run --user --scope -q -p MemoryMax=24G -- python3 transcrever_v1.py --in \"$(ls -S {saida}/* | head -1)\" --outdir {saida} --whisper-model large-v3"
⚠️ Teto de memória não é enfeite
Um modelo de transcrição grande pode comer a memória da máquina inteira e travar tudo antes de dar erro. Por isso o comando do piloto roda dentro de systemd-run ... -p MemoryMax=24G: se passar do teto, morre só a transcrição, não o computador. Somado ao timeout_video_s, você tem um limite de memória e um de tempo. Ajuste os números para a sua máquina, mas não tire os dois.
{url}
O link, já com aspas seguras
{saida}
Pasta temporária do coletor
.vtt / .srt primeiro
Depois .txt, se for só isso
Vazio = falha
Vai para o relatório com o exit
🌐 Colete páginas web e repositórios
Texto escrito é mais fácil que vídeo, mas tem as suas armadilhas: menus, rodapés e anúncios que não são o especialista falando; páginas que só mostram o conteúdo depois de rodar JavaScript; repositórios em que o raciocínio está espalhado entre README, docs e comentários. Os dois coletores de texto lidam com isso sem nenhuma biblioteca extra — só Python padrão e git.
🌐 coletar_web.py
- • Baixa a página e joga fora script, style, nav, footer, header, aside, form.
- • Títulos viram #, listas viram -; blocos de código mantêm a indentação.
- • Só aceita http:// e https://.
- • Menos de 80 palavras? Provável paywall ou página feita só de JavaScript → falha registrada, colete à mão.
- • Salva em raw/<tipo>/<titulo>-<hash>.md.
📦 coletar_repo.py
- • Clona raso (git clone --depth 1) numa pasta temporária.
- • Junta os .md, .rst e .txt (até --max-arquivos, padrão 40).
- • De cada arquivo de código, pega só o primeiro bloco de comentário, onde o autor costuma explicar o porquê.
- • Comentário com menos de 8 palavras é ignorado (é cabeçalho de licença, não explicação).
- • Salva tudo em um único raw/repos/<nome>.md.
📊 O que o piloto mostrou sobre guias
- • O coletor de web funcionou bem nos guias: no do makeshorts, pegou 885 palavras de 936 visíveis no HTML (o resto era menu e rodapé).
- • Os guias INEMA têm entre 885 e 1.427 palavras cada. Seis guias somaram 7.269 palavras, abaixo da meta de 8.000 do config.
- • Lição: a meta de palavras por tipo deve ser calibrada depois de ver o tamanho real das fontes. O módulo 2.2 mostra como o stats.py reprovou e o que foi feito.
Saída típica do coletor de web (formato real das linhas impressas)
ok 1418 pal. raw/guia/maestro-roteador-triagem-de-modelo-e-esforco-para--ded1bc.md
ok 885 pal. raw/guia/makeshorts-fabrica-de-shorts-com-ia-70fe54.md
já coletado: https://inematds.github.io/makeshorts/guia/
FALHA <URL>: texto curto demais
Como ler: "ok" traz o número de palavras e o arquivo criado. "já coletado" significa que a URL já está no manifesto e nada foi refeito (rodar de novo é seguro). "FALHA" sempre vem com o motivo, e a mesma linha vai para o relatório.
📤 Exporte à mão em vez de pagar API
Posts de rede social, newsletters, notas, PDFs: muita coisa boa do especialista não está numa página aberta. A tentação é ligar uma API paga que raspa tudo. O kit fecha essa porta por regra: a skill de coleta diz "nenhuma API paga sem autorização explícita do dono do projeto (serviço + finalidade)". O caminho é exportar à mão e entregar o arquivo ao coletar_arquivo.py.
🆕 O que é uma API paga, neste contexto?
Uma API é uma porta de acesso que um serviço oferece para programas. "Paga" quer dizer que cada chamada consome crédito ou cobra por volume. Um agente com acesso a uma chave de API pode gastar sem você ver. Ter a chave guardada num arquivo não é autorização para usar.
✓ Caminho do kit
- ✓Use a exportação oficial da plataforma (o "baixar meus dados")
- ✓Converta para .txt ou .md antes (PDF não entra direto)
- ✓Diga de onde veio em --origem: vira o campo url do manifesto
- ✓Sem autorização? Registre como falha e siga com o resto
✗ O que o kit não faz
- ✗Chamar serviço pago "só para testar"
- ✗Trocar o transcritor local por transcrição na nuvem sem pedir
- ✗Usar uma chave só porque ela existe no .env
- ✗Aceitar binário: o coletor só copia .md .txt .srt .vtt .json .csv .html
🧪 Exercício copiável — entre com uma exportação
Objetivo: pôr no acervo um arquivo que você exportou à mão, com origem rastreável. Rode na raiz do seu mentor.
python3 tools/coletar_arquivo.py <posts-exportados.txt> \ --tipo posts --origem "<export da rede X em 2026-10>"
Como verificar: a saída mostra ok <N> pal. raw/posts/<nome>.txt. Em seguida, grep -A3 '"tipo": "posts"' raw/MANIFESTO.json deve mostrar a sua origem no campo url.
▶️ Rode os 4 coletores
Todos os comandos abaixo rodam na raiz do mentor que o novo-mentor.py gerou (a pasta mentor-<slug>/). Todos aceitam várias URLs de uma vez, são seguros para rodar de novo (o que já está no manifesto é pulado) e devolvem exit 1 se pelo menos uma fonte falhou.
🎬 Vídeo
Objetivo: trazer o texto de um ou mais vídeos, por legenda ou pelo seu transcritor.
python3 tools/coletar_video.py "<URL do vídeo 1>" "<URL do vídeo 2>" --idiomas pt,pt-orig
Como verificar: ls raw/videos mostra um arquivo por vídeo, com o título e o ID no nome. head -5 raw/videos/<arquivo>.txt traz Origem: e Texto: legenda ou Texto: transcrição local.
🌐 Página / guia
Objetivo: trazer o texto limpo de guias ou artigos, separados por tipo.
python3 tools/coletar_web.py "https://inematds.github.io/<projeto>/guia/" --tipo guia
Como verificar: a linha "ok" deve ter algumas centenas de palavras ou mais. Abra o .md gerado: se ele começa com menu ou cookie, a página tem pouco texto real e vale coletar à mão.
📦 Repositório
Objetivo: juntar a documentação e os comentários de topo de um repositório do especialista.
python3 tools/coletar_repo.py https://github.com/inematds/mentor-especialista --max-arquivos 40
Como verificar: grep -c '^## ' raw/repos/mentor-especialista.md conta quantos arquivos entraram (cada um vira uma seção ##).
📤 Arquivo exportado
Objetivo: registrar notas ou exportações locais, com origem.
python3 tools/coletar_arquivo.py <notas.md> --tipo notas --origem "<caderno de 2026>"
Como verificar: python3 -c "import json;print(len(json.load(open('raw/MANIFESTO.json'))))" sobe em 1 a cada arquivo novo.
💡 Feche sempre com o mesmo comando
Depois de qualquer coleta, rode python3 tools/stats.py. Ele soma tudo por tipo, confere contra as metas e diz se o acervo está pronto (exit 0) ou o que falta. O módulo 2.2 explica cada motivo de reprovação.
Checagem rápida: uma live importante do especialista não tem legenda e o seu transcrever_cmd está vazio. O que o coletor faz?
📌 Resumo do Módulo
Próximo Módulo:
2.2 - Subagentes, manifesto e falhas: coletar em paralelo sem perder nada, e os dois bugs reais que o piloto achou.