| name | podcast-downloader |
| description | Search and download podcast episodes from Apple Podcasts. Use when user wants to find podcasts, download podcast episodes, get podcast information, or mentions Apple Podcasts, iTunes, podcast search, or audio downloads. |
| allowed-tools | Bash(python3:*), Bash(curl:*), Read, Write |
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
