ingest-youtube — YouTube-볼트 커넥터
YouTube 동영상의 자막을 마크다운 볼트에 질의 가능한 타입드-메모리 엔트리로 가져와, 다운스트림 스킬(지식 그래프 추출, 음성 지문 훈련, 콘텐츠 재사용, 액션 아이템 추출)이 사용할 수 있게 합니다.
ingest-slack, ingest-whatsapp, ingest-notion, ingest-linear, ingest-github, ingest-gmail과 동일한 패턴입니다. YouTube를 추가한다는 것은 새로운 아키텍처가 아니라 새로운 정규화기를 추가한다는 의미입니다.
사용 시기
- 사용자가 YouTube URL을 붙여넣고 자막이나 요약을 요청할 때
- 사용자가 단일 동영상에 대해
/ingest-youtube <url>명령어를 사용할 때 - 사용자가 볼트에 강연/팟캐스트/기조연설을 캡처, 동기화, 수집, 받아쓰기, 또는 가져오기 요청할 때
다음 상황에서는 사용하지 마십시오:
- 실제 동영상 파일 다운로드(
yt-dlp를-f best와 함께 직접 사용) - 채널 전체 수집이나
--days윈도우(이 스크립트는 한 번에 하나의 동영상 URL만 처리) - 라이브 스트리밍(자막이 안정적이지 않음)
- YouTube 외 소스(Vimeo, Twitch, Twitter Spaces는 각각의 커넥터가 있음)
- 볼트 파일을 원하지 않는 일회성 자막 읽기(
yt-dlp --write-auto-sub를 직접 실행하고 stdout으로 파이프)
작동 방식
- 입력을 하나의 YouTube 동영상 URL로 파싱합니다.
yt-dlp가 설치되어 있는지 확인합니다. 설치되지 않은 경우, 스크립트는 설치 지침과 함께 종료됩니다:brew install yt-dlp(macOS) 또는pip3 install --user yt-dlp.yt-dlp --list-subs <url>을 호출하여 사용 가능한 자막을 열거합니다.- 자막 우선순위: 수동 자막 > 자동 생성 캡션. 수동 자막은 크리에이터가 제공한 구두점과 화자 레이블을 유지합니다. 자동 생성 자막은 대문자이고 구두점이 없습니다.
yt-dlp --write-sub --sub-lang <lang> --skip-download를 통해 최고 우선순위 자막을 VTT로 다운로드합니다. 기본 언어 선호도:en,es(영어 우선, 스페인어 차선).- VTT 타임코드를 제거하고 정리된 산문 단락으로 병합합니다. 반복된 줄을 중복 제거합니다(자동 생성 VTT는 줄이 두 배로 나타납니다). 소스에 화자 레이블이 있으면 유지합니다.
yt-dlp --print-json --skip-download를 통해 동영상 메타데이터(제목, 채널, 업로드 날짜, 길이, video_id, URL)를 가져옵니다.- 채널명과 동영상 제목을 슬러그화합니다.
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md에 기록합니다. - 자막에서 트리거 키워드(의사 결정, 프레임워크, 모델, 원칙, "교훈은", 플레이북, 안티-패턴, 사례 연구)를 스캔합니다. 각 일치 항목에 대해
Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.md에 글쓰기 시드 스텁을 생성하여 시드가 캡처 수집기에 들어가도록 합니다. - 요약 출력: 파일 경로, 자막 단어 수, 언어, 감지된 시드.
호출
python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]
기본값:
--vault:$VAULT_ROOT환경 변수 또는 현재 디렉토리--lang:en,es(영어 우선, 스페인어 차선; 일반적인 이중 언어 기본값과 일치)--whisper: 미래 대체 플래그로 허용되지만, 이 버전은 자막이 없을 때 스텁을 기록합니다.
출력 계약
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md에 있는 볼트 파일은 프론트매터를 가집니다:
---
type: external-input
source: youtube
video_id: <11-char ID>
url: https://www.youtube.com/watch?v=<id>
channel: <channel-name>
channel_url: https://www.youtube.com/<handle>
title: <video title>
upload_date: <YYYY-MM-DD>
duration_seconds: <int>
language: <ISO code>
subtitle_source: manual | auto | whisper
word_count: <int>
ingested_at: <ISO 8601 timestamp>
---
본문은 단락 산문으로 정리된 자막입니다. 소스에 화자 레이블이 있으면 턴마다 **<speaker>:** <text> 형식으로 포맷합니다.
멱등성
동일한 동영상 URL을 재처리하면 동일한 볼트 파일을 덮어씁니다. 시드 스텁 파일 이름은 video_id를 해시하므로, 동일한 소스 동영상은 재실행 간에 동일한 스텁 파일 이름을 생성합니다. 재실행은 새로고침하며 중복되지 않습니다.
자막 누락
yt-dlp --list-subs가 수동 또는 자동 자막을 반환하지 않으면, 스크립트는 조용히 실패하는 대신 동영상 메타데이터와 소스 URL이 포함된 스텁 볼트 노트를 기록합니다. --whisper 플래그는 향후 로컬 전사 대체를 위해 예약되어 있으며, 현재는 대체가 구현되지 않았다고 보고합니다.
오늘 수동 대체 방법:
yt-dlp로 오디오를 다운로드하고, 로컬 Whisper 워크플로우로 전사한 다음, 수집을 재실행하기 전에 캡션이나 자막 텍스트를 추가하십시오.
제한 사항
- 실행당 하나의 YouTube 동영상 URL만 처리합니다. 채널 핸들, 재생 목록 및
--days윈도우는 범위를 벗어납니다. yt-dlp가 반환하는 자막에 의존합니다. 자막이 없는 동영상은 자막 대신 메타데이터 스텁을 생성합니다.- 이 버전에서는 동영상 파일을 다운로드하거나 내장 Whisper 전사를 수행하지 않습니다.
- 네트워크 가용성, YouTube 자막 액세스 및 로컬
yt-dlp동작에 따라 수집 성공 여부가 결정됩니다.
승인 테스트
최초로 업로드된 YouTube 동영상에 대해 실행합니다:
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
예상 출력:
Wrote 39 words to /tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md. Language: en. Subtitle source: manual.
출력 파일에는 유효한 프론트매터와 깨끗한 산문 본문이 포함됩니다.
의존성
yt-dlp(필수):brew install yt-dlp또는pip3 install --user yt-dlp로 설치whisper-cpp(이 스크립트 외부 수동 대체용, 선택 사항)
출처
adelaidasofia/ai-brain-starter에 번들로 포함되어 있으며, AI 에이전트 주변의 검증 하네스로 메모리가 손상되지 않고 축적되도록 합니다. 이 스킬은 ingest-* 계열 볼트 커넥터의 일부입니다.