youtube-collector

name	youtube-collector
description	Skill for registering YouTube channels, collecting new content, and generating transcript-based summaries. Use when the user (1) requests YouTube channel registration/management, (2) requests collection of new videos from registered channels, or (3) requests YouTube video summaries. Data is stored in YAML format under the .reference/ folder.
context	fork

YouTube Collector

Collects new content from registered YouTube channels and generates transcript-based summaries.

Prerequisites

Required packages:

pip install google-api-python-client youtube-transcript-api pyyaml

API key setup: For security, the API key is stored in the user's home directory.

# Set API key (interactive)
python3 scripts/setup_api_key.py

# Or specify directly
python3 scripts/setup_api_key.py --api-key YOUR_API_KEY

# Check current configuration
python3 scripts/setup_api_key.py --show

Configuration file path:

• macOS/Linux: ~/.config/youtube-collector/config.yaml
• Windows: %APPDATA%\youtube-collector\config.yaml

Workflow

1. Channel Registration

Register by channel URL or handle:

# Register by handle
python3 scripts/register_channel.py --channel-handle @channelname --output-dir .reference/

# Register by URL
python3 scripts/register_channel.py --channel-url "https://youtube.com/@channelname" --output-dir .reference/

Result: Channel information is added to .reference/channels.yaml.

2. Content Collection

The script automatically handles video listing + transcript collection + YAML file saving:

# Collect from a specific channel
python3 scripts/collect_videos.py --channel-handle @channelname --output-dir .reference/ --max-results 10

# Collect from all registered channels
python3 scripts/collect_videos.py --all --output-dir .reference/

Result: .reference/contents/{channel_handle}/{video_id}.yaml files are generated.

3. Summary Generation

After checking newly added videos from the collection result JSON, add a summary field to each video's YAML file:

summary:
  source: "transcript"  # or "description" (when transcript is unavailable)
  content: |
    ## 서론
    - 문제 제기 또는 주제 소개
    - 영상의 목적/배경

    ## 본론
    - 핵심 내용 상세 설명
    - 해결책, 방법론, 예시 등
    - 주요 포인트별 정리

    ## 결론
    - 핵심 요약
    - 시사점 또는 다음 단계

Summary generation criteria:

• transcript.available: true -> Transcript-based summary, summary.source: "transcript"
• transcript.available: false -> Description-based summary, summary.source: "description"

4. Data Retrieval

Checking collected content:

• Browse the .reference/contents/ folder structure
• Read YAML files for specific channels/videos and provide the information

Script Options

register_channel.py

Option	Description
--channel-handle	Channel handle (@username)
--channel-url	Channel URL
--channel-id	Channel ID (UC...)
--output-dir	Output directory (default: .reference)

collect_videos.py

Option	Description
--channel-handle	Specific channel handle
--channel-id	Specific channel ID
--all	Process all channels in channels.yaml
--output-dir	Output directory (default: .reference)
--max-results	Maximum collection count per channel (default: 10)
--language	Preferred transcript language (default: ko)
--no-skip-existing	Overwrite existing files

Data Structure

Detailed schema: references/data-schema.md

Video Data Example

video_id: "abc123"
title: "영상 제목"
published_at: "2025-12-10T10:00:00Z"
url: "https://youtube.com/watch?v=abc123"
thumbnail: "https://..."
description: "영상 설명..."
duration: "PT10M30S"
collected_at: "2025-12-13T15:00:00Z"
transcript:
  available: true
  language: "ko"
  text: "자막 전체..."
summary:
  source: "transcript"
  content: |
    ## 서론
    - 영상의 배경 및 목적

    ## 본론
    - 핵심 내용 1
    - 핵심 내용 2

    ## 결론
    - 핵심 요약

Error Handling

Situation	User-Facing Message
API key not configured	"YouTube Data API 키가 필요합니다. python3 scripts/setup_api_key.py로 설정해주세요."
No channels registered	"등록된 채널이 없습니다. 먼저 채널을 등록해주세요."
Required packages not installed	"필요한 패키지를 설치해주세요: pip install google-api-python-client youtube-transcript-api pyyaml"
API quota exceeded	"YouTube API 할당량이 초과되었습니다. 내일 다시 시도해주세요."