OpenSkillIndex← back to search
claude-code레퍼런스/시나리오

Optimization ref-video-downloader

동영상을 다운로드하여 로컬에 저장한다. 품질 선택, 메타데이터 캡처, 배치 다운로드를 지원한다. yt-dlp가 없으면 자동 설치 후 진행한다.

install
source · Clone the upstream repo
git clone https://github.com/sunLeee/optimization
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/sunLeee/optimization "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/data-fetch/ref-video-downloader" ~/.claude/skills/sunleee-optimization-ref-video-downloader && rm -rf "$T"
manifest: .claude/skills/data-fetch/ref-video-downloader/SKILL.md
source content

ref-video-downloader

동영상을 다운로드하여 로컬에 저장하는 스킬.

목적

  • YouTube, Vimeo 등 동영상 플랫폼에서 동영상 다운로드
  • 품질/포맷 선택 지원
  • 메타데이터 (제목, 설명, 썸네일) 자동 저장
  • 배치 다운로드 (플레이리스트) 지원
  • [@skills/ref-video-transcript/SKILL.md]와 연계하여 트랜스크립트 동시 저장

사용법

/ref-video-downloader https://www.youtube.com/watch?v=xxxxx
/ref-video-downloader https://www.youtube.com/watch?v=xxxxx --quality 1080p
/ref-video-downloader https://www.youtube.com/watch?v=xxxxx --audio-only
/ref-video-downloader https://www.youtube.com/playlist?list=xxxxx --playlist

옵션

옵션설명기본값
--quality
동영상 품질 (480p, 720p, 1080p, 4K)720p
--format
출력 포맷 (mp4, webm)mp4
--audio-only
오디오만 추출 (mp3)false
--playlist
플레이리스트 전체 다운로드false
--with-transcript
트랜스크립트 함께 저장false
--lang
자막 언어 (ko, en, ja 등)ko

프로세스

flowchart TD
    Start["/ref-video-downloader<br/>[video-url] [options]"]

    S1["Step 1: 환경 확인"]
    S1_1["yt-dlp 설치 여부 확인"]
    S1_2["미설치 시 자동 설치"]

    S2["Step 2: URL 분석"]
    S2_1["플랫폼 감지<br/>(YouTube, Vimeo 등)"]
    S2_2["동영상 ID 추출"]
    S2_3["플레이리스트 여부 확인"]

    S3["Step 3: 다운로드 옵션 설정"]
    S3_1["품질 선택 (--quality)"]
    S3_2["포맷 선택 (--format)"]
    S3_3["오디오 전용 (--audio-only)"]

    S4["Step 4: 메타데이터 수집"]
    S4_1["제목, 설명"]
    S4_2["썸네일 이미지"]
    S4_3["info.json 저장"]

    S5["Step 5: 동영상 다운로드"]
    S5_1["yt-dlp 실행"]
    S5_2["진행률 표시"]

    S6["Step 6: 트랜스크립트 연계<br/>(옵션)"]
    S6_1["--with-transcript 시<br/>ref-video-transcript 호출"]
    S6_2["동일 폴더에<br/>transcript.md 저장"]

    End([완료])

    Start --> S1
    S1 --> S1_1
    S1 --> S1_2

    S1 --> S2
    S2 --> S2_1
    S2 --> S2_2
    S2 --> S2_3

    S2 --> S3
    S3 --> S3_1
    S3 --> S3_2
    S3 --> S3_3

    S3 --> S4
    S4 --> S4_1
    S4 --> S4_2
    S4 --> S4_3

    S4 --> S5
    S5 --> S5_1
    S5 --> S5_2

    S5 --> S6
    S6 --> S6_1
    S6 --> S6_2

    S6 --> End

    style Start fill:#e1f5ff
    style S1 fill:#fff4e1
    style S2 fill:#e1ffe1
    style S3 fill:#ffe1f5
    style S4 fill:#f5e1ff
    style S5 fill:#e1f5ff
    style S6 fill:#fff4e1
    style End fill:#90EE90

출력 구조

docs/references/videos/
├── {sanitized-title}/
│   ├── video.mp4            # 다운로드된 동영상
│   ├── info.json            # 메타데이터 (제목, 설명, URL, 날짜)
│   ├── thumbnail.jpg        # 썸네일 이미지
│   └── transcript.md        # (선택) ref-video-transcript 연계 시

핵심 명령어

yt-dlp 설치 확인 및 자동 설치

# 설치 확인
which yt-dlp || pip install yt-dlp

# 버전 확인
yt-dlp --version

품질별 다운로드

# 720p 다운로드
yt-dlp -f "bestvideo[height<=720]+bestaudio/best[height<=720]" \
  --merge-output-format mp4 \
  -o "docs/references/videos/%(title)s/video.%(ext)s" \
  "VIDEO_URL"

# 1080p 다운로드
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" \
  --merge-output-format mp4 \
  -o "docs/references/videos/%(title)s/video.%(ext)s" \
  "VIDEO_URL"

# 4K 다운로드
yt-dlp -f "bestvideo[height<=2160]+bestaudio/best[height<=2160]" \
  --merge-output-format mp4 \
  -o "docs/references/videos/%(title)s/video.%(ext)s" \
  "VIDEO_URL"

오디오 전용 추출

yt-dlp -x --audio-format mp3 --audio-quality 0 \
  -o "docs/references/videos/%(title)s/audio.%(ext)s" \
  "VIDEO_URL"

메타데이터 저장

yt-dlp --write-info-json --write-thumbnail \
  --skip-download \
  -o "docs/references/videos/%(title)s/info" \
  "VIDEO_URL"

플레이리스트 다운로드

yt-dlp --yes-playlist \
  -f "bestvideo[height<=720]+bestaudio/best[height<=720]" \
  --merge-output-format mp4 \
  -o "docs/references/videos/playlist/%(playlist_index)s-%(title)s/video.%(ext)s" \
  "PLAYLIST_URL"

메타데이터 템플릿 (info.json)

{
  "title": "동영상 제목",
  "description": "동영상 설명",
  "url": "원본 URL",
  "uploader": "채널명",
  "upload_date": "YYYYMMDD",
  "duration": 3600,
  "view_count": 10000,
  "downloaded_at": "2026-01-21T10:00:00Z",
  "quality": "720p",
  "format": "mp4"
}

예제

User: /ref-video-downloader https://www.youtube.com/watch?v=xyz123

Claude:
=== 동영상 다운로드 ===

URL: https://www.youtube.com/watch?v=xyz123

[1/5] 환경 확인 중...
  - yt-dlp 버전: 2026.01.15

[2/5] 동영상 정보 수집 중...
  - 제목: "FastAPI 완전 정복 2026"
  - 채널: TechTutorials
  - 길이: 1:23:45
  - 품질: 720p (기본값)

[3/5] 메타데이터 저장 중...
  - info.json 저장 완료
  - thumbnail.jpg 저장 완료

[4/5] 동영상 다운로드 중...
  [████████████████████] 100%
  - video.mp4 (512MB)

[5/5] 완료

=== 다운로드 완료 ===

저장 위치: docs/references/videos/fastapi-complete-2026/
├── video.mp4 (512MB)
├── info.json
└── thumbnail.jpg

💡 트랜스크립트도 필요하시면:
   /ref-video-transcript https://www.youtube.com/watch?v=xyz123

오디오 추출 예제

User: /ref-video-downloader https://www.youtube.com/watch?v=xyz123 --audio-only

Claude:
=== 오디오 추출 ===

URL: https://www.youtube.com/watch?v=xyz123

[1/3] 동영상 정보 확인...
  - 제목: "Podcast Episode 42"
  - 길이: 45:30

[2/3] 오디오 추출 중...
  [████████████████████] 100%

[3/3] MP3 변환 중...
  - audio.mp3 (42MB)

=== 완료 ===

저장 위치: docs/references/videos/podcast-episode-42/audio.mp3

플레이리스트 예제

User: /ref-video-downloader https://www.youtube.com/playlist?list=PLxxx --playlist

Claude:
=== 플레이리스트 다운로드 ===

URL: https://www.youtube.com/playlist?list=PLxxx

플레이리스트 정보:
- 제목: "Python 기초 강의"
- 동영상 수: 10개
- 총 길이: 약 5시간

계속 진행할까요? (Y/n)
→ Y

[1/10] 다운로드: "01. Python 소개" ✓
[2/10] 다운로드: "02. 변수와 타입" ✓
...
[10/10] 다운로드: "10. 마무리" ✓

=== 완료 ===

저장 위치: docs/references/videos/playlist/python-basics/
├── 01-python-intro/video.mp4
├── 02-variables-types/video.mp4
...
└── 10-conclusion/video.mp4

오류 처리

오류원인해결
yt-dlp not found
yt-dlp 미설치자동 설치 진행
Video unavailable
지역 제한/비공개VPN 또는 다른 영상 선택
Format not available
요청 품질 없음낮은 품질로 자동 대체
Disk full
저장공간 부족저장공간 확보 후 재시도

관련 스킬

스킬명관계설명
[@skills/ref-video-transcript/SKILL.md]연계트랜스크립트 추출
[@skills/prd-workflow/SKILL.md]부모레퍼런스 수집 단계
[@skills/markdown-converter/SKILL.md]관련변환 도구

Changelog

날짜변경 내용
2026-01-21초기 스킬 생성