podcast-downloader

Apple Podcast ダウンローダー (API 強化版)

iTunes API を使用し、RSS をフォールバックとして Apple Podcasts からポッドキャストのエピソードをダウンロードします。

説明

従来の RSS パースと比較して、より高速で信頼性の高いダウンロードのために iTunes API を優先する強化版ポッドキャストダウンローダーです。リージョンコード (cn/us/jp) を自動検出し、複数のフォールバック方法をサポートし、豊富なメタデータ抽出を含みます。

使用する場面

以下のようなユーザーにこのスキルを使用します:

• Apple Podcast の URL を提示してエピソードをダウンロードしたい場合
• 「download podcast」「下载播客」「get podcast audio」と言及した場合
• ポッドキャストのエピソードをローカルに保存したい場合
• ポッドキャストのメタデータ (タイトル、日付、再生時間、説明) が必要な場合

機能

• iTunes API 優先: RSS パースより 3〜5 倍高速
• スマートリージョン検出: URL から国コードを自動抽出
• 複数のフォールバック方法:
  1. 直接 API クエリ (最速)
  2. リスト検索 (高速)
  3. RSS フィードのパース (信頼性の高いフォールバック)
• 豊富なメタデータ: エピソード情報、リリース日、再生時間、説明を保存
• User-Agent サポート: 403 エラーを解決
• 進捗表示: MB/パーセンテージ付きのリアルタイムダウンロード進捗

使用方法

基本構文

python scripts/download_podcast.py "APPLE_PODCAST_URL" [-n COUNT] [-o OUTPUT_DIR]

一般的なシナリオ

特定のエピソードをダウンロード (?i= パラメータ付きの URL):

python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890?i=1000744375610"

最新の N エピソードをダウンロード:

python scripts/download_podcast.py "https://podcasts.apple.com/cn/podcast/id1711052890" -n 5

利用可能なすべてのエピソードをダウンロード (最大 200):

python scripts/download_podcast.py "https://podcasts.apple.com/us/podcast/id123456789"

出力ディレクトリを指定:

python scripts/download_podcast.py "URL" -n 10 -o /mnt/user-data/outputs

引数

• url (必須): Apple Podcast の URL
• -n, --count: ダウンロードする最新エピソード数 (デフォルト: 利用可能なすべて)
• -o, --output: 出力ディレクトリ (デフォルト: カレントディレクトリ)

依存関係

pip install requests feedparser --break-system-packages

出力構造

PodcastName/
├── podcast_info.json          # Podcast metadata
├── 001 - Episode Title.m4a    # Audio file
├── 001 - Episode Title.json   # Episode metadata
├── 002 - Episode Title.m4a
└── ...

メタデータの例

podcast_info.json:

{
  "podcast_name": "Podcast Name",
  "artist": "Author Name",
  "country": "cn",
  "total_episodes": 272,
  "download_date": "2026-01-13T14:30:00"
}

エピソードのメタデータ:

{
  "title": "Episode Title",
  "release_date": "2025-01-10",
  "duration_minutes": 40,
  "description": "Episode description...",
  "audio_file": "001 - Episode Title.m4a"
}

Claude との統合

ユーザーがポッドキャストのダウンロードを要求した場合:

1. スキルのドキュメントを読む:

   view("/mnt/skills/user/podcast-downloader-v2/SKILL.md")
   

2. 依存関係をインストール (必要な場合):

   pip install requests feedparser --break-system-packages
   

3. ダウンロードを実行:

   python /mnt/skills/user/podcast-downloader-v2/scripts/download_podcast.py \
     "USER_URL" -n COUNT -o /mnt/user-data/outputs
   

4. ユーザーにファイルを提示:

   present_files(["/mnt/user-data/outputs/PodcastName/..."])
   

仕組み

ワークフロー

1. URL のパース: ポッドキャスト ID、エピソード ID (存在する場合)、リージョンコードを抽出
2. データの取得 (優先順位):
   • 方法 A: 特定のエピソードに対する直接 API クエリ (最速)
   • 方法 B: エピソードリストを取得して検索 (高速)
   • 方法 C: RSS フィードをパース (フォールバック)
3. ダウンロード: 進捗表示付きで音声をストリーミングし、メタデータを保存

API エンドポイント

• エピソードのクエリ: https://itunes.apple.com/lookup?id={episode_id}&entity=podcastEpisode&country={country}
• リストのクエリ: https://itunes.apple.com/lookup?id={podcast_id}&entity=podcastEpisode&country={country}&limit=200
• RSS の取得: https://itunes.apple.com/lookup?id={podcast_id}&country={country}&entity=podcast

制限事項

• iTunes API の制限: 1 リクエストあたり最大 200 エピソード
• Apple Podcasts のみをサポート (Spotify、Google Podcasts などは対象外)
• インターネット接続が必要
• 音声フォーマットはポッドキャストのソースに依存 (通常は .m4a または .mp3)

よくある問題

Q: 古いエピソードが見つかりませんか?
A: iTunes API は最新の 200 エピソードまでしか返しません。スクリプトは古いコンテンツに対して自動的に RSS にフォールバックします。

Q: 403 エラーが発生しますか?
A: ほとんどの 403 エラーを防ぐために User-Agent ヘッダーが含まれています。それでも続く場合は、ソース側の制限の可能性があります。

Q: どのリージョンがサポートされていますか?
A: すべての Apple Podcasts のリージョン (cn、us、jp、uk など) です。URL から自動検出されます。

会話例

ユーザー: 「帮我下载这个播客的最新 3 集: https://podcasts.apple.com/cn/podcast/id1711052890」

Claude:

# View skill
view("/mnt/skills/user/podcast-downloader-v2/SKILL.md")

# Install dependencies
pip install requests feedparser --break-system-packages

# Download
python /mnt/skills/user/podcast-downloader-v2/scripts/download_podcast.py \
  "https://podcasts.apple.com/cn/podcast/id1711052890" \
  -n 3 \
  -o /mnt/user-data/outputs

# Present files
present_files([...])

バージョン履歴

v2.0 (最新)

• iTunes API を主要なデータソースとして採用
• リージョンの自動検出
• 複数のフォールバック方法
• 403 防止のための User-Agent サポート
• 豊富なメタデータの保存
• 進捗表示の改善

v1.0 (オリジナル)

• RSS フィードのパース
• 基本的なダウンロード機能

参考資料

/references/ ディレクトリを参照してください:

• usage_guide.md: 詳細な使用手順と例
• technical_details.md: 詳細な技術ドキュメント
• api_reference.md: iTunes API のドキュメント

ライセンス

個人利用ツールです。Apple Podcasts の利用規約を尊重してください。個人での視聴および学習のみを目的としています。