Escriba é um pipeline de extração, higienização via LLM e estruturação de dados não estruturados de vídeo para bases de conhecimento (RAG/NotebookLM).
Diferente de simples scripts de download, o Escriba atua como um Escriba Digital: ele não apenas "baixa" o conteúdo, ele o interpreta, deduplica roll-ups de legendas automáticas e segmenta semanticamente os tópicos para criar documentos .md de altíssima fidelidade.
Ativos de vídeo corporativo (como treinamentos, conferências e reuniões) frequentemente se tornam "dados mortos" devido à dificuldade de busca e consulta. O Escriba resolve este gargalo de negócios ao automatizar a extração de transcrições, aplicar processos de higienização semântica e gerar documentos Markdown hierarquizados.
O output final é uma base de conhecimento limpa e otimizada, pronta para:
- Alimentar ferramentas de IA generativa e assistentes virtuais (como o Google NotebookLM).
- Integrar arquiteturas RAG (Retrieval-Augmented Generation) locais ou em nuvem.
- Reduzir drasticamente os custos e o tempo operacional gastos com curadoria manual de conteúdo.
- Estudo Sem Interrupções: O Escriba cuida de toda a parte chata e técnica (como bloqueios e erros de login) para que você foque apenas no aprendizado.
- Economia de Tempo Real: Ele mapeia canais inteiros em minutos e baixa apenas o que é novo, garantindo que sua biblioteca esteja sempre atualizada sem esforço.
- Conteúdo Pronto para Estudar: Esqueça textos bagunçados. Você recebe documentos organizados por assunto, fáceis de ler e perfeitos para usar em ferramentas como o NotebookLM.
- Biblioteca de Conhecimento Offline: Uma ferramenta essencial para pesquisadores e estudantes que precisam organizar grandes volumes de informação e ter tudo acessível para consulta rápida, mesmo sem internet.
- ⚡️ Mapeamento JSON Híbrido: Leitura ultrarrápida de conteúdo via YouTube-DLP (YouTube/Vimeo) com fallback inteligente e unificação de metadados por pasta.
- 🛠️ Auto-Healing de Autenticação: Detecta cookies inválidos, regenera o cache e continua o download sem interrupções.
- 🧠 Motor de NLP Avançado: Pipeline de 6 fases para limpeza de ruído, deduplicação de "muletas" orais e ancoragem temporal.
- 📁 Repositório Único Inteligente: Banco de dados JSON amarrado ao nome da pasta (
escriba_[folder_name].json), com migração e consolidação automática de bases legadas. - 🎙️ Fallback de Áudio: Se o vídeo não possui legendas, o Escriba extrai o áudio bruto (
.mp3/.m4a) para processamento externo. - 📚 Consolidação Inteligente (Lexis): Agrupamento automático em volumes de ~1.8MB com índices cronológicos e metadados enriquecidos para o NotebookLM.
O fluxo de processamento do Escriba transforma conteúdo audiovisual bruto em documentos semânticos estruturados:
graph LR
A[YouTube / Vimeo / Video] --> B{Processamento}
subgraph B [Escriba Pipeline]
B1[Extração de Metadados]
B2[Higienização via LLM/NLP]
B3[Deduplicação de Roll-ups]
end
B --> C[Markdown Estruturado]
C --> D[(Bases de Conhecimento / RAG)]
O núcleo foi refatorado para seguir padrões rigorosos de qualidade Python (PEP 8):
youtube.py: Abstração de rede e orquestração doyt-dlppara YouTube.vimeo.py: Módulo especializado para extração e mapeamento de canais Vimeo.history.py: Gestão de estado atômico e persistência JSON.rules.py: Motor de limpeza léxica e processamento de regras.utils.py: Sistema de design CLI e utilitários auxiliares.lexis.py: Motor nativo de consolidação em volumes massivos; realiza enriquecimento de metadados e gera índices estruturados para o NotebookLM.
O Escriba é otimizado para macOS, mas roda perfeitamente em Linux, Windows e Docker.
A maneira mais rápida de rodar o Escriba com todas as dependências isoladas.
# 1. Build da Imagem
docker build -t escriba .
# 2. Execução (Monte o volume para preservar o cache e os arquivos)
docker run --rm -v "$(pwd):/app" escriba @CanalExemplo# 1. Clone e acesse o diretório
cd escriba
# 2. Prepare o ambiente (Criação única)
python3 -m venv .venv
./.venv/bin/python3 -m pip install -r requirements.txt
# 3. Use o script diretamente
python3 escriba.py @CanalTip
Auto-Venv: O script possui lógica interna para se re-executar no ambiente virtual local se detectado!
Para garantir a integridade das regras de limpeza e do banco de dados:
# Executa todos os testes unitários
./.venv/bin/pytest tests/O Escriba possui um motor de limpeza de termos dinâmico. Você pode personalizar como palavras específicas são tratadas criando um arquivo rules.txt:
- Global:
/Users/jandirp/scripts/escriba/rules.txt - Local:
./rules.txt(regras específicas para a pasta/projeto atual).
Formato do arquivo:
Termo Original, Termo Corrigido
PalavraAntiga = PalavraNova
Shabat, Shabbat
Ceu, Céu
O Escriba aceita Handles (@Canal), URLs completas (YouTube/Vimeo) ou IDs de vídeos únicos.
# Sincronização Incremental (Padrão: mapeia canal, extrai subs e gera MD)
escriba @FilipeDeschamps
# Suporte a Vimeo (Canais e Vídeos)
escriba https://vimeo.com/user136027363
# Modo Áudio: Baixa MP3 de um vídeo específico
escriba -a https://youtu.be/dQw4w9WgXcQ
# Histórico Retroativo: Baixar apenas vídeos a partir de uma data
escriba -d 20260101 @CanalExemplo
# Manutenção: Regenerar todos os arquivos .md a partir do cache local
escriba --regen-md
# Consolidação NotebookLM: Gera volumes baseados nos arquivos do canal
escriba @CanalExemplo --consolidar| Opção | Propósito |
|---|---|
-l, --lang |
Força o idioma das legendas (ex: pt, en). |
-a, --mp3 |
Baixa apenas o áudio convertido em MP3. |
-d, --date |
Data limite (YYYYMMDD). Baixa apenas vídeos posteriores a esta data. |
-rc, --refresh-cookies |
Purga o cache de cookies e extrai novos do Chrome. |
-f, --fast |
Modo Turbo: Remove o delay entre requisições de metadados. |
--no-md |
Pula a segmentação semântica e preserva apenas o arquivo bruto. |
--keep-srt |
Mantém o arquivo .srt no disco após converter para .md. |
--regen-md |
Modo Offline: Gera/Regenera todos os .md a partir dos .srt locais. |
--force |
(Usado com --regen-md) Sobrescreve arquivos existentes e força re-processamento. |
--upgrade-md |
Converte cabeçalhos de .md antigos para o formato YAML + H1. |
--consolidar |
Gera volumes unificados (Lexis) otimizados para o NotebookLM. |
--lexis-reset |
Apaga os volumes consolidados existentes e reconstrói do zero. |
--migrate |
Migra bancos de dados JSON legados para a estrutura multi-canal atual. |
--ignore-metadata |
Pula a recuperação de metadados faltantes no histórico. |
-v, --version |
Exibe a versão atual do sistema. |
O Escriba implementa um pipeline proprietário de Engenharia de Tópicos para garantir que a transcrição seja legível por humanos e útil para LLMs.
- Janelas Adaptativas: O tamanho da análise varia conforme a duração do vídeo.
- Vetorização TF-IDF: Cada janela é convertida em um vetor de importância léxica.
- Cosine Similarity: Detecta vales de similaridade para identificar quebras de tópico.
- Deduplicação Dinâmica: Remove o comportamento de "roll-up" das legendas automáticas.
- Dicionário de Marcadores Orais: Filtra ruídos como "né", "tipo", "basically".
- Sanitização Estrutural: Limpeza automática de artefatos HTML.
Ferramenta desenvolvida para capacitar estudantes e profissionais a dominar grandes volumes de informação. O Escriba é o guardião da memória digital.
MIT © 2026 Ekklezia.