O que video2knowledge faz?
Transforme um vídeo em: legendas com carimbo de data/hora → documento de conhecimento → HTML / Cartões Anki / 图文笔记.
Dois caminhos de ingestão local, inferência totalmente local por padrão (sem API de nuvem).
O processamento permanece totalmente local — vídeos, legendas e saídas nunca são
enviados; eles residem em uma pasta local runs/ (gitignorada). O repositório rastreia apenas
alterações de código/configuração.
A única exceção é opcional e nunca automática:
--backend openai-api/mimo-asr(ASR) e--api-base(documento de conhecimento, qualquer endpoint compatível com OpenAI) enviam esse áudio ou texto da legenda para o terceiro que você nomeou. Não passá-los mantém tudo no host. Diga isso explicitamente quando os recomendar.
Pré-requisitos e Configuração Inicial
Necessário no host: ollama, ffmpeg, python3 (ou uv). Única vez:
bash scripts/setup_models.sh
Isso (idempotentemente) detecta automaticamente o perfil de hardware da sua máquina (RAM / GPU /
Apple Silicon / NVIDIA) via scripts/hardware_profile.py, então baixa o
VLM recomendado, cria um venv em .venv/ e instala faster-whisper +
genanki. Veja o que foi escolhido:
python3 scripts/hardware_profile.py
Os perfis variam de tiny (máquinas com 4 GB → whisper-tiny + qwen3.5:0.8b) até
high-gpu (NVIDIA ≥8 GB → whisper-large-v3 + qwen3.5:9b no CUDA). Tabela completa e ajuste
em references/hardware-profiles.md. Substitua qualquer escolha com variáveis de ambiente
(VLM_MODEL=, ASR_DEFAULT_MODEL=, ...) ou flags de CLI.
Ative o venv antes de executar qualquer etapa Python:
source .venv/bin/activate
Escolha um Caminho de Ingestão (Etapa 1)
Árvore de decisão:
- Trilha de fala clara (palestra, conversa, entrevista, narração) → Caminho 2 (ASR).
Mais rápido, texto mais preciso, carimbos de data/hora detalhados. Para Mandarim, prefira o
backend FunASR Paraformer — pergunte à máquina com
python3 scripts/hardware_profile.py --recommend. →references/path2-asr.md - Vídeo silencioso / apenas slides / gravação de tela, ou você precisa de texto e diagramas na tela
→ Caminho 1 (multimodal). →
references/path1-multimodal.md - Vídeo de slide/PPT com trilha de fala (o caso comum de curso online): o conteúdo
principal está na tela (tabelas, fórmulas, exemplos) E o palestrante narra →
Caminho 3 (fusão de caminho duplo). Executa ASR para narração + VLM OCR para slides e
os funde por carimbo de data/hora. →
references/path3-fusion.md
Os Caminhos 1 e 2 emitem o mesmo esquema de segmento ({start,end,text}), então a Etapa 2 é
independente do caminho. O Caminho 3 emite um merged.json fundido consumido pelo --merged da Etapa 2.
Caminho 1 — Legendas multimodais
python3 scripts/mm_caption.py \
--video VIDEO --out-dir OUT \
--model openbmb/minicpm-v4.6:latest --interval 2.0
Saídas: OUT/captions.srt, OUT/captions.json, OUT/frames/.
Para vídeos de slides/PPT, use amostragem com dedup (propósito geral, sem ajuste de limite) além do prompt de OCR para tabela/fórmula:
python3 scripts/mm_caption.py \
--video VIDEO --out-dir OUT \
--mode dedup --prompt-ocr
Caminho 2 — Transcrição ASR
Qual mecanismo? Pergunte à máquina primeiro:
python3 scripts/hardware_profile.py --recommend
Medido em um curso de Mandarim de 61,5 h, ambos os mecanismos na mesma palestra de 30 minutos com a mesma lista de 39 termos de hotword:
| termos homófonos corretos | velocidade | |
|---|---|---|
faster-whisper small + hotwords | 44% | 2,5× tempo real |
| Paraformer-zh (FunASR, CPU) | 94% | 12–16× tempo real |
Hotwords não podem corrigir isso: 背谱/被谱 são idênticos em pinyin e tom, então o audio em si é ambíguo. A recomendação se baseia em RAM, não em VRAM — a vantagem do Paraformer é a precisão em Mandarim e é executado em CPU. Se você tem GPU, deixe-a livre para o VLM: executar whisper e o VLM juntos transforma uma solicitação de 8 tokens de 3,8 s para mais de 60 s.
Padrão (local, faster-whisper):
python3 scripts/asr_caption.py \
--video VIDEO --out-dir OUT \
--model small --language zh \
--hotwords "termo1, termo2" # viés de jargão opcional via initial_prompt
Paraformer (recomendado para Mandarim; precisa de seu próprio venv — o pino de tokenizers do funasr não co-instala com o ambiente principal):
bash scripts/setup_models.sh --with-funasr # constrói .venv-funasr, imprime o caminho
python3 .venv-funasr/bin/python scripts/asr_funasr.py \
--video VIDEO --out-dir OUT --language zh --hotwords "背谱,视谱,音阶"
Mecanismos de nuvem existem para hosts que não podem transcrever localmente e são opcionais —
eles enviam o áudio para um terceiro. bash scripts/setup_models.sh --with-openai-client adiciona o SDK openai necessário; --backend openai-api
aceita qualquer endpoint compatível com OpenAI e --backend mimo-asr é para
gateways em formato de chat que não retornam carimbos de data/hora. Veja references/path2-asr.md.
Saídas: OUT/subtitles.{srt,vtt,json}.
Em seguida, corrija homófonos. O ASR ouve sons, não palavras, então termos de domínio aparecem escritos errados e o erro se propaga para todos os artefatos downstream. Medido: 20 classes de erro genuíno em 46 lugares, 100% de precisão.
python3 scripts/fix_homophones.py --subtitles OUT/subtitles.json
Corresponde com pinyin sensível a tom, não distância de edição, e reescreve subtitles.srt /
.vtt para corresponder. Execute antes da Etapa 2. --dry-run para pré-visualizar, --block 实度
para colocar um fragmento na lista de bloqueio, --glossary @terms.txt para adicionar seus próprios.
Caminho 3 — Fusão de caminho duplo (ASR × VLM)
Execute o Caminho 2 e depois o Caminho 1 (OCR), alimente os termos de OCR de volta para as hotwords do ASR, funda e construa a partir do arquivo mesclado:
# 1a. ASR
python3 scripts/asr_caption.py --video VIDEO --out-dir OUT --language zh
# 1b/1c. quadros dedup + VLM OCR
python3 scripts/mm_caption.py --video VIDEO --out-dir OUT --mode dedup --prompt-ocr
# 1d. termos de OCR -> hotwords + verificação de cobertura (re-executar ASR com
# --hotwords @OUT/ocr_hotwords.txt quando a cobertura é baixa)
python3 scripts/hotwords_from_ocr.py --captions OUT/captions.json \
--subtitles OUT/subtitles.json --out OUT/ocr_hotwords.txt
# 2. fundir por carimbo de data/hora + verificação de alinhamento semântico
python3 scripts/merge_visual.py --subtitles OUT/subtitles.json --visual OUT/captions.json --out OUT/merged.json
# 3. construir (Etapa 2 com --merged)
python3 scripts/build_knowledge.py --subtitles OUT/subtitles.json --merged OUT/merged.json --out-dir OUT --format all
O loop de fusão tem três peças de caminho cruzado: (1) hotwords_from_ocr.py
extrai termos na tela (n-gramas CJK recorrentes, títulos de slides, acrônimos
Latinos — heurístico, sem LLM) e relata quais o ASR nunca ouviu,
os jargões provavelmente mal ouvidos; (2) merge_visual.py anexa visuais por
carimbo de data/hora e, em seguida, religa conservadoramente uma linha de narração a um slide
ADJACENTE quando sua sobreposição de palavras com o slide anexado por carimbo de data/hora é próxima de zero e o
vizinho corresponde claramente melhor (atraso do palestrante / deriva de carimbo de data/hora),
sinalizando casos incertos como weak em vez de adivinhar — exceto em slides
ASSENTADOS (≥60 s na tela), onde a elaboração verbal é a norma e nenhum sinal é emitido
(--no-semantic restaura a correspondência de carimbo de data/hora pura); (3) build_knowledge.py --merged alimenta o LLM com texto intercalado de áudio+visual (limites de bloco nunca
cortam uma tabela de slides; linhas de eco de prompt são filtradas por impressão digital de cada campo
lista; os limites de campo escalam com a duração do vídeo, 3× em 3 h) com marcadores ⚠️ em
notas de troca/fracas, e re-classifica campos de lista reduzidos por mapa em uma passagem global com
o resumo como contexto. As respostas do LLM no nível de bloco são armazenadas em cache em
build_cache.json, então uma construção de 3 horas interrompida é retomada em vez de
reiniciada. Em lotes, batch_run.py acumula termos de OCR em
course_hotwords.txt para que vídeos posteriores transcrevam melhor, e --asr-verify
re-transcreve um vídeo cuja cobertura de termos de OCR caiu abaixo de 50%.
O modelo de texto padrão segue o mesmo perfil de hardware: openbmb/minicpm5-2b
(2,5B denso, 1,6 GB) em low/low-mac/mid, e o VLM do Caminho 1 é baixado em
high+ (qwen3.5/qwen3.8 são visão+texto unificados, então nada é baixado
duas vezes). Substitua com --model, ou V2K_TEXT_MODEL= para fixar um para cada execução.
Medição de qualidade: scripts/recall_check.py --run-dir <dir> --draft emite uma
lista dourada de itens obrigatórios (termos / números de ambos os canais / cobertura de linha do tempo) que um
humano poda em minutos; --golden então avalia os artefatos produzidos contra ela
(baselines em tests/golden/BASELINE.md) — "conteúdo ausente" se torna um número
que você pode rastrear em todas as alterações de parâmetros.
Refinar em Artefatos de Conhecimento (Etapa 2)
Aponte build_knowledge.py para a saída .json de qualquer caminho:
python3 scripts/build_knowledge.py \
--subtitles OUT/subtitles.json \
--out-dir OUT --format all
Produz, em OUT/:
| Artefato | Arquivo | Seção |
|---|---|---|
| 2.1 Documento de conhecimento (com modelo) | knowledge.md | usa assets/default-template.md ou --template <arquivo> |
| 2.2 HTML autocontido | knowledge.html | linha do tempo clicável [mm:ss] |
| 2.2b Exportação para Office/impressão | knowledge.docx / knowledge.pdf | --format docx / --format pdf (automático em --format all quando python-docx/fpdf2 instalados) |
| 2.3 Cartões de conhecimento | cards.csv | question,answer,tags,timestamp,source — desduplicados: uma palestra longa é resumida map/reduce sobre blocos e o modelo refaz a mesma pergunta em cada um, então cada repetição é descartada (medido: 145 de 1608 cartões, pior caso 117 linhas → 11) |
| 2.4 Notas ilustradas (图文笔记) | notes.md + notes.html | quadros-chave × narração, veja abaixo |
| 2.4b Notas Office/impressão | notes.docx / notes.pdf | build_notes.py --docx --pdf (quadros incorporados) |
| 2.4c Notas destiladas (纯享版) | notes-distilled.md / .docx / .pdf | mesmos nós e quadros, sem narração citada — 42% menor e gratuito (renderizado a partir da saída já calculada) |
Em seguida, converta cartões para Anki (2.3 final):
python3 scripts/gen_apkg.py --csv OUT/cards.csv --out OUT/cards.apkg --deck "Cartões de Conhecimento do Vídeo"
Notas ilustradas (2.4, 图文笔记)
Uma nota rolável que intercala QUADROS-CHAVE desduplicados com a narração em torno
de cada carimbo de data/hora — o artefato "reassista como uma leitura". Precisa de frames.json
(de extract_frames.py, geralmente via modo dedup do Caminho 1) mais as legendas
de qualquer caminho:
python3 scripts/build_notes.py \
--subtitles OUT/subtitles.json \
--frames OUT/frames/frames.json \
--out-dir OUT --describe-frames
A densidade de nós é automática. --max-frames 0 (o padrão) dimensiona a nota para
~1 nó por 45 segundos, limitado a 12–60: um clipe de 12 minutos obtém 16 nós, uma
palestra de 41 minutos 55, uma de 3 horas 60. O orçamento antigo de 1-por-4min dava a uma
palestra de 37 minutos apenas 9 nós, e o 1-por-90s que se seguiu ainda tinha um piso
de 8 — medido em uma biblioteca de 306 vídeos / 61,5h, a média do clipe é de 12,1 min, então
o piso limitava a maior parte da biblioteca a 8 nós, não importando quanto tempo o vídeo
durasse. O piso era o que precisava mudar, não o teto. Passe um explícito
--max-frames N para fixá-lo. A seleção é estratificada por cluster: cada explosão de mudança
mantém seu quadro final assentado, então uma explosão de animação não priva mais slides-chave isolados
de seu próprio nó.
Por quadro-chave: título da seção LLM → imagem do quadro → descrição VLM 画面 opcional
(--describe-frames) → nota de 1-2 frases condensada da janela de narração →
trecho 原声 literal.
O prompt de 画面 pede por informação de ensino, não pessoas: anotações de pauta, símbolos de acorde, fórmulas de compasso, anotações e texto na tela — e recusa explicitamente descrever o performer ("senhora tocando piano", "explicação com gestos" não são o que uma nota de revisão precisa). Um quadro sem conteúdo de ensino legível recebe o nome de seu tópico em vez ("cena de execução de piano, sem legendas"). Esta única mudança de prompt é a diferença entre uma nota que ajuda você a estudar e uma que narra o vídeo.
Duas visualizações, uma passagem. Cada execução escreve um par gêmeo das mesmas seções — sem chamada de modelo extra:
| Arquivo | Contém | Para |
|---|---|---|
notes.md | quadros + notas + 原声 citado | verificação cruzada das palavras exatas do professor |
notes-distilled.md | mesmos nós, mesmos quadros, sem narração citada | revisão — medido em 295 nós, os blockquotes eram 53% dos caracteres |
--docx / --pdf exporta ambas as variantes (notes.docx + notes-distilled.docx,
e da mesma forma para PDF). notes.html incorpora quadros como base64 em um único
arquivo compartilhável — essa é apenas a visualização completa, sem gêmeo HTML destilado.
Degrada para quadros + trechos brutos quando nenhum modelo está acessível.
Dê ao VLM um modelo com capacidade de visão explicitamente. --describe-frames sem
--vlm-model volta para o modelo de texto, que não pode ver; a execução avisa e
descarta as descrições em vez de falhar uma vez por quadro:
python3 scripts/build_notes.py ... --describe-frames \
--model openbmb/minicpm5-2b --vlm-model openbmb/minicpm-v4.6:latest
Veja references/outputs.md para esquema, execuções de formato único e modo degradado.
Modelos Personalizados (2.1)
Modelo padrão: assets/default-template.md. Substitua com --template <arquivo>:
python3 scripts/build_knowledge.py --subtitles s.json --out-dir o \
--template ./meu-modelo-de-palestra.md --format knowledge
Os modelos são Markdown simples usando {{placeholders}} ({{title}}, {{summary}},
{{bullets}} (visão geral dos pontos principais de áudio e imagem), {{timeline}}, {{key_points}}, {{qa}}, {{glossary}},
{{source}}, {{duration}}, {{date}}, {{meta}}). Apenas os placeholders que você incluir são preenchidos;
todo o resto permanece literal. Especificação completa + 3 exemplos de modelos
(palestra / reunião / tutorial) em references/templates.md.
Processamento Apenas Local e Rastreamento de Alterações
Todo o processamento de vídeo permanece em sua máquina. Vídeos, quadros extraídos,
legendas, documentos de conhecimento e cartões são escritos em uma pasta local runs/ que é
gitignorada — nada sobre sua mídia é enviado ou commitado.
O repositório GitHub rastreia apenas alterações de código e configuração (scripts,
referências, modelos, README). Isso fornece um histórico claro de como a skill evoluiu, sem
expor a mídia de nenhum usuário. Use mensagens de commit descritivas feat:/fix:/docs:.
Se você quiser um registro local de uma execução específica, escreva um manifest.json nessa pasta
de execução (caminho usado, modelos, argumentos, lista de saída) — mas mantenha-o local:
cat > "$RUN/manifest.json" <<EOF
{"video":"~/Movies/palestra.mp4","pa
Nota: O conteúdo foi truncado para tradução conforme fornecido.