Skip to content

README.md

Latest commit

 

History

History
302 lines (215 loc) · 9.32 KB

README.md

File metadata and controls

302 lines (215 loc) · 9.32 KB
   ____          _         ____
  / ___|__ _ ___| |_ ___  |  _ \  _____      ___ __
 | |   / _` / __| __/ __| | | | |/ _ \ \ /\ / / '_ \
 | |__| (_| \__ \ |_\__ \ | |_| | (_) \ V  V /| | | |
  \____\__,_|___/\__|___/ |____/ \___/ \_/\_/ |_| |_|

      Intelligent Podcast Downloader & Transcriber

A cross-platform CLI tool for downloading and transcribing podcasts. Supports Apple Podcasts, Xiaoyuzhou, and RSS feeds with built-in local speech-to-text powered by Whisper.

Disclaimer

This tool is for EDUCATIONAL and PERSONAL USE ONLY.

By using this software, you agree to: use for personal learning and research only; respect copyright laws and intellectual property; support content creators through official channels; comply with platform terms of service.

Prohibited: commercial redistribution, mass downloading for public sharing, bypassing paid subscriptions, any activity that harms content creators or platforms. The developers fully support and uphold the rights of content creators and platforms.

本工具仅供学习和个人使用。

使用本软件即表示您同意：仅用于个人学习和研究；尊重版权法律和知识产权；通过官方渠道支持内容创作者；遵守平台服务条款。

禁止： 商业性再分发、大规模下载用于公开传播、绕过付费订阅服务、任何损害创作者或平台的行为。开发者拥护并尊重内容创作者和平台的所有权利。

Features

  • Smart URL Detection - Automatically identifies platform from URL, no need to specify downloader
  • Multi-Platform Support
    • Apple Podcasts (single episodes and podcast pages)
    • Xiaoyuzhou / 小宇宙 (single episodes and podcast feeds)
    • Standard RSS 2.0 feeds
  • Async Concurrent Downloads - Configurable concurrency for faster batch downloads
  • Auto Transcription - Downloads are automatically transcribed to text after completion
  • Built-in Speech-to-Text - Local transcription via faster-whisper (CUDA/CPU), with optional mlx-whisper (Metal) for Mac
  • Subtitle Output - Generates SRT (millisecond precision) and timestamped TXT files
  • Progress Display - Real-time download and transcription progress tracking
  • Episode Selection - Download all, latest N, or specific episodes from Apple Podcasts links
  • Smart File Management - Auto-naming, skip existing files, resume-safe temp files

Installation

Install via pip

pip install casts_down

Includes all dependencies — download, transcription, and Whisper model auto-download. Ready to use immediately.

macOS Apple Silicon (Metal acceleration)

pip install "casts_down[metal]"

Adds mlx-whisper for Metal GPU acceleration. Falls back to faster-whisper CPU if unavailable.

Install from GitHub

# Latest release
pip install git+https://github.com/host452b/casts_down.git@v2.2.0

# Latest main branch
pip install git+https://github.com/host452b/casts_down.git

# SSH
pip install git+ssh://git@github.com/host452b/casts_down.git@v2.2.0

Install from source

git clone https://github.com/host452b/casts_down.git
cd casts_down
pip install -e ".[dev]"

Build & Publish

git clone https://github.com/host452b/casts_down.git
cd casts_down

make build          # .pyz standalone executable (<1s)
make dist           # wheel + sdist for PyPI
make publish        # build + upload to PyPI
make publish-test   # build + upload to TestPyPI
make release        # clean + build all (.pyz + wheel + sdist)

See BUILD.md for details.

Quick Start

# Download and transcribe (transcription is automatic)
casts-down "https://podcasts.apple.com/podcast/id123"

# Download all episodes
casts-down "https://feeds.example.com/podcast.rss" --all

# Download without transcription
casts-down "https://feeds.example.com/podcast.rss" --no-transcribe

# Xiaoyuzhou
casts-down "https://www.xiaoyuzhoufm.com/episode/xxx"

# Transcribe existing audio files
casts-down transcribe ./podcasts/episode.mp3
casts-down transcribe ./podcasts/          # entire directory

Usage

Download (+ Auto Transcribe)

casts-down <URL> [OPTIONS]
Option Short Description Default
--all -a Download all episodes latest 1
--latest N -l N Download latest N episodes 1
--output DIR -o DIR Output directory ./podcasts
--concurrent N -c N Parallel downloads 3
--skip-existing -s Skip already downloaded files off
--transcribe/--no-transcribe -t Transcribe after download on
--model NAME -m Whisper model for transcription small

Transcribe

casts-down transcribe <FILE>... [OPTIONS]

Transcribe audio files or directories. Outputs .srt (subtitle) and .txt (timestamped text) alongside each audio file.

Option Short Description Default
--model NAME -m Whisper model (tiny, base, small, medium, large-v3) small
--language CODE Language code (zh, en, etc.) auto-detect
--skip-transcribed Skip files already transcribed on
--overwrite Force re-transcribe existing outputs off

Setup (Optional)

casts-down setup-transcribe

Pre-downloads the Whisper model so the first transcription has zero wait. Also installs mlx-whisper on Mac Apple Silicon for Metal GPU acceleration.

Platform Engine Acceleration
macOS Apple Silicon mlx-whisper + faster-whisper Metal GPU
macOS Intel faster-whisper CPU
Linux + NVIDIA faster-whisper CUDA
Linux (no GPU) faster-whisper CPU

Platform Support

Fully Supported

Apple Podcasts

  • Podcast homepage (download all or latest N episodes)
  • Single episode links (smart matching and download)
  • Automatic RSS extraction via iTunes API

Xiaoyuzhou / 小宇宙

  • Single episode links
  • Podcast links (first 15 episodes)
  • Full podcast list (requires additional reverse engineering)

RSS Feeds

  • Standard RSS 2.0 podcast feeds (most reliable method)

Not Supported

Pocket Casts - Client application, does not host audio files. Use the original podcast RSS feed instead.

Output Example

podcasts/
  My Podcast - Episode 1.mp3
  My Podcast - Episode 1.srt     # SRT subtitle (00:01:23,456 --> 00:01:27,890)
  My Podcast - Episode 1.txt     # [00:01:23] Timestamped plain text

Examples

Download NPR's "Up First" podcast

casts-down "https://feeds.npr.org/510318/podcast.xml" --latest 3

Download from Apple Podcasts

casts-down "https://podcasts.apple.com/us/podcast/the-daily/id1200361736" --all

Download only (no transcription)

casts-down "https://feeds.example.com/podcast.rss" --latest 5 --no-transcribe

Batch download with skip existing

casts-down "https://feeds.example.com/podcast.rss" --all -o ./downloads --skip-existing

Transcribe a directory of audio files

casts-down transcribe ./podcasts/ --model medium --language zh

Technical Stack

Component Technology
Language Python 3.10+
CLI Framework click
HTTP Client aiohttp (async concurrent)
RSS Parsing feedparser
HTML Parsing BeautifulSoup4
Progress Display tqdm
ASR Engine faster-whisper (built-in) / mlx-whisper (optional Metal)

Notes

Important considerations:

  1. RSS Feed Expiration - Some feeds may require authentication or contain expired URLs
  2. Audio URL Validity - Some audio URLs contain time-limited tokens that may expire
  3. Rate Limiting - Frequent requests may trigger platform restrictions
  4. Copyright - Ensure all downloads are for personal use only
  5. Model Download - First transcription auto-downloads the Whisper model (~466 MB for small). Run casts-down setup-transcribe to pre-download.

Troubleshooting

Cannot extract Apple Podcasts RSS

  • Ensure URL format is correct (must contain podcast ID, e.g. /id1234567)
  • Check network connection
  • Try using the RSS feed URL directly if available

Download timeout

  • Reduce concurrency: --concurrent 1
  • Check network connection and proxy settings
  • Some servers may have rate limiting

Transcription fails

  • Try a smaller model: --model base or --model tiny
  • Check available disk space (models are 75MB - 3GB)
  • For Chinese content, specify language: --language zh
  • On Mac Apple Silicon, install Metal support: pip install "casts_down[metal]"

Abnormal file names

  • Tool automatically cleans illegal characters from filenames
  • If issues persist, please submit an Issue

Quick Test

# Test download + transcription
casts-down "https://feeds.npr.org/510318/podcast.xml" --latest 1

# Test download only
casts-down "https://podcasts.apple.com/us/podcast/the-daily/id1200361736" --latest 1 --no-transcribe

# Test standalone transcription
casts-down transcribe ./podcasts/episode.mp3 --model tiny

License

MIT License. Copyright (c) 2024 Casts Down Contributors.

Contributing

Contributions are welcome! Please submit Issues and Pull Requests.

Made with <3 by open source contributors