강의를 노트로 (Lecture to Notes)
YouTube, Bilibili 또는 X/Twitter 강의 영상을 완전하고 컴파일 가능한 .tex 노트 세트와 렌더링된 PDF로 변환합니다.
의존성
시작하기 전에 확인하세요 (which 사용). 누락된 도구가 있으면 사용자에게 설치하도록 요청하세요.
| 도구 | 필수 여부 | 목적 |
|---|---|---|
yt-dlp | 항상 | 동영상/자막/메타데이터 다운로드 (YouTube + Bilibili + X/Twitter 지원). yt-dlp --version 확인: 약 90일보다 오래된 빌드는 최신 Bilibili 및 YouTube 페이지에서 실패함 |
ffmpeg | 항상 | 프레임 추출, 오디오 추출 |
xelatex | 항상 | LaTeX 컴파일 (TeX Live + CTeX for Chinese) |
magick | 항상 | 프레임 몽타주 및 연락처 시트 |
ffprobe | 항상 | 재생 시간 및 프레임 높이 (ffmpeg와 함께 제공) |
pdftotext | 항상 | verify_notes.py에서 렌더링된 페이지 확인 (poppler) |
python3 | 항상 | 설치된 헬퍼 스크립트 및 로컬 ASR 지원 |
sherpa-onnx + X ASR 모델 | 선택사항 (zh/en ASR) | 빠른 로컬 중국어/영어 전사 (토큰 타임스탬프 포함) |
| Whisper 백엔드 | ASR 폴백 / 비-zh-en / CC 없음 | transcribe_whisper.py는 mlx-whisper (macOS arm64) → faster-whisper → openai-whisper 순서로 선택 |
rapidocr-onnxruntime | Bilibili / 하드코딩 자막 | ocr_hardsubs.py가 자막 밴드와 오버레이 지오메트리 읽기 |
Pillow + numpy | 항상 | frame_filter.py 오버레이 및 합성 패널 자르기, talking-head 점수 |
Python 패키지를 설치하세요: pip install rapidocr-onnxruntime Pillow numpy 및 하나의 전사 백엔드: Apple 실리콘에서는 pip install mlx-whisper, 그 외에는 pip install faster-whisper (또는 가장 느린 폴백으로 openai-whisper).
/ABSOLUTE/PATH/TO/lecture-to-notes/assets/smart_crop.py는 선택적 실험 기능입니다.
LaTeX 패키지 확인 (건너뛰지 마세요 — which xelatex 만으로는 불충분)
which xelatex가 통과한다고 해서 필요한 LaTeX 패키지가 설치되었다는 뜻은 아닙니다. 최소 TeX 설치(MacTeX Basic, TeX Live scheme-basic)에서는 바이너리가 존재하지만 ctex, tcolorbox 및 기타 패키지가 누락되어 있습니다. 이로 인해 긴 중국어 줄이 \textwidth를 넘거나(CJK 줄바꿈 없음) File '...' not found 오류로 컴파일이 중단되는 등의 무음 실패가 발생합니다.
시작하기 전에 필요한 패키지를 확인하세요:
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 "❌ LaTeX 패키지 누락: $pkg"
MISSING=1
fi
done
if [ "$MISSING" -ne 0 ]; then
echo "누락된 패키지 설치:"
echo " tlmgr install ctex tcolorbox environ trimspaces etoolbox"
echo "또는 전체 TeX 배포판 설치:"
echo " macOS: https://www.tug.org/mactex/ (~4 GB, 모든 것 포함)"
echo " Linux: sudo apt install texlive-full"
fi
ctex를 설치할 수 없는 경우(예: 최소 설치에서 l3kernel 버전 충돌), notes-template.tex에는 시스템 폰트와 함께 XeTeX의 내장 CJK 줄바꿈(\XeTeXlinebreaklocale "zh")을 사용하는 폴백이 포함되어 있습니다 — ctex나 xeCJK가 필요하지 않습니다.
쿠키 및 yt-dlp 최신 상태
지원되는 모든 플랫폼은 인증되지 않은 다운로드를 거부할 수 있으며, 두 가지 실패는 다르게 보입니다:
| 증상 | 플랫폼 | 의미 |
|---|---|---|
Sign in to confirm you're not a bot | YouTube | 봇 감지 |
프로브 또는 다운로드 중 HTTP Error 412 | Bilibili | 안티 스크래핑 검사 |
WARNING: Your yt-dlp version (...) is older than 90 days | 모든 플랫폼 | 추출기가 사이트의 현재 마크업보다 오래됨 |
먼저 버전을 수정하세요. 오래된 추출기는 쿠키가 수정하는 것과 동일한 오류를 생성하기 때문입니다:
brew upgrade yt-dlp, pipx upgrade yt-dlp, 또는 pip install -U yt-dlp, 그런 다음 yt-dlp --version으로 확인하세요. Homebrew는 자체 업데이터를 비활성화하므로 yt-dlp -U는 아무것도 변경하지 않고 성공을 보고합니다.
그런 다음 쿠키를 제공하세요. video_source.py probe가 직접 쿠키를 받습니다:
python3 "/ABSOLUTE/PATH/TO/lecture-to-notes/assets/video_source.py" probe \
--cookies-from-browser chrome "<URL>" > metadata.json
브라우저 프로필을 사용할 수 없는 경우(예: 헤드리스 호스트) --cookies FILE을 대신 사용하세요. 인증 이유로 실패한 프로브는 이제 재시도할 플래그를 명명하므로 해당 메시지를 막다른 길이 아닌 다음 작업으로 취급하세요.
나머지 워크플로우는 yt-dlp를 직접 호출합니다. 모든 명령을 편집하는 대신 yt-dlp 설정 파일을 한 번 작성하고 XDG_CONFIG_HOME을 가리키도록 하여 다운로드, 자막 가져오기, 썸네일 가져오기 모두가 쿠키를 사용하도록 하세요:
mkdir -p "$WORKDIR/.xdg/yt-dlp"
printf -- '--cookies-from-browser chrome\n' > "$WORKDIR/.xdg/yt-dlp/config"
# 그런 다음 이 강의 작업 디렉토리의 모든 이후 yt-dlp 호출 앞에 다음을 붙입니다:
XDG_CONFIG_HOME="$WORKDIR/.xdg" yt-dlp --no-playlist ... "<URL>"
브라우저 쿠키는 로그인된 계정의 Bilibili 1080P+도 잠금 해제하므로 동일한 설정이 프레임 품질을 향상시킵니다.
목표
YouTube, Bilibili 또는 X/Twitter 동영상 URL에서 전문적인 중국어 강의 노트를 생성합니다. 출력물은 다음을 충족해야 합니다:
- 동영상의 실제 교육 콘텐츠 사용, 단순한 자막 전사만이 아님
- 동영상의 원본 커버 이미지를 첫 페이지에 배치
- 연락처 시트 검토를 통해 선택된 전체 프레임 교수 그림 포함; 동영상이 카메라 피드와 슬라이드를 나란히 배치하는 경우, 각 그림은 슬라이드 텍스트를 읽을 수 있도록 측정된 하나의 패널을 유지
- 능숙한 첫 번째 독자가 자막을 디코딩하지 않고도 질문, 메커니즘, 증거, 결과, 경계를 이해할 수 있어야 함
- 소스에 적합한 정보 밀도 달성 — 모든 그림, 상자, 공식 및 단락이 공간을 차지할 가치가 있음
\section{}/\subsection{}으로 구조화됨- 발표자의 결론과 자신의 요약을 결합한 종합 섹션으로 마무리
\documentclass에서\end{document}까지 완전한.tex- PDF로 성공적으로 컴파일
양보할 수 없는 품질 기준 (Codex / 프로덕션 모드)
중단하고 완료되었다고 말하지 마세요 아래의 모든 항목이 참이 아닌 한. 골격 개요, 얇은 산문에 이미지가 많은 PDF, 또는 중간 산출물 누락은 자동 실패입니다.
필수 작업 디렉토리 산출물 ("완료"라고 말하기 전에 디스크에 존재해야 함)
| 파일 | 필수 내용 |
|---|---|
metadata.json | video_source.py probe (또는 동등한 전체 덤프)에서 생성 |
audio.srt | 작성에 사용된 최종 자막 트랙 (수동 CC, 정리된 자동, 하드서브 OCR, X ASR 또는 Whisper) |
audio_corrected.srt | 최종 트랙의 사본, 또는 로컬 ASR이 사용된 경우 용어집/LLM 수정 트랙 |
hardsub_ocr.srt | ocr_hardsubs.py detect가 하드코딩 자막을 보고한 경우 ocr_hardsubs.py extract 출력; 그렇지 않으면 없음 |
bands.json | ocr_hardsubs.py detect --geometry 또는 frame_filter.py bands의 오버레이 지오메트리 (네비게이션 스트립, 자막 밴드) |
layout.json | 조밀한 샘플에 대한 frame_filter.py layout의 패널 레이아웃; 항상 측정됨, composite: false는 단일 사진 동영상을 기록 |
cover.jpg | 표지 |
video.mp4 | 프레임 소스 (사용자가 다운로드를 금지하고 프레임을 제공하는 경우에만 생략 가능) |
frames/ | 조밀한 샘플, 기본값 1프레임 / 15초 |
frame_scores.json | 조밀한 샘플에 대한 frame_filter.py score; 호스트가 이미지를 표시할 수 없는 경우 필수 |
figures/ | 의미 있는 이름(fig_01_topic.jpg, ...)을 가진 선택된 그림 자산, bands.json을 통해 오버레이 자르기, layout.json을 통해 하나의 패널로 합성 자르기 |
figure_manifest.tsv | 헤더 figure\tframe\tstart\tend\ttopic\tpanel — 그림 이미지당 한 행, panel은 유지되는 layout.json 패널 이름 (main, left, ...) 또는 full |
figure_verification.txt | 모든 매니페스트 타임스탬프에 대한 verify_figures.py의 전체 표준 출력 |
lecture_profile.json | 독자 및 소스 적합 프로필; 필수 필드는 아래에 설명됨 |
teaching_atoms.tsv | 헤더 atom\tstatus\tevidence — 모든 교육 원자가 노트에 매핑됨 |
numerical_claims.tsv | extract_claims.py extract로 생성, extract_claims.py check --write로 채워짐; 강의에 수치 주장이 없으면 헤더만 있어도 유효 |
notes.tex | 완전한 중국어 강의 노트 |
notes.pdf | 2회 패스 xelatex 출력 |
verify_notes.txt | validate_notes_script.py의 전체 표준 출력, OVERALL PASS로 끝남 |
소스 적합 프로필 및 독자 계약 (엄격함)
자막 수정 및 연락처 시트 검토 후, 노트 개요를 작성하기 전에 lecture_profile.json을 생성하세요:
{
"mode": "technical-slide",
"audience": "capable first-time reader",
"central_question": "What should the reader be able to explain after reading?",
"reader_outcome": "A concrete capability, decision, or mental model",
"visual_teaching_atoms": 24,
"formula_teaching_atoms": 18
}
정확히 하나의 모드를 선택하세요:
technical-slide: 슬라이드, 칠판 작업, 공식, 코드 또는 다이어그램이 대부분의 교육 내용을 전달;conceptual-talk: 강연, 인터뷰 또는 토론이 시각적 메커니즘보다는 주장, 예시 및 추론을 통해 대부분의 내용을 전달;mixed: 두 모드 모두 상당한 교육 내용을 제공.
visual_teaching_atoms 및 formula_teaching_atoms를 초안이 아닌 소스에서 계산하세요. 시각적 원자는 한 지점을 가르치는 데 도움이 되는 별개의 소스 시각 자료입니다. 공식 원자는 보존할 가치가 있는 소스 방정식 또는 유도입니다. 더 많은 자산을 정당화하기 위해 이러한 수치를 부풀리지 말고, 할당량을 트리거하기 위해 개념적 강연을 기술적으로 분류하지 마세요.
모든 모드에서 엄격한 게이트는 소스 충실도, 완전한 교육 원자 적용 범위, 추적 가능한 수치 주장, 명확한 소스 귀속 및 일관된 독자 경로입니다. 아래의 수치 밀도 게이트는 소스 적합 백스톱입니다. 이는 발명된 방정식, 가치 없는 talking-head 스크린샷, 반복적인 상자 또는 동의어 패딩을 승인하지 않습니다.
밀도 및 구조 게이트 (소스 적응형)
재생 시간이 $T$분인 강의의 경우 (메타데이터에서):
게이트 vs 목표 (혼동하지 마세요): 아래 숫자는 엄격한 게이트입니다 (실패 = 전달 불가). 고품질 Codex급 노트는 종종 CJK 게이트보다 약 25~40% 더 많습니다. 그것은 목표이지 두 번째 엄격한 최저값이 아닙니다. 엄격한 최저값을 측정된 금값으로 높이면 더 많은 교육 원자가 아닌 패딩을 조장합니다. (CS336 L3에서 검증됨: $T\approx 89$ → 게이트 CJK 6246 / 그림 25; 금값 ~8035 CJK / 27 그림 / 31 페이지.)
-
중국어 문자 수 (
notes.tex본문의 CJK 통합 한자만):technical-slide: 최소 $ \max(5000,\ \mathrm{round}(70\times T))$;mixed: 최소 $ \max(3500,\ \mathrm{round}(55\times T))$;conceptual-talk: 최소 $ \max(2500,\ \mathrm{round}(45\times T))$. 영어 전문 용어, LaTeX 명령어 또는 캡션만 세지 마세요. 이는 완전성 최저값일 뿐, 동일한 아이디어를 반복하라는 초대가 아닙니다.
-
그림: 이해를 실질적으로 향상시키는 모든 별개의 시각적 교육 원자를 포함하며, 기술적 목표 $ \max(20,\ \mathrm{round}(T/3.5))$까지 포함합니다. 4개의 실제 시각적 원자가 있는
conceptual-talk에는 20개의 talking-head 프레임이 아닌 4개의 검증된 그림이 포함되어야 합니다. 30개의 별개 메커니즘이 있는 슬라이드 중심 강의는 20개에서 멈춰서는 안 됩니다. -
섹션 ($T\ge 60$):
technical-slide는 최소 8개,mixed는 6개,conceptual-talk는 5개를 사용하세요. 단, 더 적은 독자 질문이 명백히 더 명확한 구조를 생성하는 경우는 예외입니다. 각 주요 섹션은 하나의 독자 질문에 답하고\subsection{本章小结}로 끝나며 답을 명시하고 다음 질문을 준비합니다. -
판단 상자: 상자는 정의, 배경 의존성, 결정 규칙 또는 실패 경계를 주요 흐름과 분리할 때만 사용하세요. 기술적 기본값은 $T\ge60$의 경우 12입니다.
mixed및conceptual-talk에는 상자 할당량이 없습니다. 단지 수를 늘리기 위해 연속적인 추론을 상자로 나누지 마세요. -
교육 원자 형태 (템플릿을 찍어내지 말고 적응하세요):
- 독자가 이해해야 할 것과 그것이 중요한 이유를 진술;
- 따라가는 데 필요한 순서로 메커니즘 또는 추론 설명;
- 적절한 소스 증거 첨부: 숫자, 예제, 인용 수준의 의역, 공식, 코드, 표 또는 검증된 그림;
- 해석을 변경할 때 결과 또는 경계 진술. 소스와 독자가 필요로 하는 구성 요소만 사용하세요. 최소 두 개의 기호가 있는 표시 공식 후에는 즉시 기호 설명 목록을 추가하세요.
-
개요 전용 섹션 금지. 강의의 5분 구간이 별개의 메커니즘, 숫자 또는 설계 선택을 도입하는 경우, 요약 목록의 글머리 기호가 아닌 자체 하위 섹션 또는 증거가 포함된 명확하게 표시된 단락으로 나타나야 합니다.
-
편집 전 적용 범위 감사 (타임라인): SRT를 사용하여 3~5분 단계로 타임라인을 살펴보세요. 해당 산문이나 그림이 없는 간격을 나열하고
xelatex전에 간격을 채우세요. -
교육 원자 체크리스트 (주제 적용 범위, 기술 강의의 경우 엄격): 전달 전에 SRT + 슬라이드에서 강의별 원자 목록을 추출하세요 (15~40개 원자). 각 원자는
notes.tex의 하위 섹션, 레이블이 지정된 단락 또는 그림+캡션에 매핑되어야 합니다. 누락된 원자 → 산문 확장; CJK만으로 "통과"하지 마십시오. 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. 체크리스트를teaching_atoms.tsv(atom\tstatus\tevidence)로 유지하세요. -
메커니즘 밀도 (엄격 — L2 금값 비교 2026-07-12): CJK/그림/상자 게이트만으로는 충분하지 않습니다. CS336 L2 첫 Grok 패스: 5463 CJK / 8 공식 / 0 코드 (게이트 통과, 금값 불완전); 청구 기반 보완 후: ~6450 CJK / 31 공식 / 3 코드 / 33 페이지 (Codex와 일치). 또한 필요:
- 표시 수학: 소스 공식 원자의 경우 최소 $
\min(N_{\mathrm{formula\ atoms}},\ \max(10,\ \mathrm{round}(T/4)))$ 블록
(
\[ ... \]또는equation)을 보존하고, 각각 즉시 기호
- 표시 수학: 소스 공식 원자의 경우 최소 $
\min(N_{\mathrm{formula\ atoms}},\ \max(10,\ \mathrm{round}(T/4)))$ 블록
(
…
[번역을 위해 잘림]