Build audio add-ons · OpenBlast

A small API. No extension runtime.

OpenBlast uses the BitChord HTTP add-on contract. Listeners add your service root or manifest.json URL: in the Android app under Settings → Add-ons → Audio add-ons, and in the web player under Settings → Audio sources. No executable package is installed.

The starter is a Cloudflare Worker with a small configurable catalog, CORS support and tests. It starts with an empty catalog; add your own audio URLs and their measured metadata before deploying.

cd examples/audio-addon
node --test worker.test.mjs
npx wrangler deploy

Configure CATALOG in wrangler.toml. Keep signed audio URLs short-lived and generate them at stream resolution if your service needs that. The example catalog suits a small collection; use a database for a larger service.

The three endpoints

Describe your service

GET/manifest.json

{
  "id": "org.example.catalog",
  "name": "My audio catalog",
  "version": "1.0.0",
  "resources": ["search", "stream"],
  "allowDownloads": true,
  "checkValidLossless": false,
  "settings": [{
    "key": "quality", "default": "lossless",
    "options": [{"label": "Best available FLAC", "value": "lossless"}]
  }]
}

Use a stable, unique ID. allowDownloads: false excludes your source from file downloads. checkValidLossless: true requires a supported wired, USB or HDMI output before OpenBlast queries your service. Bluetooth and unknown outputs do not qualify.

Find the recording

GET/search?q=title%20artist&quality=lossless

{"tracks": [{
  "id": "recording-42", "title": "Example Song",
  "artist": "Example Artist", "album": "Example Album",
  "duration": 203, "format": "flac",
  "artwork": "https://cdn.example.org/cover.jpg"
}]}

duration in seconds
no match → {"tracks":[]}

Return the real title and credited performers, including version labels such as live or remix. OpenBlast checks recording identity and duration; the first search result is not automatically accepted.

Hand over the audio

GET/stream/recording-42?quality=lossless

{
  "url": "https://cdn.example.org/recording-42.flac",
  "codec": "flac", "format": "flac", "manifest": "none",
  "sampleRate": 96000, "bitDepth": 24,
  "encrypted": false
}

sampleRate in Hz
bitrate in bits per second
manifest: none, hls or dash

IDs are opaque and URL-encoded as one path segment. For unencrypted segmented playback use manifest: "hls" or "dash". File downloads currently require a direct audio file.

Describe the audio you actually serve.

Lossless describes the encoding, not a promise about the original master. Do not relabel AAC or MP3 as FLAC, upsample to claim higher resolution, or advertise 24-bit/192 kHz for every track.

ffprobe -v error -select_streams a:0 \
  -show_entries stream=codec_name,sample_rate,bits_per_raw_sample \
  -of json recording.flac

OpenBlast reads direct FLAC headers and uses the playback decoder's format for the quality display. HLS/DASH renditions must contain supported lossless audio; encrypted audio is unsupported. Browser codec support differs from Android.

Source priority is intentional: OpenBlast checks eligible matching lossless results for the best available quality, and equal quality keeps the listener’s source order. Playback starts right away while the higher-quality lookup runs, then switches over without a gap.

Make delivery reliable.

Transport

Public HTTPS endpoints, including redirects and media URLs. Local and private destinations are rejected by the Android add-on transport.

Browser access

Enable CORS on API responses, audio, manifests and every segment, and answer OPTIONS. Public services without sign-in can send Access-Control-Allow-Origin: *.

Seeking

Support Range requests and HTTP 206 with correct Content-Range and Content-Length for direct files.

Rate limits

Return HTTP 429 with Retry-After. OpenBlast waits that out for the current song and tries another enabled source meanwhile; the next song asks again.

Failures

Use a suitable HTTP status and {"error":"A safe explanation"}. Never return an HTML error page as audio.

Response size

Keep JSON small. The Android client limits metadata responses to 2 MiB and downloads to 512 MiB.

Expiration

Stream responses may be cached for five minutes. Keep URLs valid for playback and seeking past that, or return a stable URL; OpenBlast asks for a fresh link when one is refused.

Secrets

Configured URL paths and query parameters are stored on the listener's device, so they can't hold credentials meant to stay secret. OpenBlast sends no Google session or app cookies to add-ons.

Test it before you share it.

Run the starter tests and check all three endpoints.
Add your manifest in OpenBlast and use Check to inspect its availability.
Select Lossless quality, play a known recording, and inspect Signal path. Check a non-match, a timeout and an expired URL too.
Test downloads, seeking and playback on the devices you target. Inspect the file with ffprobe instead of trusting its extension.
Document region limits, costs, authentication and availability.

Audio add-ons allow extending OpenBlast with external catalog and lossless playback streams.

Your catalog.More ways to listen.