Apple Podcast Downloader (API Enhanced)

Description

When to Use

• 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:
  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

Usage

Basic Syntax

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

Common Scenarios

?i=

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

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

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

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_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 Integration

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):
   • 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

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

Example Conversation

# 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

• iTunes API as primary data source
• Auto region detection
• Multiple fallback methods
• User-Agent support for 403 prevention
• Rich metadata saving
• Improved progress display

• RSS feed parsing
• Basic download functionality

References

/references/

• usage_guide.md

  : Detailed usage instructions and examples

• technical_details.md

  : In-depth technical documentation

• api_reference.md

  : iTunes API documentation

License