RSS & Atom Audio Feeds
Subscribe to RSS 2.0 or Atom audio feeds with stable chapter identity and conservative history-preserving synchronization.
When to use an RSS library
An RSS library turns a remote podcast, serialized audiobook, or other audio feed into one playable book. The server stores book and chapter metadata only. Audio is read from the remote URL during playback, so the full feed does not need to be downloaded to the server first.
One RSS library maps to one book. Valid audio entries become chapters, with title, author, narrator, cover, description, publication time, and duration imported when the feed provides them.
Supported formats and metadata
Leelaa Reader currently supports:
- RSS 2.0 standard channel, item, GUID, and enclosure fields
- iTunes Podcast author, owner, artwork, summary, and duration fields
- Media RSS audio content, artwork, and title fields, including custom namespace prefixes
- Dublin Core creator and publication metadata
- Podcast 2.0 person metadata for authors, hosts, and narrators
- Atom feed metadata and
rel="enclosure"audio links
JSON Feed, OPML import, feed auto-discovery from web pages, and private feeds that require a signed-in Cookie session are not supported yet.
How audio chapters are selected
The server looks for audio in this order:
- RSS
<enclosure>; - Media RSS audio
<media:content>; - Atom
<link rel="enclosure">; - A direct URL with a recognized audio extension such as
.mp3,.m4a,.m4b,.aac,.flac,.wav,.wma,.ogg, or.opus.
Episode web pages, article links, images, and videos are not treated as audio. If a feed can be parsed but contains no supported audio entries, connection testing reports that condition instead of accepting an empty library.
Relative audio and artwork URLs are resolved against the final feed URL. Remote feed resources must use HTTP or HTTPS.
Stable chapters and sync behavior
The server uses an RSS guid or Atom entry id whenever possible. When that source ID remains unchanged, a new CDN URL, temporary token, title, duration, or feed position updates the existing chapter without changing its backend chapter ID or losing its progress association.
Chapters created by older releases do not have a source item ID. The first sync after upgrading claims them by their existing audio URL and adds the stable ID instead of rebuilding every chapter.
Many podcast feeds expose only their latest episodes, so synchronization is intentionally conservative:
- entries present in the current feed are updated in the feed's current order;
- existing chapters missing from the current response are retained and appended in their previous relative order;
- parse failures and feeds with no valid audio do not clear the existing book;
- duplicate source IDs or audio URLs create only one chapter.
As a result, removing an episode upstream does not automatically delete a chapter already synchronized into Leelaa Reader. The current release does not provide per-episode RSS deletion or a strict upstream-mirror deletion mode.
Add and schedule a feed
- Sign in as an administrator and open Profile -> Library Management.
- Select Add Library, then choose RSS.
- Enter a name and an HTTP or HTTPS feed URL.
- Save the library. The server validates the document and requires at least one supported audio entry.
- Trigger synchronization from the library list, or enable scheduled automatic sync.
A feed URL does not need to end in .xml or /feed; it only needs to return a supported RSS or Atom document. A limited number of HTTP redirects is supported.
Private feeds and tokens
RSS mode does not currently provide separate username, password, or Cookie fields. You can use a full private-feed URL containing a provider-issued token, but treat it as a password:
- do not post the complete URL in public issues, screenshots, or logs;
- replace the URL when its token expires;
- feeds requiring an interactive login or Cookie session are not supported.
If episode audio URLs use short-lived tokens, a stable GUID or Atom entry ID lets later syncs refresh the URL without replacing the chapter ID.
Troubleshooting
"RSS read failed"
- Open the URL and confirm it returns an XML feed rather than a login, challenge, or normal HTML page.
- Confirm the server or Docker container can resolve and reach the host.
- Check that a token in the URL has not expired or been truncated.
- Review Tasks & Logs for the failure stage: request, HTTP status, response size, unsupported format, or no valid audio.
The feed opens but no chapters are found
Verify that entries contain an RSS enclosure, Media RSS audio content, an Atom enclosure, or a direct audio URL. A normal episode web page is intentionally not accepted as an audio chapter.
Episodes removed upstream are still present
This is the expected conservative sync policy. It protects listening history when a feed returns only a recent window. Per-episode RSS cleanup is not available yet; do not work around it by resetting the database, clearing progress, or rebuilding the device environment.