Communitygithub.com

CacinieP/video2knowledge

Converta vídeos em legendas com carimbo de data/hora e artefatos de conhecimento estruturados. Dois caminhos de ingestão: um VLM multimodal nativo (máx. 4B parâmetros, via Ollama) lê quadros de vídeo amostrados em legendas com carimbo de data/hora; o ASR transcreve o áudio em legendas com carimbo de data/hora — faster-whisper localmente, ou FunASR Paraformer para Mandarim (medido 44% -> 94% em homófonos de domínio, 背谱 vs 被谱) com uma passagem de reparo de pinyin sensível ao tom posteriormente. Em seguida, refine em um documento de conhecimento estruturado (modelo personalizado suportado), uma página HTML autocontida, um CSV de cartões de conhecimento desduplicados, um baralho Anki apkg e notas ilustradas (图文笔记) em duas visualizações — a completa com narração citada e uma versão destilada 纯享版 para revisão. Totalmente local por padrão — nenhum vídeo, áudio ou saída sai do host; endpoints de ASR/LLM em nuvem são opcionais e explicitamente rotulados como upload para terceiros. O repositório rastreia apenas alterações de código e configuração. Use ao transcrever ou resumir um vídeo, construir cartões de estudo a partir de uma palestra ou gravação, transformar um si...

O que é video2knowledge?

Video2knowledge é uma skill de agente de IA que transforma vídeos em artefatos de conhecimento estruturados — legendas com carimbo de data/hora, documentos de conhecimento, cartões de estudo Anki e notas ilustradas — tudo processado localmente sem upload para a nuvem. Suporta três caminhos de ingestão: (1) legendas multimodais via VLM para vídeos silenciosos ou baseados em slides, (2) transcrição ASR com suporte a mandarim aprimorado para palestras e entrevistas, e (3) fusão de caminho duplo que combina ASR e OCR de VLM para o caso comum de cursos online com narração sobre slides. A skill é adequada para qualquer plataforma de agente de IA que possa executar Python e chamar ferramentas locais como ffmpeg e Ollama. O processo de refinamento produz uma ampla gama de saídas: um documento de conhecimento Markdown, HTML autocontido para navegação de linha do tempo clicável, CSV de cartões de pergunta-resposta desduplicados, baralho Anki, e notas ilustradas em duas variantes (completa com citações de narração e uma versão destilada para revisão). Os usuários podem personalizar modelos de documento de conhecimento e ajustar parâmetros de hardware para equilibrar velocidade e precisão. A skill enfatiza o processamento local-privado por padrão, com uploads para terceiros sendo explicitamente opt-in. Ela também inclui verificações de qualidade como recall de termos homófonos e rastreamento de conteúdo ausente em artefatos.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add CacinieP/video2knowledge

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 corretosvelocidade
faster-whisper small + hotwords44%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/:

ArtefatoArquivoSeção
2.1 Documento de conhecimento (com modelo)knowledge.mdusa assets/default-template.md ou --template <arquivo>
2.2 HTML autocontidoknowledge.htmllinha do tempo clicável [mm:ss]
2.2b Exportação para Office/impressãoknowledge.docx / knowledge.pdf--format docx / --format pdf (automático em --format all quando python-docx/fpdf2 instalados)
2.3 Cartões de conhecimentocards.csvquestion,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.htmlquadros-chave × narração, veja abaixo
2.4b Notas Office/impressãonotes.docx / notes.pdfbuild_notes.py --docx --pdf (quadros incorporados)
2.4c Notas destiladas (纯享版)notes-distilled.md / .docx / .pdfmesmos 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:

ArquivoContémPara
notes.mdquadros + notas + 原声 citadoverificação cruzada das palavras exatas do professor
notes-distilled.mdmesmos nós, mesmos quadros, sem narração citadarevisã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.

Habilidades Relacionadas