ingest-youtube — YouTube-투-볼트 연결 도구
YouTube 트랜스크립트를 다운스트림 스킬(지식 그래프 추출, 음성 지문 훈련, 콘텐츠 재사용, 액션 항목 추출)이 활용할 수 있는 typed-memory 항목으로 마크다운 볼트에 가져옵니다.
이는 ingest-slack, ingest-whatsapp, ingest-notion, ingest-linear, ingest-github, ingest-gmail과 동일한 패턴을 따릅니다. YouTube를 추가한다는 것은 새로운 아키텍처가 아닌 새로운 정규화기를 추가한다는 의미입니다.
사용 시기
- 사용자가 YouTube URL을 붙여넣고 트랜스크립트나 요약을 요청할 때
- 사용자가 단일 동영상에 대해
/ingest-youtube <url>이라고 말할 때 - 사용자가 강연/팟캐스트/기조연설을 볼트에 캡처, 동기화, 가져오기, 트랜스크립트하거나 가져오라고 요청할 때
다음의 경우에는 사용하지 마십시오:
- 실제 동영상 파일 다운로드(
-f best옵션으로yt-dlp직접 사용) - 채널 전체 가져오기 또는
--days기간 설정; 이 스크립트는 한 번에 하나의 동영상 URL만 가져옵니다. - 라이브 스트림(트랜스크립트가 안정적이지 않음)
- YouTube가 아닌 소스(Vimeo, Twitch, Twitter Spaces는 각자의 연결 도구 보유)
- 볼트 파일을 원하지 않는 일회성 트랜스크립트 읽기(
--write-auto-sub옵션으로yt-dlp를 직접 실행하고 stdout으로 파이프)
작동 방식
- 입력을 하나의 YouTube 동영상 URL로 파싱합니다.
yt-dlp가 설치되어 있는지 확인합니다. 설치되지 않은 경우, 설치 지침(brew install yt-dlp(macOS) 또는pip3 install --user yt-dlp)과 함께 스크립트가 종료됩니다.- URL이 단일 http(s) YouTube 동영상인지 확인하고
yt-dlp --ignore-config --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에 씁니다. - 트랜스크립트에서 트리거 키워드(decision, framework, model, principle, "the lesson is", playbook, anti-pattern, case study)를 스캔합니다. 각 일치 항목에 대해
Meta/Captures/<YYYY-MM-DD>-youtube-<channel-slug>-<video-id>.md에 writing-seed 스텁을 생성하여 시드가 캡처 수집기에 도달하도록 합니다. - 요약 출력: 파일 경로, 트랜스크립트 단어 수, 언어, 감지된 시드 목록.
호출 방법
python3 ingest.py <youtube-url> [--vault <path>] [--lang <code>]
기본값:
--vault:$VAULT_ROOT환경 변수 또는 현재 디렉토리--lang:en,es(영어 우선, 스페인어 차선; 일반적인 이중 언어 기본값)--whisper: 향후 대체(fallback) 플래그로 수용되지만, 이 버전에서는 자막이 없을 때 스텁을 씁니다.
출력 계약
External Inputs/YouTube/<channel-slug>/<YYYY-MM-DD>-<video-slug>.md의 볼트 파일에는 다음과 같은 머리말(frontmatter)이 포함됩니다:
---
type: external-input
source: youtube
video_id: <11자리 ID>
url: https://www.youtube.com/watch?v=<id>
channel: <채널명>
channel_url: https://www.youtube.com/<handle>
title: <동영상 제목>
upload_date: <YYYY-MM-DD>
duration_seconds: <정수>
language: <ISO 코드>
subtitle_source: manual | auto | whisper
word_count: <정수>
ingested_at: <ISO 8601 타임스탬프>
---
본문은 깔끔한 산문 단락 형태의 트랜스크립트입니다. 소스에 화자 레이블이 있는 경우, 각 턴에 대해 **<화자>:** <텍스트> 형식으로 포맷합니다.
멱등성(idempotency)
동일한 동영상 URL을 다시 가져오면 동일한 볼트 파일을 덮어씁니다. 시드 스텁 파일명은 video_id를 해싱하므로, 동일한 소스 동영상은 재실행 시 동일한 스텁 파일명을 생성합니다. 재실행은 새로고침하며 중복을 만들지 않습니다.
자막 누락
yt-dlp --list-subs가 수동 또는 자동 자막을 반환하지 않는 경우, 스크립트는 조용히 실패하지 않고 동영상 메타데이터와 소스 URL이 포함된 스텁 볼트 노트를 작성합니다. --whisper 플래그는 향후 로컬 트랜스크립션 대체(fallback)를 위해 예약되어 있으며, 현재는 해당 대체가 구현되지 않았다고 보고합니다.
오늘 수동 대체(fallback)를 위해서는 yt-dlp로 오디오를 다운로드하고, 로컬 Whisper 워크플로우로 트랜스크립트한 다음, ingest를 다시 실행하기 전에 캡션이나 트랜스크립트 텍스트를 추가하십시오.
제한 사항
- 실행당 하나의 YouTube 동영상 URL만 가져옵니다. 채널 핸들, 재생 목록 및
--days기간은 범위 밖입니다. yt-dlp가 반환하는 자막에 의존합니다. 자막이 없는 동영상은 트랜스크립트 대신 메타데이터 스텁을 생성합니다.- 이 버전에서는 동영상 파일을 다운로드하거나 내장 Whisper 트랜스크립션을 수행하지 않습니다.
- 네트워크 가용성, YouTube 자막 접근 권한 및 로컬
yt-dlp동작이 가져오기 성공 여부를 결정합니다.
승인 테스트
가장 처음 업로드된 YouTube 동영상에 대해 실행:
python3 ingest.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --vault /tmp/test
예상 출력:
/tmp/test/External Inputs/YouTube/jawed/2005-04-24-me-at-the-zoo.md에 39단어 기록. 언어: en. 자막 소스: manual.
출력 파일에는 유효한 머리말과 깔끔한 산문 본문이 포함됩니다.
의존성
yt-dlp(필수):brew install yt-dlp또는pip3 install --user yt-dlp로 설치whisper-cpp(이 스크립트 외부의 수동 대체(fallback)용 선택 사항)
소스
AI 에이전트 주변의 검증 하네스인 adelaidasofia/ai-brain-starter에 번들로 포함되어 있어 메모리가 손상되지 않고 누적되도록 합니다. 이 스킬은 ingest-* 볼트 연결 도구 제품군의 일부입니다.