Apple Podcast Downloader
A comprehensive skill for searching, browsing, and downloading podcast episodes from Apple Podcasts using the iTunes Search API.
Core Capabilities
- Search Podcasts - Find podcasts by keyword, author, or topic
- Browse Episodes - List episodes from a specific podcast
- Download Audio - Download podcast episodes as MP3 files
- Get Metadata - Retrieve detailed information about podcasts and episodes
Quick Start
Search for Podcasts
When user asks to search for podcasts:
- Use the helper script to search:
python3 .claude/skills/podcast-downloader/scripts/itunes_api.py search "keyword" [limit]
- 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:
- Get the collection ID from search results
- Fetch episodes:
python3 .claude/skills/podcast-downloader/scripts/itunes_api.py episodes <collection_id> [limit]
- 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:
- Ensure download directory exists:
mkdir -p downloads/podcasts
- Download using the helper script:
python3 .claude/skills/podcast-downloader/scripts/itunes_api.py download <collection_id> <episode_index> [output_path]
- 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:
- Search for "The Daily"
- Get the collection ID from results
- Fetch episodes (limit 1)
- Download the first episode
- 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:
- Search for "Python Bytes"
- Get collection ID
- Fetch 10 latest episodes
- Display numbered list
- Wait for user selection
- Download selected episode(s)
Example 3: Batch Download
User Request: "Download the 5 latest episodes from All-In Podcast"
Steps:
- Search for "All-In Podcast"
- Get collection ID
- Fetch 5 latest episodes
- Download each episode sequentially
- Report progress and completion
Best Practices
User Experience
- Always confirm before downloading - Show episode details and ask for confirmation
- Display progress - Show download progress and estimated time
- Handle errors gracefully - Provide clear error messages and suggestions
- 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
