Back to Details

podcast-downloader

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Apple Podcast Downloader (API Enhanced)

Apple Podcast 下载器（API增强版）

Download podcast episodes from Apple Podcasts using iTunes API with RSS fallback.
借助iTunes API（RSS作为备选方案）从Apple Podcasts下载播客剧集。

Description

功能说明

Enhanced podcast downloader that prioritizes iTunes API for faster, more reliable downloads compared to traditional RSS parsing. Automatically detects region codes (cn/us/jp), supports multiple fallback methods, and includes rich metadata extraction.
这是一款增强型播客下载器，与传统RSS解析相比，它优先使用iTunes API实现更快、更可靠的下载。该工具可自动检测地区代码（cn/us/jp），支持多种备选方案，并能提取丰富的元数据。

When to Use

使用场景

Use this skill when users:
  • Provide Apple Podcast URLs and want to download episodes
  • Mention "download podcast", "下载播客", "get podcast audio"
  • Want to save podcast episodes locally
  • Need podcast metadata (title, date, duration, description)
当用户有以下需求时，可使用本工具：
  • 提供Apple Podcasts链接并想要下载剧集
  • 提及“download podcast”、“下载播客”、“get podcast audio”
  • 想要将播客剧集保存到本地
  • 需要播客元数据（标题、日期、时长、描述）

Features

核心特性

  • iTunes API Priority: 3-5x faster than RSS parsing
  • Smart Region Detection: Auto-extracts country code from URL
  • Multiple Fallback Methods:
    1. Direct API query (fastest)
    2. List search (fast)
    3. RSS feed parsing (reliable fallback)
  • Rich Metadata: Saves episode info, release date, duration, description
  • User-Agent Support: Resolves 403 errors
  • Progress Display: Real-time download progress with MB/percentage
  • iTunes API优先：下载速度比RSS解析快3-5倍
  • 智能地区检测：自动从链接中提取国家代码
  • 多种备选方案：
    1. 直接API查询（最快）
    2. 列表搜索（较快）
    3. RSS源解析（可靠的备选方案）
  • 丰富元数据：保存剧集信息、发布日期、时长、描述
  • User-Agent支持：解决403错误
  • 进度显示：实时显示下载进度（MB/百分比）

Usage

使用方法

Basic Syntax

基本语法

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

Common Scenarios

常见使用场景

Download specific episode (URL with 
?i=
parameter):
bash
python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890?i=1000744375610"
Download latest N episodes:
bash
python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890" -n 5
Download all available episodes (up to 200):
bash
python scripts/download_podcast.py "https://podcasts.apple.com/us/podcast/id123456789"
Specify output directory:
bash
python scripts/download_podcast.py "URL" -n 10 -o /mnt/user-data/outputs
下载指定剧集（链接包含
?i=
参数）：
bash
python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890?i=1000744375610"
下载最新N集：
bash
python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890" -n 5
下载所有可用剧集（最多200集）：
bash
python scripts/download_podcast.py "https://podcasts.apple.com/us/podcast/id123456789"
指定输出目录：
bash
python scripts/download_podcast.py "URL" -n 10 -o /mnt/user-data/outputs

Arguments

参数说明

  • url
    (required): Apple Podcast URL
  • -n, --count
    : Number of latest episodes to download (default: all available)
  • -o, --output
    : Output directory (default: current directory)
  • url
    （必填）：Apple Podcasts 链接
  • -n, --count
    ：要下载的最新剧集数量（默认：所有可用剧集）
  • -o, --output
    ：输出目录（默认：当前目录）

Dependencies

依赖安装

bash
pip install requests feedparser --break-system-packages
bash
pip install requests feedparser --break-system-packages

Output Structure

输出结构

PodcastName/
├── podcast_info.json          # Podcast metadata
├── 001 - Episode Title.m4a    # Audio file
├── 001 - Episode Title.json   # Episode metadata
├── 002 - Episode Title.m4a
└── ...
PodcastName/
├── podcast_info.json          # 播客元数据
├── 001 - Episode Title.m4a    # 音频文件
├── 001 - Episode Title.json   # 剧集元数据
├── 002 - Episode Title.m4a
└── ...

Metadata Examples

元数据示例

podcast_info.json:
json
{
  "podcast_name": "Podcast Name",
  "artist": "Author Name",
  "country": "cn",
  "total_episodes": 272,
  "download_date": "2026-01-13T14:30:00"
}
Episode metadata:
json
{
  "title": "Episode Title",
  "release_date": "2025-01-10",
  "duration_minutes": 40,
  "description": "Episode description...",
  "audio_file": "001 - Episode Title.m4a"
}
podcast_info.json:
json
{
  "podcast_name": "Podcast Name",
  "artist": "Author Name",
  "country": "cn",
  "total_episodes": 272,
  "download_date": "2026-01-13T14:30:00"
}
剧集元数据:
json
{
  "title": "Episode Title",
  "release_date": "2025-01-10",
  "duration_minutes": 40,
  "description": "Episode description...",
  "audio_file": "001 - Episode Title.m4a"
}

Claude Integration

与Claude集成

When user requests podcast download:
  1. Read skill documentation:
    python
    view("/mnt/skills/user/podcast-downloader-v2/SKILL.md")
  2. Install dependencies (if needed):
    bash
    pip install requests feedparser --break-system-packages
  3. Execute download:
    bash
    python /mnt/skills/user/podcast-downloader-v2/scripts/download_podcast.py \
  "USER_URL" -n COUNT -o /mnt/user-data/outputs
  4. Present files to user:
    python
    present_files(["/mnt/user-data/outputs/PodcastName/..."])
当用户请求下载播客时：
  1. 查看技能文档:
    python
    view("/mnt/skills/user/podcast-downloader-v2/SKILL.md")
  2. 安装依赖（如有需要）:
    bash
    pip install requests feedparser --break-system-packages
  3. 执行下载:
    bash
    python /mnt/skills/user/podcast-downloader-v2/scripts/download_podcast.py \
  "USER_URL" -n COUNT -o /mnt/user-data/outputs
  4. 向用户展示文件:
    python
    present_files(["/mnt/user-data/outputs/PodcastName/..."])

How It Works

工作原理

Workflow

工作流程

  1. URL Parsing: Extract podcast ID, episode ID (if present), region code
  2. Data Retrieval (priority order):
    • Method A: Direct API query for specific episode (fastest)
    • Method B: Fetch episode list and search (fast)
    • Method C: Parse RSS feed (fallback)
  3. Download: Stream audio with progress display, save metadata
  1. 链接解析：提取播客ID、剧集ID（如有）、地区代码
  2. 数据获取（优先级顺序）:
    • 方法A：直接API查询指定剧集（最快）
    • 方法B：获取剧集列表并搜索（较快）
    • 方法C：解析RSS源（备选方案）
  3. 下载：流式传输音频并显示进度，保存元数据

API Endpoints

API端点

  • Query episode: 
    https://itunes.apple.com/lookup?id={episode_id}&entity=podcastEpisode&country={country}
  • Query list: 
    https://itunes.apple.com/lookup?id={podcast_id}&entity=podcastEpisode&country={country}&limit=200
  • Get RSS: 
    https://itunes.apple.com/lookup?id={podcast_id}&country={country}&entity=podcast
  • 查询剧集: 
    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

Limitations

限制说明

  • iTunes API limit: 200 episodes maximum per request
  • Only supports Apple Podcasts (not Spotify, Google Podcasts, etc.)
  • Requires internet connection
  • Audio format depends on podcast source (usually .m4a or .mp3)
  • iTunes API限制：每次请求最多返回200集
  • 仅支持Apple Podcasts（不支持Spotify、Google Podcasts等平台）
  • 需要网络连接
  • 音频格式取决于播客来源（通常为.m4a或.mp3）

Common Issues

常见问题

Q: Can't find old episodes?
A: iTunes API returns max 200 recent episodes. Script automatically falls back to RSS for older content.
Q: Getting 403 errors?
A: User-Agent headers are included to prevent most 403 errors. If persists, may be source restriction.
Q: Which regions are supported?
A: All Apple Podcasts regions (cn, us, jp, uk, etc.). Auto-detected from URL.
Q: 找不到旧剧集？
A: iTunes API最多返回200集最新剧集。脚本会自动切换到RSS源获取旧内容。
Q: 出现403错误？
A: 工具已包含User-Agent请求头以避免大部分403错误。如果问题持续，可能是来源方的限制。
Q: 支持哪些地区？
A: 支持所有Apple Podcasts地区（cn、us、jp、uk等），会从链接中自动检测。

Example Conversation

对话示例

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

View skill

查看技能

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

Install dependencies

安装依赖

pip install requests feedparser --break-system-packages
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
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([...])
undefined
present_files([...])
undefined

Version History

版本历史

v2.0 (Current)
  • iTunes API as primary data source
  • Auto region detection
  • Multiple fallback methods
  • User-Agent support for 403 prevention
  • Rich metadata saving
  • Improved progress display
v1.0 (Original)
  • RSS feed parsing
  • Basic download functionality
v2.0（当前版本）
  • 以iTunes API作为主要数据源
  • 自动地区检测
  • 多种备选方案
  • 支持User-Agent以避免403错误
  • 保存丰富元数据
  • 改进进度显示
v1.0（初始版本）
  • RSS源解析
  • 基础下载功能

References

参考资料

See 
/references/
directory for:
  • usage_guide.md
    : Detailed usage instructions and examples
  • technical_details.md
    : In-depth technical documentation
  • api_reference.md
    : iTunes API documentation
查看
/references/
目录获取：
  • usage_guide.md
    : 详细使用说明和示例
  • technical_details.md
    : 深入技术文档
  • api_reference.md
    : iTunes API文档

License

许可证

Personal use tool. Please respect Apple Podcasts terms of service. For personal listening and learning only.
个人使用工具。请遵守Apple Podcasts的服务条款。仅用于个人收听和学习。