Apple Podcast Downloader

A comprehensive skill for searching, browsing, and downloading podcast episodes from Apple Podcasts using the iTunes Search API.

Core Capabilities

1. •Search Podcasts - Find podcasts by keyword, author, or topic
2. •Browse Episodes - List episodes from a specific podcast
3. •Download Audio - Download podcast episodes as MP3 files
4. •Get Metadata - Retrieve detailed information about podcasts and episodes

Quick Start

Search for Podcasts

When user asks to search for podcasts:

1. •Use the helper script to search:

python3 .claude/skills/podcast-downloader/scripts/itunes_api.py search "keyword" [limit]

1. •Display results in a clear table format showing:
   • •Podcast name
   • •Author/Publisher
   • •Total episodes
   • •Genres
   • •Collection ID (for downloading episodes)

List Episodes

When user wants to see episodes from a podcast:

1. •Get the collection ID from search results
2. •Fetch episodes:

python3 .claude/skills/podcast-downloader/scripts/itunes_api.py episodes <collection_id> [limit]

1. •Show episode list with:
   • •Episode title
   • •Release date
   • •Duration
   • •Short description
   • •Episode index number (for downloading)

Download Episodes

When user wants to download podcast audio:

1. •Ensure download directory exists:

mkdir -p downloads/podcasts

1. •Download using the helper script:

python3 .claude/skills/podcast-downloader/scripts/itunes_api.py download <collection_id> <episode_index> [output_path]

1. •Confirm download completion with file size and location

Workflow Examples

Example 1: Search and Download Latest Episode

User Request: "Download the latest episode of The Daily podcast"

Steps:

1. •Search for "The Daily"
2. •Get the collection ID from results
3. •Fetch episodes (limit 1)
4. •Download the first episode
5. •Confirm completion

Example 2: Browse and Select

User Request: "Show me the latest 10 episodes of Python Bytes and let me choose which to download"

Steps:

1. •Search for "Python Bytes"
2. •Get collection ID
3. •Fetch 10 latest episodes
4. •Display numbered list
5. •Wait for user selection
6. •Download selected episode(s)

Example 3: Batch Download

User Request: "Download the 5 latest episodes from All-In Podcast"

Steps:

1. •Search for "All-In Podcast"
2. •Get collection ID
3. •Fetch 5 latest episodes
4. •Download each episode sequentially
5. •Report progress and completion

Best Practices

User Experience

1. •Always confirm before downloading - Show episode details and ask for confirmation
2. •Display progress - Show download progress and estimated time
3. •Handle errors gracefully - Provide clear error messages and suggestions
4. •Organize downloads - Create organized directory structure (e.g., downloads/podcasts/podcast-name/)

Error Handling

Common errors and solutions:

• •No results found: Suggest alternative search terms
• •Invalid collection ID: Verify the ID or re-search
• •Download failed: Check network connection, retry with error details
• •File exists: Ask user whether to overwrite or skip

Performance

• •Limit search results: Default to 10 results, max 50
• •Batch downloads: Use sequential downloads to avoid overwhelming the API
• •Cache metadata: Reuse search results within the same conversation

Command Reference

Search Command

python3 scripts/itunes_api.py search <keyword> [limit]

Parameters:

• •keyword: Search term (required)
• •limit: Number of results (optional, default: 10)

Output: JSON array of podcast objects

Episodes Command

python3 scripts/itunes_api.py episodes <collection_id> [limit]

Parameters:

• •collection_id: Podcast ID from search results (required)
• •limit: Number of episodes (optional, default: 10)

Output: JSON array of episode objects

Download Command

python3 scripts/itunes_api.py download <collection_id> <episode_index> [output_path]

Parameters:

• •collection_id: Podcast ID (required)
• •episode_index: Episode number from list (0-based) (required)
• •output_path: Save location (optional, default: downloads/podcasts/)

Output: Downloaded MP3 file path

Data Structures

Podcast Object

{
  "collectionId": 1200361736,
  "collectionName": "The Daily",
  "artistName": "The New York Times",
  "trackCount": 2464,
  "feedUrl": "https://feeds.simplecast.com/...",
  "genres": ["Daily News", "Podcasts", "News"]
}

Episode Object

{
  "trackId": 1000742770142,
  "trackName": "Episode Title",
  "releaseDate": "2025-12-26T10:45:00Z",
  "trackTimeMillis": 1247000,
  "episodeUrl": "https://...",
  "description": "Full description...",
  "shortDescription": "Brief description..."
}

Advanced Features

RSS Feed Access

Podcasts include RSS feed URLs that can be used for:

• •Getting ALL episodes (not limited by API)
• •Subscribing in podcast apps
• •Accessing additional metadata

Access via feedUrl field in search results.

Metadata Extraction

Extract rich metadata including:

• •Artwork (multiple resolutions: 30px, 60px, 100px, 600px)
• •Genres and categories
• •Explicit content ratings
• •Publisher information
• •Episode descriptions

Filtering and Sorting

When displaying results, consider:

• •Sorting by release date (newest first)
• •Filtering by duration
• •Grouping by genre
• •Showing only recent episodes (e.g., last 30 days)

Troubleshooting

Common Issues

Issue: "curl: command not found" Solution: Install curl or use Python's requests library

Issue: "Invalid JSON response" Solution: Check network connection and API availability

Issue: "Permission denied" when saving files Solution: Check directory permissions or use different output path

Issue: "File too large" Solution: Check available disk space, typical episodes are 20-100MB

Additional Resources

• •For detailed API documentation, see reference.md
• •For more usage examples, see examples.md
• •Helper script source: scripts/itunes_api.py

Notes

• •This skill uses the free Apple iTunes Search API (no authentication required)
• •Audio files are downloaded directly from podcast CDNs
• •Supports all podcasts available on Apple Podcasts
• •Download speeds depend on network connection and CDN performance