rss2podcast

Turn an RSS feed into a listenable podcast. Fetches each entry, extracts the article body, sends it to gopipertts for Piper TTS synthesis, and publishes the resulting MP3s as a standards-compliant podcast RSS feed.

How it works

1. Parse the source RSS feed.
2. For each entry not yet processed (tracked in state.json):
   • Fetch the linked article and extract the body with trafilatura (falls back to RSS summary).
   • Strip HTML to plain speakable text.
   • POST to gopipertts /api/tts, save the MP3 to disk.
   • Append the entry to state.json immediately (crash-safe).
3. Rewrite feed.xml from the full state with feedgen (iTunes namespace).
4. Write style.xsl to the output root so browsers render feeds as a readable HTML page.

Install

uv sync

Or install as a tool:

uv tool install .

Usage

Single feed (CLI)

EFF Updates (equivalent to the config.sample.yaml entry):

uv run rss2podcast --feed-url https://www.eff.org/rss/updates.xml --feed-name "EFF Updates" --output-dir podcasts --url-root https://podcasts.example.com --tts-endpoint http://localhost:8080/ --voice en_US-amy-medium --description "EFF updates, narrated by Piper TTS" --author EFF --limit 5

Ars Technica:

uv run rss2podcast --feed-url https://feeds.arstechnica.com/arstechnica/index --feed-name "Ars Technica" --output-dir podcasts --url-root https://podcasts.example.com --tts-endpoint http://localhost:8080/ --voice en_US-amy-medium --description "Ars Technica articles, narrated by Piper TTS" --author "Ars Technica" --limit 1 --prune-xpath '//div[contains(@class,"author-bio")]' --merge-xpath '//div[contains(@class,"post-content")]'

Hackaday:

uv run rss2podcast --feed-url https://hackaday.com/blog/feed/ --feed-name Hackaday --output-dir podcasts --url-root https://podcasts.example.com --tts-endpoint http://localhost:8080/ --voice en_US-amy-medium --description "Hackaday articles, narrated by Piper TTS" --author Hackaday --prune-xpath '//div[contains(@class,"author-bio")]' --prune-xpath '//section[contains(@class,"related")]'

Multi-feed (YAML)

uv run rss2podcast --config config.yaml

See config.sample.yaml for a fully annotated example.

Output layout

{output_dir}/
  style.xsl
  {feed-slug}/
    state.json
    feed.xml
    2026-04-16-some-post-title-abc12345.mp3
    ...

Serve {output_dir} over HTTP at {url_root} and subscribe to {url_root}/{feed-slug}/feed.xml in a podcast app. When style_rss_feed is enabled (the default), opening feed.xml directly in a browser renders it as a human-readable HTML page with an inline audio player.

Scheduling

Designed to run as a cron / scheduled job. Re-runs are idempotent — entries already in state.json are skipped. Long runs are fine (no time limits, state is committed after each entry).

CLI reference

Feed selection

TTS

Feed metadata

Processing

Extraction tuning

These control how trafilatura extracts article text from fetched pages. Defaults are tuned for broad recall; tighten them for noisy feeds.

--prune-xpath examples:

# Remove Ars Technica author bio
--prune-xpath '//div[contains(@class,"author-bio")]'

# Remove multiple sections
--prune-xpath '//aside' --prune-xpath '//div[@id="related"]'

--merge-xpath example:

# Ars Technica splits the article body across multiple <div class="post-content">
# siblings separated by ad wrappers; merging them avoids mid-article truncation.
--merge-xpath '//div[contains(@class,"post-content")]'

YAML config reference

Top-level keys:

output_dir: /var/www/podcasts        # required
url_root: https://podcasts.example.com  # required
tts_endpoint: http://gopipertts:8080 # default: http://localhost:8080
limit: 5                             # optional: process only N newest per feed
save_text: false                     # optional: persist text in state.json
no_fetch: false                      # optional: skip external crawling globally
style_rss_feed: true                 # default: true; set to false to disable XSLT browser rendering
show_github_ribbon: true             # default: true; set to false to hide the "Fork me on GitHub" ribbon

Per-feed keys:

feeds:
  - name: My Feed        # required
    url: https://...     # required

    # TTS
    voice: en_US-amy-medium   # default: en_US-amy-medium

    # Feed metadata
    description: "..."
    author: "..."
    image_url: "https://..."

    # Processing (override top-level defaults)
    limit: 5             # optional: overrides top-level limit for this feed

    # Extraction tuning
    favor_recall: true         # default: true
    favor_precision: false     # default: false
    include_comments: false    # default: false
    include_tables: false      # default: false
    deduplicate: false         # default: false
    fast_extraction: false     # default: false
    prune_xpath:               # default: null
      - '//div[contains(@class,"author-bio")]'
      - '//section[@id="related"]'
    merge_xpath:               # default: null
      - '//div[contains(@class,"post-content")]'

favor_recall and favor_precision are independent trafilatura flags. Setting both to true is valid; trafilatura will apply both biases simultaneously.

Tests

uv sync --extra test
uv run pytest