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:

Read skill documentation:

python

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

Install dependencies (if needed):

bash

pip install requests feedparser --break-system-packages

Execute download:

bash

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

Present files to user:

python

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

当用户请求下载播客时：

查看技能文档:

python

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

安装依赖（如有需要）:

bash

pip install requests feedparser --break-system-packages

执行下载:

bash

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

向用户展示文件:

python

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

How It Works

工作原理

Workflow

工作流程

URL Parsing: Extract podcast ID, episode ID (if present), region code
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)
Download: Stream audio with progress display, save metadata

链接解析：提取播客ID、剧集ID（如有）、地区代码
数据获取（优先级顺序）:
- 方法A：直接API查询指定剧集（最快）
- 方法B：获取剧集列表并搜索（较快）
- 方法C：解析RSS源（备选方案）
下载：流式传输音频并显示进度，保存元数据

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")

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([...])

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的服务条款。仅用于个人收听和学习。