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

podcast-downloader

Apple Podcast Downloader

Core Capabilities

Quick Start

Search for Podcasts