Build an add-on for Lelap

Lelap is a player. Everything it can browse, search and stream online comes from add-ons: small, stateless HTTP services that answer a few GET requests with JSON.

What an add-on does

An add-on can answer any of three resources, for the types it declares:

  • Catalogs: lists of titles to browse or search, such as “New releases” or “Poetry”.
  • Meta: the details of one item, such as the description, narrators, chapters or a podcast’s episodes.
  • Streams: where to play an item, as one audio URL or a list of parts.

Types are audiobook, podcast and episode. An add-on describes itself in a manifest at /manifest.json; listeners add it by pasting that URL into the app. There is no account, no registration and no review.

A session with an add-on
GET https://addon.example.com/manifest.json
  → who you are, what you serve, which catalogs you have

GET https://addon.example.com/catalog/audiobook/new.json
  → { "metas": [ …titles and covers… ] }

GET https://addon.example.com/meta/audiobook/example%3Asecret-garden.json
  → { "meta": { …description, chapters… } }

GET https://addon.example.com/stream/audiobook/example%3Asecret-garden.json
  → { "streams": [ { "url": "https://media.example.com/…" } ] }

Every request is a plain GET with everything it needs in the path, so responses cache well and an add-on runs anywhere that answers HTTP: Cloudflare Workers, Deno, Bun or Node.

Audio goes straight to the listener

Stream URLs point at the source, and the app plays them from there. Audio never passes through Lelap’s servers, and an add-on doesn’t have to serve it either: it only says where the files are. What a listener plays, and what they downloaded, stays on their device.

Start here

  1. Describe it. The manifest builder turns a short form into a valid manifest.json and starter code for the SDK.
  2. Pick a sample. The samples are small, tested add-ons in TypeScript with Hono, in plain Node and in Python, plus one with hard-coded catalogs and no code beyond the SDK. Copy the one closest to your stack.
  3. Fill in your data. The data model samples show every object the app reads, from a catalog row to a stream in parts.
  4. Put it online. Hosting covers Cloudflare Workers, Docker and any HTTPS host, and the CORS header every add-on needs.

Reference

  • Protocol v1: every route, object and field, with example responses and a JSON Schema.
  • SDK guide: write an add-on in TypeScript with @lelap/sdk, run it on Cloudflare Workers, Deno or Bun, and add it to the app.

Lelap’s own add-ons are built the same way: the Catalog add-on ( https://catalog.lelap.app/manifest.json) brings Open Library and Podcast Index, and the LibriVox add-on ( https://catalog.lelap.app/librivox/manifest.json) streams public-domain recordings. Their source is in the repository.

Rules for add-ons

Only build add-ons for audio you have the rights to stream: public-domain works, your own recordings, feeds their publishers make public, or a library you run yourself.

  • Lelap keeps no directory of third-party add-ons and doesn’t list, link to or recommend any. Share your add-on’s URL however you like; listeners decide what to install.
  • You run your add-on and you answer for what it serves. Follow the terms of the services it connects to.
  • Rights holders can reach us about our own sites and add-ons at copyright@lelap.app. See the terms.