ObsidianYouTubeSync가 유튜브 시청 기록을 옵시디언에 정리한다

ObsidianYouTubeSync — 유튜브 시청 기록 내려받기, 자막 추출, AI 지식 그래프 구축

ObsidianYouTubeSync 저장소

ObsidianYouTubeSync는 유튜브 시청 기록을 내려받아 동영상 정보와 자막·대본을 추출하고, Google Gemini로 요약과 분류 태그를 생성한 뒤 옵시디언에서 검색할 수 있는 마크다운 노트로 저장하는 도구다. 저장된 자료는 OpenClaw, GraphRAG 등 지식 그래프 파이프라인에 활용할 수 있도록 구조화된다.

동영상 기록이 수백 또는 수천 건인 사용자를 대상으로 한다. 전체 기록을 한꺼번에 동기화하거나 새 동영상만 추가할 수 있으며, 이미 처리한 동영상은 건너뛴다. 제작자는 이 도구를 개인 지식 관리, 시청 기록 정리, 대본 데이터셋 준비, 지식 그래프 구축, 벡터 데이터베이스 검색, LLM 학습 데이터 준비 등에 활용할 수 있다고 소개한다.

주요 기능과 출력 형식

도구는 yt-dlp와 브라우저 쿠키를 이용해 유튜브 시청 기록을 가져온다. 동영상마다 수동 자막과 자동 생성 자막을 포함한 캡션·대본을 추출하고, Google Gemini(GenAI)로 간결한 요약을 만든다. AI 분류는 Technology/ArtificialIntelligence, Science/Neuroscience처럼 계층형 분류 체계를 적용한다.

각 동영상은 태그, URL, 채널, 날짜, 요약을 담은 YAML 메타데이터가 포함된 마크다운 노트가 된다. 기존 노트 폴더에도 같은 분류 체계를 적용할 수 있다. 여러 동영상을 병렬 처리하는 ThreadPoolExecutor 설정을 제공하며, 유튜브 쇼츠는 자동으로 감지해 건너뛴다. AI 에이전트 연동을 위한 Model Context Protocol(MCP) 서버도 제공한다.

노트에는 동영상마다 URL, 채널, 동기화 날짜, 요약, 태그가 들어간다. 본문에는 동영상 제목, 추출 링크, 설명, 원문 대본을 둘 수 있다. 예시의 태그는 기술, 인공지능, LLM, 인지과학 같은 주제와 인물·개념을 계층적으로 나타낸다. 제작자는 인물·회사·지역 태그를 그래프의 노드로, 분류 태그를 개념 간 유형이 지정된 연결로 활용할 수 있다고 설명한다. 요약은 의미 유사도 검색용 임베딩에, 대본은 검색이나 파인튜닝을 위한 텍스트 분할에 사용할 수 있다는 설명이다.

옵시디언에서는 YAML 속성을 기본 인식하며, 계층형 태그를 태그 창의 트리로 표시하고 Dataview로 시청 기록을 조회할 수 있다. 인물·회사·개념 태그가 겹치는 동영상은 그래프 뷰에서 연결해 볼 수 있다.

설치와 설정

필요한 환경은 Python 3.10 이상, Python 패키지 관리 도구 uv, Google Gemini API 키, 유튜브에 로그인한 Chrome·Safari·Firefox다. 옵시디언은 시각화와 Dataview 조회에 권장되지만 필수는 아니다. Gemini API 키는 Google AI Studio에서 무료 등급으로 이용할 수 있다. uv 설치 방법은 설치 안내를 참고한다.

저장소를 내려받고 uv로 환경을 설정한다.

git clone https://github.com/mr8lu/ObsidianYouTubeSync.git
cd ObsidianYouTubeSync

uv sync

예시 환경 파일을 복사한 뒤 .env에 Gemini API 키를 입력한다. 대규모 기록 동기화에는 Webshare 순환 프록시를 선택적으로 설정할 수 있다.

cp .env.example .env

GEMINI_API_KEY=your_gemini_api_key_here

# 선택 사항: 대규모 기록 동기화에 권장하는 Webshare 순환 프록시
WEBSHARE_PROXY_USER=your_proxy_user
WEBSHARE_PROXY_PASS=your_proxy_password

기본 저장 경로는 ~/Documents/Obsidian Vault다. 저장소 안내에 따르면 실제 볼트가 다른 위치에 있다면 동기화를 실행하기 전에 sync.py와 retag_notes.py의 OBSIDIAN_VAULT_PATH를 수정해야 한다.

동기화와 재분류 사용법

전체 동기화는 새 동영상을 내려받고 기록을 갱신하되 기존 동영상은 건너뛴다. 이미 저장된 모든 노트를 최신 분류 체계로 다시 태그하려면 재분류 명령을 실행한다.

./run.sh --sync

./run.sh --retag

임의의 노트 폴더에도 AI 분류를 적용할 수 있다. --dry-run은 파일을 변경하지 않는 미리보기이며, 실제 재분류는 이 옵션 없이 실행한다. --workers로 병렬 처리 작업자 수를 지정할 수 있다.

python3 retag_notes.py --folder "~/Documents/Obsidian Vault/Apple Notes" --dry-run

python3 retag_notes.py --folder "~/Documents/Obsidian Vault/Books"

python3 retag_notes.py --folder "~/Documents/Obsidian Vault/Books" --workers 10

AI 에이전트와 지식 그래프 연동

OpenClaw 연동 방법으로는 SKILL.md 파일을 이용하는 방식을 권장한다. ~/.openclaw/skills/obsidian-youtube-sync/ 폴더를 만들고, ./run.sh와 uv run retag_notes.py 실행 방법을 설명하는 SKILL.md를 넣는다. 저장소 안내에는 작동 예시 템플릿을 요청하면 제공한다고 적혀 있다. 설치 후 OpenClaw에 시청 기록 동기화나 폴더 재분류를 요청할 수 있다. OpenClaw에 관한 자세한 정보는 OpenClaw 사이트에서 확인할 수 있다.

또 다른 방법은 MCP 서버를 Claude Desktop, Cursor 등 MCP 클라이언트에 연결하는 것이다. Claude Desktop을 설정할 때는 claude_desktop_config.json에 다음 내용을 추가하고, 저장소의 실제 경로로 /absolute/path/to/를 바꾼다.

{
 "mcpServers": {
 "ObsidianYouTubeSync": {
 "command": "uv",
 "args": [
 "--directory",
 "/absolute/path/to/ObsidianYouTubeSync",
 "run",
 "mcp_server.py"
 ]
 }
 }
}

MCP에 관한 자세한 내용은 Model Context Protocol을 참고한다. GraphRAG를 이용하려면 먼저 ./run.sh --sync를 실행하고, GraphRAG 파이프라인이 ~/Documents/Obsidian Vault/YouTube/ 폴더를 읽도록 설정한다. 저장소 안내는 YAML 앞부분을 노드 메타데이터로, 대본을 검색용 텍스트로, 태그를 유형이 지정된 연결 구조로 활용하는 방식을 제시한다.

OpenClaw 파이프라인에서는 각 노트가 인물·회사·지역 태그를 포함한 문서 노드가 된다. Technology/ArtificialIntelligence/LLM 같은 계층형 분류는 온톨로지 클래스 트리에 대응하며, 채널 메타데이터는 그래프에서 출처를 나타내는 연결로 활용할 수 있다.

Pinecone, Weaviate, Chroma 같은 벡터 데이터베이스에는 요약을 임베딩하고, 대본은 메타데이터를 고려해 분할하며, 태그는 검색 필터로 쓸 수 있다고 안내한다. LLM 파인튜닝 데이터셋에는 대본과 요약의 쌍으로 지시문·응답 쌍을 만들고, 계층형 태그를 분류 레이블로 활용하는 방식을 제안한다. YAML 앞부분을 읽는 Python 스크립트로 내보낼 수 있다는 설명도 포함됐다.

개발 상태와 호환성

저장소의 로드맵에서 유튜브 시청 기록 동기화, Gemini 요약, 전체 대본·자막 추출, 계층형 AI 태그, 병렬 처리, 볼트 전체 재분류, 프록시·요청 제한 대응, MCP 서버는 완료로 표시돼 있다. GraphRAG 내보내기 보조 스크립트, 옵시디언 커뮤니티 플러그인, Notion·Logseq 내보내기는 계획 중이다. 로컬 LLM(Ollama), 유튜브 재생목록 동기화, OpenClaw 전용 커넥터는 검토 단계로 표시됐다.

개인정보와 보안

저장소 안내는 노트가 사용자 컴퓨터에 저장되며 클라우드 동기화는 하지 않는다고 설명한다. Gemini에는 요약을 위해 동영상 제목·설명·대본 등 공개된 동영상 메타데이터만 전송하며, 유튜브 계정 자격 증명은 접근하거나 저장하지 않는다고 밝힌다. API 키는 Git에 포함되지 않는 .env 파일에서 읽으며 프록시 자격 증명도 로컬에만 보관한다고 안내한다.

macOS에서는 터미널에 시스템 설정의 개인정보 보호 및 보안 항목에서 전체 디스크 접근 권한을 부여해야 한다고 명시돼 있다. 기여 방법은 CONTRIBUTING.md에 안내돼 있으며, 저장소는 MIT 라이선스로 배포된다.