kdyvideo — YouTube 비디오 7차원 심층 분석

YouTube 기술 영상을 yt-dlp로 다운로드하고 TwelveLabs API(Marengo 3.0 + Pegasus 1.2)로 인덱싱한 후, 7차원 프레임워크로 구조화 분석하여 실행 가능한 가이드와 스킬 복제 지침을 자동 생성하는 스킬.

출처: jordanwwoods/analyze-video + twelvelabs-io/twelve-labs-claude-code-plugin 통합 설계 참조: docs/intel/notebooklm-research/README.md 시나리오 C

기본 경로

GENERAL_PRO 결정 순서:
1. 환경변수 GENERAL_PRO_PATH
2. CWD가 00-general-pro* 내부이면 해당 루트
3. ~/{develop,dev}/00-general-pro-web 존재 탐색
4. 실패 시 AskUserQuestion: "00-general-pro-web 경로를 입력해주세요"

GENERAL_PRO  = {결정된 경로}
SKILLS_DIR   = $GENERAL_PRO/03-skills
INTEL_DIR    = $GENERAL_PRO/docs/intel
VIDEO_DIR    = $INTEL_DIR/kdyvideo
REFS_DIR     = $GENERAL_PRO/03-skills/kdyvideo/references

인수 처리

사용자가 제공한 인수: $ARGUMENTS

YouTube URL에서 비디오 ID 추출:

• ?v= 파라미터: https://youtube.com/watch?v={VIDEO_ID}
• 단축 URL: https://youtu.be/{VIDEO_ID}
• VIDEO_ID가 추출되지 않으면 → 오류 출력 후 중단

Phase 0: 환경 확인

0-1: yt-dlp 설치 확인

yt-dlp --version

미설치 시 설치 안내:

# pip (권장)
pip install yt-dlp

# Homebrew (macOS)
brew install yt-dlp

# winget (Windows)
winget install yt-dlp

0-2: TwelveLabs API 키 확인

환경변수 TWELVE_LABS_API_KEY 존재 여부 확인:

echo $TWELVE_LABS_API_KEY

• 설정됨 → Phase 2 TwelveLabs 인덱싱 사용
• 미설정 → 자막 기반 폴백 모드 사용 (사용자에게 알림)

API 키 발급 안내: https://playground.twelvelabs.io/ → Settings → API Keys

0-3: ffmpeg 설치 확인

ffmpeg -version

미설치 시 안내:

# yt-dlp 비디오 처리에 ffmpeg 필요
# https://ffmpeg.org/download.html
# macOS: brew install ffmpeg
# Windows: winget install ffmpeg

0-4: 출력 디렉토리 준비

VIDEO_ID = {URL에서 추출}
OUTPUT_DIR = $VIDEO_DIR/{VIDEO_ID}
mkdir -p $OUTPUT_DIR

Phase 1: 비디오 다운로드 및 메타데이터 추출

--skip-download 플래그가 있고 $OUTPUT_DIR/{VIDEO_ID}.mp4가 존재하면 Phase 1 전체 스킵.

1-1: 비디오 다운로드 (720p 기본)

yt-dlp \
  -f "bestvideo[height<=720]+bestaudio/best[height<=720]" \
  --merge-output-format mp4 \
  -o "$OUTPUT_DIR/%(id)s.%(ext)s" \
  "$YOUTUBE_URL"

다운로드 실패 시 → 예외사항 섹션 참조.

1-2: 메타데이터 추출

yt-dlp \
  --write-info-json \
  --skip-download \
  -o "$OUTPUT_DIR/%(id)s" \
  "$YOUTUBE_URL"

{VIDEO_ID}.info.json에서 추출할 필드:

• title: 영상 제목
• description: 설명란
• duration: 총 재생 시간 (초)
• channel: 채널명
• tags: 태그 목록
• upload_date: 업로드 날짜
• view_count: 조회수

1-3: 자막 추출

yt-dlp \
  --write-auto-sub \
  --write-sub \
  --sub-lang "ko,en" \
  --sub-format "vtt" \
  --skip-download \
  -o "$OUTPUT_DIR/%(id)s" \
  "$YOUTUBE_URL"

우선순위: 한국어 자막 → 영어 자막 → 자동 생성 자막 → 자막 없음(비디오 분석만)

Phase 2: TwelveLabs 인덱싱

TWELVE_LABS_API_KEY가 미설정이면 이 Phase를 건너뛰고 자막 기반 폴백 모드로 Phase 3 실행.

2-1: 인덱스 생성 또는 재사용

TwelveLabs 인덱스 이름: kdyvideo-{VIDEO_ID}

# TwelveLabs Python SDK 사용
from twelvelabs import TwelveLabs

client = TwelveLabs(api_key=TWELVE_LABS_API_KEY)

# 기존 인덱스 확인
indexes = client.index.list()
existing = next((i for i in indexes if i.name == f"kdyvideo-{VIDEO_ID}"), None)

if existing:
    index_id = existing.id
else:
    index = client.index.create(
        name=f"kdyvideo-{VIDEO_ID}",
        models=[
            {"name": "marengo3", "options": ["visual", "conversation", "text_in_video"]},
            {"name": "pegasus1.2", "options": ["visual", "conversation"]},
        ]
    )
    index_id = index.id

2-2: 비디오 업로드

task = client.task.create(
    index_id=index_id,
    file=f"{OUTPUT_DIR}/{VIDEO_ID}.mp4"
)

2-3: 인덱싱 완료 대기

import time

while True:
    task_status = client.task.retrieve(task.id)
    if task_status.status == "ready":
        video_id_tl = task_status.video_id
        break
    elif task_status.status == "failed":
        raise Exception(f"인덱싱 실패: {task_status.error}")
    print(f"인덱싱 중... ({task_status.status})")
    time.sleep(30)  # 30초 간격 폴링

긴 영상(60분+)은 인덱싱에 5~15분 소요 — 사용자에게 예상 시간 안내.

Phase 3: 7차원 분석

분석 프레임워크 상세: $REFS_DIR/seven-dimensions.md

--dimensions 인수가 있으면 지정된 차원만 실행. 없으면 전체 1~7 실행.

각 차원은 TwelveLabs generate API(인덱싱 모드) 또는 자막 텍스트(폴백 모드)로 독립 실행.

TwelveLabs generate API 사용 (기본 모드)

result = client.generate.text(
    video_id=video_id_tl,
    prompt=DIMENSION_PROMPT,  # seven-dimensions.md 참조
)
dimension_output = result.data

자막 기반 폴백 모드

자막 파일({VIDEO_ID}.ko.vtt 또는 {VIDEO_ID}.en.vtt)을 읽어 Claude에게 직접 분석 요청:

자막 전체 텍스트를 제공하고, seven-dimensions.md의 각 차원 프롬프트로 분석.

7개 차원 실행 순서

각 차원 완료 후 $OUTPUT_DIR/dimension-{N}.json에 중간 저장.

Phase 4: 리포트 생성

4-1: 7차원 분석 결과 합성

7개 차원 결과를 구조화 마크다운으로 통합:

# {영상 제목} — 7차원 분석 리포트

> 채널: {channel} | 업로드: {upload_date} | 재생시간: {duration}
> YouTube: {YOUTUBE_URL}
> 분석일: {오늘 날짜}

## 1. 개요 (Overview)
{dimension-1 결과}

## 2. 사용 도구 (Tools)
{dimension-2 결과}

## 3. 단계별 프로세스 (Steps)
{dimension-3 결과}

## 4. 명령어 및 코드 (Commands)
{dimension-4 결과}

## 5. 설정 구성 (Config)
{dimension-5 결과}

## 6. 아키텍처 (Architecture)
{dimension-6 결과}

## 7. 팁 및 주의사항 (Tips)
{dimension-7 결과}

4-2: 스킬 복제 가이드 생성

시청자가 영상의 기술/방법을 직접 재현하기 위한 단계별 가이드:

## 스킬 복제 가이드

### 사전 요구사항
{dimension-2(도구) + dimension-5(설정) 기반 체크리스트}

### 단계별 재현 방법
{dimension-3(단계) + dimension-4(명령어) 기반 실행 가이드}

### 아키텍처 구현 참고
{dimension-6 기반 다이어그램 또는 설명}

### 주의사항 및 팁
{dimension-7 기반}

4-3: 결과 저장

저장 경로: $VIDEO_DIR/{VIDEO_ID}-analysis.md
중간 파일: $VIDEO_DIR/{VIDEO_ID}/dimension-{N}.json (옵션 삭제)

--output <dir> 인수가 있으면 해당 경로에 저장.

완료 후 사용자에게 출력:

분석 완료: {VIDEO_TITLE}
저장 위치: $VIDEO_DIR/{VIDEO_ID}-analysis.md
분석된 차원: {완료된 차원 목록}

예외사항

관련 스킬/에이전트

사용 예시

# 기본 전체 분석
/kdyvideo https://youtube.com/watch?v=dQw4w9WgXcQ

# 특정 차원만 분석 (도구+단계+명령어)
/kdyvideo https://youtube.com/watch?v=dQw4w9WgXcQ --dimensions 2,3,4

# 다운로드 건너뛰기 (기존 다운로드 재사용)
/kdyvideo https://youtube.com/watch?v=dQw4w9WgXcQ --skip-download

# 결과 저장 위치 지정
/kdyvideo https://youtube.com/watch?v=dQw4w9WgXcQ --output /tmp/video-analysis

# 단축 URL 사용
/kdyvideo https://youtu.be/dQw4w9WgXcQ

# 자막 폴백 모드 (TwelveLabs API 키 없이)
# → TWELVE_LABS_API_KEY 환경변수가 없으면 자동으로 자막 모드 선택
/kdyvideo https://youtube.com/watch?v=dQw4w9WgXcQ

주의사항

• TwelveLabs 무료 티어: 600분/월 인덱싱 제한. 장기 사용 시 유료 플랜 검토
• 60분+ 영상은 인덱싱에 5~15분 소요 — 사용자에게 미리 안내
• 한국어 자막이 없는 영상: 영어 자막 기반 분석 후 결과를 한국어로 번역
• yt-dlp는 YouTube 정책 변경에 따라 주기적으로 업데이트 필요: pip install -U yt-dlp
• 저작권이 있는 영상은 개인 연구 목적으로만 사용 (공정 이용 범위 준수)
• TwelveLabs는 비디오 데이터를 서버에 업로드함 — 기밀 영상 업로드 금지