| name | podcast-downloader |
| description | Download podcast episodes from Apple Podcasts using iTunes API with RSS fallback |
Apple Podcast Downloader (API Enhanced)
Download podcast episodes from Apple Podcasts using iTunes API with RSS fallback.
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.
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)
Features
- iTunes API Priority: 3-5x faster than RSS parsing
- Smart Region Detection: Auto-extracts country code from URL
- Multiple Fallback Methods:
- Direct API query (fastest)
- List search (fast)
- 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
Usage
Basic Syntax
python scripts/download_podcast.py "APPLE_PODCAST_URL" [-n COUNT] [-o OUTPUT_DIR]
Common Scenarios
Download specific episode (URL with ?i= parameter):
python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890?i=1000744375610"
Download latest N episodes:
python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890" -n 5
Download all available episodes (up to 200):
python scripts/download_podcast.py "https://podcasts.apple.com/us/podcast/id123456789"
Specify output directory:
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)
Dependencies
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
└── ...
Metadata Examples
podcast_info.json:
{
"podcast_name": "Podcast Name",
"artist": "Author Name",
"country": "cn",
"total_episodes": 272,
"download_date": "2026-01-13T14:30:00"
}
Episode metadata:
{
"title": "Episode Title",
"release_date": "2025-01-10",
"duration_minutes": 40,
"description": "Episode description...",
"audio_file": "001 - Episode Title.m4a"
}
Claude Integration
When user requests podcast download:
-
Read skill documentation:
view("/mnt/skills/user/podcast-downloader-v2/SKILL.md")
-
Install dependencies (if needed):
pip install requests feedparser --break-system-packages
-
Execute download:
python /mnt/skills/user/podcast-downloader-v2/scripts/download_podcast.py \
"USER_URL" -n COUNT -o /mnt/user-data/outputs
-
Present files to user:
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
API Endpoints
- 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
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)
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.
Example Conversation
User: "帮我下载这个播客的最新 3 集: https://podcasts.apple.com/cn/podcast/id1711052890"
Claude:
view("/mnt/skills/user/podcast-downloader-v2/SKILL.md")
pip install requests feedparser --break-system-packages
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([...])
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
References
See /references/ directory for:
usage_guide.md: Detailed usage instructions and examplestechnical_details.md: In-depth technical documentationapi_reference.md: iTunes API documentation
License
Personal use tool. Please respect Apple Podcasts terms of service. For personal listening and learning only.
