Using narratorr-requests

Searching

The Request page is the catalog search. Type a title, author, or series and press Search (search runs on submit, not per-keystroke — each new query round-trips to narratorr’s metadata provider; repeats are served from a short shared cache).

Each result card shows the cover, title, author(s), narrator(s), and series (with position). A badge tells you where the book stands, most-actionable state wins:

Badge	Meaning
In library	narratorr already has it imported — nothing to request. If the book has a companion eBook, a green Get eBook button appears too (see eBooks).
(your request’s status)	You’ve already requested it — shows Requested / Approved / Processing / Available / etc.
On the way	narratorr is already acquiring it for someone else (no duplicate request offered).
Request button	Not owned and not yet requested — request it.

Note

If narratorr isn’t connected yet, search shows a “not connected yet” notice — an admin needs to configure it in Settings. Searching very rapidly can hit a short per-user rate limit (“Too many searches — slow down a moment.”); just wait a beat.

Requesting a book

Click Request on a card. What happens next depends on your account:

• Normal users → the request is created pending and waits for an admin to approve it.
• Admins and auto-approve users → the request is auto-approved and handed to narratorr immediately (no queue).

A couple of rules:

• One active request per book. Requesting a book you already have an active request for just returns the existing one. You can re-request a book that was previously denied or failed.
• Quota. Non-admin users have a rolling-window request quota. At the limit, the request is rejected with a “quota reached” message (429). An admin can also block a user from requesting entirely — a distinct hard denial (403), not just a cap of zero.

See your quota at a glance

Both the Request (search) page and My Requests show a quota badge in the header — used / limit requests used · N remaining · last N days (e.g. 3 / 10 requests used · 7 remaining · last 30 days). It turns amber as you approach the cap and red once you’re at it; admins and uncapped users see Unlimited requests instead, and a blocked user sees Requests blocked by admin.

My Requests

The My Requests page lists everything you’ve requested and updates live (it polls every few seconds), so you’ll see a request move through its stages without refreshing.

Status	Means
Requested	Awaiting admin review.
Approved	Approved; handoff to narratorr pending/in-flight.
Processing	narratorr is searching / downloading / importing it.
Available	Imported into the library — done. If the book has a companion eBook, a Get eBook button appears on the row.
Denied	An admin declined it (the reason, if given, is shown).
Failed	The acquisition failed (the reason, if known, is shown).

There’s no cancel or retry — a denied or failed book can simply be requested again from search. If you haven’t requested anything yet, the empty page offers a Browse audiobooks button straight to search.

eBooks: download or Send to Kindle

If your library keeps companion EPUBs alongside its audiobooks (and eBook support is enabled on both sides — see Configuration), a book that’s In library grows a green Get eBook button: on its search card, and on your My Requests row once the request is Available. An imported book without a companion shows a muted No eBook pill on search cards; a book still on the way shows no eBook action until it’s imported.

Get eBook opens a sheet with the book, an EPUB badge and its size, and two actions — whichever is ready for you is the highlighted primary:

• Download eBook — downloads the EPUB through narratorr-requests (your browser never talks to narratorr directly). Rapid downloads hit a short per-user rate limit.
• Send to Kindle — emails the EPUB to your Kindle address. It’s ready once an admin has set a Kindle sender and you’ve saved a Kindle address; until then the button renders disabled with the reason.

Send results — success or failure — appear inside the sheet (a failed download surfaces as a toast instead). On a successful send you’ll see “Sent to Amazon” — allow a few minutes for Amazon to convert and deliver it to your device. Sends are rate-limited (three starts a minute, 10 accepted per day, per user), re-sending the same book within a minute just returns the earlier result, and a book over Amazon’s 25 MiB personal-document cap can’t be emailed — the sheet tells you to download it instead.

Setting up Send to Kindle (one-time)

1. Add your Kindle address in the account modal (click your username) — the Kindle address field under eBooks. Find yours in Amazon under Devices → your Kindle → Email. It must be the @kindle.com address (the @free.kindle.com variant isn’t accepted).

2. Approve the sender at Amazon. Amazon only accepts personal documents from addresses on your Approved Personal Document E-mail List — and what you approve is the app’s sender address (shown in the account modal and on the send sheet), not your own Kindle address (that’s where books arrive). In Amazon: Account → Content & Devices → Preferences → Personal Document Settings → Approved Personal Document E-mail List → “Add a new approved e-mail address”, then enter the sender mailbox — the walkthrough shows the exact address with a copy button.

Once per Amazon account — after that, sending is one click. Your Kindle address is private to you; admins can’t see or edit it.

Your account

Clicking your username in the header opens the account modal, in two groups:

Audiobooks

• Email — your contact address, with a Save button. For local-auth users it starts as your login email; for OIDC users it’s backfilled from your provider (and anything you set here survives future logins — clearing it re-enables the provider backfill).
• Email me when my request is — three opt-in checkboxes: approved, denied (includes the admin’s reason, when given), and ready to listen. Checkboxes apply instantly; they render disabled (with an explanation) until you’ve saved an email above and an admin has configured an Email (SMTP) notifier.

eBooks — shown only when eBook support is on:

• Kindle address — where Send to Kindle delivers, with its own Save. Must end in @kindle.com; clear it to remove it.
• Amazon setup — a Required note (Kindle delivery won’t work until you approve the sender in your Amazon account), with “Approve the sender at Amazon” expanding the one-time walkthrough — it names the exact sender address to allowlist, with a copy-to-clipboard button (see Setting up Send to Kindle).

Admin: the Queue

Admins get a Queue page (all users’ requests, filterable by status, defaulting to the pending review queue). On a pending request:

• Approve → the request is approved and handed to narratorr (added idempotently by ASIN), then it moves to Processing.
• Deny → optionally enter a reason (the requester sees it), then confirm.

Decisions — approve or deny — are claimed atomically, so two admins can’t both act on the same request; the second gets a “not pending” notice.

Admin: Users

The Users page manages accounts (sorted pending → active → rejected, with a banner counting who’s awaiting approval). On the list you can Approve / Reject a pending account and Make admin / Demote — disabled on your own row (you can’t change your own role or status, so the last admin can’t lock themselves out). Reject is durable and re-approvable later; from a user’s detail page you can also reject an active user to revoke their access.

The rest lives on that detail page (click the username), alongside their request history:

• Request quota — one of four explicit modes, not a blank/number toggle:

  Mode	Effect
  Use app default	No override — follows the app-wide default (see Configuration).
  Unlimited	No cap for this user, even if the app default is limited.
  Custom limit	A custom positive cap for just this user, on the same rolling window.
  Blocked	A hard admin denial — the user can’t request at all, distinct from “a cap of zero.”

• Auto-approve requests — that user’s requests skip the pending queue (they still count against their quota, unless blocked). Admins always auto-approve.

Admins are exempt

The admin role bypasses the approval queue, the request quota, and always auto-approves — handy for the owner account, and why the first user (the admin) can request immediately.