Scrobbling

Add-ons can hear what you play and pass it on: your reading tracker learns which book you are in the middle of, and your other podcast apps continue where you stopped. Two such add-ons come with Lelap’s catalog service: Hardcover and gPodder sync.

How it works

While you listen, the app notes when you start, about every five minutes of playing, when you pause and when you finish. These notes wait on your device and go to every add-on you installed that asks for them. Offline listening is sent once you are online again, with the times you actually listened. A failing add-on is tried again later, for up to 30 days.

The notes say what you played (title, author, IDs such as ISBNs, or the podcast feed and episode), where you were and when. They never contain where the audio comes from or the paths of your own files. Add-ons follow the profile: hide one from a profile in its settings and that profile’s listening isn’t reported to it. The protocol side is in Protocol v1 → Scrobble.

Hardcover

Hardcover tracks what you read. With its add-on, a book you start listening to moves to Currently reading with your progress, and moves to Read when you finish it. Your Want to read shelf shows on Home, and books on it that an add-on can play open as usual.

  1. On Hardcover, open Settings → Hardcover API and copy your token.
  2. Open https://catalog.lelap.app/hardcover/configure, paste the token and make your add-on link.
  3. In Lelap, open Settings → Add-ons and paste the link.

Books are matched by ISBN or Audible ASIN when the add-on that lists them knows one, and otherwise by title and author. Books Hardcover doesn’t know are skipped. Hardcover tokens expire after a while; when yours does, make a new link the same way and replace the add-on.

gPodder sync

gPodder-compatible servers keep the places of podcast episodes for several apps at once, such as gpodder.net or a Nextcloud with the gPodder Sync app. With this add-on, every episode you play in Lelap is reported as a play action with where you started and stopped.

  1. Open https://catalog.lelap.app/gpodder/configure and choose the server type: the gpodder.net API, or Nextcloud gPodder Sync.
  2. Enter the server address (https only), your user name and your password. Use an app password where the server offers one. The add-on checks the login before it makes the link.
  3. In Lelap, open Settings → Add-ons and paste the link.

The gPodder API identifies episodes by their audio URL, which the app never sends. The add-on reads the podcast’s public feed to look it up by the episode’s guid; only the feed’s text passes through it, never audio.

Tokens and privacy

  • Your token or password is sealed into the add-on link with a key only the catalog service has (AES-256-GCM). It isn’t stored on the server, and a link copied out of a log or a screenshot doesn’t show it.
  • The link itself still works for whoever has it, so keep it to yourself. Lelap keeps it on your device and syncs it end-to-end encrypted. To stop a leaked link, revoke the token or change the password at the service.
  • The add-ons are stateless: they act on each batch of events and forget it. What you played is kept by Hardcover or your gPodder server, under their terms.

Self-hosting

Both add-ons are part of the catalog service, on Workers and in the catalog Docker image. Set CONFIG_SECRET to at least 32 random characters (on Workers with wrangler secret put CONFIG_SECRET); without it, the configure pages say they are unavailable. Keep it stable: changing it makes every link stop working until it is configured again. On Docker, the gPodder add-on can’t reach private addresses unless you set SCROBBLE_ALLOW_PRIVATE=true, for a gPodder server on your own network. See Hosting.