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 and feeds you ask for and processes them locally. Your data is never uploaded to a third-party service, there is 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 or live, and more). Spotify's DRM-gated catalog and Apple Podcasts catalog URLs are refused upfront, with a clear hint toward the RSS-feed workaround.

🌍 AI Helpers

Documentation

💻 Documentation

🗺️ Landscape

📋 Examples

Why it exists

Podcast pipelines (ASR, diarization, summarization, 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, plus the small extras around it (feed, latest_episode) that make working with RSS sources friendly.

Installation

Prerequisites: Python 3.10-3.13, git, and 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 PyPI (recommended)

# Core library
pip install podcast-helper

# Optional surfaces
pip install "podcast-helper[cli]"
pip install "podcast-helper[api]"
pip install "podcast-helper[mcp]"

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

From source (no PyPI)

git clone https://github.com/warith-harchaoui/podcast-helper.git
cd podcast-helper
pip install -e .

# Optional surfaces
pip install -e ".[cli]"
pip install -e ".[api]"
pip install -e ".[mcp]"

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 / summarization pipelines), see 📋 EXAMPLES.md.

What URLs are accepted

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; there is no synthetic upmix:

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 normalized schema regardless of feed flavor:

{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.

Install any combination of extras:

pip install 'podcast-helper[cli]'          # + click twin
pip install 'podcast-helper[api]'          # + FastAPI HTTP surface
pip install 'podcast-helper[mcp]'          # + MCP tools (needs [api] too, pulled in automatically)
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 surface 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 catalog of triggers, phrasings, accepted URLs and when not to reach for podcast-helper, see TRIGGERS.md.

For an ambitious visual product on top, see GUI.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: you can't fast-forward beyond the live edge. Use speed=... on VOD only.

Not built yet

• start_instant / end_instant for VOD seek.
• apple_podcasts_to_rss(url), resolving an Apple Podcasts catalog URL to its RSS feed via the iTunes Search API.
• Podcast Index API integration.
• Chapters (ID3 CTOC/CHAP, Podcasting 2.0 <podcast:chapters>) and transcripts.
• OPML import/export.

See CHANGELOG.md for what has already shipped.

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.