YouTube 요약
파이프라인: 자막 가져오기 -> 전체 읽기 -> 구조화된 마크다운 요약 작성 -> PDF 렌더링
scripts/fetch_transcript.py가 첫 번째 단계를 처리하고 scripts/md_to_pdf.py가 마지막 단계를 처리합니다. 요약 작성은 그 사이에 이루어집니다.
1. 접근 권한: 사용자가 이미 시청할 수 있는 영상만
- 공개 및 미등록 영상은 로그인이 필요 없습니다. 항상 쿠키 없이 먼저 시도하세요.
- 비공개 또는 멤버 전용 영상은 스크립트가
NEEDS_SIGNIN과 함께 종료됩니다. 접근 권한이 부여된 사용자 본인의 계정으로 로그인된 브라우저에서 쿠키를 읽어야만 진행할 수 있습니다.--browser를 전달하기 전에 어떤 브라우저(및 프로필, 여러 개 사용하는 경우)인지 물어보세요. 쿠키는 사용자의 자격 증명입니다.- yt-dlp 문서에서는 로그인 계정을 자동화된 방식으로 사용하면 속도 제한이나 계정 차단이 발생할 수 있다고 경고합니다. 사용자 본인의 업로드 영상의 경우 YouTube Studio 다운로드 또는 Google Takeout이 위험이 없는 대안이며, 스크립트는 결과 로컬 파일을 허용합니다.
- 개인정보 보호 설정, 지역 제한, DRM 또는 유료 콘텐츠를 우회하려 하지 말고, 타인의 계정을 절대 사용하지 마세요. 사용자의 계정으로 영상을 볼 수 없으면 그렇게 알리고 중단하세요.
--browser를 사용했는데도 "이 동영상은 비공개입니다"라는 메시지가 나타나면, 일반적으로 접근 권한이 있는 계정이 브라우저의 기본 로그인 계정이 아니기 때문입니다.--browser chrome:"Profile 2"를 제안하거나, 해당 계정으로 새 프로필에 로그인하도록 안내하세요.
2. 자막 가져오기 (분리 실행: 긴 영상은 시간 소요)
세션 중간에 지워질 수 있는 임시 스크래치패드가 아닌, 내구성 있는 작업 폴더를 사용하세요: ~/youtube-summaries/<video-id-or-file-stem>/
세션이 종료되어도 작업이 유지되도록 분리하여 시작하세요:
OUT=~/youtube-summaries/<id>; mkdir -p "$OUT"
nohup python3 -I ~/.claude/skills/youtube-summary/scripts/fetch_transcript.py "<url-or-file>" \
--out "$OUT" [--browser chrome] [--lang en|auto] [--force-audio] [--audio mp3|m4a|wav] \
> "$OUT/run.log" 2>&1 &!
그런 다음 폴링 대신 백그라운드 Bash until-루프로 대기하세요.
예: until grep -qE '^(DONE|FAILED|NEEDS_SIGNIN)' "$OUT/status"; do sleep 15; done; cat "$OUT/status"
스크립트가 하는 일:
- 메타데이터를 조회한 다음, 수동 자막을 사용하고, 없으면 자동 자막으로 대체합니다.
- 자막이 없으면 오디오를 다운로드하고 Apple Silicon에서는 mlx-whisper large-v3-turbo를, 그 외 환경에서는 openai-whisper를 사용하여 텍스트로 변환합니다. ffmpeg가 설치되어 있지 않으면
imageio-ffmpeg에서 가져옵니다. - Whisper의 침묵 환각("Thank you.")과 자동 자막의 반복되는 반복을 제거합니다.
transcript.txt를 2분 단위[h:mm]문단으로 작성하고meta.json도 생성합니다.
소요 시간: M 시리즈 Mac(8GB)에서 오디오 1시간당 약 4~5분의 변환 시간이 소요되며, 다운로드 시간은 별도입니다. 예상 대기 시간을 사용자에게 알리고, 진행 상황을 요청하면 다운로드 % 또는 run.log의 마지막 타임스탬프를 보고하세요.
자동 자막이 좋지 않은 경우(음악, 심한 악센트, 잘못된 언어) --force-audio를 사용하세요. 비영어 영상에는 --lang auto를 사용하세요.
오디오 추출: 사용자가 오디오 자체("mp3 주세요", "오디오 추출", 팟캐스트 버전, 오프라인 듣기)를 원할 때 --audio mp3(또는 m4a/wav)를 전달하세요. 파일은 <title>.<format>으로 $OUT에 저장되고, 해당 경로는 meta.json의 audio_file에 기록됩니다. 가용한 자막이 있으면 여전히 자막을 사용하므로, 오디오를 요청해도 느린 변환이 강제되지 않습니다. 사용자가 오디오만 원하고 요약은 원하지 않는 경우, 이 단계 후에 중단하고 파일을 알려주세요.
3. 모든 내용을 읽고 요약하기
transcript.txt 전체를 읽으세요. 사용자는 보통 모든 세부 사항을 원합니다. 약 60,000단어 이상이면 순서대로 청크로 나누어 읽고 청크별로 노트를 작성한 후 요약을 작성하세요.
$OUT/summary.md를 자신의 언어로 작성하세요: 요약이지, 원문 그대로의 기록이 아닙니다. 짧은 인용은 괜찮지만, 긴 원문 그대로의 구절은 좋지 않습니다. 기본 구조(영상에 맞게 섹션을 조정하세요):
# <영상 제목>
| | |
|---|---|
| 영상 | <제목> |
| 채널 | <채널> |
| 링크 | <url> |
| 길이 | <시간> |
| 발표자 | <영상에 실제로 언급된 이름만> |
| 자막 | <수동 자막 / 자동 자막 / 로컬 Whisper 변환> |
## 1. 한눈에
- 5~8개 글머리: 영상이 다루는 내용과 주요 결론
## 타임라인
| 시간 | 주제 |
|---|---|
| 0:00 | ... |
## 2. <장/주제별 섹션, 영상 순서대로>
### <하위 주제>
- 모든 구체적인 사실, 숫자, 이름, 정의, 예제, 단계, 경고 및 권장 사항
- 데모 및 연습은 번호가 매겨진 단계로; 비교는 표로
## 주요 사실 / 요점
| 항목 | 값 |
## 이 요약에 대한 참고 사항
> 자막이 생성된 방식; 수정한 잘못 들린 용어; 발표자가 잘못 말한 내용(수정 포함); 들리지 않거나 불확실한 내용.
이러한 형태가 유용한 이유: 타임라인을 통해 독자가 영상의 특정 부분으로 바로 이동할 수 있고, 표는 사람들이 나중에 검색하는 사실을 모아두며, 참고 사항 섹션은 변환 오류에 대한 투명성을 유지합니다. 음성-텍스트 변환은 제품 이름과 전문 용어를 망가뜨리므로, 문맥에서 수정하고 수정 사항을 나열하세요. 발표자가 잘못 말한 사실은 그대로 반복하지 말고 확인하세요.
본문의 출처를 유지하세요: 참고 사항 섹션 위의 모든 내용은 transcript.txt 또는 meta.json에서 비롯되어야 합니다. 독자는 이 문서를 영상이 말하는 내용의 기록으로 취급하므로, 사용자가 영상에 대해 알고 있는 내용(발표자가 실제로 누구인지, 촬영 장소, 역사 등)은 확실하더라도 본문에 속하지 않습니다. 그러한 맥락이 정말로 도움이 된다면 참고 사항에 넣고 "영상 외부"라고 표시하세요. 영상에서 제공하지 않는 이름이나 대명사를 절대 할당하지 마세요. 영상 설명이 내용과 관련이 없는 경우(재사용되거나 스팸 설명이 자주 있음), 무시하고 참고 사항에 그렇게 명시하세요.
문서 크기를 영상에 맞추세요. <!-- pagebreak -->는 긴 문서(예: 여러 시간 스트림의 각 장)의 새로운 주요 부분을 시작하는 데만 사용하고, 표지 표 다음에는 절대 사용하지 마세요. 2분짜리 클립은 1~2페이지에 맞아야 합니다.
4. PDF 렌더링 및 확인
uv run ~/.claude/skills/youtube-summary/scripts/md_to_pdf.py "$OUT/summary.md" "$OUT/<Title>.pdf"
1페이지와 조밀한 페이지 하나를 PNG로 렌더링하고, 보고하기 전에 살펴보세요:
uvx --with pypdfium2 --with pillow python -c "..."
그런 다음 사용자에게:
- PDF의 절대 경로 및 페이지 수
- 3~5줄 개요
- 주의 사항: 자동 생성된 자막, 들리지 않은 섹션 등
오디오 파일은 클 수 있습니다. 언급하고 사용자가 삭제 여부를 결정하도록 하세요.
문제 해결
Sign in to confirm you're not a bot/ 공개 영상에서 HTTP 403: 기다렸다가 재시도하세요. 지속되면 IP 또는 속도 제한 문제입니다. 반복하지 마세요.- yt-dlp JS-runtime 경고: Deno가 없으면 스크립트가
--js-runtimes node를 전달합니다. Node 22+가 필요합니다. - 자막 단어 없음 또는 쓰레기로 가득 찬 자막: 언어를 확인하거나(
--lang auto),--force-audio로 다시 실행하세요.