Apple Podcast Downloader - Claude Skill

A comprehensive Claude Code skill for searching, browsing, and downloading podcast episodes from Apple Podcasts.

✨ Features

• 🔍 Smart Search - Find podcasts by keyword, author, or topic across Apple Podcasts
• 📋 Episode Browser - Browse episodes with rich metadata (title, date, duration, description)
• 📥 Audio Download - Download episodes as MP3 files with progress tracking
• 🌏 Unicode Support - Full support for Chinese, Japanese, Korean, and other languages
• 📊 Rich Metadata - Access RSS feeds, artwork, ratings, and detailed information
• ⚡ Zero Dependencies - Uses only Python 3 standard library
• 🔐 No Auth Required - Free Apple iTunes API with no authentication needed

🚀 Quick Start

Installation

Method 1: Via Claude Code Plugin (Recommended)

If you’re using Claude Code, you can install this skill as a plugin:

1. Add the plugin marketplace (first time only):

   /plugin marketplace add BurnWang/apple-podcast-downloader
   

2. Install the skill:

   /plugin install podcast-downloader
   

3. That’s it! The skill is now available in all your Claude Code sessions.

Note: Plugins can be toggled on/off as needed using Claude Code’s plugin management. See the Claude Code Plugin Documentation for more details.

Method 2: Manual Installation

1. Clone to your Claude skills directory:

   # For global installation (available in all projects)
   cd ~/.claude/skills/
   git clone https://github.com/BurnWang/apple-podcast-downloader.git
   
   # For project-specific installation
   cd your-project/.claude/skills/
   git clone https://github.com/BurnWang/apple-podcast-downloader.git
   

2. No additional dependencies required - uses only Python 3 standard library.

Basic Usage

Simply ask Claude natural questions:

"Find podcasts about Python programming"
"Download the latest episode of The Daily"
"Show me the 5 most recent Talk Python To Me episodes"
"Search for 绿皮火车 podcast"  (Chinese search works!)

Manual Usage

You can also use the helper script directly:

# Search for podcasts
python3 scripts/itunes_api.py search "keyword" 10

# Get episodes from a podcast
python3 scripts/itunes_api.py episodes 1200361736 5

# Download an episode
python3 scripts/itunes_api.py download 1200361736 0 downloads/

📚 Documentation

• SKILL.md - Main skill definition for Claude
• examples.md - 8 detailed usage examples
• reference.md - Complete API reference

🎯 Use Cases

1. Quick Download

User: “Download the latest episode of Python Bytes” Claude: Searches → Displays episode → Downloads automatically

2. Browse and Choose

User: “Show me recent episodes of The Daily” Claude: Lists 10 latest episodes → User picks → Downloads

3. Batch Operations

User: “Download episodes 1, 3, and 5 from Talk Python” Claude: Fetches list → Downloads selected episodes

4. International Podcasts

User: “搜索绿皮火车播客” Claude: Works seamlessly with Chinese characters!

🛠️ Technical Details

Architecture

apple-podcast-downloader/
├── SKILL.md              # Claude skill definition
├── CLAUDE.md             # Claude Code guidance
├── README.md             # This file
├── examples.md           # Usage examples
├── reference.md          # API documentation
├── LICENSE               # MIT License
├── .claude-plugin/       # Plugin marketplace configuration
│   └── marketplace.json  # Plugin metadata and distribution
└── scripts/
    └── itunes_api.py     # Python helper script

How It Works

1. Search: Uses iTunes Search API to find podcasts
2. Browse: Fetches episode metadata using podcast ID
3. Download: Streams audio files directly from CDN with progress tracking

API Information

• Provider: Apple iTunes Search API
• Authentication: None required
• Rate Limits: ~20 requests/second (unofficial)
• Cost: Free

🔧 Advanced Features

Supported Formats

• Audio: MP3, M4A (auto-downloaded)
• Metadata: JSON output for programmatic access

Error Handling

• Network errors with retry suggestions
• Invalid IDs with helpful messages
• Unicode encoding for international content

Performance

• Streaming downloads for large files
• Progress indicators for downloads >10MB
• Efficient JSON parsing

🤝 Contributing

Contributions are welcome! Here’s how:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built for Claude Code
• Uses Apple iTunes Search API
• Created as a teaching example for NotebookLM tutorial

🎓 Educational Value

This skill is an excellent example for learning:

• Claude Code skill development
• Claude Code plugin distribution
• REST API integration
• File download with progress tracking
• Unicode handling in Python
• Error handling and user experience

Perfect for tutorials and workshops on building Claude skills and plugins!

---

Made with ❤️ by BurnWang