Audiobook source candidates
Research notes for future storefronts beyond the built-in sources (Audible,
Libro.fm, Chirp, GraphicAudio — see stores.md). Candidates would
plug into bookclerk-source's ContentSource trait. Criteria:
- Public API or reverse-engineerable Android APK (Libro.fm pattern)
- DRM-free audio or community-documented decrypt path
- No DRM mention → treat as unknown until investigated
APKs were downloaded via apkeep (APKPure) and decompiled with jadx
(2026-07-22). Package IDs and key endpoints below are from those APKs plus
community tooling (audiobook-dl,
kobodl, etc.).
| Concern | Notes |
|---|---|
| Trait surface | login / list_accounts / scan / fetch_title → PlainFetch (decrypt inside plugin) |
| Plain path | Matches Libro.fm today (no bookclerk-media) |
| DRM | Owned by the source plugin (Audible: Adrm/Widevine); host never sees keys |
| Auth storage | Per-account tokens in encrypted_secrets (DB), keyed by account id |
| Config plugins | Plugin instance document ([[settings]] schema); enablement is a deployment per host |
| Diagnostics | Top-level [diagnostics] only (not an integration plugin) |
Sources are plugin instances: bookclerk plugins undeploy chirp keeps this
host from loading that store. Store-specific knobs (bitrate, container,
access as applicable) are the plugin's declared settings. Crash/error-burst
reporting stays under [diagnostics] — distinct from [integrations.*].
| Rank | Source | Access | DRM | Integration fit |
|---|---|---|---|---|
| 1 | GraphicAudio | Clear Retrofit API in APK | DRM-free (official ZIP / app Lo+Hi URLs) | Excellent — Libro-like |
| 2 | Kobo Audiobooks | Documented storeapi.kobo.com (kobodl) |
Audiobook spine usually plain; ebooks use KDRM | Strong — Audible-like auth |
| 3 | Chirp | GraphQL web + Android Mockingjay APIs | URL AES on web; local download encryptor in app; files play as MP3 | Strong with caveats |
| 4 | Storytel / Mofibo | Android API (api.storytel.net) |
Serves audio/mpeg after auth (community) |
Strong; rate-limit risk |
| 5 | Audiobooks.com | api.audiobooks.com/api/v2/ in APK |
Stream page yields MP3 (community) | Good; Storytel-owned |
| 6 | Downpour | app.downpour.com + web downloads |
Mixed: mostly DRM-free, some DRM titles | Medium — filter isDrm |
| 7 | LibriVox | Public catalog API | Public domain / free | Easy but niche |
| 8 | Podimo | GraphQL gateway | Unknown (CDN mp3/m3u8 present) | Medium / investigate |
| — | Google Play Books | Partial official export | Per-title export flag | Weak for library sync |
| — | Spotify / Everand | — | Heavy / app-bound DRM | Poor fit |
Why: Same integration shape as Libro.fm: password login → library list → plain download URLs. Official store also sells DRM-free MP3/M4B/FLAC ZIPs.
APK: com.efsharp.graphicaudio
Base URL: https://www.graphicaudio.net/access/
| Method | Path | Role |
|---|---|---|
POST |
activation/login |
Form: username, password, client_id |
POST |
activation/thirdparty |
Token activate |
POST |
activation/remove |
Forget device |
GET |
api/products |
Library (Authorization header) |
GET |
api/links?product= |
Download URLs |
GET/PUT |
api/bookmark |
Progress |
DownloadInfoResponse fields: Lo / Hi → low/high quality stream/download
URLs (m4a in-app). No Widevine/MediaDrm usage in app code beyond ExoPlayer
boilerplate.
Bookclerk mapping: GraphicAudio content-source plugin (id = "graphicaudio"),
PlainFetch, credentials stored in encrypted_secrets. Optional: also scrape
Magento “My Downloadable Products” for ZIP MP3/M4B/FLAC purchases.
Risks: Niche catalog (dramatized productions). Device activation may cap concurrent clients (same pattern as many mobile apps).
Why: Mature community client already emulates device auth and downloads audiobook spines as numbered audio files. Closest “Audible-sized” commercial catalog among DRM-tractable options.
APK: com.kobobooks.android (large; strings confirm audiobook player +
ExoPlayer DRM stack for ebooks / streaming)
API (from kobodl, still current pattern):
- Device auth:
https://storeapi.kobo.com/v1/auth/device - Refresh:
…/v1/auth/refresh - Init resources:
…/v1/initialization - Library sync: tokenized
library_sync - Audiobook download URL → JSON
Spine[]withUrl+FileExtension
DRM: Ebook path uses KDRM / AdobeDrm. Audiobook download path in kobodl
skips content-key decrypt when DrmType is not KDRM/AdobeDrm and writes
plain part files. Treat as plain for typical audiobooks; verify live
before committing.
Bookclerk mapping: Device-activation login (browser code, like Audible
QR/OAuth UX), PlainFetch for spine parts (ZIP/M4B packaging in
acquire). Do not need KDRM remover unless we also want ebooks.
Risks: Activation UX; API churn; regional audiobook availability.
Why: Deal-focused owned library; strong community downloaders; APK exposes dedicated API hosts.
APK: com.chirpbooks.chirp
| Constant | Value |
|---|---|
MOCKINGJAY_API_ROOT |
https://api.chirpbooks.com/api |
MOCKINGJAY_LISTEN_API_ROOT |
https://listen-api.chirpbooks.com/api |
| Web | https://www.chirpbooks.com |
Android uses Apollo GraphQL (com.mockingjay.* queries/mutations:
AndroidCurrentUserAudiobooksQuery, sign-in, archive, position, …) plus
“Kingfisher” playback/download. Web/community path
(audiobook-dl):
- Cookie session
- GraphQL
fetchAudiobookTracks/fetchAudiobookTrackUrl - AES-CBC decrypt of
webPlayerMediaUrl(key from pagedata-dk, IV from paddeduser_id) - Resulting URL is playable MP3
App also has KingfisherDownloadedTrackEncryptor / ExoPlayer offline cache —
local-at-rest encryption for offline listening, separate from the web URL
obfuscation.
Bookclerk mapping: Prefer GraphQL password signIn (proven live) →
token → library/track queries → decrypt webPlayerMediaUrl → Plain MP3.
Avoid cookie sessions for headless use. APK Mockingjay schema is a second
source of truth (scripts/source-probes/).
Risks: Cloudflare (needs a real User-Agent from some egress); URL crypto may change; Findaway distribution roots appear in cover CDN paths (monitor for future DRM shifts).
Why: Large subscription catalog; community client already implements login + MP3 asset fetch.
APK: grit.storytel.app (decompiled; Kotlin/com.storytel.*)
Documented API (audiobook-dl):
| Call | Role |
|---|---|
POST …/api/login.action |
Password AES-CBC with fixed key/IV, Android UA |
GET api.storytel.net/book-details/consumables/{id} |
Metadata |
GET api.storytel.net/assets/v2/consumables/{id}/abook |
302 → MP3 |
GET api.storytel.net/playback-metadata/… |
Chapters |
POST api.storytel.net/libraries/bookshelf |
Library |
DRM: Download responses expected as audio/mpeg. Not classic Widevine
file DRM in the community path. Treat acquire as Plain, but watch for
CDN/format changes. Aggressive download rate-limits can invalidate sessions.
Bookclerk mapping: Password login + JWT; scan bookshelf; Plain fetch.
Subscription semantics differ from purchase libraries (titles can leave the
catalog).
Risks: Cloudflare; rate limits; ToS / account flags; regional catalogs.
APK: com.audiobooks.androidapp
API base in APK: https://api.audiobooks.com/api/v2/
App REST (preferred over cookies): form posts with APK apiKey
(NetworkConstants.API_KEY). Live probe: authenticate/startup → guest
token; authenticate/login (emailAddress, password, deviceId, …);
booklist/library; media via book/mediaurls/{id}. Cookie scrape of
/book/stream/{id} (ci_session) is fallback only.
DRM: Unknown officially; community obtains plain MP3 streams. Confirm
book/mediaurls with a test account before locking the design.
Fit: Good if overlapping Storytel work; US catalog / credits model.
APK: com.blackstonehybrid
Hosts: https://app.downpour.com/ (app API), cdn.blackstonepublishing.com,
storefront downpour.com (Shopify + UCP commerce — not library download).
Entitlement model includes isDrm(). FAQ: most titles DRM-free MP3; some
publisher-required DRM playable only in-app. App uses Readium audiobook
manifests.
Bookclerk mapping: Prefer DRM-free web account downloads when available;
app API for library sync, skip/error when isDrm == true. Heavy Kotlin
obfuscation → slower RE than GraphicAudio.
Risks: Mixed DRM; obfuscated client; need live classification of titles.
Public API: https://librivox.org/api/feed/audiobooks (+ audiotracks,
authors). No auth. DRM-free public domain.
Fit: Trivial Plain source; valuable for tests / CI without credentials,
not a commercial library manager feature.
APK: com.podimo
Hosts: https://graphql.pdm-gateway.com/graphql, CDN
cdn.podimo.com/audios/…mp3|m3u8.
DRM: No clear documentation. Presence of bare MP3 CDN URLs is promising but unproven for audiobook entitlements. Community support in audiobook-dl via password login.
Fit: Worth a follow-up GraphQL schema dump; not first priority.
| Source | Verdict |
|---|---|
| Google Play Books | Some titles offer official M4A export; no good library/download API for automation; eBook DRM tooling ≠ audiobooks |
| Spotify Audiobooks | App-bound DRM; no credible personal-library acquire path |
| Everand / Scribd | Streaming subscription; cookie scrapers exist; DRM/ToS hostile to Bookclerk model |
| Nextory | audiobook-dl login support; APK not fetched this pass; treat DRM as unknown |
| OverDrive / Libby / cloudLibrary | Library lending, not ownership; different product semantics |
- GraphicAudio — smallest Libro-shaped spike (
ContentSource+ Plain acquire + APK probe script). - Kobo audiobooks — reuse kobodl protocol knowledge; device-activation auth UX.
- Chirp — GraphQL + URL decrypt; optional APK Mockingjay probe.
- Storytel / Audiobooks.com — shared Storytel-family learnings; handle subscription semantics explicitly in UX/docs.
- Downpour — only after
isDrmfiltering is validated live.
LibriVox can land anytime as a zero-auth sandbox source.
API-first probes (no cookies) live in scripts/source-probes/. Re-run:
python3 scripts/source-probes/probe_all.py
| Source | Unauth result | Notes |
|---|---|---|
| GraphicAudio | OK | Public samples + plain audio/mp3 (ID3); login returns 401 JSON for bad password |
| Chirp | OK | GraphQL alive; signIn returns “Invalid username or password” (password API) |
| Storytel | OK | INVALID_CREDENTIALS; bookshelf 401 without JWT |
| Audiobooks.com | OK | Guest authenticate/startup token; login rejects bad password; splashcategories OK |
| Kobo | OK | Anonymous device auth + init (kobo_audiobooks_enabled); library_sync 401 without user |
| LibriVox | OK | Public JSON catalog (needs a real User-Agent — CF 1010 otherwise) |
| Downpour | Partial | app.downpour.com up (Gadget shell); library REST still obfuscated |
| Podimo | Blocked here | GraphQL behind Cloudflare from cloud egress |
Preference confirmed: mobile/API auth over stored cookies for GA, Chirp, Storytel, Audiobooks.com, and Kobo device auth.
Test accounts (empty owned libraries except Chirp auto-entitlement):
| Source | Result |
|---|---|
| GraphicAudio | Login OK; scan upserts 0 owned titles (5 promotional samples skipped) |
| Chirp | Login OK (user_id=5330622); scan found Firefly: Big Damn Hero (product_id=444622) |
Connect each store in the Accounts UI (email + password; the password is sealed in the database, never read from env or argv), then:
bookclerk library scan --source graphicaudio
bookclerk library scan --source chirp
# After verification, disable scan inclusion:
bookclerk library set-scan <account> --source graphicaudio --scan false
Probe harness still uses TEST_GA_* / TEST_CHIRP_* for Python smoke tests.
| Source | Env vars | Notes |
|---|---|---|
| Storytel | TEST_STORYTEL_EMAIL, TEST_STORYTEL_PASSWORD |
+ pycryptodome; CLI later: BOOKCLERK_STORYTEL_PASSWORD |
| Audiobooks.com | TEST_ABC_EMAIL, TEST_ABC_PASSWORD |
APK apiKey already in probe |
| Kobo | (browser ActivateOnWeb) | No password API |
| Downpour | TEST_DOWNPOUR_EMAIL, TEST_DOWNPOUR_PASSWORD |
After REST deobfuscation |
| Podimo | TEST_PODIMO_EMAIL, TEST_PODIMO_PASSWORD |
After Cloudflare |
| LibriVox | — | None |
Keep library.auto_acquire = false, disable scan after login, acquire ≤1 title.
Store SKUs (example: Red Rising 1 of 2, base $12):
| Cart option | Price delta | Magento ZIP | Browser Player (/library) |
Access App API (/access) |
|---|---|---|---|---|
| Listen with Access App and Browser Player | +$0 | No | Yes | Yes (≤4 devices) |
| MP3 Zip Download + App + Browser | +$2 | Yes (≤3 attempts) | Yes | Yes |
| M4B Zip Download + App + Browser | +$2 | Yes (≤3 attempts) | Yes | Yes |
| FLAC Zip Download + App + Browser | +$3 | Yes (≤3 attempts) | Yes | Yes |
Official docs: ZIP downloads also unlock App + Browser; App Access–only does
not include a computer ZIP. The 4-device limit is for Access App
activations (client_id); Browser Player is a separate website feature (no
device-slot language in FAQ). Magento ZIP links live under
My Downloadable Products.
-
Browser Player (default:
access = "web") — implemented
Magento login →library/index/content_library→/library/player/listen/title/{slug}/→<audio src>onmedia.graphicaudio.net→ download with CloudFront signed cookies set by the player page (bare URL without cookies returns 403). No device slot. Requires the account password stored at connect time. Login does not register an Access App device. -
Magento ZIP (opt-in:
access = "zip") — implemented
Magento customer session → My Downloadable Products → follow download link (307 → signed CloudFront ZIP) → extract M4B/MP3/FLAC →PlainFetch(onewholefile when M4B). No Access App device slot. Each Magento link hit consumes one of ≤3 download attempts — transfer must complete after resolve. Same stored password as Browser Player. -
Access App API (opt-in:
access = "device") — implemented (streaming)
POST /access/activation/login+api/products+api/links→ Hi/Lo M4A streamed to disk (no full-file RAM buffer). Consumes one of four device slots perclient_id.POST /access/activation/removewithclient_iddrops a slot. Reuse a stableclient_idfrom.ga.auth. Only this mode registers a device atauth login.
Config:
bookclerk plugins config set graphicaudio access web # web | zip | device
bookclerk plugins config set graphicaudio bitrate hi # hi | lo (device)
bookclerk plugins config set graphicaudio container auto # auto | m4b | mp3 | flac (zip)
Disable with bookclerk plugins undeploy graphicaudio. There is no ZIP→Browser→App cascade —
pick one path explicitly (default web).
- SKU: M4B Zip Download + App + Browser (order 1001007764)
- Magento ZIP:
media.graphicaudio.net/m4b-256kbps/SONSOFARES01-m4b.zip(~464 MB) → singleSONSOFARES01.m4b(~521 MB, Nerochplchapters) - Browser / App Hi: same ~521 MB M4A object under
app-high/ - App Lo:
app-normal/…_lo.m4a(~198 MB, signed query string) - Remaining Magento downloads after probe: 2 (one attempt used to capture the CDN redirect; Browser Player acquire does not consume ZIP attempts)
- After
activation/remove, re-runauth login --force(sameclient_id) before scan — stale tokens may list samples only until refreshed
Buy one title as M4B Zip Download (≈ base + $2), not App Access–only.
That single SKU unlocks ZIP + Browser + App, so we can validate all three paths without a second purchase. Prefer a short/cheap title. After purchase:
- Confirm ZIP under My Downloadable Products (primary acquire path).
- Probe Browser Player network calls while logged into Magento (session OK for discovery; implement API-first afterward if possible).
- Only then exercise Access App login if (1)/(2) miss media — and remove the
Bookclerk
client_idwhen done.
App Access–only first is only worthwhile for the cheapest Browser Player RE experiment if you accept buying ZIP later.
Note: Earlier cloud probe logins used a Bookclerk client_id against the
test GA account and may have registered a device — check Account → Access App
device management and remove unknown devices.
- Confirm owned-title
api/linkssigned-URL TTL vs Browser Player CloudFront cookie TTL in long acquires. - Live-check one Kobo audiobook spine for empty/
NoneDRM fields. - Decide whether subscription sources (Storytel, Podimo) belong in Bookclerk (owned-library product) or stay out of scope.
- Chirp: prefer GraphQL password
signInover cookie sessions for headless/daemon use (probe confirms this path).
Source: docs/contributing/research/source-candidates.md at main · View as Markdown