JustinChenzeting/강의노트-영상변환

강의 노트 → 내레이션이 포함된 강의 영상

여러분은 정확히 하나의 파일, 즉 슬라이드, 다이어그램 및 내레이션을 모두 포함하는 beamer lecture.tex 파일을 작성합니다. 번들로 제공되는 스크립트가 나머지 모든 작업(설치, LaTeX → PNG 페이지 → 텍스트 음성 변환 → ffmpeg → MP4)을 처리하므로, 비용은 강의당 약 하나의 긴 답변 정도이며, 이후 편집 시에는 변경된 줄만 다시 합성합니다.

빠른 시작: 전체 파이프라인

각 단계는 하나의 명령어입니다: python3 <skill-dir>/scripts/lv.py <command>, 여기서 <skill-dir>는 이 파일이 포함된 폴더의 절대 경로입니다(Windows에서는 python3 대신 py -3를 사용하세요). 아래에서는 lv가 전체 명령어의 약칭입니다. 셸 변수는 일반적으로 명령어 간에 유지되지 않으므로 매번 전체 명령어를 작성하세요.

lv setup                           # 0. 일회성 설치; 10분 제한 시간을 주거나 백그라운드에서 실행
lv init PHYS101-L05                # 1. 작업 폴더(WORK)를 출력하고 템플릿을 복사
lv ingest notes.pdf --out WORK     #    .pdf .png .jpg .heic .md .txt 파일 혼합 가능; 여러 파일도 괜찮음
#                                       노트 읽기(§1), 계획 수립(§2), WORK/lecture.tex 작성(§3-4)
lv check WORK/lecture.tex          # 2. 컴파일 + 번호가 매겨진 연속 사진 + 레이아웃 경고, 오디오 없음
lv render WORK/lecture.tex         # 3. -> WORK/PHYS101-L05.mp4 (또는 출력 경로 지정)

• 0단계는 모든 것을 설치합니다(uv, 개인 Python 3.12, 작동하는 LaTeX가 없을 때만 TinyTeX, ffmpeg, Kokoro 음성)를 사용자별 캐시에 설치: 빠른 연결에서 약 3분, 느린 연결에서 최대 10분이 소요되며 관리자 권한이 필요하지 않습니다. 멱등적입니다: 이미 완료된 경우 몇 초 만에 완료되며, 중단된 경우 다시 실행하면 재개됩니다. 사용자에게 일회성 설치라고 알리십시오. [setup] READY로 시작하는 줄로 끝납니다. 다른 종료는 메시지나 references/troubleshooting.md에 수정 사항이 있는 오류입니다. lv doctor는 아무것도 변경하지 않고 설치된 항목을 보여줍니다. 다른 명령어는 설치가 누락된 경우에도 setup을 실행합니다.
• 각 단계에서 확인을 요청하지 않고 파이프라인을 처음부터 끝까지 실행하십시오. 실제 차단 요인(열거나 읽을 수 없는 노트, 관리자 암호가 필요한 설치 단계, 비디오를 변경하는 모호한 요청)이 있는 경우에만 중단하십시오.
• WORK는 기본적으로 ./lecture-videos/<name>(또는 사용자가 구성한 work_root)입니다. 사용자가 요청한 위치에 MP4를 두십시오. 그렇지 않으면 WORK의 기본값으로 충분합니다. WORK를 유지하십시오: .tex, 대본 및 오디오 캐시는 이후 편집을 저렴하게 만듭니다.

1. 먼저 직접 노트를 읽으십시오

ingest는 WORK/source.txt(텍스트 레이어가 있는 페이지), WORK/manifest.tsv(각 페이지를 읽은 방법), 눈으로 확인해야 하는 페이지의 전체 크기 이미지(WORK/pages/), 그리고 개요 시트(WORK/glance-*.jpg, 각각 6페이지)를 작성합니다.

• 모든 개요 시트를 확인하십시오. 여백 주석, 강조 표시된 부분 및 텍스트 추출이 놓치는 그림을 포착하며, 시트당 대략 한 페이지의 토큰 비용이 듭니다. 시트에 입력된 페이지에 손글씨나 주석이 표시되면 --visual 3,7-9로 다시 실행하여 해당 페이지를 전체 크기로 가져오십시오.
• 손글씨 또는 스캔된 페이지([handwritten/scanned], [image])는 전체 크기로 읽어야 합니다: 해당 이미지를 모두 열고 WORK/transcript.md에 내용을 순서대로 작성하고, 방정식은 LaTeX로, 각 그림에 대한 한 줄 설명(축, 레이블, 주요 숫자)을 포함하십시오. 읽을 수 없는 항목은 추측하지 말고 [illegible]로 표시하십시오. 손글씨 노트는 종종 사용자 자신의 수업 노트이므로 기본 소스로 취급하십시오. 이미지를 볼 수 없으면 말하고 추측하는 대신 입력된 버전을 요청하십시오.
• 그림이 있는 입력된 페이지([has figure]): 개요 시트에서 읽을 수 없는 값이나 레이블이 필요할 때만 전체 크기 이미지를 여십시오.
• 그 이후로는 source.txt + transcript.md에서만 계획을 수립하십시오. 이미지를 다시 읽지 마십시오.
• .docx, .pptx 또는 .key 노트: 먼저 PDF로 내보낸 다음(예: LibreOffice soffice --headless --convert-to pdf 사용) PDF를 수집하십시오.

노트를 읽는 동안 노트의 오류나 불일치(숫자 오타, 레이블 바뀜)를 기록하십시오. 비디오에서 올바른 값을 사용하고 최종 보고서에 각 수정 사항을 나열하십시오.

1b. 신뢰할 수 있는 출처에서 공백 채우기

노트는 종종 간결합니다: 건너뛴 유도 단계, 정의되기 전에 사용된 용어, 설명 없는 그림. 학생을 혼란스럽게 할 수 있는 내용이 있고 웹에 접속할 수 있다면, 적절한 수준의 명확한 설명(대학 강의 노트 및 OCW, LibreTexts, 표준 교과서, 대학원 수준 내용의 경우 리뷰 기사)을 위해 간략히 검색(2-5개의 목표 지향적 질문, 문헌 검토 아님)하십시오. 노트의 표기법과 일치하는 출처를 선호하십시오. 충돌하는 경우 노트를 따르고 차이점을 언급하십시오. 추가 내용은 짧게 유지하고 노트 내용에 도움이 되도록 하며, 학부생을 대상으로 하고 선택적으로 대학원 수준의 설명을 추가하십시오. 사용한 출처를 최종 보고서에 나열하십시오. 강의에서 다루지 않는 주제는 추가하지 마십시오.

2. 작성 전 계획 수립 (머리 속이나 몇 줄로)

• 길이: 사용자가 다른 길이를 지정하지 않는 한 약 10분(9-11분)을 목표로 하십시오. 깊이가 범위보다 중요합니다: 노트에 10분 안에 단계를 건너뛰지 않고 설명할 수 있는 것보다 더 많은 내용이 있다면, 핵심 내용을 철저히 다루고 사용자에게 생략된 내용을 알리고 파트 2를 제안하십시오. 내레이션 예산은 목표 길이의 분당 약 155단어, 체크포인트당 15초 차감(기본 음성은 분당 ~165단어로 말하며, 줄 사이의 일시 중지가 나머지를 사용). 10분 비디오 ≈ 1,350단어 + 4개 체크포인트(측정됨: 1,481단어 + 4개 체크포인트 = 9.9분).
• 구성: 제목 → 동기 부여 → 노트 순서의 개념 → 작업 예제 → 요약. 프레임당 하나의 아이디어, 프레임당 1-5개의 오버레이 단계, 총 약 40-70페이지.
• 논리 체인: 추론 체인을 번호가 매겨진 단계로 나열하십시오(가정되는 것, 따르는 것, 이유). 모든 유도는 시작 원리에서 결과까지 건너뛴 단계 없이 진행됩니다: 각 대수학 이동은 자체 줄을 가지며, 각 가정은 사용되는 위치에 명시되고, 각 새 기호는 나타나기 전에 정의됩니다. 노트가 점프하는 경우("이것은 보여줄 수 있다…"), 간격을 채우십시오(§1b). 학생은 "그게 어디서 나왔지?"라고 묻지 않아야 합니다.
• 시각 자료가 강의를 이끕니다: 단어보다 먼저 그림을 계획하십시오. 모든 개념 프레임에는 시각 자료(다이어그램, 플롯 또는 물리적 모델(원자, 격자, 물질 수지의 탱크-파이프 그림, 지레 규칙의 지레))가 필요합니다. 기호가 물리적으로 무엇을 나타내는지 보여주고, 방정식만 보여주지 마십시오. 모든 그림을 원본 TikZ/pgfplots로 다시 그리십시오(유인물의 이미지를 절대 붙여넣지 마십시오). 오버레이로 단계별로 다이어그램을 작성하고, 움직임이 중요한 경우 3-6개의 짧은 애니메이션(냉각 경로, 스위핑 tie line, 활공하는 전위)을 사용하십시오. 패턴: references/visual-cookbook.md.

설명하는 방법 (이것이 비디오를 볼 가치가 있게 만드는 것입니다)

• 좋은 튜터처럼 말하고, 교과서처럼 말하지 마십시오. 일상적인 표현("기본적으로", "여기 트릭이 있습니다", "이렇게 생각하세요…"), 짧은 문장, 무엇보다 이유를 먼저 말하십시오. 혼란을 예상하십시오("처음에는 이것이 거꾸로 보이지만, 그렇지 않은 이유는 다음과 같습니다").
• 모든 중요한 방정식을 두 번 설명하십시오:
  1. 수학적으로: 어디서 왔는지, 단계별로, 각 항이 무엇인지.
  2. 물리적으로/직관적으로: 실제 시스템에서 무엇을 의미하는지, 비유 또는 극한 사례("c가 정확히 c′에 있으면 합금은 모두 액체이며, 공식은 정확히 그 값을 제공합니다")와 함께. 둘 다 화면에 표시하십시오: 수학 라인, 그런 다음 한 줄의 "물리적으로:" 참고 또는 그림.
• 각 유도 후에 큰 소리로 빠른 sanity check를 실행하십시오: 단위, 극한 사례 또는 다이어그램의 숫자.
• 체크포인트: 10분당 3-5개, 테스트하는 개념 바로 뒤에 배치하십시오(§4).

3. WORK/lecture.tex 작성

init는 이미 assets/template.tex를 WORK/lecture.tex에 복사했습니다. 모든 구성을 보여줍니다. 예제 프레임을 강의로 교체하십시오. 중요한 규칙:

• \usepackage{lecturevideo}는 테마(아이보리 종이, 진한 잉크, 하나의 빨간색 악센트 또는 구성된 경우 사용자 고유 브랜딩), 팔레트(accent, ink, mute, blu, grn, gold), 그림 스타일(pd 축, dot, lab, note, tie, atom, atomA, atomB) 및 내레이션 명령을 로드합니다. 강의 내에서 테마 스타일을 변경하지 마십시오.
• 내레이션: \say<n>{...}, 오버레이 페이지 n당 하나, 프레임 상단에 배치됩니다. \say<2-13>{...}는 애니메이션 범위를 설명합니다. \wait<n>{2}는 페이지를 조용히 유지합니다. 모든 페이지에는 하나가 필요합니다. 렌더러는 누락된 페이지의 이름을 지정합니다.
• 말하는 텍스트는 일반 영어입니다: 숫자와 기호는 단어로("forty six percent", "T three", "seven hundred seventy nine degrees", "alpha plus beta"). \say 내부에 LaTeX 및 %, &, #, $가 없습니다. 무엇을 볼지("watch the dot", "notice the tie line") 말한 다음 왜 중요한지 말하십시오. 슬라이드 텍스트를 그대로 읽기보다는 확장하십시오.
• 슬라이드는 실제 설명을 제공합니다. 일시 중지, 되감기 또는 PDF로 복습하는 시청자는 슬라이드만으로도 따라갈 수 있어야 합니다. 각 시각 자료 옆에 최대 약 15단어의 3-5개 글머리 기호(핵심 사실, 조건, 결과, 물리적 의미)를 배치하십시오. 유도의 경우 각 단계를 자체 줄로 표시하고 옆에 짧은 이유("mass balance on B", "divide by W")를 추가하고, 내레이션이 도달할 때 공개하고, 악센트 색상의 "물리적으로:" 줄로 끝내십시오. 유도가 약 6줄 이상 필요한 경우, 다음 프레임에서 계속(맨 위에 마지막 줄 반복)하는 것이 비좁게 채우는 것보다 낫습니다.
• 레이아웃: 한쪽(약 55%)에 시각 자료, 다른 쪽에 텍스트(columns) 또는 시각 자료 위에 2-3줄의 텍스트를 아래에 배치하십시오. 학술적이고 깔끔하게: 프레임당 하나의 아이디어, 강조를 위해서만 악센트 색상 사용, 결과 및 상태 표시자.
• #1을 취하는 그림 매크로는 전문(preamble)에 들어갑니다(프레임 본문의 #은 beamer를 깨뜨립니다).
• 강의에 필요한 LaTeX 패키지(siunitx, chemfig, ...)는 사용할 수 있습니다. 개인 TinyTeX가 사용 중일 때, 누락된 패키지는 첫 번째 컴파일 시 자동으로 설치됩니다.

4. 시험 스타일 체크포인트

\examq[5]{Checkpoint: lever rule}
  {slide question}{spoken question}{slide answer}{spoken answer}

이것은 1개의 질문 페이지(내레이션, 그 다음 "5초의 시간이 있습니다."), 5개의 조용한 1초 카운트다운 페이지(줄어드는 링 포함) 및 1개의 내레이션 답변 페이지를 만듭니다.

이 강의에 대한 실제 시험처럼 질문을 작성하십시오: 구체적인 주어진 숫자, 하나의 명확한 작업, 비디오를 따라온 사람이 약 30초 안에 답할 수 있고, 짧은 작업 답변이 있어야 합니다. 유형을 혼합하십시오:

• 계산: "c′ = 20, c″ = 85인 T₃에서 35 wt.% B의 합금: 액체 분율은 얼마입니까?"
• 다이어그램 읽기: "900 °C에서 20 wt.% Ag 합금. 어떤 상들이며, 대략적인 조성은 무엇입니까?"
• 예측: "5 wt.% Ag 합금이 800 °C에서 500 °C로 천천히 냉각됩니다. 무엇이 형성되고 어디에 형성됩니까?"
• 식별/분류: "한 온도에서 Liquid → α + β: 이것은 어떤 불변 반응입니까?"
• 오류 찾기: "한 학생이 고체 분율에 대해 tie line 위에 c″ − c를 사용합니다. 무엇이 잘못되었습니까?"

모호한 프롬프트("상(phase)이란 무엇입니까?"), 노트에서 가르치지 않은 잡동사니, 여러 부분으로 구성된 질문을 피하십시오. 답변은 결과뿐만 아니라 추론 단계를 보여야 합니다. 비디오가 방금 보여준 다이어그램 또는 방정식에서 숫자를 가져와 질문, 그림 및 답변이 일치하도록 하십시오. 일반적인 오해를 기반으로 한 질문이 잘 작동합니다("핀 간격을 절반으로 줄이면 소스 응력이 두 배가 됩니다: 참 또는 거짓?"). 5초 카운트다운을 유지하십시오(슬라이드에 "더 오래 필요하면 일시 중지하십시오"라고 표시됨). 사용자가 더 긴 일시 중지를 요청하는 경우에만 \examq[8]를 사용하십시오.

5. 확인 후 렌더링

lv check WORK/lecture.tex

컴파일하고, 페이지, 내레이션 단어 수, 예상 시간 및 layout: 경고(내용이 너무 높거나 줄이 너무 넓음, 소스 줄 번호 포함)를 인쇄하고, 번호가 매겨진 연속 사진 WORK/lecture_build/sheet-*.png를 작성합니다. 시트를 확인하여 충돌, 잘린 레이블, 곡선 이탈 마커 또는 빈 프레임이 있는지 확인하고 수정한 후 다시 실행하십시오(저렴함). 이미지를 볼 수 없으면 모든 layout: 경고를 수정하고 그림을 단순하게 유지하십시오. 예상 시간이 목표 길이에서 약 10% 이상 벗어나면 지금 내레이션을 다듬거나 확장하십시오(체크포인트 제외). 그런 다음:

lv render WORK/lecture.tex ["OUT/Lecture title.mp4"]

내레이터: Microsoft Edge 신경망 음성 en-GB-SoniaNeural(무료, 인터넷 필요) +10%, 720p. 오프라인이거나 Edge가 실패하면 번들로 제공되는 Kokoro 음성 bf_emma로 자동 대체됩니다. 옵션: --tts edge|kokoro|say, --voice <id or profile>, --rate, --height. 사용자가 음성 이름을 지정하거나 자신의 음성(복제된 음성 포함)을 원하는 경우 references/voices.md를 읽으십시오.

자막은 무료로 제공됩니다. 모든 렌더링은 MP4 옆에 OUT.srt 및 OUT.vtt도 작성하고 선택 가능한 자막 트리를 포함하며, \say 텍스트를 기반으로 합성된 오디오 시간에 맞춰 제공되므로 토큰 비용이 들지 않고 편집 후에도 동기화가 유지됩니다. 비디오를 절대 필사하거나 자막을 직접 작성하지 마십시오. 내레이션을 작성된 대로 표시합니다(lexicon.tsv 재철자 전). --no-subs는 자막을 끕니다.

발음 수정은 WORK/lexicon.tsv(written<TAB>spoken)에 저장되며 오디오에만 적용됩니다. 편집 후 다시 렌더링하는 데는 몇 초가 걸립니다. 변경되지 않은 줄은 오디오 캐시에서 가져오기 때문입니다.

6. 보고

비디오 경로(및 해당 .srt/.vtt 자막), 시간, 페이지 및 체크포인트 수, 노트에 대한 모든 수정 사항, 간격을 채우는 데 사용된 출처, 개략적인 재그림인 그림, 생략된 내용(파트 2 제안)을 제공하십시오. 편집을 위해 WORK를 유지하십시오.

개인 설정

브랜딩(로고, 색상, 기관의 beamer 테마), 기본 음성, 작업 및 출력 폴더는 스킬 외부의 사용자 구성 폴더에 있으므로 스킬은 이식 가능합니다: references/customization.md. 한 사용자의 기본 설정을 위해 스킬 자체의 에셋을 편집하지 마십시오.

이것이 이런 방식으로 구축된 이유

• 하나의 소스 파일은 슬라이드와 내레이션을 정렬된 상태로 유지합니다. LaTeX는 페이지 정확한 내레이션 맵(.narr)을 자체적으로 작성합니다.

…

[번역을 위해 잘림]