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.
| Ferramenta | Obrigatória | Propósito |
|---|---|---|
yt-dlp | Sempre | Download 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 |
ffmpeg | Sempre | Extração de quadros, extração de áudio |
xelatex | Sempre | Compilação LaTeX (TeX Live + CTeX para chinês) |
magick | Sempre | Montagem de quadros e folhas de contato |
ffprobe | Sempre | Duração e altura do quadro (acompanha o ffmpeg) |
pdftotext | Sempre | Verificações de páginas renderizadas em verify_notes.py (poppler) |
python3 | Sempre | Scripts auxiliares instalados e suporte a ASR local |
sherpa-onnx + modelo ASR X | Opcional para ASR zh/en | Transcrição local rápida em chinês/inglês com timestamps de token |
| Backend Whisper | Fallback ASR / não-zh-en / sem CC | transcribe_whisper.py escolhe mlx-whisper (macOS arm64) → faster-whisper → openai-whisper |
rapidocr-onnxruntime | Bilibili / quaisquer legendas embutidas | ocr_hardsubs.py lê a faixa de legenda e a geometria de sobreposição |
Pillow + numpy | Sempre | frame_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:
| Sintoma | Plataforma | Significado |
|---|---|---|
Sign in to confirm you're not a bot | YouTube | detecção de bot |
HTTP Error 412 na sondagem ou download | Bilibili | verificação anti-raspagem |
WARNING: Your yt-dlp version (...) is older than 90 days | qualquer | extratores 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
.texcompleto de\documentclassaté\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")
| Arquivo | Conteúdo obrigatório |
|---|---|
metadata.json | De video_source.py probe (ou despejo completo equivalente) |
audio.srt | Faixa de legenda final usada para escrita (CC manual, automática limpa, OCR de legenda embutida, ASR X ou Whisper) |
audio_corrected.srt | Cópia da faixa final, ou faixa corrigida por glossário/LLM quando ASR local foi usado |
hardsub_ocr.srt | Saída de ocr_hardsubs.py extract quando ocr_hardsubs.py detect relatou legendas embutidas; ausente caso contrário |
bands.json | Geometria da sobreposição (faixa de navegação, faixa de legenda) de ocr_hardsubs.py detect --geometry ou frame_filter.py bands |
layout.json | Layout do painel de frame_filter.py layout sobre a amostra densa; sempre medido, composite: false registra um vídeo de imagem única |
cover.jpg | Capa da primeira página |
video.mp4 | Fonte 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.json | frame_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.tsv | Cabeç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.txt | Saída completa de verify_figures.py sobre todos os timestamps do manifesto |
lecture_profile.json | Perfil de leitor e adequação à fonte; os campos obrigatórios são descritos abaixo |
teaching_atoms.tsv | Cabeçalho atom\tstatus\tevidence — cada átomo de ensino mapeado para as anotações |
numerical_claims.tsv | Gerado 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.tex | Anotações completas da aula em chinês |
notes.pdf | Saída de xelatex com duas passagens |
verify_notes.txt | Saí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.)
-
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.
-
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-talkcom 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. -
Seções para $T\ge 60$: use pelo menos 8 para
technical-slide, 6 paramixede 5 paraconceptual-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. -
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$;
mixedeconceptual-talknão têm cota de caixa. Nunca divida o raciocínio contínuo em caixas meramente para aumentar uma contagem. -
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.
-
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.
-
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. -
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 comoteaching_atoms.tsv(atom\tstatus\tevidence). -
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
(
\[ ... \]ouequation), cada um com uma lista de símbolos imediata.
- 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
(