VideoBook: 하나의 동영상을 그림과 함께 보는 전자책으로 만들기
사용자가 YouTube / Bilibili 링크를 주면 읽을 수 있는 기술 전자책을 만들어 냅니다:
output/<video_id>/book.md + book.html (플레이어 카드 내장, 스크린샷 클릭 확대, Mermaid 다이어그램),
선택적으로 transcript.corrected.txt 자막 교정 대조 원고를 제공하며, GitHub Pages에 게시하여 다른 사람이 읽을 수 있게 할 수 있습니다.
이 스킬은 오케스트레이션 계층이며 자체 포함되어 있습니다: 에이전트에 필요한 모든 지침은 이 디렉토리 내(SKILL.md + references/)에 있으며,
저장소의 instructions.md / README.md에 의존하지 않습니다 (이 파일들은 사람 독자를 대상으로 하며, 원래대로 유지하고 이 스킬이 관리하지 않습니다).
유일한 외부 의존성은 파이프라인의 실행 코드 src/*.py입니다: 명령어와 인수는 항상 스크립트 --help를 기준으로 하며, 스크립트 로직을 재작성하지 마십시오.
변동 가능한 데이터(예: src/make_corrected.py의 오타 MAP)는 스킬에 복사하지 말고, 규칙만 작성하고 원본 파일을 가리키십시오;
유일한 예외는 2단계의 조판 지침으로, 이 디렉토리에는 동일한 소스의 복사본 references/stitcher-prompt.md가 있습니다 (저장소 버전이 우선합니다).
사전 조건 (처음 실행 시 반드시 읽기)
- 작업 디렉토리 = videobook 저장소 루트 디렉토리 (판단 기준:
src/dump_transcript.py와prompts/존재), 모든 상대 경로(output/<video_id>/...)는 이 디렉토리를 기준으로 해석됩니다. 저장소가 로컬에 없으면 먼저git clone https://github.com/Luke-Evan/videobook.git를 사용자 코드 프로젝트 디렉토리로 복제하십시오 (임시 디렉토리나 별도의 projects 디렉토리를 만들지 말고), 그런 다음cd로 들어가십시오. - Python >= 3.10 (3.12 권장). 의존성 설치:
uv sync(uv 사용 시) 또는pip install -r requirements.txt. 실행은 항상 저장소 환경의 인터프리터를 사용하십시오:uv run python src/xxx.py또는.venv/Scripts/python.exe src/xxx.py. - 일회성 로그인:
python src/capture_frames.py --setup-profile을 실행하면 전용 Chrome이 열리고 (데이터 디렉토리.capture-profile/), Bilibili / YouTube에 로그인한 후 창을 닫으면 로그인 상태가 오래 지속됩니다. 로그인 계정의 멤버십 등급이 스크린샷 해상도 상한을 결정합니다. - 해외 동영상: 터미널에 프록시 필요 (자막 가져오기), 브라우저에도 글로벌 프록시 필요 (그렇지 않으면 생성된 페이지의 YouTube iframe이 검은 블록으로 표시됨).
- 샌드박스 외부/권한 상승이 필요한 명령어는 개요 표의 마지막 열을 참조하십시오; 순수 로컬 단계는 샌드박스 내에서 수행 가능합니다.
파이프라인 개요
| 단계 | 작업 | 명령어 | 세부 사항 | 권한 상승 |
|---|---|---|---|---|
| 1 | 자막 추출 | python src/dump_transcript.py "<URL>" | references/transcript.md | Bilibili 필요 |
| 1b | 플랫폼에 자막이 없을 때 로컬 ASR 대체 | python src/asr_transcript.py <video_id> | references/transcript.md | 아니요 (시간 소요) |
| 1.5 | 강의 공식 강의 노트 + 4K 슬라이드 (기본 실행, 강의에 홈페이지가 없으면 건너뜀) | python src/course_assets.py <video_id> --course-url <강의 홈페이지> | references/course-assets.md | 렌더링 필요 |
| 2 | 대규모 언어 모델이 자막을 book.md로 재작성 | 조판 지침에 따라 생성 (references/stitcher-prompt.md, 저장소에 prompts/stitcher_system.md가 있으면 그것을 기준으로 함) | references/writing.md | 아니요 |
| 2b | 자막 교정 대조 원고 (선택 사항) | python src/make_corrected.py <video_id> | references/correction.md | 아니요 |
| 3 | 프레임 캡처 및 자리 표시자를 이미지로 구체화 | python src/capture_frames.py <video_id> "<URL>" | references/capture.md | 예 |
| 4 | HTML 렌더링 + 로컬 미리보기 시작 | python src/post_process.py "<URL>" output/<id>/book.md 그런 다음 python -m http.server 8080 --directory output/<id> | — | 아니요 |
| 5 | 사용자에게 결과 알림, 대용량 파일 정리 문의 | — | 아래 '전달' 참조 | — |
| 6 | 완성된 결과물을 pages 브랜치에 게시 (선택 사항) | python src/publish.py <video_id> 그런 다음 git push origin pages | references/publish.md | 아니요 (push는 네트워크 필요) |
오류, 화질 문제, 자막을 가져올 수 없는 경우, ASR 중단 등은 먼저 references/troubleshooting.md를 확인하십시오.
철칙 (협상 불가)
- 자막 적용 범위 < 50% (종료 코드 3)인 경우 2단계에 진입할 수 없음: 먼저 로그인 상태/프록시를 수정하거나 ASR 대체로 전환하십시오.
- 스크린샷 이미지는 반드시 로그인된 브라우저의 플랫폼 플레이어에서 가져와야 함, 3단계에서 어떤 방식으로든 동영상/오디오 파일을 다운로드할 수 없음 (ffmpeg 프레임 추출은 최후의 대체 수단). 금지된 방법 목록은
references/capture.md참조. - 쿠키는 시스템 임시 디렉토리에만 쓰고 사용 후 즉시 삭제, 절대 저장소에 저장하지 말고, 작업 공간에 수동으로
cookies.txt를 두지 마십시오. output/은 어떤 git 작업의 영향을 받지 않음; 완성된 결과물은 orphan 브랜치pages에만 게시되며,main에는 코드만 있습니다.- 교정 원고 충실성: 각 단락은 강사의 원래 단어와 순서를 유지하고, ASR 오타 교체 + 말버릇 제거만 수행; 단락 삭제, 여러 줄 삭제, 대규모 재작성 금지 (검증 계층이 직접 거부).
- 책 쓰기 충실성 하한: 문어체화가 요약화를 의미하지 않음; 비유, 사례, 추론 체인 유지; 편집자 보충 설명은 반드시 '편집자 설명'으로 표시.
- 강의 자료 저작권: 강의 노트와 슬라이드는 강사 소유 (일반적으로 CC BY-NC), 책 시작 부분의 정보 블록과 끝 부분에 출처 링크, 저자 표시 및 라이선스 이름을 반드시 유지.
- 슬라이드 적용 철칙:
slides_text.md의 각 페이지는 책에 정확히 한 번 나타나야 하며, 제출 전--audit가 반드시 PASS해야 함. - 대용량 파일 삭제(
audio.m4a,video_source.mp4등) 전에 반드시 사용자에게 물어보고, 확인을 받은 후에 삭제. - HTML을 생성하거나 수정할 때 텍스트와 배경의 대비가 WCAG AA의 4.5:1 이상이어야 함.
- 각 단계는 멱등적으로 다시 실행 가능: 자리 표시자 구체화 전에 스크립트가 자동으로
book.tagged.md를 백업하며, 이 파일이 남아 있으면 3단계를 다시 실행하여 스크린샷을 복원할 수 있습니다.
전달 (5단계에서 한 번에 말하기)
output/<video_id>/book.md의 위치;- 미리보기 주소
http://localhost:8080/book.html, 서비스를 종료하려면 터미널에서Ctrl+C; - YouTube 동영상은 브라우저가 YouTube에 접속 가능해야 함 (프록시), Bilibili 동영상은 직접 시청 가능;
- 스크린샷 해상도는
.capture-profile/에 로그인된 계정의 등급에 따라 다름; 더 선명하게 하려면 계정을 변경하여 로그인한 후 3단계를 다시 실행; - 강의 공식 자료를 사용한 경우, 설명서에 슬라이드 그림은 공식 4K 렌더링 이미지임을 명시 (책 시작 부분에 출처와 CC 라이선스 표기), 데모 프레임은 여전히 동영상 프레임이며,
course/디렉토리는 전체 삭제해도 읽기에 지장 없음; - 프로세스 중 생성된 대용량 미디어 파일 삭제 여부 문의 (철칙 9).
이 디렉토리 내용 (필요할 때 읽고, 한 번에 모두 읽지 마십시오)
| 파일 | 언제 읽을지 |
|---|---|
references/transcript.md | 1단계 자막 가져오기; 플랫폼에 자막이 없어 로컬 ASR로 전환할 때 |
references/writing.md | 2단계에서 자막을 book.md로 재작성할 때 |
references/stitcher-prompt.md | 2단계의 조판 지침 원문 (저장소에 prompts/stitcher_system.md가 있으면 저장소 버전 기준) |
references/course-assets.md | 강의에 공식 홈페이지가 있을 때 1.5단계, 슬라이드 적용 철칙, 슬라이드 업그레이드 |
references/correction.md | 자막 교정 대조 원고 및 AI 행 수준 수정 제안 생성 |
references/capture.md | 3단계 프레임 캡처: 우선 순위, 명시적으로 금지된 방법, QA 습관 |
references/publish.md | 6단계 pages 브랜치에 게시 |
references/troubleshooting.md | 모든 오류, 화질 이상, 자막을 가져올 수 없는 경우, 권한 상승 거부 |
유지 관리 규칙
- 이 스킬은 파이프라인 코드와 동일한 저장소에서 버전 관리됨:
src/*.py의 인수, 단계 순서 또는 철칙이 변경되면 이 디렉토리도 반드시 동기화해야 함. - 저장소의
instructions.md와README.md는 사람 독자를 대상으로 하며, 원래대로 유지하고 이 스킬이 관리하지 않습니다. 스킬을 활성화하기 위해 이 파일들을 수정하지 마십시오; 내용이 이 디렉토리와 중복될 경우, 에이전트는 이 디렉토리를 기준으로 합니다. references/stitcher-prompt.md를 동기화할 때 파일 헤더의 출처 주석에 커밋 번호를 업데이트하십시오.- 다른 사람 설치:
skill-installer는--repo Luke-Evan/videobook --path skills/videobook사용; 또는 복제한 후 이 디렉토리를~/.codex/skills/(Codex 전용) 또는~/.agents/skills/(크로스 에이전트)에 복사/심볼릭 링크. - 이 디렉토리에는 쿠키, 로그인 상태,
output/결과물 또는 미디어 파일이 포함되어 있지 않으며, 안전하게 공개 배포할 수 있습니다.