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:

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/..."])

How It Works

Workflow

1. URL Parsing: Extract podcast ID, episode ID (if present), region code
2. Data Retrieval (priority order):
3. Method A: Direct API query for specific episode (fastest)
4. Method B: Fetch episode list and search (fast)
5. Method C: Parse RSS feed (fallback)
6. 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 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([...])

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 examples
- technical_details.md: In-depth technical documentation
- api_reference.md: iTunes API documentation

License

Personal use tool. Please respect Apple Podcasts terms of service. For personal listening and learning only.