Lecture to Notes (Conferencia a Apuntes)
Convierte un video de conferencia de YouTube, Bilibili o X/Twitter en un conjunto completo y compilable de notas .tex y un PDF renderizado.
Dependencias
Verifique antes de comenzar (use which). Solicite al usuario que instale cualquier herramienta faltante.
| Herramienta | Requerida | Propósito |
|---|---|---|
yt-dlp | Siempre | Descarga de video/subtítulos/metadatos (soporta YouTube + Bilibili + X/Twitter). Verifique yt-dlp --version: una compilación de más de ~90 días falla en páginas actuales de Bilibili y YouTube |
ffmpeg | Siempre | Extracción de fotogramas, extracción de audio |
xelatex | Siempre | Compilación de LaTeX (TeX Live + CTeX para chino) |
magick | Siempre | Montajes de fotogramas y hojas de contactos |
ffprobe | Siempre | Duración y altura de fotograma (incluido con ffmpeg) |
pdftotext | Siempre | Comprobaciones de páginas renderizadas en verify_notes.py (poppler) |
python3 | Siempre | Scripts auxiliares instalados y soporte ASR local |
sherpa-onnx + modelo ASR X | Opcional zh/en ASR | Transcripción local rápida en chino/inglés con marcas de tiempo de token |
| Whisper backend | ASR de respaldo / no zh-en / sin CC | transcribe_whisper.py elige mlx-whisper (macOS arm64) → faster-whisper → openai-whisper |
rapidocr-onnxruntime | Bilibili / cualquier subtítulo quemado | ocr_hardsubs.py lee la banda de subtítulos y la geometría de superposición |
Pillow + numpy | Siempre | frame_filter.py para superposiciones y recortes de paneles compuestos, puntuaciones de cabezas parlantes |
Instale la parte de Python con pip install rapidocr-onnxruntime Pillow numpy más un backend de transcripción: pip install mlx-whisper en Apple Silicon, de lo contrario pip install faster-whisper (o openai-whisper como respaldo más lento). /ABSOLUTE/PATH/TO/lecture-to-notes/assets/smart_crop.py sigue siendo un experimento opcional.
Verificación de paquetes LaTeX (NO omitir — which xelatex solo es insuficiente)
Que which xelatex pase no significa que los paquetes LaTeX requeridos estén instalados. En instalaciones mínimas de TeX (p. ej., MacTeX Basic, TeX Live scheme-basic), el binario existe pero faltan paquetes como ctex, tcolorbox, etc. Esto provoca fallos silenciosos: líneas chinas largas desbordan \textwidth (sin división de líneas CJK) o la compilación aborta con File '...' not found.
Verifique los paquetes requeridos antes de comenzar:
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 "❌ Falta el paquete LaTeX: $pkg"
MISSING=1
fi
done
if [ "$MISSING" -ne 0 ]; then
echo "Instale los paquetes faltantes:"
echo " tlmgr install ctex tcolorbox environ trimspaces etoolbox"
echo "O instale la distribución TeX completa:"
echo " macOS: https://www.tug.org/mactex/ (~4 GB, incluye todo)"
echo " Linux: sudo apt install texlive-full"
fi
Si no se puede instalar ctex (p. ej., debido a conflictos de versión de l3kernel en instalaciones mínimas), la plantilla notes-template.tex incluye un respaldo que utiliza la división de líneas CJK incorporada de XeTeX (\XeTeXlinebreaklocale "zh") con fuentes del sistema — sin necesidad de ctex o xeCJK.
Cookies y frescura de yt-dlp
Cada plataforma compatible puede rechazar una descarga no autenticada, y los dos fallos se ven diferentes:
| Síntoma | Plataforma | Significado |
|---|---|---|
Sign in to confirm you're not a bot | YouTube | detección de bots |
HTTP Error 412 al sondear o descargar | Bilibili | comprobación anti-scraping |
WARNING: Your yt-dlp version (...) is older than 90 days | cualquier | los extractores son anteriores al marcado actual del sitio |
Primero corrija la versión, porque un extractor obsoleto produce los mismos errores que las cookies solucionan: brew upgrade yt-dlp, pipx upgrade yt-dlp, o pip install -U yt-dlp, luego confirme con yt-dlp --version. Homebrew deshabilita el autoactualizador, por lo que yt-dlp -U informa éxito sin cambiar nada.
Luego suministre cookies. video_source.py probe las toma directamente:
python3 "/ABSOLUTE/PATH/TO/lecture-to-notes/assets/video_source.py" probe \
--cookies-from-browser chrome "<URL>" > metadata.json
Use --cookies FILE en su lugar cuando el perfil del navegador no esté disponible, por ejemplo en un host sin interfaz gráfica. Una sonda que falla por una razón de autenticación ahora nombra la bandera con la que reintentar, así que trate ese mensaje como la siguiente acción, no como un callejón sin salida.
El resto del flujo de trabajo llama a yt-dlp directamente. En lugar de editar cada comando, escriba un archivo de configuración de yt-dlp una vez y apunte XDG_CONFIG_HOME hacia él, para que las descargas, las descargas de subtítulos y las descargas de miniaturas recojan las cookies:
mkdir -p "$WORKDIR/.xdg/yt-dlp"
printf -- '--cookies-from-browser chrome\n' > "$WORKDIR/.xdg/yt-dlp/config"
# luego prefije cada llamada posterior a yt-dlp en este workdir de conferencia:
XDG_CONFIG_HOME="$WORKDIR/.xdg" yt-dlp --no-playlist ... "<URL>"
Las cookies del navegador también desbloquean Bilibili 1080P+ para cuentas iniciadas, por lo que la misma configuración mejora la calidad de los fotogramas.
Objetivo
Producir un apunte profesional de conferencia en chino a partir de una URL de video de YouTube, Bilibili o X/Twitter. La salida debe:
- usar el contenido docente real del video, no solo la transcripción de subtítulos
- colocar la imagen de portada original del video en la primera página
- incluir figuras docentes de fotograma completo seleccionadas mediante revisión de hoja de contactos; cuando el video coloca una transmisión de cámara y diapositivas una al lado de la otra, cada figura mantiene un panel medido para que el texto de la diapositiva siga siendo legible
- permitir que un lector capaz por primera vez entienda la pregunta, el mecanismo, la evidencia, la consecuencia y el límite sin descifrar la transcripción
- lograr una densidad de información ajustada a la fuente — cada figura, recuadro, fórmula y párrafo se gana su espacio
- estar organizado estructuralmente con
\section{}/\subsection{} - terminar con una sección de síntesis que combine las conclusiones del orador y su propia destilación
- ser un
.texcompleto desde\documentclasshasta\end{document} - compilar correctamente a PDF
Listón de calidad no negociable (modo Codex / producción)
DETÉNGASE y no reclame finalización a menos que cada elemento a continuación sea verdadero. Esquemas preliminares, PDFs con muchas imágenes y prosa ligera, o artefactos intermedios faltantes son fallos automáticos.
Artefactos obligatorios del directorio de trabajo (deben existir en disco antes de decir "listo")
| Archivo | Contenido requerido |
|---|---|
metadata.json | De video_source.py probe (o volcado completo equivalente) |
audio.srt | Pista de subtítulos final utilizada para escribir (CC manual, auto limpio, OCR de subtítulos duros, ASR X o Whisper) |
audio_corrected.srt | Copia de la pista final, o glosario/pista corregida por LLM cuando se usó ASR local |
hardsub_ocr.srt | Salida de ocr_hardsubs.py extract cuando ocr_hardsubs.py detect informó subtítulos quemados; ausente en caso contrario |
bands.json | Geometría de superposición (barra de navegación, banda de subtítulos) de ocr_hardsubs.py detect --geometry o frame_filter.py bands |
layout.json | Diseño de panel de frame_filter.py layout sobre la muestra densa; siempre medido, composite: false registra un video de una sola imagen |
cover.jpg | Portada de la primera página |
video.mp4 | Fuente para fotogramas (puede omitirse solo si el usuario prohíbe la descarga y proporciona fotogramas) |
frames/ | Muestra densa, por defecto 1 fotograma / 15s |
frame_scores.json | frame_filter.py score sobre la muestra densa; obligatorio cuando el anfitrión no puede mostrarle imágenes |
figures/ | Activos de figuras seleccionadas con nombres semánticos (fig_01_topic.jpg, ...), superposiciones recortadas mediante bands.json, compuestos recortados a un panel mediante layout.json |
figure_manifest.tsv | Encabezado figure\tframe\tstart\tend\ttopic\tpanel — una fila por imagen de figura; panel nombra el panel de layout.json que mantiene (main, left, ...) o full |
figure_verification.txt | Salida completa de verify_figures.py sobre todas las marcas de tiempo del manifiesto |
lecture_profile.json | Perfil de lector y ajuste a la fuente; los campos requeridos se describen a continuación |
teaching_atoms.tsv | Encabezado atom\tstatus\tevidence — cada átomo de enseñanza mapeado a las notas |
numerical_claims.tsv | Generado por extract_claims.py extract, completado por extract_claims.py check --write; solo encabezado es válido cuando la conferencia no contiene afirmaciones numéricas |
notes.tex | Notas de conferencia completas en chino |
notes.pdf | Salida de xelatex (dos pasadas) |
verify_notes.txt | Salida completa de verify_notes.py, terminando en OVERALL PASS |
Perfil de ajuste a la fuente y contrato con el lector (estricto)
Después de la corrección de subtítulos y la revisión de la hoja de contactos, cree lecture_profile.json antes de esbozar las notas:
{
"mode": "technical-slide",
"audience": "capable first-time reader",
"central_question": "¿Qué debería poder explicar el lector después de leer?",
"reader_outcome": "Una capacidad, decisión o modelo mental concreto",
"visual_teaching_atoms": 24,
"formula_teaching_atoms": 18
}
Elija exactamente un modo:
technical-slide: diapositivas, trabajo en pizarra, fórmulas, código o diagramas llevan la mayor parte del contenido docente;conceptual-talk: una charla, entrevista o discusión lleva la mayor parte del contenido a través de afirmaciones, ejemplos y razonamiento en lugar de mecanismos visuales;mixed: ambos modos contribuyen con contenido docente sustancial.
Cuente los visual_teaching_atoms y formula_teaching_atoms de la fuente, no del borrador. Un átomo visual es un elemento visual distinto de la fuente que ayuda a enseñar un punto. Un átomo de fórmula es una ecuación o derivación de la fuente que vale la pena preservar. No infle estos conteos para justificar más activos, y no clasifique una charla conceptual como técnica meramente para activar cuotas.
Para todos los modos, las puertas estrictas son la fidelidad a la fuente, la cobertura completa de átomos de enseñanza, las afirmaciones numéricas trazables, la atribución clara de la fuente y un camino de lectura coherente. Las puertas de densidad numérica a continuación son respaldos de ajuste a la fuente. Nunca autorizan ecuaciones inventadas, capturas de pantalla de cabezas parlantes de bajo valor, recuadros repetitivos o relleno de sinónimos.
Puertas de densidad y estructura (adaptativas a la fuente)
Para una conferencia de duración $T$ minutos (de metadatos):
Puerta vs objetivo (no confundir): los números a continuación son puertas estrictas (fallo = no entrega). Una nota de calidad clase Codex a menudo aterriza ~25–40% por encima de la puerta CJK; eso es un objetivo, no un segundo piso duro. Elevar el piso duro al valor dorado medido fomenta el relleno, no más átomos de enseñanza. (Validado en CS336 L3: $T\approx 89$ → puerta CJK 6246 / figs 25; dorado ~8035 CJK / 27 figs / 31 páginas.)
-
Recuento de caracteres chinos en el cuerpo de
notes.tex(ideogramas unificados CJK solamente):technical-slide: al menos $\max(5000,\ \mathrm{round}(70\times T))$;mixed: al menos $\max(3500,\ \mathrm{round}(55\times T))$;conceptual-talk: al menos $\max(2500,\ \mathrm{round}(45\times T))$. No cuente jerga en inglés, comandos LaTeX o subtítulos solos. Son pisos de completitud, no invitaciones a repetir la misma idea.
-
Figuras: incluya cada átomo de enseñanza visual distinto que mejore materialmente la comprensión, hasta el objetivo técnico $\max(20,\ \mathrm{round}(T/3.5))$. Una
conceptual-talkcon cuatro átomos visuales reales debe contener cuatro figuras verificadas, no veinte fotogramas de cabezas parlantes. Una conferencia liderada por diapositivas con treinta mecanismos distintos no debe detenerse en veinte. -
Secciones para $T\ge 60$: use al menos 8 para
technical-slide, 6 paramixedy 5 paraconceptual-talk, a menos que menos preguntas del lector produzcan una estructura demostrablemente más clara. Cada sección principal responde una pregunta del lector y termina con\subsection{本章小结}que establece la respuesta y prepara la siguiente pregunta. -
Recuadros de juicio: use recuadros solo cuando separan una definición, dependencia de fondo, regla de decisión o límite de falla del flujo principal. El valor predeterminado técnico es 12 para $T\ge60$;
mixedyconceptual-talkno tienen cuota de recuadros. Nunca divida el razonamiento continuo en recuadros meramente para aumentar un recuento. -
Forma del átomo de enseñanza (adapte, no estampe una plantilla):
- establezca lo que el lector necesita entender y por qué es importante;
- explique el mecanismo o razonamiento en el orden necesario para seguirlo;
- adjunte evidencia de la fuente: un número, ejemplo, paráfrasis a nivel de cita, fórmula, código, tabla o figura verificada según corresponda;
- establezca la consecuencia o límite cuando cambie la interpretación. Use solo los componentes que la fuente y el lector necesitan. Después de cada fórmula mostrada con al menos dos símbolos, agregue una lista de explicación de símbolos inmediata.
-
Sin secciones de solo esquema. Si un lapso de 5 minutos de la conferencia introduce un mecanismo, número o elección de diseño distinto, debe aparecer como su propia subsección o un párrafo claramente etiquetado con evidencia — no un punto en una lista de resumen.
-
Auditoría de cobertura antes de compilar (línea de tiempo): recorra la línea de tiempo en pasos de 3 a 5 minutos usando el SRT; enumere cualquier brecha sin prosa o figura correspondiente; llene las brechas antes de
xelatex. -
Lista de verificación de átomos de enseñanza (cobertura de temas, estricta para conferencias técnicas): Antes de la entrega, extraiga una lista de átomos específica de la conferencia del SRT + diapositivas (15–40 átomos). Cada átomo debe mapearse a una subsección, un párrafo etiquetado o una figura+subtítulo en
notes.tex. Átomos faltantes → expanda la prosa; no "apruebe" solo con CJK. Ejemplo de átomos para una conferencia de arquitectura LLM: Pre/Post-Norm, LN vs RMSNorm, FLOPs≠runtime, SwiGLU, bloque serial vs paralelo, RoPE, ratio FFN, dim de cabeza, ancho/profundidad, tamaño de vocabulario, dropout vs weight decay, z-loss, QK-Norm, Prefill vs Decode, MQA/GQA, atención deslizante / intercalada / híbrida. Persista la lista de verificación comoteaching_atoms.tsv(atom\tstatus\tevidence). -
Densidad de mecanismos (estricta — comparación dorada L2 2026-07-12): Las puertas CJK/fig/recuadro por sí solas no son suficientes. CS336 L2 primer pase Grok: 5463 CJK / 8 fórmulas / 0 código (puerta SUPERADO, dorado incompleto); después de completación basada en afirmaciones: ~6450 CJK / 31 fórmulas / 3 código / 33 páginas (coincide con Codex). También requiere:
- Matemáticas mostradas: para átomos de fórmula fuente, preserve al menos
$\min(N_{\mathrm{formula\ atoms}},\ \max(10,\ \mathrm{round}(T/4)))$ bloques
(
\[ ... \]oequation), cada uno con una explicación de símbolos inmediata.
- Matemáticas mostradas: para átomos de fórmula fuente, preserve al menos
$\min(N_{\mathrm{formula\ atoms}},\ \max(10,\ \mathrm{round}(T/4)))$ bloques
(
...