Fiction sources

Fiction sources

Candela has thirty-four fiction backends as of v1.13.0 (up from twelve at v0.5.22, twenty-one at v0.5.51, twenty-five at v1.2.4). Each can be toggled on/off independently in Settings → Plugins — the plugin manager iterates the registry automatically thanks to the @SourcePlugin annotation + :core-plugin-ksp KSP processor (v0.5.27). Disabling a backend removes its chip from the Browse picker; if you disable your currently-selected source, Browse auto-snaps to the first remaining one.

Source	Module	Shipped	Hosted by
Royal Road	:source-royalroad	v0.1.x	royalroad.com
GitHub	:source-github	v0.4.x	github.com
Memory Palace	:source-mempalace	v0.4.x	you (LAN-only)
RSS / Atom feeds	:source-rss	v0.4.71+, #236	any feed publisher
Local EPUB folder	:source-epub	v0.4.71+, #235	your device
Local PDF file	:source-pdf	v1.1.0, #996	your device
Scanned text (OCR)	:source-ocr	v1.1.0, #995	your device (on-device ML Kit)
Outline (self-hosted wiki)	:source-outline	v0.4.78+, #245	you (your Outline server)
Project Gutenberg	:source-gutenberg	v0.5.x, #237	gutenberg.org / Gutendex
Archive of Our Own	:source-ao3	v0.5.x, #381; auth PR1 v0.5.51 #426	archiveofourown.org
Standard Ebooks	:source-standard-ebooks	v0.5.x, #375	standardebooks.org
LibriVox	:source-librivox	v1.1.0, #1015	librivox.org (public-domain audiobooks)
Wikipedia	:source-wikipedia	v0.5.x, #377	<lang>.wikipedia.org
Wikisource	:source-wikisource	v0.5.x	<lang>.wikisource.org
Radio	:source-radio (was :source-kvmr → renamed #417)	v0.5.20 + Radio Browser search	KVMR / Cap Public / KQED / KCSB / SomaFM + Radio Browser API (30k+ stations)
Notion	:source-notion	v0.5.22+, #233 + #390; beautiful covers v0.5.51 #514	notion.so (defaults to TechEmpower's resource library)
Hacker News	:source-hackernews	v0.5.x	news.ycombinator.com
arXiv	:source-arxiv	v0.5.x	arxiv.org
PLOS	:source-plos	v0.5.x	plos.org
Discord	:source-discord	v0.5.x	discord.com
Telegram	:source-telegram	v0.5.51, #462	telegram.org (public channels)
Palace Project	:source-palace	v0.5.51, #502	thepalaceproject.org (OPDS catalog, non-DRM only)
Slack	:source-slack	v0.5.51, #454	slack.com workspaces (bot-token auth)
Matrix	:source-matrix	v0.5.51, #457	federated (matrix.org, kde.org, FOSDEM, self-hosted Synapse / Dendrite / Conduit)
Google News	:source-google-news	v1.4.0	news.google.com (topic feeds)
Bookshare	:source-bookshare	v1.4.0	bookshare.org (accessible library; discovery wired, full access pending the Benetech partner key)
reddit	:source-reddit	v1.10.0, #1492	reddit.com (OAuth installed-app; bring your own free client id)
Google Drive	:source-google-drive	v1.10.0, #1496	your Google Drive (narrow drive.file scope)
Your calendar	:source-calendar	v1.10.0, #1495	your device (on-device CalendarContract, never uploaded)
Epic free games	:source-epic-free-games	v1.10.0	store.epicgames.com (weekly free-game rotation)
Prime Gaming	:source-primegaming	v1.10.0	gaming.amazon.com (via community LootScraper feed)
Candela Handbook	:source-handbook	v1.11.0, #1561	bundled on-device (the app's own user guide, fully offline)

Plus the Readability catch-all (:source-readability, #472) — always-on, lowest-confidence match (0.1). Any HTTP(S) URL not otherwise claimed by one of the 33 specialized backends produces a single-chapter "article" fiction via Readability4J. No URL is a dead-end.

Royal Road

The flagship source — full-fidelity browsing with the same filter set as the website.

Filter knobs: tags include / tags exclude, status (ongoing / hiatus / completed / dropped / stub), type (original / fanfiction), length (≥ 50k / 200k / 500k / 1M / 1.5M / 2M / 5M words), rating (any / only NSFW / only SFW), content warnings, sort.

Tabs: Popular, Best Rated, New, Search.

Sign-in: WebView captures cookies after the user logs in. Premium chapters and the user's Follows list become accessible. Sign-out flushes locally; remote revoke is in your RR account settings.

GitHub

Browse fiction repos hosted on GitHub. Each repo with a book.toml (mdbook layout) becomes a fiction; chapters resolve from SUMMARY.md and the linked markdown files.

Backends within the source:

• Registry — curated list at candela-registry.
• Search — live /search/repositories calls.
• Topic-tag multi-select + archived qualifier for refining search.
• My Repos / Starred / Gists — visible only when signed in (#200, #201, #202).
• Public/Private/Both filter on the My Repos tab when private-repo scope is enabled (#204).

Sign-in (OAuth Device Flow):

• Default scopes: read:user public_repo gist.
• "Enable private repos" toggle in Settings upgrades to read:user repo gist on next sign-in.
• Lifts anon 60 req/hr → 5,000 req/hr.

Manifest formats supported: mdbook (book.toml), bare README + chapter files, storyvox.json (custom). HonKit (book.json) is tracked at #123.

Memory Palace

Mount your own Memory Palace as a Browse backend. Diary entries and KG-timeline chapters render as fictions.

Setup: Settings → Memory Palace → host (e.g. http://palace.local:9080) + API key. Hit "Test connection" first.

Per-wing filter: dropdown on the Browse tab (#191) to narrow listings to a specific palace wing.

Caveat: the palace is your own infra — host it on your home network, expose it on a tunnel, or run it locally. Connection errors surface as "The realm is unreachable" with a Try-again CTA.

RSS / Atom feeds

Subscribe to any RSS or Atom feed; each item becomes a chapter, the feed itself becomes a fiction. Suggested-feeds list is curated in the separate candela-feeds repo and fetched at runtime (#246) — bumping that list is a docs-only change in candela-feeds, no app release required.

Setup: Browse → RSS tab → either pick a suggested feed or paste a URL.

Caveats:

• Some feeds publish full content; some publish summaries with a "read more" link. Candela plays whatever's in the feed item — partial content stays partial.
• A bug in early v0.4.7x routed every feed item to chapter 0 ("always plays the first one") — fixed in 7904232. Update if you're seeing this.

Local EPUB folder

Pull from a folder of .epub files on your device — useful for personal libraries (Calibre exports, Project Gutenberg downloads, sideloaded titles).

Setup: Settings → Library & Sync → EPUB → Choose folder. Storage Access Framework prompts for a folder; Candela keeps a permission grant for that URI. The folder doesn't have to be in Candela's private storage — anywhere the SAF can reach (internal storage, SD card, USB-OTG).

How it works: for each .epub in the folder, Candela parses the .opf manifest (META-INF/container.xml → first rootfile) and extracts the spine into chapters. No DRM handling — DRM-locked EPUBs won't open.

Outline (self-hosted wiki)

Treat your Outline wiki as a fiction source — collections become fictions, articles become chapters. Useful for serial fiction drafts, knowledge bases you want narrated, or just listening to your own writing.

Setup: Settings → Library & Sync → Outline:

• Server URL — your Outline install's URL with protocol (e.g. https://outline.example.com).
• API token — generated from your Outline user settings → API tokens.
• Test connection before saving.

Caveats: Candela is read-only against Outline. Updates in Outline propagate on next chapter poll.

Project Gutenberg

The 70,000+ public-domain book catalog. Candela queries the Gutendex JSON wrapper for catalog/search and downloads each book's EPUB once on tap. Chapters render through the same :source-epub parser as local EPUB files. Most legally clean source in the roster — Gutenberg actively encourages programmatic access.

Archive of Our Own

14M+ fanfiction works. Discovery is per-tag via AO3's documented Atom feeds; content is the official EPUB download per work (same shape as Gutenberg). Default OFF on fresh installs because AO3 includes Explicit-rated works — opt in from Settings → Library & Sync.

Standard Ebooks

~900 hand-curated, typographically polished public-domain classics. Same CC0 legal posture as Gutenberg; the differentiator is editorial polish (cover art, consistent typography, proofreading). Tap-to-add downloads the recommended EPUB.

Wikipedia

First non-fiction long-form backend. Each article is one fiction; each top-level <h2> section is one chapter (chapter 0 = "Introduction"). The Wikipedia REST API at <lang>.wikipedia.org drives both discovery (featured + most-read for Popular, opensearch for Search) and content. Language code is configurable per-user in Settings.

Radio (KVMR / SomaFM / Radio Browser)

The audio-stream backend. Started as :source-kvmr and was generalized to :source-radio in #417 — the rename ships with a one-cycle SourceIds.KVMR alias so persisted fictions keep working. Five curated stations (KVMR 89.3 Nevada City, Cap Public Radio, KQED 88.5, KCSB 91.9, SomaFM Groove Salad) plus Radio Browser API search across 30,000+ stations worldwide. Each "fiction" surfaces with one chapter ("Live") whose audioUrl is a public stream; playback bypasses the TTS pipeline and routes through Media3 / ExoPlayer directly.

Notion

Treat any Notion page or database as a fiction catalog. Pages (or rows in a database) become fictions; each fiction splits into chapters on every heading_1 boundary (chapter 0 = "Introduction" — the lead paragraph cluster before the first heading_1).

Default root: the bundled default points at the techempower.org content page — Guides, Resources, About, Donate, plus ~80 free-tech resource entries (#390). Fresh installs land pre-configured. Existing users with a different stored value keep it. Note: TechEmpower's root is a page (anonymous reader walks the page hierarchy via the unofficial Notion API) — the page-vs-database distinction matters if you're wiring a new root yourself.

Beautiful covers (v0.5.51, #514): the Notion reader now renders proper page covers; for pages without a cover the source falls back to the first body image; if neither exists, a brass-edged synthetic BrandedCoverTile uses a Library Nocturne palette so the catalog grid never looks broken.

Setup: Settings → Plugins → Notion:

• Root page ID or Database ID — paste from the URL (32-character hex, with or without hyphens).
• Integration token — create at notion.so/my-integrations, then share your root with the integration. Stored encrypted; never displayed.

Caveats:

• Notion's REST API requires authentication on every call — there is no anonymous tier and "public share" pages don't have a REST surface. The toggle defaults ON but the source returns AuthRequired until you paste a token.
• Property mapping (databases only): Candela finds the database's mandatory title property by type (not by name). Description tries Description / Summary / Abstract then falls back to any rich_text property. Author tries Author / By. Tags pull from any Tags / Categories / Topics multi-select.

Telegram

Public Telegram channels as fictions (#462, v0.5.51). Architectural twin to Discord but simpler — no threads, no servers, no search. Invite the bot to a public channel; the channel becomes a fiction, each message becomes a chapter.

Setup: Settings → Plugins → Telegram → bot token (123456:ABC-DEF… from @BotFather).

Palace Project

The first library-borrowing backend (#502, v0.5.51) — OPDS catalog walker for the Palace Project's free library titles. Ships non-DRM titles only in this PR; LCP DRM is explicitly deferred. Libby + Hoopla follow-ups defer to their own PRs.

Slack

Slack channels as fictions via the Web API (#454, v0.5.51). Channels become fictions, messages become chapters with cursor-based pagination. Bot-token auth (xoxb-…).

Default OFF on fresh installs because workspaces are private and bot-token onboarding is high-friction. Settings → Plugins → Slack to opt in.

Matrix

Federated Matrix rooms as fictions via the Client-Server API (#457, v0.5.51). Works against matrix.org, kde.org, fosdem.org, or any self-hosted Synapse / Dendrite / Conduit server. Room = fiction, message = chapter (with same-sender coalescing so a thread of small messages from one author reads as a single chapter).

Default OFF on fresh installs. The Settings → Plugins screen surfaces it; bot-token / access-token onboarding gates content visibility.

LibriVox

Public-domain human-narrated audiobooks from librivox.org (#1015, v1.1.0). Unlike every other backend, LibriVox chapters are pre-recorded audio, not TTS — each chapter's audioUrl is a public MP3 that plays through Media3 / ExoPlayer directly, bypassing the neural-voice pipeline. Browse the catalog or search by title/author; tap a book to add it, tap a chapter to stream. (Radio and LibriVox are the two audio-stream backends — everything else is narrated by the TTS engine.)

Local PDF file

Open a .pdf from your device and have it read aloud (#996, v1.1.0). Candela extracts the embedded text layer; each page (or logical section) becomes a chapter the TTS engine narrates. Pick a single file or a whole folder of PDFs through the system file picker (Storage Access Framework) — the grant persists, so the folder reappears as a Browse tab. Scanned or image-only PDFs that carry no text layer are best read through the OCR source instead.

Scanned text (OCR)

Turn photos and scans into narrated text entirely on-device (#995, v1.1.0). Point the camera at a page (or import an image) and Google ML Kit's on-device recognizer extracts the words — nothing leaves the phone — producing a chapter you can listen to. Useful for physical books, mail, signage, or any printed page. Capture several pages in a row to build a multi-chapter "fiction." Enable it under Settings → Plugins → OCR.

Adding a backend

Since the v0.5.27 plugin-seam refactor, adding a new fiction backend is ~4 touchpoints (down from ~17 pre-Phase-2):

1. Add a Gradle module declaring an android.library + Hilt + kotlinx-serialization (if HTTP).
2. Implement FictionSource from :core-data.
3. Annotate the implementation with @SourcePlugin — the :core-plugin-ksp KSP processor emits the Hilt @IntoSet factory at compile time. No manual Hilt module needed.
4. Optional: add a settings adapter if your backend needs config (token, host, etc.).

The Plugin manager in Settings → Plugins iterates the registry and auto-surfaces a card with an on/off toggle and details modal. The Telegram, Palace, Slack, and Matrix backends in v0.5.51 are recent templates; for HTTP-backed shape see :source-wikipedia or :source-notion. See the Building from source page for dev-setup details.