Skip to main content

@deadair/plugin-sdk

Everything you need to write a deadair plugin, and nothing else. This package is the only thing a plugin imports from deadair: no database, no DI container, no HTTP framework. zod is a peer dependency, so you and the host share one copy; the one dependency of its own is the XML parser behind parseFeed.

A plugin extends deadair by declaring capabilities:

capabilitywhat it lets you do
catalogsupply music: list playlists, list their tracks
streamget the station the audio to play (resolveStreamUrl)
steerown your audio output and let deadair only tell you what to do
enrichmentsupply facts about a track: year, genre, label, trivia, prose
speechsay something out loud: text in, audio out
llmproduce words: a conversation in, text out
analysismeasure a track's audio: bytes in, cue points and loudness out
mixermake one piece of audio out of several: parts in, audio out
chartssay what is popular: a chart id in, ranked names out
similaritysay who else sounds like this: an artist in, artists out
newssay what happened outside the station: a feed in, entries out
searchask the open web a question: words in, pages out
weathersay what it is like outside: a place in, measurements out
scrobblereport what the station played to somebody else's service
oauthhold operator tokens, obtained through the host's redirect

There is no second axis. capabilities is the whole declaration, and the host checks it on every call together with whether you actually implemented the methods, because a plugin that claims a capability and forgets the method is a TypeError in the middle of a request rather than an honest "not supported".

The shape of a plugin​

A plugin package default-exports the result of definePlugin(manifest, factory) and points at that entry file from its own package.json:

{
    "name": "deadair-plugin-discogs",
    "version": "1.0.0",
    "type": "module",
    "main": "./dist/index.js",
    "deadair": {
        "plugin": "./dist/index.js"
    },
    "peerDependencies": {
        "@deadair/plugin-sdk": ">=0.1.0",
        "zod": "^4.0.0"
    }
}

The deadair.plugin field is how the host finds your entry point. Without it, your package is just a package.

The SDK and zod are PEERS, and that is the one part of this file that is not a matter of taste: the station hands your plugin its own copy of each, linked into the plugins directory beside it, so a class you extend is the class the host checks against. Ship neither. The range that is enforced is your manifest's apiVersion (see Versioning); the package range is advice to whoever installs your devDependencies, which is why it is a floor rather than a caret. How to build, package and install one from outside this repository is on the website, at https://deadair.radio/docs/plugin-development.

The rules​

  1. No ambient I/O. Get at the world through the PluginHost. host.fetch() is your egress, and it will refuse any hostname you did not declare in permissions.network.

    This is a rule, not a cage, and it is never going to be one. The host imports you into its own process, permanently, so global fetch and fs are within reach. Use them and you opt out of the rate limiting, timeouts, redirect checks and audit logging the host does on your behalf, and you make your manifest a lie to the operator who installed you.

  2. Payloads that get stored or sent are JSON-safe. No Date, no class instances, no functions on anything in capabilities/. Durations are integers in milliseconds; dates are ISO-8601 strings. Not because the boundary is a wire (it is a function call) but because those values end up in Postgres and in the console's JSON, and a Date comes back out of a jsonb column as a string either way.

    The host's own methods are under no such rule: host.fetch hands you a real Response, host.signal a real AbortSignal, and speak() returns a real ReadableStream.

  3. Ask for what you need and no more. permissions is shown to the operator before they enable you.

  4. undefined, never null, for "not set".

  5. Do no work in the factory. Build the object, put setup in onLoad(), and register the undo for anything you start.

  6. Secrets are write-only. A secret config field is encrypted at rest and never read back into the settings UI. Read it with host.secrets.get().

  7. A URL you hand back to be stored must be stable. artworkUrl is kept, and the host's art cache is keyed by the URL string itself, so the same image has to mint the same URL every time you are asked about it. If yours carries credentials, fix the varying part — a salt, a nonce, a timestamp — once in init() and reuse it for art. Vary it per call and every mention becomes a new row and another download of identical bytes; nothing errors, it just never caches. resolveStreamUrl is under no such rule, because nothing stores what it returns.

A complete minimal plugin​

An enrichment plugin that looks a track up by ISRC and returns its release year and genres.

import {
    definePlugin,
    type EnrichmentPluginInstance,
    jsonBody,
    Plugin,
    type PluginManifest,
    type TrackEnrichment,
    type TrackRef,
} from '@deadair/plugin-sdk';
import { z } from 'zod';

const configSchema = z.object({
    apiKey: z.string().min(1),
    includeGenres: z.boolean().default(true),
});

const manifest: PluginManifest = {
    id: 'example.recordbin',
    name: 'Record Bin',
    version: '1.0.0',
    capabilities: ['enrichment'],
    apiVersion: '^1.0.0',
    description: 'Release years and genres from the Record Bin catalogue.',
    homepage: 'https://example.com/recordbin',
    permissions: {
        network: ['api.recordbin.example.com'],
        storage: false,
        oauth: false,
    },
    configFields: [
        {
            key: 'apiKey',
            label: 'API key',
            type: 'secret',
            required: true,
            help: 'Create one under Account → Developers.',
        },
        {
            key: 'includeGenres',
            label: 'Include genres',
            type: 'boolean',
            default: true,
        },
    ],
    configSchema,
};

class RecordBinPlugin extends Plugin implements EnrichmentPluginInstance {
    priority = 500;
    matchKeys: EnrichmentPluginInstance['matchKeys'] = ['isrc'];

    private apiKey?: string;
    private includeGenres = true;

    protected async onLoad(): Promise<void> {
        this.apiKey = await this.host.secrets.get('apiKey');
        const config = await this.host.config.get();
        this.includeGenres = config.includeGenres !== false;
        this.host.logger.info('record bin ready');
    }

    async testConnection(): Promise<{ ok: boolean; message?: string }> {
        const response = await this.request('/health');
        return response.ok ? { ok: true, message: 'Connected.' } : { ok: false, message: `HTTP ${response.status}` };
    }

    async enrichTrack(ref: TrackRef): Promise<Partial<TrackEnrichment>> {
        if (!ref.isrc) return {};

        const response = await this.request(`/recordings/${encodeURIComponent(ref.isrc)}`);
        if (!response.ok) {
            await response.body?.cancel().catch(() => {});
            this.host.logger.warn('lookup failed', { isrc: ref.isrc, status: response.status });
            return {};
        }

        const body = await jsonBody<{ year?: number; genres?: string[]; label?: string }>(response);

        return {
            year: body.year,
            label: body.label,
            genres: this.includeGenres ? body.genres : undefined,
            links: [{ label: 'Record Bin', url: `https://example.com/recordbin/${ref.isrc}` }],
        };
    }

    private async request(path: string): Promise<Response> {
        return await this.host.fetch(`https://api.recordbin.example.com${path}`, {
            headers: { authorization: `Bearer ${this.apiKey ?? ''}` },
            timeoutMs: 5_000,
        });
    }
}

export default definePlugin(manifest, () => new RecordBinPlugin());

What host.fetch gives back​

A real Response. Not a copy, not a POJO: await response.json() is how you read JSON, response.body is how you stream audio, and you can hand it to any library that takes one. That is what lets the Spotify SDK's fetch hook be wired straight through instead of adapted in both directions.

Two things about it are the host's doing rather than the platform's, and both are part of the contract:

  • url is the last hop of the redirect chain, not necessarily what you asked for, so relative links in the body resolve against it. redirected tells you whether it moved. The host follows redirects by hand to re-check your allowlist on every hop, so it sets both itself.
  • The body is bounded. timeoutMs covers getting the response (connect, headers, the whole redirect chain) and stops there, because a large body legitimately outlives the call that asked for it. Reading it is bounded separately by an idle deadline between chunks, a total byte cap and a lifetime cap. Exceeding any of them fails the read rather than truncating it, so bytes you get are always bytes the server sent.

A body you are not going to read is one you should cancel(). The host force-cancels whatever you still hold when your plugin is disposed, and the lifetime cap catches the rest, but neither is prompt. On an error path, let it go yourself:

if (!response.ok) {
    await response.body?.cancel().catch(() => {});
    throw new PluginError(`upstream said ${response.status}`).withCode('upstream');
}

jsonBody(response) parses the body and throws with the status, the URL and the start of the body when it will not parse, which beats Unexpected token < in JSON at position 0 when an API answers a 200 with an HTML error page. tryJsonBody(response) returns undefined instead of throwing. Both are async, and both are ordinary functions rather than methods, so the response you hold stays the platform's own.

The host sets a User-Agent for you (<your plugin id>/<version> (deadair)) when you do not set one yourself, because a number of APIs refuse the default one Node sends. Set the header yourself when the upstream's policy asks for more than that: MusicBrainz wants a contact address, which usually means a contact config field the operator fills in. Yours always wins.

An upstream that answers is not a failure: a 404 or a 500 comes back as an ordinary Response with ok: false, and what it means is yours to decide. host.fetch only rejects when there is no response to give you, and when it does it rejects with a PluginError carrying the same PluginErrorCode vocabulary your own failures use, so you can branch on it:

  • upstream — the request never completed, or the server misbehaved (an unreachable host, a redirect chain past the cap, a redirect somewhere your manifest does not allow, a body over the size cap).
  • timeout — the host abandoned the call at its deadline, or the body went quiet for longer than the idle deadline allows.
  • rate_limited — you are over the host's fetch quota by more time than the call had left. retryAfterMs says how long the wait would have been.
  • forbidden — the hostname is not in your permissions.network.
  • config — the URL did not parse, or was not http(s). Usually an operator setting you built it from.

The body's own failures arrive the same way, on the read rather than on the fetch, because that is when they happen.

Let these propagate unless you can do something better with them. The host maps each one to a status and error code for the operator console, and swallowing them turns a precise answer into a silent empty result.

When the body should not arrive whole​

Nothing special. response.body is a ReadableStream<Uint8Array> and you read it, or pass it on, or pipe it through something:

const response = await host.fetch(`${this.baseUrl}/audio/speech`, { method: 'POST', body });
if (!response.ok || response.body === null) {
    await response.body?.cancel().catch(() => {});
    throw new PluginError(`engine said ${response.status}`).withCode('upstream');
}

return { mime: 'audio/mpeg', audio: response.body };

There was once a second egress here, host.streams, with handles, sequence numbers, base64 chunks and an idempotent close(), because a live object could not cross the boundary. All of it is gone: a ReadableStream is already a pull-based stream with backpressure and a cancel, and the boundary is a function call. See CLAUDE.md § "Trust and egress".

What survives is the bounds, and they are the reason it was ever thought about: a body is read outside the deadline that fetched it, so an idle deadline, a lifetime cap and a byte cap are what stop it being an unbounded socket.

Declaring the upstreams you reach​

permissions.network is a list of bare hostnames, and a leading *. is a wildcard subdomain that does not match the apex:

network: ['api.spotify.com', 'accounts.spotify.com'];

Use the object form when the upstream publishes a rate limit. host.fetch then paces you at it, parking each call until there is headroom instead of failing it, and you write no pacer at all:

network: [
    { host: 'musicbrainz.org', ratePerSecond: 1, bucket: 'musicbrainz' },
    { host: '*.musicbrainz.org', ratePerSecond: 1, bucket: 'musicbrainz' },
    'coverartarchive.org',
];

bucket is what makes those first two entries share one allowance. Published limits are usually per service rather than per hostname, and two entries without a shared bucket are two allowances, which is how a plugin ends up at twice the rate it declared and the station gets blocked. Entries with different buckets never pace each other, so a slow upstream does not hold up a fast one.

When the operator picks the address (a mirror, a self-hosted server), name the config field it lives in instead of a hostname:

configFields: [{ key: 'baseUrl', label: 'Server URL', type: 'url' }],
permissions: {
    network: [
        { host: 'musicbrainz.org', ratePerSecond: 1, bucket: 'musicbrainz' },
        { fromConfig: 'baseUrl', ratePerSecond: 10 },
    ],
    ...
}

The host reads the hostname out of that setting when your plugin is initialized, so changing it takes effect on the reinitialization the save triggers. A setting that is blank or unparseable contributes no entry, so an unconfigured plugin is refused exactly as if the host were undeclared, and a wildcard is never accepted from a setting: those come only from a manifest an operator could read before installing.

Order it after the hostname you know, as above. First match wins, so an operator who points baseUrl back at the canonical service still gets the strict rate rather than the mirror's.

A setting holding SEVERAL addresses contributes one entry each, which is how a plugin pointed at a list the operator pasted — a reader of feeds — declares upstreams it cannot know at authoring time. One address per line (a text field), or the JSON array a multiselect stores, and where a line carries more than the address the address is its last |-separated field:

configFields: [{ key: 'feeds', label: 'Feeds', type: 'text' }],
permissions: {
    network: [{ fromConfig: 'feeds', ratePerSecond: 1, bucket: 'rss' }],
    ...
}
https://example.com/rss.xml
world|World news|https://example.com/world.xml

Every rule above is applied per address rather than to the value as a whole, so one mistyped line costs its own upstream and not the rest. Repeats collapse into one entry, or two feeds at one publisher would install a second limiter and quietly double the rate you asked to be paced at. A shared bucket is usually right here, because what is being paced is your own outbound rate rather than any one publisher's published limit.

The rate is a floor on the interval, not a promise of throughput: the host caps every bucket at its own ceiling, so asking to go faster than the host allows does nothing. Parking is spent from the call's budget, which is the other half of this: see below.

Knowing how much time you have​

Every call into your code has a deadline, and it is not a constant: a background job may run on a far longer budget than a request someone is waiting on, and the same method of yours gets called both ways. Two things tell you about it, and they answer different questions.

host.signal is an AbortSignal that fires when the host gives up on the call. It is the host's own signal, not a copy, so honouring it and being abandoned are the same moment rather than two clocks that nearly agree. host.fetch watches it for you; pass it on to anything else of yours that takes one. Outside any host call (from a timer you set yourself) it is a signal that never aborts, because nothing is waiting on that work.

host.remainingMs() is the number behind it, for deciding whether to START something rather than for being interrupted during it. Reach for it when the work is a sequence whose later steps are optional, which is the usual shape for anything paced against a rate-limited API:

const core = await this.lookup(ref);
if (host.remainingMs() < 2_000) return core; // good enough, out of time
return { ...core, ...(await this.enrich(core)) };

What it saves you from is hardcoding a guess at the host's deadline, which means either quitting early on a budget you actually had or being killed halfway through with nothing to return.

It is the host's clock, not an allowance: everything the call does spends from it, including the time host.fetch parks waiting for rate-limit headroom, and host.fetch caps its own timeout by it. Read a small number as advice to wrap up, not as permission to run that long.

When your audio needs a helper to fetch it​

Almost every provider answers resolveStreamUrl out of its own head: it knows a URL, it signs one, it hands it back. host.trackFetcher is for the one shape that cannot — audio that is reachable, but only to a process speaking a protocol you do not.

Spotify is the case it exists for. Its tracks come off the CDN encrypted, so there is no URL to mint at all; a separate binary runs beside the audio player, speaks Spotify's own protocol, and re-serves the track as plain audio over HTTP. You lend it a login, and get back the URL you were going to return anyway:

async resolveStreamUrl(trackId: string): Promise<ProviderStream | undefined> {
    const session = await this.currentSession();          // your account, your refresh
    if (!session) return undefined;                       // not connected yet

    return host.trackFetcher.serve({ trackId, session });
}

The login goes to the fetcher and nowhere else: it is not stored, not written to config, and not readable back out of the host. serve resolves to undefined when the operator's station has no fetcher configured, which you pass straight through — an item nobody can resolve is skipped, not an error.

Requires the trackFetcher permission. Do not reach for it when your audio can simply be fetched. Mint the URL yourself and keep your credentials to yourself, which is both simpler and narrower.

Declaring the permission is also what puts the console's playback authorization card on your plugin's page, where the operator authorizes the fetcher itself. Declaring stream does not: a plugin that mints its own URLs has nothing there to authorize.

Enriching artists and albums, not just tracks​

enrichTrack is the only method an enrichment plugin must write. enrichArtist and enrichAlbum are optional, and worth writing for anything that belongs to the artist or the record rather than to one recording:

async enrichArtist(ref: ArtistRef): Promise<Partial<ArtistEnrichment>> {
    // `mbid` is the id that crosses providers; `providerRef` is your own id
    // from the last time you answered about this artist. Both may be absent
    // the first time anything asks, in which case you have a name.
    const id = ref.providerRef ?? (await this.search(ref.name));
    if (!id) return {};

    const body = jsonBody<{ bio?: string; image?: string }>(await this.request(`/artists/${id}`));
    return { providerRef: id, biography: body.bio, imageUrl: body.image, externalIds: [{ source: 'recordbin', id }] };
}

The reason to split them is cost, not tidiness. The host asks once per artist and once per album, so an artist who appears on forty tracks is one request rather than forty, and the answer is stored against the artist where the console and the DJ can both read it. Anything you return from enrichTrack is still stored against the track, so a single with no album, or a compilation whose tracks were licensed separately, is still described correctly by TrackEnrichment.label.

The providerRef you return is remembered as the id that answer was fetched under, and handed back to you — and only to you — as ref.providerRef next time. That is what turns a second pass into a lookup instead of another search, so state it whenever you have one.

It is deliberately separate from externalIds, which answers a different question: what this thing is called elsewhere. List those in whatever order you like, including ids that are not yours. A local library that reads a MusicBrainz id out of a file's tags should absolutely report it, and doing so must not cost it its own ref.

Facts, and the prose facts are extracted from​

facts and documents are both things to say about a record, and the difference between them is who wrote the sentence.

A fact is a line you composed and are willing to have read out on air unchanged. Keep them short and independently speakable, because that is what happens to them: a talk break is shown a couple of them and the DJ works one in. Compose them only out of things you actually know — a fact assembled from a field you guessed at is a station saying something untrue in a confident voice.

A document is somebody else's prose, verbatim: an encyclopaedia article, a song description, a set of sleeve notes. Nothing reads one aloud and nothing renders one on a page. The host extracts claims from it, checks each claim against the text it came from, and keeps the citation. So:

return {
    documents: [{ url: article.url, title: article.title, text: article.extract, retrievedAt: new Date().toISOString() }],
};

Three rules make that worth doing.

Hand over the prose, not your summary of it. The host stores the document, so a better extraction later costs your upstream nothing, and a claim's quoted span has to occur in the text you supplied or the claim is dropped. A summary you wrote is a span nobody can check.

Plain text. Strip the furniture a reader ignores anyway: navigation, licence footers, reference markers, markup. What is left reaches a language model, and eventually a mouth.

url is a citation, not a link. It is the address an operator opens to check whether the station is telling the truth about a record, so it has to be somewhere a person can actually read the text you sent. A document whose URL is not http(s) is dropped whole.

Searching the open web​

A search plugin has one method, and the caller supplies the subject:

async search(query: SearchQuery): Promise<SearchResult[]> {
    const hits = await this.engine.run(query.query, query.limit, query.recency);
    return hits.map(hit => ({ title: hit.title, snippet: plainText(hit.description), url: hit.url, site: hit.profile }));
}

Three things about it are easy to get wrong.

A snippet is plain text. Search APIs are the worst offenders in the SDK for this: Brave wraps every matched query term in <strong> unless you pass text_decorations=0, and descriptions carry HTML entities either way. Run them through plainText from html.text.ts. What is left reaches a language model, and possibly a mouth.

There is nowhere to put a synthesized answer, deliberately. Several engines sell one — Tavily's answer, SearXNG's first infobox — and it is a paragraph somebody else's model wrote about pages this station never sees. Nothing can check it against a source, so nothing here can carry it. If your plugin has prose worth extracting claims from, declare enrichment too and return it as a documents entry, where the provenance and the quote check already live.

An empty array is an answer. An unconfigured plugin, an engine that is down, a rate limit and a query nothing matched are one outcome to every caller. Throw only for something the operator has to go and fix.

Note what search is not. Looking for something to PLAY is searchTracks on the catalog capability, which answers with provider ids the station can resolve into audio. Nothing a search plugin returns can be scheduled.

Saying what it is like outside​

A weather plugin has one method, and the caller supplies the place:

async getWeather(query: WeatherQuery): Promise<WeatherReading | undefined> {
    const point = await this.resolve(query.place);          // your service, your geocoder
    if (point === undefined) return undefined;              // nowhere of that name

    const forecast = await this.forecast(point, query.days ?? 0);
    return { place: point.name, observedAt: forecast.time, current: forecast.now, days: forecast.days };
}

Three things about it are easy to get wrong.

Everything is metric. Celsius, km/h, and no unit field anywhere. What a station SAYS is a station's own decision, settled where the words are made, beside every other decision about how that station talks. A plugin converting would make the units on the wire depend on which plugin was installed, which is the one thing a capability must not let happen. It is ConfigField.unit's rule one layer down.

You resolve the place, and the host never geocodes. query.place is a name somebody typed. Turning it into coordinates is exactly the per-service quirk this boundary exists to absorb — one service ships a geocoder, one takes coordinates only, one wants its own city ids — and a host that geocoded would have to pick one service to geocode with. Answer with the place as YOUR service resolved it, because that is the part a presenter says out loud and the only evidence anybody has that the right town was found.

A condition is a closed vocabulary. WeatherCondition is ten arms. WMO code 73, an icon string of snow and a numeric condition id are three spellings of one thing, and mapping them is yours. Your service's own word survives beside it as description, which nothing deterministic reads and a model may use.

undefined is an answer, on the same terms as a search plugin's empty array: an unconfigured plugin, a place nothing could resolve and a service that is down are one outcome to every caller. Throw only for something the operator must fix.

Music providers​

A music-provider declares any subset of four sub-capabilities and lists the ones it implements in manifest.capabilities:

  • catalog — searchTracks, getTrack, listPlaylists, getPlaylistTracks. Being browsable, and nothing more: a provider that can be searched but whose audio deadair cannot get at is a legitimate thing to be, and it declares this alone.

    SearchTracksOptions carries genre, yearFrom and yearTo beside limit and offset, structured and provider-neutral: the caller's query is free text going at a title and an artist name, and a style is a different axis. Express them however your upstream does — the host never learns one service's filter dialect, exactly as it never learns a speech engine's knobs.

    Two rules here are load-bearing, and both are about not lying quietly. A filter you cannot apply means you have nothing to offer for that search, so answer []; never ignore it and answer as though it had not been asked for, because the caller merges several providers into one list and nothing marks which rows honoured it. And limit is a TOTAL rather than a page size: page internally if your upstream's own ceiling is lower, since a short answer is indistinguishable from a genuinely thin search.

  • stream — resolveStreamUrl: hand back a complete URL the audio consumer can fetch directly, carrying its own authentication, because it is fetched with no headers from us. A provider that cannot answer it plays its own audio and declares steer instead.

    How you get that URL is your business. Most providers mint one out of their own head. If your audio is reachable only to a process speaking a protocol you do not (Spotify's, whose tracks come off the CDN encrypted) lend the station's fetcher a login and return the URL it gives you back; see When your audio needs a helper to fetch it above.

    This capability is a URL, not bytes. Audio that reaches the station as bytes through Node is the exceptional path and always was, even now that response.body makes it trivial: the audio consumer is Liquidsoap in a sibling container, so a URL it can fetch is zero copies and a stream through here is two.

  • steer — enqueue, play, pause, skip, getPlaybackState. The provider owns the audio output and deadair only tells it what to do. Named from the plugin's side on purpose: deadair's own playout module is the opposite end of this, the one that owns the running order.

  • oauth — getAuthorizeUrl(state) and handleCallback(params). The host owns the redirect endpoint (host.oauth.getRedirectUri()) and the token vault (saveTokens / getTokens); you only build the authorize URL and exchange the code.

import { definePlugin, type MusicProviderPluginInstance, Plugin, type ProviderTrack } from '@deadair/plugin-sdk';

class LibraryPlugin extends Plugin implements MusicProviderPluginInstance {
    async searchTracks(query: string): Promise<ProviderTrack[]> {
        // ...
        return [];
    }
}

Speaking​

A plugin that declares speech turns a line of text into audio. The result is a stream rather than a value, and the usual implementation is to hand back the engine's own response body:

class KokoroPlugin extends Plugin implements SpeechPluginInstance {
    async speak({ text, voice }: SpeechRequest): Promise<SpeechHandle> {
        const response = await this.host.fetch(`${this.baseUrl}/audio/speech`, {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify({ input: text, voice: this.voices[voice ?? ''] ?? this.defaultVoice }),
        });

        if (!response.ok || response.body === null) {
            await response.body?.cancel().catch(() => {});
            throw new PluginError(`TTS answered ${response.status}`).withCode('upstream');
        }

        return { mime: 'audio/mpeg', audio: response.body };
    }
}

That is the whole thing. The audio is never held whole on either side, the host reads it or cancels it, and cancelling reaches the socket without this plugin forwarding anything.

Three things that are easy to get wrong:

  • Let go of a refusal's body. speak throws instead of handing it over, so that cancel() is the only chance anything has to release it.
  • Check the size at the END, not on the first chunk. A server can dribble a short JSON error out in several pieces, so "was any of that plausibly audio" is only answerable once the stream stops. A TransformStream that counts and throws in flush is the shape that fits; failing there fails the render loudly instead of storing a click.
  • mime is the answer, not the request. SpeechRequest.format is a hint you may ignore; what you return in SpeechHandle.mime is what the station stores and later serves, and both consumers of station audio pick their behaviour from that header rather than from the bytes.

Voices​

SpeechRequest.voice is an opaque id the operator chose (host, newsreader). Map it to whatever your engine takes, out of your own config, and fall back to your default for an id you do not know — a missing voice is worth a logger.warn and a rendered line, not a silent station.

The host never interprets that string, and that is deliberate. It is what lets one station voice be a named preset on one engine and a cloned reference clip on another, so swapping engines does not rewrite every persona. Engine-specific tuning belongs in your config, not in the request: the host should not be carrying knobs only one implementation understands.

Implement listVoices() if you have more than one, so the console can draw a list and preview them. It is optional, and a single-voice plugin is a legitimate thing to be.

Set SpeechVoice.spec on each one. It is an opaque token the host does not read — whatever identifies a RENDERING to you, like af_heart@0.95 — and its only job is keying the cached preview at GET /voices/{id}/sample. Without it that cache is keyed on the station voice ID, which is exactly the part that does not change when the operator remaps it underneath, so a remap serves the old voice back forever. Leaving it out is safe for an engine whose voices cannot be reconfigured, and wrong for one whose can.

A voice map wants a list config field, not a text box with a separator in it. Declare a column for the station's name and one for your engine's, and implement suggestConfigOptions() to fill the second from whatever the operator's own server currently reports — published under "<fieldKey>.<columnKey>". That is the difference between a table somebody can complete and one that requires knowing your engine's voice ids by heart, and the shipped plugins get it wrong at your peril: one of them ran with an empty map against a server holding 68 voices for as long as the field was a box. Keep the column string rather than select — a cell with choices renders as an autocomplete, so a value your list cannot enumerate (a blend expression, a clip added a minute ago) stays typeable.

Producing words​

A plugin that declares llm continues a conversation. It is a transport, not a writer: nothing in this capability knows what a break, a show or a running order is, because deciding what to say is the station's business and the shapes that need saying keep multiplying.

class MyModelPlugin extends Plugin implements LlmPluginInstance {
    async generate(request: LlmRequest): Promise<LlmHandle> {
        const stream = streamText({
            model: this.provider(request.model ?? this.defaultModel),
            messages: toProviderMessages(request.messages),
            ...(request.tools === undefined ? {} : { tools: toProviderTools(request.tools) }),
        });

        return {
            text: stream.textStream,
            result: buildResult(stream),
        };
    }
}

The words come back as a stream for a stronger reason than memory: the host serializes generations through one slot and holds it until the words stop arriving, not until generate resolves. On a local model, releasing early lets two generations overlap and both get slower.

A caller that only wants the answer uses collectGeneration(handle), which drains the stream and then returns the result. Reaching for handle.result without draining handle.text is how a caller waits forever, because an undrained provider stream applies backpressure.

Four things that are easy to get wrong:

  • result.text is the authority, not the chunks. A plugin that buffers and one that forwards are both legal, and only the first would agree with whatever a caller concatenated off the stream.
  • Send reasoning_effort only when asked. It means nothing to a plain model and a strict OpenAI-compatible server answers 400 rather than ignoring it. Absent means send nothing at all.
  • request.model overrides your configured one. A station wants a big model for a show and a small one for a station ident, and one plugin holds exactly one config row, so the choice has to travel with the call.
  • Refuse tools you cannot do. Throw unsupported rather than dropping them: a break written without the facts a tool would have supplied is worse than one that fell back to the deterministic writer.
  • A plugin holding several backends qualifies its ids. LlmModelInfo.id is what comes back as LlmRequest.model, so it has to be enough to route on: two backends ship models with similar names, and the host does not inspect the string. Mark exactly one entry default: true, whichever one an unnamed request will actually reach. If the backends are rows an operator adds, a secret column keeps each credential in its own row — see Rows, and a credential inside one.
  • Carry back what the provider signed. Put it in LlmResult.providerState and the host quotes it verbatim onto the assistant turn it builds, as LlmMessage.providerState, without ever reading it. Some providers refuse a tool round trip whose earlier turns arrive stripped of their own thinking blocks or call signatures, and that is a fact about a wire protocol rather than about a conversation. Leave it unset if yours signs nothing, which most do.

Tools​

LlmRequest.tools are declarations, and what comes back in LlmResult.toolCalls is data. The host runs the tool and sends the result back as another message; nothing executable crosses this boundary in either direction, which is why every shape here except LlmHandle is JSON-safe.

When you replay a conversation, an assistant turn that asked for a tool must carry its toolCalls, and the tool turn answering it must carry the matching toolCallId. A model that cannot see its own call has no idea what the message after it is answering.

Implement listModels() if you want tools to work at all. Tool support is a property of the model, not the server — one endpoint commonly serves both a model that can call tools and one that cannot — so the host reads LlmModelInfo.tools to decide whether it may send any. With no listModels, it has no way to learn that and sends none.

Mark one entry default: true. A request that names no model gets yours, and without the mark the host cannot tell which of your models that is: it has to assume the least capable one, so a server with a dozen installed never gets sent tools at all.

Two things worth separating when you write it. Which models exist is usually discoverable — ask the server, rather than making an operator type out what the machine already knows. Which of them accept tools is not, and no endpoint reports it, so that part has to be config. Getting this backwards produces a setup loop with no way in: an operator cannot name a model before they can reach the server, and cannot test the server before they have saved it. Let the address be saved on its own, and say the model names in testConnection — for many plugins it is the only place an operator can learn them.

Decoded audio​

analysis and mixer are the two capabilities that need decoded PCM, which is the one thing that does not happen inside deadair. The expected shape for both is an adapter over a separate program — the bundled one is an HTTP sidecar serving both — in the same relationship a speech plugin has with its engine.

Measuring, and joining​

analyzeTrack(ref) is what analysis requires: bytes in, cue points and loudness out. Two fields in the answer are not measurements and both matter. schemaVersion is what YOU produced rather than the constant this package exports, because an adapter is reporting the analyzer's version and the two drift across an upgrade. complete says whether the whole file was measured, and the host cannot check it: a truncated download measures perfectly confidently and the specific lie it tells is that a record which fades ended cold. Always answering true disables the check silently.

join(request) is what mixer requires: several URLs and a gap in, one piece of audio out, as a mime and a stream. Trim each part to its own cue points unless told not to, and put the silence BETWEEN the parts and never at the ends — what you are making is one item in somebody's running order. Answer unsupported rather than failing where the thing behind you cannot join what it was given; a station that asks has somewhere to go, since a programme whose parts were not joined simply airs as its parts.

Why these are two capabilities and can still be one plugin​

Joining is the same requirement seen from the other end: whatever decodes for you can almost certainly concatenate. So declare both and serve them off one address, which is what the bundled adapter does — splitting it would be two config rows for one process, free to drift apart.

They are two capabilities all the same, because the host picks one plugin per capability. Carried on analysis as an optional method, the station's joiner was whichever plugin the operator chose to MEASURE with: install one that measures better and cannot join, name it, and joining stops with nothing to do about it but choose a worse analyzer. Two keys (analysis.pluginId and render.mixerPluginId) let a station measure with one engine and join with another, and let a mix-only plugin exist at all.

Declaring several capabilities is ordinary here rather than a compromise: the bundled music providers declare three and four.

Configuration fields​

configFields is a declarative form description. The host renders it; plugins never ship UI.

typenotes
stringfree text
textfree text over several lines
urlfree text, validated as a URL
secretwrite-only, encrypted, read via host.secrets.get()
numbernumeric input, bounded by min / max if declared
booleantoggle
selectone of options
multiselectany number of options, stored as a JSON array
listany number of rows over columns; read with parseRows()
notenot an input; static help text in the form

Use dependsOn to hide a field until another one is filled in. Use min and max on a number to say what it will take, which the form bounds the input to. Use configSchema for anything the form cannot express: the host parses the operator's submission with it before storing, so by the time onLoad() runs your config is already valid. Read a multiselect back with parseMultiSelect(config.myField).

Rows, and a credential inside one​

A list is a table the operator adds rows to, declared with columns and stored as a JSON array of objects. A column is string, url, select or secret.

{ key: 'providers', label: 'Providers', type: 'list', columns: [
    { key: 'name', label: 'Name', type: 'string', required: true },
    { key: 'baseUrl', label: 'Address', type: 'url' },
    { key: 'apiKey', label: 'API key', type: 'secret' },
]}

A secret cell behaves exactly as a secret field does and for the same reasons: the console never shows it, the API never returns it, and it is encrypted on its own. It is not in the row. parseRows gives you the ordinary cells, and the credential is fetched separately:

for (const row of parseRows(config.providers)) {
    const apiKey = await readRowSecret(this.host, 'providers', row, 'apiKey');
}

Every row also carries ROW_ID_KEY ($id), minted by the host the first time the row is saved and stable across reorders and edits. It exists so a ciphertext can belong to a row rather than to a position in an array the console rewrites whole on every save. Ignore it and nothing changes; readRowSecret is the only thing that reads it.

One constraint falls out of that: a field key and a column key may not contain a /, because rowSecretKey joins on it. The manifest schema refuses one, so you find out at load rather than at save.

A column that only some rows have​

Where a table's columns are not all about the same row — a provider reached at an address the operator runs, beside one reached where its vendor lives — a column says which rows it applies to:

{ key: 'kind', label: 'Kind', type: 'select', options: [...] },
{ key: 'baseUrl', label: 'Address', type: 'url', dependsOn: 'kind', dependsOnValues: ['server'] },

dependsOn names another column in the same list and dependsOnValues the values of that cell this one applies to; omit the values and any non-empty value will do, which is what a field's dependsOn already means.

This says more than the field-level dependsOn does, and the difference is worth knowing. A field's dependsOn hides a control and the server never reads it. A column's says the cell does not apply: the console will not draw it or send it, and the host will not derive anything from it — so a url column that does not apply to a row contributes no hostname to your network allowlist. An address left behind on a row whose kind was changed would otherwise widen that allowlist by a host you can never call.

Forgiving where being strict would cost you: a target the list does not declare shows the cell, a target cell that is still empty shows the cell, and values with no target are ignored. The empty case is the one to keep in mind — a column has no default, so a row somebody has just added has an empty cell everywhere, and the whole row stays fillable until they say what kind of thing it is. A secret cell that stops applying keeps whatever is stored; nothing here deletes a credential.

Asking for a better control​

control says how a field should be DRAWN where the ordinary input for its type reads badly. It never changes what is stored.

controlonwhat it draws
slidernumbera track, using min, max and step. Both bounds are required
tagsstringchips over a comma-separated line, split and joined by the form

Both are opt-in per field rather than inferred, and the reason is the same each time: a slider is right for a value somebody feels for (a percentage, a trim in decibels) and wrong for one they have to hit exactly, since 3500 out of 0 to 600000 is a pixel. tags suits a set of short names and not a value that can contain a comma. A field that asks for a control it cannot have — a slider with an open end — falls back to the ordinary input rather than failing, because this is a hint about drawing and a spinner beats a blank space.

unit is the same idea one step further, for a number whose stored unit is not the one a person means: bytes is typed in gigabytes, and fraction holds a share between 0 and 1 and is shown as a percentage. The value on the wire is always the declared unit, so nothing downstream learns that the console converts.

rangeWith names the number field that is the upper end of the range this one opens, and is declared on the lower end. They stay two fields with two keys and two independent validations; what it buys is one control with two handles, instead of a relationship that lives only in two labels. Declare it where the range is narrow enough that the whole track is usable — a pair bounded by a sanity guard rather than by intent leaves both handles bunched at one end.

Note what min/max are and are not for a plugin. The host stores what it is handed and your configSchema is what judges it, so these bound the control rather than the value: they belong on a field whose range is a fact about your upstream, and they do not replace a schema. (The station's own settings use the same descriptor and do enforce them, because the settings route is their only writer.)

Choices your server decides​

options is fixed when the manifest is written, which is fine for a closed set and useless for anything the operator's own server knows. Implement suggestConfigOptions() and the form asks you what to offer:

async suggestConfigOptions(): Promise<Record<string, ConfigFieldOption[]>> {
    const models = await this.fetchModels();
    return { model: models.map(id => ({ value: id, label: id })) };
}

Implementing it is the whole opt-in — there is nothing to declare on the field. Return a map so the form costs one call however many fields you have, and leave out a key you have nothing to say about.

What the operator sees depends on the field's type. A string or url becomes free text with suggestions, so a value you could not enumerate is still typeable; a select or multiselect has its declared options replaced. There is a refresh control either way, and a field whose suggestions failed is still a field somebody can use.

Two things to get right, because the failure is a setup loop with no way in:

  • Do not require a field whose value can only be learned from the server. It runs against your SAVED config, like testConnection does, so the operator has to be able to save the address before they can be told what is on it.
  • Answer with what you have rather than throwing. An unreachable upstream should cost the dropdown, not the form.

Versioning​

PLUGIN_API_VERSION is the API version this SDK implements. Your manifest's apiVersion is a semver range (^1.0.0), and the host refuses to load a plugin whose range does not cover its own version.

That is one number, and the package's version is another. @deadair/plugin-sdk is released with the station and carries the station's version, so SDK 0.4.2 is exactly the SDK that station 0.4.2 runs. It moves on every station release whether or not anything here changed, which is why a plugin's peer range is a floor (>=0.1.0) and never a caret: ^0.1.0 would refuse the next station minor for no reason. PLUGIN_API_VERSION moves only when the contract does, and a major step there is the only thing that ever makes a working plugin stop loading.

The published package.json lists two @repo/config-* packages at 0.0.0 among its devDependencies. They are this repository's shared lint and compiler configs, are never installed by anybody who depends on the SDK, and are not on npm.