podcast-helper 0.4.0

Podcast Helper — universal audio stream consumer exposed as library, argparse CLI, click CLI, FastAPI HTTP surface and MCP tools. URL-in → PCM-out for local files, direct audio URLs, RSS feed enclosures, and yt-dlp-supported sources (YouTube, Vimeo, Twitch, SoundCloud, …). Built on youtube-helper + ffmpeg + feedparser + podcastparser; Shannon-correct resampling, mono downmix or native channels preserved.

Podcast Helper

🇫🇷 · 🇬🇧

Podcast Helper belongs to a collection of libraries called AI Helpers developed for building Artificial Intelligence.

The Promise

Local-first by design. podcast-helper runs entirely on your machine — it fetches only the episodes/feeds you ask for and processes them locally; your data is never uploaded to a third-party service, no telemetry, no account, no cloud lock-in. Part of the AI Helpers suite: sovereignty over your data through local-first Open Source.

Universal audio stream consumer for podcasts and any audio-bearing URL. URL-in → PCM-out for local files, direct audio URLs (RSS enclosure MP3 / M4A / Opus / WAV / HLS m3u8), RSS / Atom feed URLs (auto-picks the latest episode), and every yt-dlp-supported source (YouTube, Vimeo, SoundCloud, Twitch VOD / live, …). Refuses Spotify-DRM and Apple Podcasts catalog URLs upfront, with clear hints toward the RSS feed workaround.

🌍 AI Helpers

Documentation

💻 Documentation

📋 Examples

Why it exists

Podcast pipelines (ASR, diarization, summarisation, search indexing) usually start with the same question: "give me a stream of PCM frames from this URL, never mind whether it's a .mp3 link, a feed, a YouTube video, or a podcast hosted on a CDN I've never heard of." This library is that one function — and the small extras around it (feed, latest_episode) that make working with RSS sources friendly.

Installation

Prerequisites — Python 3.10–3.13 and git, ffmpeg, cross-platform:

• 🍎 macOS (Homebrew): brew install python git ffmpeg
• 🐧 Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-pip git ffmpeg
• 🪟 Windows (PowerShell): winget install Python.Python.3.12 Git.Git Gyan.FFmpeg

We recommend using Python environments. Check this link if you're unfamiliar with setting one up: 🥸 Tech tips.

From source

# Core library
pip install "git+https://github.com/warith-harchaoui/podcast-helper.git@v0.4.0"

# Optional surfaces
pip install "podcast-helper[cli] @ git+https://github.com/warith-harchaoui/podcast-helper.git@v0.4.0"
pip install "podcast-helper[api] @ git+https://github.com/warith-harchaoui/podcast-helper.git@v0.4.0"
pip install "podcast-helper[api,mcp] @ git+https://github.com/warith-harchaoui/podcast-helper.git@v0.4.0"

PyPI release coming soon.

This pulls in youtube-helper (and transitively yt-dlp, os-helper, audio-helper, video-helper) plus feedparser + podcastparser for RSS.

Quick start

import asyncio
import podcast_helper as ph

async def main():
    # Pass *any* URL — file, direct mp3, RSS feed, YouTube, SoundCloud, Twitch VOD.
    async for frame in ph.extract_audio_stream(
        "https://feeds.npr.org/510289/podcast.xml",   # ← RSS, auto-pick latest episode
        target_sample_rate=16000,
        to_mono=True,
        frame_ms=20,
    ):
        # frame["pcm"]: np.float32 (320,) for 20ms @ 16kHz
        # frame["t_abs_s"]: 0.0, 0.02, 0.04, ...
        await asr.feed(frame["pcm"])

asyncio.run(main())

For the full catalog of recipes (RSS, yt-dlp sources, live streams, stereo / multichannel, anti-aliasing, downstream ASR / VAD / summarisation pipelines), see 📋 EXAMPLES.md.

What URLs are accepted

Source	Detection	What happens
Local file / file://	path exists on disk OR file:// scheme	ffmpeg opens it directly.
Direct audio URL (.mp3, .m4a, .opus, .wav, .m3u8, …)	URL extension is a known audio container	ffmpeg opens it directly with your headers= if any.
RSS / Atom feed (.xml, .rss, .atom)	URL extension is a known feed container	podcastparser (fallback: feedparser) parses it; latest episode's enclosure is fetched.
YouTube / Vimeo / SoundCloud / Twitch VOD / Twitch live / …	yt-dlp's extractor identifies it	yt-dlp picks bestaudio*, hands the direct URL + headers to ffmpeg.
Generic web URL (anything else)	yt-dlp's generic extractor	URL used as-is.
Spotify (open.spotify.com)	hostname match	NotImplementedError — Spotify audio is DRM-gated. Use the show's RSS feed if it exists.
Apple Podcasts (podcasts.apple.com)	hostname match	NotImplementedError — Apple URLs point to the catalog, not the audio. Use the show's RSS feed (linked on the show's site, or via getrssfeed.com / Podcast Index).

Signal-processing correctness

When target_sample_rate differs from the source rate, the conversion is performed by ffmpeg's libswresample (default) or libsoxr (resample_quality="high"). Both apply an anti-aliasing low-pass filter at the new Nyquist frequency (target_sample_rate / 2) before decimation — satisfying the Shannon-Nyquist sampling theorem. Naïve subsampling is never used.

Channel handling has exactly two modes — no synthetic upmix:

to_mono	Output shape	What ffmpeg does
True (default)	(n_samples,)	Standard downmix (stereo → L+R with -3 dB, 5.1 → ITU mix)
False	(n_samples, n_channels) interleaved	Preserves the source's native channel count

Working with RSS feeds explicitly

If you want to inspect or select episodes yourself:

import podcast_helper as ph

# Full episode list, most-recent first
episodes = ph.feed("https://feeds.npr.org/510289/podcast.xml", max_episodes=20)
for ep in episodes:
    print(ep["published_at"], "—", ep["title"], "—", ep["duration_seconds"], "s")

# Or just the latest one
ep = ph.latest_episode("https://feeds.npr.org/510289/podcast.xml")
print(ep["title"], "→", ep["enclosure_url"])

# Then stream its audio
import asyncio
async def main():
    async for frame in ph.extract_audio_stream(ep["enclosure_url"]):
        ...
asyncio.run(main())

Each Episode dict has a normalised schema regardless of feed flavour:

{guid, title, description, link, published_at (ISO UTC),
 duration_seconds, enclosure_url, enclosure_type, enclosure_size_bytes,
 image_url}

Multi-surface exposure

podcast-helper exposes the same public functions through five interchangeable surfaces — pick the one that fits the caller.

Surface	Entry point	Extra	Best for
Library (async iterator)	import podcast_helper as ph	—	Python code, notebooks, downstream ASR / VAD / summarisation
argparse CLI	podcast-helper	— (stdlib only)	shell scripts, CI, ffmpeg pipelines
click CLI	podcast-helper-click	[cli]	click-native shells (bash / zsh completion, colored help)
FastAPI HTTP	uvicorn podcast_helper.api:app	[api]	HTTP microservices, cross-language callers
MCP server	podcast-helper-mcp	[api,mcp]	Claude Desktop, MCP-aware agents, IDE integrations
Browser GUI	GET /gui (served by the API)	[api]	drop-a-URL episode browser: list · preview · archive, no terminal

Install any combination of extras:

pip install 'podcast-helper[cli]'          # + click twin
pip install 'podcast-helper[api]'          # + FastAPI HTTP surface
pip install 'podcast-helper[api,mcp]'      # + MCP tools on top of FastAPI
pip install 'podcast-helper[cli,api,mcp]'  # everything

Every surface publishes the same verbs — feed, latest, stream, record, probe — with identical argument names, so switching between them is a copy-paste. The Dockerfile in this repo ships the FastAPI + MCP surfaces on port 8000 out of the box (docker build -t podcast-helper . && docker run --rm -p 8000:8000 podcast-helper).

Browser GUI — the episode browser (GET /gui)

With the [api] extra, the FastAPI app serves a self-contained single-page episode browser (Tailwind via CDN + vanilla JS, no build step) that drives the very same endpoints:

pip install 'podcast-helper[api]'
uvicorn podcast_helper.api:app --port 8000
# open http://localhost:8000/gui  (or just http://localhost:8000/)

Paste a feed / RSS / audio / yt-dlp URL → List episodes (calls /feed) → click an episode to see its metadata and play the enclosure inline → Record to file (calls /record) to download a compressed archive. Probe classifies any URL. Nothing is uploaded — playback streams the enclosure straight to your browser and archiving runs ffmpeg on your own machine.

For the exhaustive catalogue of triggers, phrasings, accepted URLs and when not to reach for podcast-helper, see TRIGGERS.md. podcast-helper also ships as an installable Claude / OpenCode skill — see skills/README.md.

For an ambitious visual product on top, see GUI.md. For a competitive comparison against the Python audio / podcast ecosystem, see LANDSCAPE.md.

Live streams

For YouTube / Twitch live URLs, the resolved direct URL is typically an HLS .m3u8 manifest. extract_audio_stream detects this (is_live=True) and automatically disables -re real-time pacing (the source paces itself). The async iterator runs indefinitely until the live stream ends; callers should break when they're done.

speed != 1.0 for live streams raises ValueError (as of v0.2.0) — you can't fast-forward beyond the live edge. Use speed=... on VOD only.

Roadmap

Version	Feature
v0.1.0	extract_audio_stream + feed + latest_episode. yt-dlp + ffmpeg + feedparser + podcastparser.
v0.2.0	record_to="ep.mp3" | ".m4a" | ".opus" | ".ogg" | ".flac" | ".wav" (ffmpeg multi-output: PCM to caller + compressed archive to disk in parallel). speed: float for VOD (raises on live), via atempo= filter (pitch-preserving).
v0.4.0 (this release)	Browser episode-browser GUI at GET /gui; installable Claude / OpenCode skill (skills/podcast-helper/); exhaustive TRIGGERS.md. Additive, backward-compatible.
v0.5.0	start_instant / end_instant for VOD seek. apple_podcasts_to_rss(url) via iTunes Search API. Podcast Index API integration.
v0.6.0+	Chapters (ID3 CTOC/CHAP, Podcasting 2.0 <podcast:chapters>), transcripts, OPML import/export.

Author

• Warith HARCHAOUI

Acknowledgements

Special thanks to Mohamed Chelali and Bachir Zerroug for fruitful discussions.

License

This project is licensed under the BSD-3-Clause License — see the LICENSE file for details.