| name | youtube-learning-notes |
| description | YouTube 영상을 다운로드해 자막과 스크린샷을 결합한 한국어 학습 노트(.md)로 정리한다. "YouTube 영상 정리", "영상 학습노트", "유튜브 노트", "자막 기반 노트", "영상 요약 마크다운", "video to notes", "YouTube summary in Korean", "study notes from video", "transcribe and screenshot" 같은 표현은 물론, 사용자가 YouTube/유튜브/youtu.be 링크를 던지며 "정리", "요약", "공부 자료", "스크립트", "캡처와 같이" 등을 언급하면 반드시 이 스킬을 사용한다. yt-dlp로 영상·자막을 받고, ffmpeg로 핵심 장면을 캡처하고, 스크린샷-자막 매칭을 모델이 직접 검토한 뒤 영상을 보지 않아도 이해되는 한국어 노트를 만든다. |
YouTube Learning Notes
YouTube 영상 한 편을 입력받아 자막과 스크린샷이 결합된 한국어 학습 노트(Markdown)를 만들어내는 워크플로우. 영상을 다시 보지 않아도 핵심 흐름·시각 정보·인용을 파악할 수 있도록 정리한다.
언제 쓰는가
- 사용자가 YouTube URL을 주면서 "정리/요약/학습 노트/공부자료/스크립트로" 같은 요청을 할 때
- 강의·발표·인터뷰·튜토리얼처럼 시각 정보(슬라이드, 데모 화면, 도표)와 발화 내용을 동시에 옮겨야 할 때
- "Slack에 공유할 영상 요약", "회의록처럼 만들어줘"라는 요청에서도 영상이 출처면 우선 검토
단순히 "이 영상 무슨 내용이야?" 같은 한 줄 답변이면 이 스킬을 켜지 말고 짧게 답한다. 노트 산출물이 목적일 때만 쓴다.
전체 흐름
- 입력 수집 — URL, 노트 언어(기본 한국어), 노트 저장 경로
- 영상·자막 다운로드 (
yt-dlp)
- 자막(.srt) 파싱 → 장면/포인트 10~20개 선정
- 각 시점 스크린샷 추출 (
ffmpeg)
- 스크린샷-자막 매칭 검토 (필수 QA) — 모델이 이미지를 직접 보고 자막 섹션과 어울리는지 확인
- 한국어 학습 노트(.md) 작성 — 내용을 함축한 Obsidian 호환 파일명으로 저장
각 단계의 상세 절차는 아래에 정리한다. scripts/의 보조 스크립트는 반복 작업을 줄이기 위한 것이며, 반드시 써야 하는 것은 아니다.
작업 원칙 (효율)
- 독립적인 도구 호출은 한 번에 병렬로 실행한다. 여러 스크린샷을 검토할 때는 한 메시지에서
Read 호출을 병렬로 묶는다. 스크린샷 추출/재추출은 extract_screenshots.py 한 번 호출에 여러 --shot을 전달해 한 프로세스에서 처리한다(이쪽은 병렬 Bash가 아님).
- 불필요하게 되묻지 않는다. 기본값(한국어 노트, 표준 저장 경로)으로 진행 가능하면 진행하고, 막히는 지점에서만 확인한다. URL과 폴더 접근만 확실하면 끝까지 자동으로 완수한다.
- 각 단계의 산출물을 검증하고 넘어간다. 다운로드 후 파일 존재·길이 확인, 추출 후 이미지 확인 — 실패를 다음 단계로 끌고 가지 않는다.
1단계 — 입력 수집
사용자에게 한 번에 확인:
- YouTube URL (필수)
- 노트 언어 (기본: 한국어)
- 저장 폴더 (기본: 사용자 마운트 폴더 또는
outputs/youtube_<해시>/)
- 톤·길이 선호 (선택; "압축적", "상세", "회의록 톤" 등)
폴더 접근 권한이 없으면 mcp__cowork__request_cowork_directory로 작업 폴더를 먼저 요청한다. 다운로드 자체를 사용자에게 위임할 가능성이 있으니, 폴더 마운트는 1단계에서 받아두는 편이 안전하다.
2단계 — 다운로드
기본 명령어 (검증된 옵션)
yt-dlp \
-f "bv*[ext=mp4]+ba[ext=m4a]/mp4" \
--write-sub --write-auto-sub \
--sub-langs "ko,en" \
--convert-subs srt \
-o "%(title)s.%(ext)s" \
"<URL>"
bv*[ext=mp4]+ba[ext=m4a]/mp4 — mp4 비디오 + m4a 오디오를 합쳐 안정적인 mp4 산출. 코덱 문제로 합치기 실패하면 /mp4 fallback이 단일 mp4를 받는다.--write-sub --write-auto-sub — 수동 자막이 있으면 그걸, 없으면 자동 생성 자막을 받는다.--sub-langs "ko,en" — 한국어를 우선, 없으면 영어. 다른 언어가 필요하면 사용자 확인 후 조정.--convert-subs srt — 이후 단계에서 파싱하기 쉬운 SRT로 통일.
샌드박스 네트워크 차단 대응 (중요)
Cowork/제한된 샌드박스에서는 YouTube/googlevideo 도메인이 차단되어 yt-dlp가 실패한다. 이 경우 즉시 fallback으로 전환한다:
- 사용자에게 자신의 머신에서 동일한
yt-dlp 명령을 실행하도록 안내 (명령어를 복사 가능한 코드 블록으로 제공)
- 받은 파일들이 들어있는 폴더를
mcp__cowork__request_cowork_directory로 마운트 요청
- 마운트 후 그 폴더 안의
.mp4와 .srt를 입력으로 사용해 3단계로 진행
다운로드 실패 시 무한 재시도하지 말고, 한두 번 안에 fallback을 제안한다. 사용자의 시간을 아끼는 것이 우선이다.
산출물 확인
다운로드 후 다음을 확인하고 다음 단계로 넘어간다:
<title>.mp4 존재 + ffprobe로 duration이 0이 아닌지<title>.ko.srt 또는 <title>.en.srt 중 하나 이상 존재- 자막 파일이 비어있지 않은지 (
wc -l이 0이면 자동자막 생성에 실패한 것 → 사용자에게 알리고 다른 영상 또는 수동 입력 권유)
3단계 — 자막 파싱 & 장면 선정
scripts/parse_srt.py를 사용하거나 같은 로직을 직접 구현한다. 이 스크립트는 SRT를 시간 정렬된 큐(cue) 리스트로 읽어 들이고, 옵션으로 첫 N개 큐를 미리보기로 보여준다.
장면 선정 휴리스틱
- 개수: 10
20장이 기본. 영상이 짧으면(<10분) 812장, 길면(>30분) 15~25장.
- 균등 배치가 아니라 의미 단위로 끊기: 화자가 새 주제를 꺼내거나, 자막에 "다음으로", "Next", "결론은" 같은 전환 신호가 있는 시점 우선.
- 자동 생성 자막은 오타/문장 경계가 부정확하니, 시간 간격이 너무 좁은(<15초) 후보는 합치고, 너무 긴(>3분) 구간은 중간 지점을 추가.
- 슬라이드·데모 화면이 바뀔 가능성이 높은 지점을 우선. 모델 본인이 영상을 못 봤더라도 자막 흐름으로 추측 가능하다.
각 후보에 대해 {시:분:초, 자막 발췌, 추정 토픽} 표를 잠시 만들고 다음 단계에서 이미지를 매칭해 검증한다.
4단계 — 스크린샷 추출
각 시점에 대해 ffmpeg로 한 프레임씩 뽑는다. scripts/extract_screenshots.py가 일괄 처리하지만, 한 장만 다시 뽑을 때는 직접 실행이 편하다.
단일 프레임 명령
ffmpeg -y -ss <HH:MM:SS> -i "<input.mp4>" -vframes 1 -q:v 2 "<output.jpg>"
-ss를 -i 앞에 두면 빠른 seek + 정확한 프레임 디코드 균형이 좋다.-q:v 2 — JPEG 품질 우수 (낮을수록 고화질, 2가 거의 무손실에 가까움).- 출력 파일명은
scene_01_00m45s.jpg 처럼 장면 번호 + 타임스탬프 포함. 나중에 자막 큐와 매칭하기 쉽다.
5단계 — 스크린샷↔자막 매칭 검토 (QA, 가장 중요한 단계)
이 단계를 건너뛰면 노트 품질이 무너진다. 자동 자막은 화면 전환과 타이밍이 어긋날 때가 잦고, ffmpeg는 검은 화면·로딩 화면·관계없는 컷오프 프레임을 잡을 수 있다.
절차
- 각 스크린샷을
Read 도구로 직접 본다 (모델이 이미지를 인식할 수 있다).
- 해당 시점의 자막 큐와 비교해 다음을 평가:
- 이미지에 보이는 텍스트/슬라이드 제목/시각 요소가 자막 토픽과 부합하는가?
- 화면이 검정/광고/인트로/엔딩 등 노이즈인가?
- 같은 장면이 여러 번 잡혀 중복인가?
- 부적절하면 ±20초 범위에서 후보 시점을 다시 뽑아 ffmpeg로 재추출하고 다시 본다.
- 예:
00:12:30이 검은 화면이면 00:12:10, 00:12:50을 시도.
- 통과한 장면만 노트에 넣는다. 결과적으로 일부 후보가 사라져도 괜찮다 — 양보다 정합성이 중요.
이 검토 단계가 실제 운용에서 4장 교체로 검증된 핵심 단계다. 그냥 지나치지 말고 모든 스크린샷을 한 번씩 본다.
6단계 — 한국어 학습 노트 작성
assets/note_template.md의 구조를 따른다. 핵심 원칙:
- 영상을 보지 않아도 완벽히 이해 가능해야 한다 — 단, "이해에 필요한 정보"만 옮긴다. 화면에 고유한 시각 정보(슬라이드·도표·코드)는 텍스트로 옮기되, 화면을 글로 다시 묘사하는 보일러플레이트는 넣지 않는다.
- 자동 자막의 오타는 문맥에 맞게 정정하되, 원문 인용 모음에는 원래 자막 흐름을 살린다 (단, 명백한 음성인식 오류는 보정해도 됨 — 예: "엠씨피" → "MCP").
- 스크린샷은 인라인으로
 형식으로 삽입.
- 모든 시간 표기는
[MM:SS] 또는 [HH:MM:SS]로 일관되게.
영상 유형에 따라 장면 서술 방식을 바꾼다 (중요)
먼저 영상이 어느 쪽인지 판단한다:
- A형 — 시각 정보가 있는 영상(강연·튜토리얼·제품 데모: 슬라이드/도표/코드/데모 화면이 뜸).
화면을 텍스트로 옮기는 게 실제로 가치가 있다. 화면의 핵심(슬라이드 제목, 도표 구조, 코드)을
옮긴 뒤 발화를 우리말로 정돈해 잇는다.
- B형 — 사람이 말하는 영상(인터뷰·대담·팟캐스트: 화면은 말하는 사람뿐).
화면은 "누가 말하는지" 맥락 정도라 화면 설명을 쓰지 않는다. 스크린샷은 맥락용으로
남기되, 본문은 화자의 요점 + 받치는 일화·배경을 흐르는 산문으로 쓴다.
라벨(화면 설명/발화 핵심/메모)은 정보를 더할 때만 쓴다. 대부분의 장면은 라벨 없이
1~3문단의 산문이 더 읽기 좋다. 한 장면을 굳이 "핵심"과 "메모"로 쪼개지 말 것 — 정작 중요한
내용이 "메모"에 들어가 라벨이 중요도를 왜곡하기 쉽다. 토막내고 싶을 때만 **굵은 라벨**:을 쓴다.
노트 섹션 구성
# <영상 제목>
> 출처: <원본 URL>
> 길이: <HH:MM:SS> · 채널: <채널명>
## 한눈에 보는 요약
- 3~7개 불릿. 영상을 한 문장씩으로 압축. "왜 보는지 → 무엇을 다루는지 → 결론" 흐름.
## 장면별 상세 설명
### [MM:SS] 1. <장면 제목>
<라벨 없는 산문 1~3문단. A형이면 화면의 시각 정보 → 발화 정돈 순으로,
B형이면 화자 요점 → 받치는 일화·배경 순으로. 화면을 글로 묘사하지 않는다.>
(장면 2, 3, ... 반복)
## 부록 — 실전 체크리스트
- 시청자가 바로 적용할 수 있는 액션 아이템. 영상이 튜토리얼/실무성이면 필수, 에세이/대담이면 생략 가능.
## 원문 인용 모음
- [MM:SS] "발화 그대로의 인용" — 자동자막이면 가벼운 정정만, 수동자막이면 원문 보존.
assets/note_template.md에 A형·B형 본보기가 모두 있으니 새 노트마다 맞는 쪽을 복사해 채우면 빠르다.
작성 디테일
- 제목은 영상 원제를 따르되, 한국어가 자연스럽지 않으면 부제로 한국어 요약을 덧붙인다.
- 장면별 설명은 자막 그대로 옮기기 → 우리말로 정돈하기 → 필요한 배경 보강하기 순서로 작성하면 빠지는 정보가 줄어든다.
- (A형) 화자가 코드/명령어/수식·슬라이드를 보여주면 코드 블록·텍스트로 옮긴다. 화면을 캡처만 하고 텍스트로 안 옮기면 검색 가능성이 떨어진다. (B형은 옮길 시각 정보가 없으니 발화에 집중.)
- 노트 길이는 보통 영상 1분당 80~150자. 너무 짧으면 정보 손실, 너무 길면 가독성 저하.
산출물 정리
작업 폴더는 다음과 같이 정리해 사용자에게 전달:
youtube_<해시 또는 슬러그>/
├── <영상 제목>.mp4
├── <영상 제목>.ko.srt # 또는 .en.srt
├── screenshots/
│ ├── scene_01_00m45s.jpg
│ ├── scene_02_02m10s.jpg
│ └── ...
└── notes.md # 최종 학습 노트
notes.md를 present_files로 공유하고, 스크린샷이 상대경로로 잘 걸리는지 마지막에 한 번 확인한다.
보조 자원
scripts/parse_srt.py — SRT를 cue 리스트로 파싱. CLI로 --preview N 옵션 지원.scripts/extract_screenshots.py — {시간 → 출력파일} 리스트를 받아 일괄 ffmpeg 호출.assets/note_template.md — 노트 작성 본보기.
각 스크립트의 자세한 사용법은 파일 상단 docstring에 적어두었다.
