casts-down 2.1.0

Cross-platform CLI for downloading and transcribing podcasts with local Whisper speech-to-text

   ____          _         ____
  / ___|__ _ ___| |_ ___  |  _ \  _____      ___ __
 | |   / _` / __| __/ __| | | | |/ _ \ \ /\ / / '_ \
 | |__| (_| \__ \ |_\__ \ | |_| | (_) \ 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 source

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

Build & Publish

git clone https://github.com/clemente0731/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