An open standard · v1.0.0-draft

Addonium

A freedom-first addon schema for music apps. If you can run a website or share a file, you can publish an addon. No accounts, no gatekeepers, no mandatory cloud.

Browse the spec Helpers API

Spec text CC0-1.0 · Code Apache-2.0 · Raw spec · JSON Schema · GitHub

Specification

Every section is its own page. Start anywhere.

  1. Table of Contents
  2. PhilosophyAddonium exists to make three things true at once:
  3. Terminology
  4. Addon TypesAddonium defines exactly two addon types. Every addon is one or the other - there is no third "partially locked" state; partial restriction is expressed thro...
  5. Distribution FormatsAddonium addons travel in exactly two file shapes:
  6. The ManifestEvery addon - Open or Locked, HTTP or compiled - has exactly one canonical manifest. For HTTP addons it is served at GET /manifest.json (or GET /{token}/mani...
  7. Authentication & Access ControlAuthentication in Addonium is transport-level and author-defined. There is no mandated identity provider, OAuth flow, or Addonium account system. The spec on...
  8. Tokenized URLsThe "url-token" auth method is the recommended default for Locked HTTP addons because it requires zero client-side auth logic - the base URL already carries ...
  9. HTTP API ReferenceAll endpoints below apply to HTTP addons (Open or Locked). For Locked addons, prefix every path with the token segment per §7, or send the configured header/...
  10. Compiled Module Contract (Locked addons only)A compiled module is a single script - plain JS, or a bundled/minified/ lightly-obfuscated variant - that a host loads in-process instead of calling over HTT...
  11. Client AllowlistingOptional. Defaults to off for both Open and Locked addons. When set, an author restricts which client applications may call their addon, independent of which...
  12. Optional Data StorageBy default, no Addonium addon stores anything about who called it. storesData in the manifest defaults to false.
  13. Updates, Versioning & CIA host periodically re-fetches manifestUrl (default: once every checkInterval seconds, or on next app launch if omitted) and diffs version. No addon needs to...
  14. Host Application ResponsibilitiesA conforming host MUST:
  15. Security Considerations
  16. Error HandlingCompiled modules should throw a typed error (e.g. { code: "UNLOCK_FAILED" | "NOT_FOUND" | "RATE_LIMITED", message }) rather than a bare string, so hosts can ...
  17. JSON SchemaThis schema validates manifest.json only. The /stream/:id response is intentionally left unschematized beyond url being required - see §8.2.1 for why format,...
  18. Example Manifests
  19. Capability Matrix
  20. FAQDoes an addon have to run anywhere special? No. Any HTTPS-capable server (a $5 VPS, a Raspberry Pi, a static host for Open Addons with pre-baked data, or not...

Helpers API (@addonium/helpers)

Zero-dependency TypeScript helpers, generated from source. bun add @addonium/helpers

  1. ◆Helper module · 4 exportsauth.ts
  2. ◆Helper module · 4 exportsclients.ts
  3. ◆Helper module · 6 exportserrors.ts
  4. ◆Helper module · 9 exportsmanifest.ts
  5. ◆Helper module · 3 exportsmodule.ts
  6. ◆Helper module · 14 exportstypes.ts
  7. ◆Helper module · 5 exportsupdate.ts
  8. ◆Helper module · 7 exportsurls.ts