youtube-fetcher-to-markdown - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #golang #go #android #linux #macos #cli #vue

youtube-fetcher-to-markdown

(★ 198)

Claude Code skill: turn YouTube videos into structured, Obsidian-ready Markdown notes with full metadata, chapters, and transcripts

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - sync-legacy-master.yml
- verify-isolated-install.sh
- openai.yaml
- banner.png
- fetch_transcript.py
- youtube-fetcher-v1-1-release-and-distribution.html
- test_fetch_transcript.py
- test_skill_bundle.py
.gitignore
LICENSE
README.md
requirements.txt
SKILL.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/JimmySadek/youtube-fetcher-to-markdown

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd youtube-fetcher-to-markdown

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Homebrew macOS/Linux용 패키지 매니저입니다.

brew install yt-dlp # macOS

Homebrew로 이미 빌드된 패키지를 바로 설치합니다. 소스 빌드가 필요 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Python

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Python 3 설치 시 'Add Python to PATH' 옵션을 꼭 체크하세요 (Windows).

python3 -m pip install -r requirements.txt

requirements.txt 등에 명시된 파이썬 라이브러리를 설치합니다.

✅ 에러 메시지 없이 실행되고 터미널에 안내 문구가 출력되면 정상입니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# YouTube Fetcher to Markdown

<p align="center">
  <img src="assets/banner.png" alt="YouTube Fetcher to Markdown — archival note skill" width="100%">
</p>

YouTube video in, structured archival Markdown note out. Capture the transcript,
creator metadata, description, chapters, actual caption language, and provenance
in one Obsidian-ready file—without an API key.

```bash
npx skills add JimmySadek/youtube-fetcher-to-markdown
```

## What you get

Paste a YouTube link and receive a file such as:

```text
~/yt_transcripts/2026-03-04_obsidian-the-king-of-learning-tools_[hSTy_BInQs8].md
```

```markdown
---
title: "Obsidian: The King of Learning Tools (FULL GUIDE + SETUP)"
channel: "Odysseas"
url: "https://www.youtube.com/watch?v=hSTy_BInQs8"
video_id: "hSTy_BInQs8"
fetched: "2026-03-04"
source_project: "my-project"
language: "en"
caption_type: "manual"
duration: "36m 26s"
upload_date: "2024-04-24"
tags:
  - yt-transcript
---

# Obsidian: The King of Learning Tools (FULL GUIDE + SETUP)

## Video Details
| Field    | Value |
|----------|-------|
| URL      | https://www.youtube.com/watch?v=hSTy_BInQs8 |
| Channel  | Odysseas |
| Duration | 36m 26s |
| Uploaded | 2024-04-24 |
| Fetched  | 2026-03-04 |
| Source   | my-project |
| Language | en (manual) |

## Video Description
The creator's description, links, and chapter markers...

## Transcript
The complete caption text...
```

The YAML frontmatter makes a collection queryable through tools such as
[Dataview](https://github.com/blacksmithgu/obsidian-dataview), while the Markdown
remains portable to Logseq, other knowledge bases, and plain text workflows.

## Why this exists

Most transcript extractors stop at raw caption text. An archival knowledge note
also needs the source URL, creator, capture date, actual language, description,
chapters, and a predictable filename. YouTube Fetcher keeps that complete record
in one local file.

## Features

- Manual and auto-generated captions with optional timestamps
- Truthful language fallback: the note records the selected caption language
- Title, channel, duration, upload date, description, and chapters when available
- Safe YAML frontmatter and Markdown tables for dynamic metadata
- Duplicate detection that preserves existing notes unless overwrite is approved
- Obsidian-vault and custom-directory output
- Raw JSON and SRT export
- No API keys and no hosted service

## Installation

### Install the skill

```bash
npx skills add JimmySadek/youtube-fetcher-to-markdown
```

Or clone the canonical repository:

```bash
git clone https://github.com/JimmySadek/youtube-fetcher-to-markdown.git
```

### Install runtime dependencies

Python 3.8 or newer is supported.

```bash
python3 -m pip install -r requirements.txt
```

`yt-dlp` is optional but recommended for descriptions, chapters, duration, and
upload dates:

```bash
brew install yt-dlp              # macOS
# or: python3 -m pip install yt-dlp
```

Check dependencies without fetching a video:

```bash
python3 scripts/fetch_transcript.py --check-deps
```

The script reports missing packages but never installs them automatically.

## Usage

```bash
python3 scripts/fetch_transcript.py "https://youtu.be/VIDEO_ID"
```

An agent using the skill resolves `scripts/fetch_transcript.py` relative to its
installed `SKILL.md`; it does not depend on one fixed home-directory path.

### Output location

The first configured option wins:

1. `--output` for one exact file
2. `--output-dir` for this run
3. `YOUTUBE_FETCHER_DIR` for a persistent directory
4. `~/yt_transcripts/` by default

```bash
# Save this note to an Obsidian vault
python3 scripts/fetch_transcript.py URL --output-dir ~/Notes/MyVault

# Set a persistent default
export YOUTUBE_FETCHER_DIR=~/Notes/MyVault
python3 scripts/fetch_transcript.py URL

# Save to one exact file
python3 scripts/fetch_transcript.py URL --output ~/Notes/video.md
```

Duplicate detection uses the resolved output directory. In a non-interactive
session, an existing note exits with code `3` and remains untouched. Run again
with `--force` only after deciding to overwrite.

### Options

| Flag | What it does |
|------|-------------|
| `--output` / `-o` | Save to one exact file |
| `--output-dir` | Save inside a directory or knowledge vault |
| `--timestamps` / `-t` | Add timestamps to transcript lines |
| `--lang` / `-l` | Request a caption language; falls back truthfully to English |
| `--source` / `-s` | Override the capture-project name |
| `--format` / `-f` | Export `json` or `srt` instead of Markdown |
| `--no-description` | Skip the description and chapters section |
| `--stdout` | Print the result instead of saving it |
| `--list` | Show available caption languages |
| `--force` | Bypass duplicate protection |
| `--check-deps` | Report dependency status |

### Supported YouTube inputs

- Standard watch URLs, regardless of query-parameter order
- `youtu.be` short links
- `/embed/`, `/shorts/`, `/live/`, and legacy `/v/` links
- Mobile and YouTube Music watch URLs
- Privacy-enhanced `youtube-nocookie.com/embed/` links
- A raw 11-character video ID

Lookalike hosts such as `youtube.com.example.org` are rejected.

## Compatibility

The repository follows the portable `SKILL.md` format. The same install command
works with Codex, Claude Code, Cursor, Windsurf, Gemini CLI, and other compatible
agents. Manual users can run the Python script directly.

## Capabilities and limitations

- **Network:** contacts YouTube captions and oEmbed; optionally invokes `yt-dlp`
  for richer metadata.
- **Filesystem:** reads Markdown frontmatter in the selected directory to detect
  duplicates and writes only the requested Markdown, JSON, or SRT output.
- **Subprocess:** uses the locally installed `yt-dlp` executable when available.
- Videos must expose captions. Private, restricted, or caption-disabled videos
  may fail.
- It does not download video, run Whisper, identify speakers, or translate text.

<details>
<summary>Exit codes</summary>

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Invalid input or fetch failure |
| `2` | Missing required dependency |
| `3` | Existing note preserved; overwrite not approved |

</details>

## License

MIT