podcast-downloader

Apple Podcast Downloader (API 增强版)

使用 iTunes API 从 Apple Podcasts 下载播客单集，并以 RSS 作为回退方案。

描述

增强版播客下载器，优先使用 iTunes API，相比传统的 RSS 解析实现更快、更可靠的下载。自动检测地区代码（cn/us/jp），支持多种回退方法，并包含丰富的元数据提取。

使用场景

当用户有以下需求时使用此技能：

• 提供 Apple Podcast URL 并希望下载单集
• 提到"download podcast"、"下载播客"、"get podcast audio"
• 希望将播客单集保存到本地
• 需要播客元数据（标题、日期、时长、描述）

功能特性

• iTunes API 优先：比 RSS 解析快 3-5 倍
• 智能地区检测：自动从 URL 中提取国家代码
• 多种回退方法：
  1. 直接 API 查询（最快）
  2. 列表搜索（快速）
  3. RSS 源解析（可靠的回退方案）
• 丰富的元数据：保存单集信息、发布日期、时长、描述
• User-Agent 支持：解决 403 错误
• 进度显示：实时显示下载进度，包含 MB/百分比

使用方法

基本语法

python scripts/download_podcast.py "APPLE_PODCAST_URL" [-n COUNT] [-o OUTPUT_DIR]

常见场景

下载指定单集（URL 中包含 ?i= 参数）：

python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890?i=1000744375610"

下载最新 N 集：

python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890" -n 5

下载所有可用单集（最多 200 集）：

python scripts/download_podcast.py "https://podcasts.apple.com/us/podcast/id123456789"

指定输出目录：

python scripts/download_podcast.py "URL" -n 10 -o /mnt/user-data/outputs

参数

• url（必填）：Apple Podcast URL
• -n, --count：要下载的最新单集数量（默认：全部可用）
• -o, --output：输出目录（默认：当前目录）

依赖项

pip install requests feedparser --break-system-packages

输出结构

PodcastName/
├── podcast_info.json          # Podcast metadata
├── 001 - Episode Title.m4a    # Audio file
├── 001 - Episode Title.json   # Episode metadata
├── 002 - Episode Title.m4a
└── ...

元数据示例

podcast_info.json：

{
  "podcast_name": "Podcast Name",
  "artist": "Author Name",
  "country": "cn",
  "total_episodes": 272,
  "download_date": "2026-01-13T14:30:00"
}

单集元数据：

{
  "title": "Episode Title",
  "release_date": "2025-01-10",
  "duration_minutes": 40,
  "description": "Episode description...",
  "audio_file": "001 - Episode Title.m4a"
}

Claude 集成

当用户请求下载播客时：

1. 阅读技能文档：

   view("/mnt/skills/user/podcast-downloader-v2/SKILL.md")
   

2. 安装依赖项（如需要）：

   pip install requests feedparser --break-system-packages
   

3. 执行下载：

   python /mnt/skills/user/podcast-downloader-v2/scripts/download_podcast.py \
     "USER_URL" -n COUNT -o /mnt/user-data/outputs
   

4. 向用户展示文件：

   present_files(["/mnt/user-data/outputs/PodcastName/..."])
   

工作原理

工作流

1. URL 解析：提取播客 ID、单集 ID（如存在）、地区代码
2. 数据获取（按优先级顺序）：
   • 方法 A：针对指定单集直接进行 API 查询（最快）
   • 方法 B：获取单集列表并搜索（快速）
   • 方法 C：解析 RSS 源（回退方案）
3. 下载：流式下载音频并显示进度，保存元数据

API 端点

• 查询单集：https://itunes.apple.com/lookup?id={episode_id}&entity=podcastEpisode&country={country}
• 查询列表：https://itunes.apple.com/lookup?id={podcast_id}&entity=podcastEpisode&country={country}&limit=200
• 获取 RSS：https://itunes.apple.com/lookup?id={podcast_id}&country={country}&entity=podcast

局限性

• iTunes API 限制：每次请求最多返回 200 集
• 仅支持 Apple Podcasts（不支持 Spotify、Google Podcasts 等）
• 需要网络连接
• 音频格式取决于播客来源（通常为 .m4a 或 .mp3）

常见问题

Q：找不到较早的单集？
A：iTunes API 最多返回 200 集最新内容。脚本会自动回退到 RSS 以获取较早的内容。

Q：遇到 403 错误？
A：已包含 User-Agent 请求头以防止大多数 403 错误。如果仍然出现，可能是来源限制。

Q：支持哪些地区？
A：支持所有 Apple Podcasts 地区（cn、us、jp、uk 等）。从 URL 自动检测。

对话示例

用户："帮我下载这个播客的最新 3 集: https://podcasts.apple.com/cn/podcast/id1711052890"

Claude：

# View skill
view("/mnt/skills/user/podcast-downloader-v2/SKILL.md")

# Install dependencies
pip install requests feedparser --break-system-packages

# Download
python /mnt/skills/user/podcast-downloader-v2/scripts/download_podcast.py \
  "https://podcasts.apple.com/cn/podcast/id1711052890" \
  -n 3 \
  -o /mnt/user-data/outputs

# Present files
present_files([...])

版本历史

v2.0（当前版本）

• 以 iTunes API 作为主要数据源
• 自动地区检测
• 多种回退方法
• User-Agent 支持以防止 403 错误
• 保存丰富的元数据
• 改进的进度显示

v1.0（原始版本）

• RSS 源解析
• 基本下载功能

参考资料

参见 /references/ 目录：

• usage_guide.md：详细使用说明和示例
• technical_details.md：深入的技术文档
• api_reference.md：iTunes API 文档

许可证

个人使用工具。请遵守 Apple Podcasts 服务条款。仅供个人收听和学习使用。