Communitygithub.com

ysyecust/lecture-to-notes

Converte vídeos de aulas do YouTube, Bilibili ou X/Twitter em notas completas em LaTeX/PDF, com alta fidelidade à fonte e foco no leitor.

O que é lecture-to-notes?

Esta skill transforma URLs de vídeos de aulas (YouTube, Bilibili, X/Twitter) em notas de estudo profissionais em chinês, no formato LaTeX (.tex) compilável e PDF renderizado. É ideal para estudantes, pesquisadores ou educadores que precisam de material escrito organizado, com figuras chave extraídas do vídeo e parágrafos coesos, evitando transcrições brutas ou imagens sem valor pedagógico. A skill garante a fidelidade ao conteúdo original, verificando cada alegação numérica, e exige uma série de verificações de qualidade como perfil de fonte, cobertura de átomos de ensino e densidade de conteúdo, com requisitos mínimos de caracteres chineses, figuras e seções dependendo da duração da aula. Suporta legendas manuais, automáticas, OCR para legendas embutidas e reconhecimento de fala local (ASR) com modelos como Whisper, além de extrair figuras com nomes semânticos e verificar sua precisão com timestamps. A saída final é um PDF estruturado, com seções, subseções, quadros de julgamento, fórmulas e uma síntese final, pronto para ser usado como material de estudo confiável.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/ysyecust/lecture-to-notes/tree/HEAD/skills/lecture-to-notes

Perguntar na sua IA favorita

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

Documentação

Aula para Anotações

Transforme um vídeo de aula do YouTube, Bilibili ou X/Twitter em um conjunto completo e compilável de notas .tex e um PDF renderizado.

Dependências

Verifique antes de começar (use which). Solicite ao usuário que instale quaisquer ferramentas ausentes.

FerramentaObrigatóriaPropósito
yt-dlpSempreDownload de vídeo/legenda/metadados (suporta YouTube + Bilibili + X/Twitter). Verifique yt-dlp --version: uma build com mais de ~90 dias falha em páginas atuais do Bilibili e YouTube
ffmpegSempreExtração de quadros, extração de áudio
xelatexSempreCompilação LaTeX (TeX Live + CTeX para chinês)
magickSempreMontagem de quadros e folhas de contato
ffprobeSempreDuração e altura do quadro (acompanha o ffmpeg)
pdftotextSempreVerificações de páginas renderizadas em verify_notes.py (poppler)
python3SempreScripts auxiliares instalados e suporte a ASR local
sherpa-onnx + modelo ASR XOpcional para ASR zh/enTranscrição local rápida em chinês/inglês com timestamps de token
Backend WhisperFallback ASR / não-zh-en / sem CCtranscribe_whisper.py escolhe mlx-whisper (macOS arm64) → faster-whisper → openai-whisper
rapidocr-onnxruntimeBilibili / quaisquer legendas embutidasocr_hardsubs.py lê a faixa de legenda e a geometria de sobreposição
Pillow + numpySempreframe_filter.py para cortes de sobreposição e painel composto, pontuações de cabeça falante

Instale a parte Python com pip install rapidocr-onnxruntime Pillow numpy mais um backend de transcrição: pip install mlx-whisper em Apple Silicon, caso contrário pip install faster-whisper (ou openai-whisper como o fallback mais lento). /ABSOLUTE/PATH/TO/lecture-to-notes/assets/smart_crop.py permanece um experimento opcional.

Verificação de pacotes LaTeX (NÃO pule — which xelatex sozinho é insuficiente)

which xelatex funcionando não significa que os pacotes LaTeX necessários estão instalados. Em instalações mínimas do TeX (ex.: MacTeX Basic, TeX Live scheme-basic), o binário existe mas ctex, tcolorbox e outros pacotes estão ausentes. Isso causa falhas silenciosas: linhas longas em chinês ultrapassam \textwidth (sem quebra de linha CJK) ou a compilação aborta com File '...' not found.

Verifique os pacotes necessários antes de começar:

MISSING=0
for pkg in ctex tcolorbox environ trimspaces listings hyperref booktabs float subcaption etoolbox; do
  if ! kpsewhich "$pkg.sty" >/dev/null 2>&1; then
    echo "❌ Pacote LaTeX ausente: $pkg"
    MISSING=1
  fi
done
if [ "$MISSING" -ne 0 ]; then
  echo "Instale os pacotes ausentes:"
  echo "  tlmgr install ctex tcolorbox environ trimspaces etoolbox"
  echo "Ou instale a distribuição TeX completa:"
  echo "  macOS:  https://www.tug.org/mactex/  (~4 GB, inclui tudo)"
  echo "  Linux:  sudo apt install texlive-full"
fi

Se ctex não puder ser instalado (ex.: devido a conflitos de versão do l3kernel em instalações mínimas), o notes-template.tex inclui um fallback que usa a quebra de linha CJK embutida do XeTeX (\XeTeXlinebreaklocale "zh") com fontes do sistema — sem necessidade de ctex ou xeCJK.

Cookies e atualização do yt-dlp

Cada plataforma suportada pode rejeitar um download não autenticado, e as duas falhas parecem diferentes:

SintomaPlataformaSignificado
Sign in to confirm you're not a botYouTubedetecção de bot
HTTP Error 412 na sondagem ou downloadBilibiliverificação anti-raspagem
WARNING: Your yt-dlp version (...) is older than 90 daysqualquerextratores são anteriores à marcação atual do site

Corrija a versão primeiro, porque um extrator desatualizado produz os mesmos erros que os cookies corrigem: brew upgrade yt-dlp, pipx upgrade yt-dlp, ou pip install -U yt-dlp, depois confirme com yt-dlp --version. O Homebrew desativa o auto-updater, então yt-dlp -U relata sucesso sem mudar nada.

Em seguida, forneça cookies. video_source.py probe os aceita diretamente:

python3 "/ABSOLUTE/PATH/TO/lecture-to-notes/assets/video_source.py" probe \
  --cookies-from-browser chrome "<URL>" > metadata.json

Use --cookies FILE quando o perfil do navegador não estiver disponível, por exemplo em um host headless. Uma sondagem que falha por motivo de autenticação agora nomeia a flag para tentar novamente, então trate essa mensagem como a próxima ação, não como um beco sem saída.

O resto do fluxo de trabalho chama yt-dlp diretamente. Em vez de editar cada comando, escreva um arquivo de configuração yt-dlp uma vez e aponte XDG_CONFIG_HOME para ele, para que downloads, buscas de legendas e buscas de miniaturas usem os cookies:

mkdir -p "$WORKDIR/.xdg/yt-dlp"
printf -- '--cookies-from-browser chrome\n' > "$WORKDIR/.xdg/yt-dlp/config"
# então prefixe cada chamada yt-dlp posterior neste diretório de trabalho da aula:
XDG_CONFIG_HOME="$WORKDIR/.xdg" yt-dlp --no-playlist ... "<URL>"

Cookies do navegador também desbloqueiam Bilibili 1080P+ para contas logadas, então a mesma configuração melhora a qualidade dos quadros.

Objetivo

Produzir uma anotação profissional de aula em chinês a partir de uma URL de vídeo do YouTube, Bilibili ou X/Twitter. A saída deve:

  • usar o conteúdo real de ensino do vídeo, não apenas a transcrição das legendas
  • colocar a imagem de capa original do vídeo na primeira página
  • incluir figuras de ensino em quadro cheio selecionadas pela revisão da folha de contato; quando o vídeo coloca uma alimentação de câmera e slides lado a lado, cada figura mantém um painel medido para que o texto do slide permaneça legível
  • permitir que um leitor capaz da primeira vez entenda a pergunta, mecanismo, evidência, consequência e limite sem decodificar a transcrição
  • atingir densidade de informação adequada à fonte — cada figura, caixa, fórmula e parágrafo ganha seu espaço
  • ser estruturalmente organizada com \section{} / \subsection{}
  • terminar com uma seção de síntese combinando as conclusões do palestrante e sua própria destilação
  • ser um .tex completo de \documentclass até \end{document}
  • compilar com sucesso para PDF

Padrão de qualidade inegociável (Codex / modo produção)

PARE e não reivindique conclusão a menos que cada item abaixo seja verdadeiro. Esboços de estrutura, PDFs com muitas imagens e pouca prosa, ou artefatos intermediários ausentes são falhas automáticas.

Artefatos obrigatórios do diretório de trabalho (devem existir em disco antes de dizer "pronto")

ArquivoConteúdo obrigatório
metadata.jsonDe video_source.py probe (ou despejo completo equivalente)
audio.srtFaixa de legenda final usada para escrita (CC manual, automática limpa, OCR de legenda embutida, ASR X ou Whisper)
audio_corrected.srtCópia da faixa final, ou faixa corrigida por glossário/LLM quando ASR local foi usado
hardsub_ocr.srtSaída de ocr_hardsubs.py extract quando ocr_hardsubs.py detect relatou legendas embutidas; ausente caso contrário
bands.jsonGeometria da sobreposição (faixa de navegação, faixa de legenda) de ocr_hardsubs.py detect --geometry ou frame_filter.py bands
layout.jsonLayout do painel de frame_filter.py layout sobre a amostra densa; sempre medido, composite: false registra um vídeo de imagem única
cover.jpgCapa da primeira página
video.mp4Fonte para quadros (pode ser omitido apenas se o usuário proibir o download e fornecer quadros)
frames/Amostra densa, padrão 1 quadro / 15s
frame_scores.jsonframe_filter.py score sobre a amostra densa; obrigatório quando o host não pode mostrar imagens
figures/Ativos de figura selecionados com nomes semânticos (fig_01_topic.jpg, …), sobreposições cortadas via bands.json, compostos cortados em um painel via layout.json
figure_manifest.tsvCabeçalho figure\tframe\tstart\tend\ttopic\tpanel — uma linha por imagem de figura; panel nomeia o painel layout.json que mantém (main, left, …) ou full
figure_verification.txtSaída completa de verify_figures.py sobre todos os timestamps do manifesto
lecture_profile.jsonPerfil de leitor e adequação à fonte; os campos obrigatórios são descritos abaixo
teaching_atoms.tsvCabeçalho atom\tstatus\tevidence — cada átomo de ensino mapeado para as anotações
numerical_claims.tsvGerado por extract_claims.py extract, preenchido por extract_claims.py check --write; apenas o cabeçalho é válido quando a aula não contém alegações numéricas
notes.texAnotações completas da aula em chinês
notes.pdfSaída de xelatex com duas passagens
verify_notes.txtSaída completa de verify_notes.py, terminando em OVERALL PASS

Perfil de adequação à fonte e contrato com o leitor (rígido)

Após a correção da legenda e a revisão da folha de contato, crie lecture_profile.json antes de esboçar as anotações:

{
  "mode": "technical-slide",
  "audience": "capable first-time reader",
  "central_question": "O que o leitor deve ser capaz de explicar após a leitura?",
  "reader_outcome": "Uma capacidade, decisão ou modelo mental concreto",
  "visual_teaching_atoms": 24,
  "formula_teaching_atoms": 18
}

Escolha exatamente um modo:

  • technical-slide: slides, trabalho no quadro, fórmulas, código ou diagramas carregam a maior parte do conteúdo de ensino;
  • conceptual-talk: uma palestra, entrevista ou discussão carrega a maior parte do conteúdo por meio de alegações, exemplos e raciocínio, em vez de mecanismos visuais;
  • mixed: ambos os modos contribuem com conteúdo de ensino substancial.

Conte visual_teaching_atoms e formula_teaching_atoms a partir da fonte, não do rascunho. Um átomo visual é um visual distinto da fonte que ajuda a ensinar um ponto. Um átomo de fórmula é uma equação ou derivação da fonte que vale a pena preservar. Não infle essas contagens para justificar mais ativos, e não classifique uma palestra conceitual como técnica meramente para acionar cotas.

Para todos os modos, os portões rígidos são fidelidade à fonte, cobertura completa de átomos de ensino, alegações numéricas rastreáveis, atribuição clara da fonte e um caminho coerente para o leitor. Os portões de densidade numérica abaixo são salvaguardas de adequação à fonte. Eles nunca autorizam equações inventadas, capturas de tela de cabeça falante de baixo valor, caixas repetitivas ou preenchimento com sinônimos.

Portões de densidade e estrutura (adaptativos à fonte)

Para uma aula de duração $T$ minutos (dos metadados):

Portão vs alvo (não confunda): os números abaixo são portões rígidos (falha = sem entrega). Uma nota de alta qualidade classe Codex geralmente fica ~25–40% acima do portão CJK; isso é um alvo, não um segundo piso rígido. Elevar o piso rígido ao valor de ouro medido incentiva preenchimento, não mais átomos de ensino. (Validado em CS336 L3: $T\approx 89$ → portão CJK 6246 / figs 25; ouro ~8035 CJK / 27 figs / 31 páginas.)

  1. Contagem de caracteres chineses no corpo de notes.tex (ideogramas unificados CJK apenas):

    • technical-slide: pelo menos $\max(5000,\ \mathrm{round}(70\times T))$;
    • mixed: pelo menos $\max(3500,\ \mathrm{round}(55\times T))$;
    • conceptual-talk: pelo menos $\max(2500,\ \mathrm{round}(45\times T))$. Não conte jargão em inglês, comandos LaTeX ou legendas sozinhas. Esses são pisos de completude, não convites para repetir a mesma ideia.
  2. Figuras: inclua cada átomo de ensino visual distinto que melhore materialmente a compreensão, até o alvo técnico $\max(20,\ \mathrm{round}(T/3.5))$. Uma conceptual-talk com quatro átomos visuais reais deve conter quatro figuras verificadas, não vinte quadros de cabeça falante. Uma aula liderada por slides com trinta mecanismos distintos não deve parar em vinte.

  3. Seções para $T\ge 60$: use pelo menos 8 para technical-slide, 6 para mixed e 5 para conceptual-talk, a menos que menos perguntas do leitor produzam uma estrutura comprovadamente mais clara. Cada seção principal responde a uma pergunta do leitor e termina com \subsection{本章小结} que declara a resposta e prepara a próxima pergunta.

  4. Caixas de julgamento: use caixas apenas quando elas separam uma definição, dependência de fundo, regra de decisão ou limite de falha do fluxo principal. O padrão técnico é 12 para $T\ge60$; mixed e conceptual-talk não têm cota de caixa. Nunca divida o raciocínio contínuo em caixas meramente para aumentar uma contagem.

  5. Forma do átomo de ensino (adapte, não carimbe um modelo):

    • declare o que o leitor precisa entender e por que é importante;
    • explique o mecanismo ou raciocínio na ordem necessária para acompanhá-lo;
    • anexe evidência da fonte: um número, exemplo, paráfrase em nível de citação, fórmula, código, tabela ou figura verificada, conforme apropriado;
    • declare a consequência ou limite quando mudar a interpretação. Use apenas os componentes que a fonte e o leitor precisam. Após cada fórmula de exibição com pelo menos dois símbolos, adicione uma lista de explicação de símbolos imediata.
  6. Sem seções apenas de esboço. Se um período de 5 minutos da aula introduz um mecanismo, número ou escolha de design distinto, ele deve aparecer como sua própria subseção ou um parágrafo claramente rotulado com evidência — não um marcador em uma lista de resumo.

  7. Auditoria de cobertura antes da compilação (linha do tempo): percorra a linha do tempo em etapas de 3 a 5 minutos usando o SRT; liste qualquer lacuna sem prosa ou figura correspondente; preencha lacunas antes de xelatex.

  8. Lista de verificação de átomos de ensino (cobertura do tópico, rígido para aulas técnicas): Antes da entrega, extraia uma lista de átomos específica da aula do SRT + slides (15–40 átomos). Cada átomo deve mapear para uma subseção, um parágrafo rotulado ou uma figura+legenda em notes.tex. Átomos ausentes → expanda a prosa; não "passe" apenas com base no CJK. Exemplo de átomos para uma aula de arquitetura LLM: Pre/Post-Norm, LN vs RMSNorm, FLOPs≠runtime, SwiGLU, serial vs parallel block, RoPE, FFN ratio, head dim, width/depth, vocab size, dropout vs weight decay, z-loss, QK-Norm, Prefill vs Decode, MQA/GQA, sliding window / interleaved / hybrid attention. Persista a lista de verificação como teaching_atoms.tsv (atom\tstatus\tevidence).

  9. Densidade de mecanismo (rígido — comparação de ouro L2 2026-07-12): Os portões CJK/fig/box sozinhos são insuficientes. CS336 L2 primeira passada Grok: 5463 CJK / 8 fórmulas / 0 código (portão PASS, ouro incompleto); após preenchimento orientado por alegações: ~6450 CJK / 31 fórmulas / 3 código / 33 páginas (corresponde ao Codex). Também exija:

    • Matemática de exibição: para átomos de fórmula da fonte, preserve pelo menos $\min(N_{\mathrm{formula\ atoms}},\ \max(10,\ \mathrm{round}(T/4)))$ blocos (\[ ... \] ou equation), cada um com uma lista de símbolos imediata.

Habilidades Relacionadas