---

name: md-download
description: 下载 Markdown 文件中的音视频和图片附件并本地化嵌入 Obsidian。支持 YouTube 视频、Patreon 视频、SoundCloud 音频、网络图片，可选下载字幕。Download SoundCloud audio, YouTube videos, Patreon videos, and web images from markdown files and embed them locally in Obsidian format. Triggers on "SoundCloud", "soundcloud", "下载音频", "音频下载", "embed audio", "嵌入音频", "本地化音频", "md文件里面的附件下载", "下载视频", "YouTube", "youtu.be", "Patreon", "patreon", "下载图片", "图片下载", "本地化图片", "download images".

---

⚠️ 必须使用脚本执行（节省 Token）

重要：本 skill 自带 Python 脚本，可自动完成下载和替换。禁止手动编辑 md 文件。

执行流程

1. 使用 AskUserQuestion 询问用户偏好（附件类型、字幕、浏览器）
2. 运行脚本命令（见下方）
3. 报告一行摘要结果

脚本命令

重要: --browser chrome 参数现在对 YouTube 和 Patreon 都是必需的，用于绕过 bot 检测。

# 推荐：自动模式 + 静默输出（最省 token）
python3 ~/.claude/skills/md-download/md-download.py batch <目录> --auto --quiet --skip-patreon-refs --browser chrome

# 仅处理指定类型
python3 ~/.claude/skills/md-download/md-download.py batch <目录> --types youtube,image --auto -q --browser chrome

# 预览模式（不实际下载）
python3 ~/.claude/skills/md-download/md-download.py batch <目录> --dry-run

禁止操作

• ❌ 禁止用 Edit 工具修改 md 文件
• ❌ 禁止用 Read 工具读取 md 文件全文
• ❌ 禁止手动构造 sed/awk 替换命令

允许操作

• ✅ 运行 Python 脚本
• ✅ 脚本失败时用 Bash 手动重试单个下载
• ✅ 读取脚本输出

---

以下为参考文档（仅供了解，不要手动执行）

Media Download & Embed Skill for Obsidian

This skill downloads media (audio/video/images) from streaming platforms and web URLs, then embeds them locally in Obsidian markdown files.

---

User Interaction Questions

IMPORTANT: Before starting the download process, use the AskUserQuestion tool to clarify user preferences:

Question 1: Attachment Types

问题：您想下载哪些类型的附件？
选项：
- 全部附件（视频 + 音频 + 图片）
- 仅视频（YouTube、Patreon 等）
- 仅音频（SoundCloud 等）
- 仅图片（网络图片链接）

Question 2: Subtitles (for video)

问题：是否需要下载视频字幕？
选项：
- 是，下载英文字幕
- 是，下载英文和中文字幕
- 否，不需要字幕

Question 3: Scope (for multiple files)

问题：下载范围？
选项：
- 处理目录下所有 MD 文件
- 仅处理指定的文件

Question 4: Patreon Browser (if Patreon links detected)

问题：您在哪个浏览器登录了 Patreon？
选项：
- Chrome
- Safari
- Firefox
- 手动提供 cookies 文件

Example AskUserQuestion Call

{
  "questions": [
    {
      "question": "您想下载哪些类型的附件？",
      "header": "附件类型",
      "options": [
        {"label": "全部附件", "description": "下载视频、音频和图片"},
        {"label": "仅视频", "description": "仅下载 YouTube、Patreon 等视频"},
        {"label": "仅音频", "description": "仅下载 SoundCloud 等音频"},
        {"label": "仅图片", "description": "仅下载网络图片链接"}
      ],
      "multiSelect": false
    },
    {
      "question": "是否需要下载视频字幕？",
      "header": "字幕",
      "options": [
        {"label": "英文字幕", "description": "下载英文自动生成字幕"},
        {"label": "英文+中文", "description": "下载英文和简体中文字幕"},
        {"label": "不需要", "description": "跳过字幕下载"}
      ],
      "multiSelect": false
    },
    {
      "question": "您在哪个浏览器登录了 Patreon？（如有 Patreon 链接）",
      "header": "Patreon",
      "options": [
        {"label": "Chrome", "description": "使用 Chrome 浏览器的 cookies"},
        {"label": "Safari", "description": "使用 Safari 浏览器的 cookies"},
        {"label": "Firefox", "description": "使用 Firefox 浏览器的 cookies"},
        {"label": "无 Patreon 链接", "description": "跳过此问题"}
      ],
      "multiSelect": false
    }
  ]
}

---

Supported Platforms

Platform	Media Type	Subtitles	Auth Required
SoundCloud	Audio (MP3)	N/A	No
YouTube	Video (MP4)	Yes (SRT)	No
Patreon	Video (MP4)	No	Yes (cookies)
Web Images	Image (JPG/PNG/GIF/WebP)	N/A	No

Prerequisites

This skill requires yt-dlp to be installed:

# macOS
brew install yt-dlp

# Linux
pip install yt-dlp

# Windows
winget install yt-dlp

---

Obsidian Attachment Directory Structure

IMPORTANT: Obsidian uses a per-file attachment directory structure. Each markdown file has its own dedicated folder for attachments.

Directory Convention

For a markdown file named Document.md, attachments go in:

assets/Document/

Example Structure

Project-Folder/
├── Part 1.md
├── Part 2.md
├── Part 3.md
└── assets/
    ├── Part 1/
    │   ├── video.mp4
    │   ├── video.en-orig.srt
    │   ├── audio.mp3
    │   └── cover-image.jpg
    ├── Part 2/
    │   ├── video.mp4
    │   ├── video.en-orig.srt
    │   └── diagram.png
    └── Part 3/
        ├── video.mp4
        └── screenshot.png

Embed Syntax

![[assets/Part 1/video.mp4]]
![[assets/Part 1/audio.mp3]]
![[assets/Part 1/cover-image.jpg]]

---

Part 1: SoundCloud Audio

SoundCloud URL Patterns

Format	Example
Standard	https://soundcloud.com/artist/track
Short link	https://on.soundcloud.com/xxxxx
Private/API	https://api.soundcloud.com/tracks/xxxxx

Audio Workflow

Step 1: Identify SoundCloud Links

Scan the markdown file for SoundCloud URLs:
- https://soundcloud.com/
- https://on.soundcloud.com/
- https://api.soundcloud.com/

Step 2: Create Assets Directory

For Document.md, create:

mkdir -p /path/to/assets/Document

Step 3: Download Audio

yt-dlp -x --audio-format mp3 -o "/path/to/assets/Document/filename.mp3" "SOUNDCLOUD_URL"

Step 4: Replace Links

Replace SoundCloud URLs with Obsidian embed syntax:

![[assets/Document/filename.mp3]]

Audio Naming Convention

01-main-theme.mp3
02-variation-theme.mp3
track-name.mp3

Audio Link Replacement Patterns

Pattern 1: Standalone URL after image

Before:

![](https://example.com/image.jpg)
https://soundcloud.com/artist/track

After:

![](https://example.com/image.jpg)

![[assets/Document/01-track-name.mp3]]

Pattern 2: Markdown link format

Before:

Listen to the [final sequence](https://soundcloud.com/artist/track) here.

After:

Listen to the final sequence (![[assets/Document/02-finale.mp3]]) here.

Pattern 3: Plain URL

Before:

https://on.soundcloud.com/xxxxx

After:

![[assets/Document/track-name.mp3]]

---

Part 2: YouTube Video

YouTube URL Patterns

Format	Example
Standard	https://www.youtube.com/watch?v=xxxxx
Short link	https://youtu.be/xxxxx
Embed	https://www.youtube.com/embed/xxxxx

Video Workflow

Step 1: Identify YouTube Links

Scan the markdown file for YouTube URLs:
- https://www.youtube.com/watch?v=
- https://youtu.be/
- https://www.youtube.com/embed/

Step 2: Create Assets Directory

For Part 1.md, create:

mkdir -p "/path/to/assets/Part 1"

Step 3: Download Video

Download as MP4 with best quality:

yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  -o "/path/to/assets/Part 1/video-name.mp4" \
  "YOUTUBE_URL"

Step 4: Download Subtitles

List available subtitles

yt-dlp --list-subs "YOUTUBE_URL"

Download auto-generated subtitles

# English only
yt-dlp --write-auto-sub --sub-lang "en-orig" --sub-format srt \
  --skip-download -o "/path/to/assets/Part 1/video-name" "YOUTUBE_URL"

# Multiple languages
yt-dlp --write-auto-sub --sub-lang "en-orig,zh-Hans" --sub-format srt \
  --skip-download -o "/path/to/assets/Part 1/video-name" "YOUTUBE_URL"

Download manual subtitles (if available)

yt-dlp --write-sub --sub-lang "en" --sub-format srt \
  --skip-download -o "/path/to/assets/Part 1/video-name" "YOUTUBE_URL"

Step 5: Replace Links

Replace YouTube URLs with Obsidian embed syntax:

![[assets/Part 1/video-name.mp4]]

Video Naming Convention

part1-topic-name.mp4
part1-topic-name.en-orig.srt
part1-topic-name.zh-Hans.srt

Subtitle files should have the same base name as the video for auto-detection.

Video Link Replacement Patterns

Pattern 1: Standalone URL

Before:

https://youtu.be/xxxxx
Here is the video content...

After:

![[assets/Part 1/part1-topic.mp4]]
Here is the video content...

Pattern 2: Markdown link format

Before:

Watch the [tutorial video](https://youtu.be/xxxxx) for details.

After:

Watch the tutorial video (![[assets/Part 1/part1-topic.mp4]]) for details.

Subtitle Languages

Common language codes for --sub-lang:

Code	Language
en	English
en-orig	English (Original/Auto)
zh-Hans	Chinese (Simplified)
zh-Hant	Chinese (Traditional)
ja	Japanese
ko	Korean
de	German
fr	French
es	Spanish

---

Part 3: Patreon Video

Authentication Requirement

IMPORTANT: Patreon requires authentication to access content. You must use browser cookies.

Getting Cookies

yt-dlp can read cookies directly from your browser. Make sure you are logged into Patreon in your browser first.

Supported browsers:
- chrome
- firefox
- safari
- edge
- brave

Patreon URL Patterns

Format	Example
Post URL	https://www.patreon.com/posts/99336137
Post with title	https://www.patreon.com/posts/title-slug-99336137

Video Workflow

Step 1: Identify Patreon Links

Scan the markdown file for Patreon URLs:
- https://www.patreon.com/posts/
- https://patreon.com/posts/

Regex pattern:

https?://(www\.)?patreon\.com/posts/[a-zA-Z0-9-]+

Step 2: Create Assets Directory

For Document.md, create:

mkdir -p "/path/to/assets/Document"

Step 3: Download Video with Browser Cookies

# Using Chrome cookies (recommended)
yt-dlp --cookies-from-browser chrome \
  -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  -o "/path/to/assets/Document/video-name.mp4" \
  "https://www.patreon.com/posts/99336137"

# Using Safari cookies
yt-dlp --cookies-from-browser safari \
  -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  -o "/path/to/assets/Document/video-name.mp4" \
  "PATREON_URL"

# Using Firefox cookies
yt-dlp --cookies-from-browser firefox \
  -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  -o "/path/to/assets/Document/video-name.mp4" \
  "PATREON_URL"

Alternative: Using Exported Cookies File

If browser cookies don't work, export cookies manually:

1. Install browser extension "Get cookies.txt LOCALLY"
2. Log into Patreon
3. Export cookies to cookies.txt
4. Use with yt-dlp:

yt-dlp --cookies /path/to/cookies.txt \
  -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  -o "/path/to/assets/Document/video-name.mp4" \
  "PATREON_URL"

Step 4: Replace Links

Replace Patreon URLs with Obsidian embed syntax:

![[assets/Document/video-name.mp4]]

Video Naming Convention

Use descriptive names based on post content:

patreon-topic-name.mp4
orchestration-snippet-part1.mp4
lesson-high-strings.mp4

Patreon Link Replacement Patterns

Pattern 1: Standalone URL

Before:

https://www.patreon.com/posts/99336137
Here is the video content...

After:

![[assets/Document/video-name.mp4]]
Here is the video content...

Pattern 2: Markdown link format

Before:

Watch the [exclusive video](https://www.patreon.com/posts/99336137) for details.

After:

Watch the exclusive video (![[assets/Document/video-name.mp4]]) for details.

Pattern 3: URL with title slug

Before:

https://www.patreon.com/posts/orchestration-snippet-99336137

After:

![[assets/Document/orchestration-snippet.mp4]]

Error Handling

403 Forbidden / Login Required

1. Ensure you are logged into Patreon in your browser
2. Try a different browser: --cookies-from-browser safari
3. Export cookies manually and use --cookies flag
4. Check if you have access to the content (subscription required)

No Video Found

Some Patreon posts may not contain video. Check the post content first.

Rate Limiting

If downloading multiple videos, add delay:

yt-dlp --sleep-interval 5 --cookies-from-browser chrome ...

User Interaction for Patreon

Before downloading Patreon content, ask which browser the user is logged into:

{
  "questions": [
    {
      "question": "您在哪个浏览器登录了 Patreon？",
      "header": "浏览器",
      "options": [
        {"label": "Chrome", "description": "使用 Chrome 浏览器的 cookies"},
        {"label": "Safari", "description": "使用 Safari 浏览器的 cookies"},
        {"label": "Firefox", "description": "使用 Firefox 浏览器的 cookies"},
        {"label": "手动提供 cookies 文件", "description": "使用导出的 cookies.txt 文件"}
      ],
      "multiSelect": false
    }
  ]
}

---

Part 4: Web Images

Image URL Patterns

Format	Example
Direct link	https://example.com/image.jpg
Markdown image	
HTML img tag	<img src="https://example.com/image.gif">
CDN links	https://cdn.xxx.com/path/image.webp

Supported Image Formats

• JPEG/JPG
• PNG
• GIF
• WebP
• SVG
• BMP
• TIFF

Image Workflow

Step 1: Identify Image Links

Scan the markdown file for image URLs:
- Markdown syntax: ![...](URL)
- HTML img tags: <img src="URL">
- Direct URLs ending with image extensions

Regex patterns:

# Markdown images
!\[([^\]]*)\]\((https?://[^)]+\.(jpg|jpeg|png|gif|webp|svg|bmp|tiff)(\?[^)]*)?)\)

# HTML images
<img[^>]+src=["'](https?://[^"']+)["']

# Direct image URLs
https?://[^\s<>"]+\.(jpg|jpeg|png|gif|webp|svg|bmp|tiff)(\?[^\s<>"]*)?

Step 2: Create Assets Directory

For Document.md, create:

mkdir -p /path/to/assets/Document

Step 3: Download Images

Use curl or wget to download images:

# Using curl (recommended)
curl -L -o "/path/to/assets/Document/image-name.jpg" "IMAGE_URL"

# Using wget
wget -O "/path/to/assets/Document/image-name.jpg" "IMAGE_URL"

# With custom User-Agent (for sites that block bots)
curl -L -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -o "/path/to/assets/Document/image-name.jpg" "IMAGE_URL"

Step 4: Handle WebP Conversion (Optional)

Some images may be in WebP format. Obsidian supports WebP, but if conversion is needed:

# Convert WebP to PNG (requires imagemagick)
convert image.webp image.png

# Or use dwebp (requires libwebp)
dwebp image.webp -o image.png

Step 5: Replace Links

Replace image URLs with Obsidian embed syntax:

Markdown image:

# Before
![Description](https://example.com/image.jpg)

# After
![[assets/Document/image.jpg]]

HTML image:

# Before
<img src="https://example.com/image.png" alt="Description">

# After
![[assets/Document/image.png]]

Image Naming Convention

Use descriptive names based on context or original filename:

01-cover-image.jpg
02-diagram-architecture.png
figure-1-workflow.jpg
screenshot-settings.png

Tips for naming:
- Keep original filename if meaningful
- Add numeric prefix for ordering
- Use lowercase and hyphens
- Preserve original extension

Image Link Replacement Patterns

Pattern 1: Markdown image syntax

Before:

![Cover Image](https://cdn.example.com/uploads/cover.jpg)

After:

![[assets/Document/cover.jpg]]

Pattern 2: HTML img tag

Before:

<img src="https://example.com/diagram.png" alt="Architecture">

After:

![[assets/Document/diagram.png]]

Pattern 3: Image with query parameters

Before:

![](https://example.com/photo.jpg?width=800&quality=90)

After:

![[assets/Document/photo.jpg]]

Pattern 4: Multiple images in one line

Before:

![](https://a.com/1.jpg) ![](https://b.com/2.jpg)

After:

![[assets/Document/1.jpg]] ![[assets/Document/2.jpg]]

Handling Special Cases

Base64 Encoded Images

Skip base64 images (they're already embedded):

![](data:image/png;base64,iVBORw0KGgo...)

Relative URLs

Skip relative URLs (they're already local):

![](./images/local.jpg)
![[existing-image.png]]

SVG Images

SVG files can be downloaded directly:

curl -L -o "assets/Document/diagram.svg" "https://example.com/diagram.svg"

Large Images / Rate Limiting

For many images, add delay between downloads:

for url in "${urls[@]}"; do
  curl -L -o "assets/Document/$(basename $url)" "$url"
  sleep 1  # 1 second delay
done

Error Handling

403 Forbidden

Some sites block direct downloads. Try adding headers:

curl -L \
  -H "Referer: https://original-site.com" \
  -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -o "image.jpg" "URL"

404 Not Found

• Check if URL is still valid
• Try Wayback Machine: https://web.archive.org/web/IMAGE_URL
• Skip and leave original link with a comment

Invalid Image

Verify downloaded file is valid:

file image.jpg  # Should show image type, not HTML/text

---

Batch Processing

Processing Multiple MD Files

When processing multiple files in a directory:

1. Create assets folder for each md file
2. Download media to respective folders
3. Update each md file with correct paths

Example: Series of Parts

# For Part 1.md through Part 14.md
for i in {1..14}; do
  mkdir -p "assets/Part $i"
done

# Download video for Part 1
yt-dlp -f "best[ext=mp4]" --merge-output-format mp4 \
  -o "assets/Part 1/part1-video.mp4" "URL1"

# Download subtitles for Part 1
yt-dlp --write-auto-sub --sub-lang "en-orig" --sub-format srt \
  --skip-download -o "assets/Part 1/part1-video" "URL1"

# Repeat for each part...

Parallel Downloads

For faster processing, run downloads in background:

yt-dlp ... "URL1" &
yt-dlp ... "URL2" &
yt-dlp ... "URL3" &
wait

---

Common Operations

Handling Special Characters

Non-Breaking Spaces

Some markdown files contain non-breaking spaces (U+00A0):

# Identify
xxd -c 1 file.md | grep -A2 -B2 "c2 a0"

# Replace
sed -i '' 's/\xc2\xa0/\n\n/g' file.md

Error Handling

Download Failures

1. Check if content is available (not deleted/private)
2. Verify network connectivity
3. Update yt-dlp: brew upgrade yt-dlp or pip install -U yt-dlp

Rate Limiting (HTTP 429)

If you get "Too Many Requests" error:
1. Wait a few minutes before retrying
2. Download one file at a time
3. Use --sleep-interval 5 flag

Link Replacement Failures

1. Check for special characters
2. Verify exact string match including whitespace
3. Use grep -n "pattern" file.md to find exact content

---

Complete Example

Input Files

Part 1.md:

https://youtu.be/abc123
Introduction to the project...

Part 2.md:

Here's the continuation:
https://youtu.be/def456

And some audio:
https://soundcloud.com/artist/track

![Diagram](https://example.com/images/diagram.png)

Part 3.md:

Exclusive Patreon content:
https://www.patreon.com/posts/orchestration-99336137

Processing

# Create directories
mkdir -p "assets/Part 1" "assets/Part 2" "assets/Part 3"

# Download Part 1 video + subtitles
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  -o "assets/Part 1/part1-intro.mp4" "https://youtu.be/abc123"

yt-dlp --write-auto-sub --sub-lang "en-orig" --sub-format srt \
  --skip-download -o "assets/Part 1/part1-intro" "https://youtu.be/abc123"

# Download Part 2 video + subtitles
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  -o "assets/Part 2/part2-continuation.mp4" "https://youtu.be/def456"

yt-dlp --write-auto-sub --sub-lang "en-orig" --sub-format srt \
  --skip-download -o "assets/Part 2/part2-continuation" "https://youtu.be/def456"

# Download Part 2 audio
yt-dlp -x --audio-format mp3 \
  -o "assets/Part 2/audio-track.mp3" \
  "https://soundcloud.com/artist/track"

# Download Part 2 image
curl -L -o "assets/Part 2/diagram.png" \
  "https://example.com/images/diagram.png"

# Download Part 3 Patreon video (requires browser cookies)
yt-dlp --cookies-from-browser chrome \
  -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --merge-output-format mp4 \
  -o "assets/Part 3/orchestration-snippet.mp4" \
  "https://www.patreon.com/posts/orchestration-99336137"

# Update markdown files with Edit tool

Output Files

Part 1.md:

![[assets/Part 1/part1-intro.mp4]]
Introduction to the project...

Part 2.md:

Here's the continuation:
![[assets/Part 2/part2-continuation.mp4]]

And some audio:
![[assets/Part 2/audio-track.mp3]]

![[assets/Part 2/diagram.png]]

Part 3.md:

Exclusive Patreon content:
![[assets/Part 3/orchestration-snippet.mp4]]

Directory Structure:

Project/
├── Part 1.md
├── Part 2.md
├── Part 3.md
└── assets/
    ├── Part 1/
    │   ├── part1-intro.mp4
    │   └── part1-intro.en-orig.srt
    ├── Part 2/
    │   ├── part2-continuation.mp4
    │   ├── part2-continuation.en-orig.srt
    │   ├── audio-track.mp3
    │   └── diagram.png
    └── Part 3/
        └── orchestration-snippet.mp4

---

Tips

1. Preview first: Read markdown to understand link structure
2. Descriptive names: Use meaningful filenames
3. Same base name: Keep video and subtitle filenames matching
4. Verify downloads: Check files are valid before updating markdown
5. Per-file folders: Each md file gets its own assets subfolder
6. Refresh Obsidian: May need refresh to show embedded media
7. Skip local images: Don't download images that are already relative paths or base64
8. Check image validity: Use file command to verify downloaded images aren't error pages
9. Handle duplicates: If same image appears multiple times, download once and reuse

References

• yt-dlp documentation
• Obsidian embed files
• Obsidian audio embeds
• Obsidian video embeds