Podcast Downloader

2. 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]

3. 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

2. Download using the helper script:

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

3. 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