radio-now-playing 1.0.0

package/dist/cjs/stats.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickSource = pickSource;
+exports.parseStats = parseStats;
+exports.readStatsTitle = readStatsTitle;
+/**
+ * Reading the current track from a station's status endpoint.
+ *
+ * Always prefer this over the stream when a station offers it: it is a small
+ * JSON request that costs the station nothing, where reading the stream —
+ * however briefly — takes one of its listener slots.
+ *
+ * Two formats, told apart by the shape of what comes back rather than by which
+ * URL was configured, because operators put these behind every path
+ * imaginable and a caller should not have to declare which server they run.
+ */
+const types_ts_1 = require("./types.js");
+const title_ts_1 = require("./title.js");
+const icy_ts_1 = require("./icy.js");
+const str = (v) => (typeof v === 'string' && v.trim() !== '' ? v.trim() : null);
+const int = (v) => {
+    const n = typeof v === 'string' ? Number(v) : v;
+    return typeof n === 'number' && Number.isFinite(n) ? n : null;
+};
+/**
+ * Icecast reports every mount from one endpoint, so a server with three
+ * streams answers with three sources and the caller has to say which. Matching
+ * on the tail of `listenurl` means the mount can be given as `/live`, `live`,
+ * or the whole URL, all of which people do.
+ */
+function pickSource(stats, mount) {
+    const raw = stats.icestats?.source;
+    if (!raw)
+        return null;
+    const sources = Array.isArray(raw) ? raw : [raw];
+    if (sources.length === 0)
+        return null;
+    if (!mount)
+        return sources[0];
+    const wanted = mount.startsWith('/') ? mount : `/${mount}`;
+    const hit = sources.find((s) => {
+        const listen = str(s.listenurl);
+        if (!listen)
+            return false;
+        try {
+            return new URL(listen).pathname === wanted;
+        }
+        catch {
+            return listen.endsWith(wanted);
+        }
+    });
+    return hit ?? null;
+}
+function parseStats(body, mount) {
+    if (!body || typeof body !== 'object')
+        return null;
+    if ('icestats' in body) {
+        const source = pickSource(body, mount);
+        if (!source)
+            return null;
+        // `title` is what a source client sends; `yp_currently_playing` is what
+        // Icecast fills in from the directory listing. Either can be the only one.
+        const title = str(source.title) ?? str(source.yp_currently_playing);
+        if (!title || (0, title_ts_1.isPlaceholder)(title))
+            return null;
+        return {
+            title,
+            ...(0, title_ts_1.splitTitle)(title),
+            listeners: int(source.listeners),
+            source: 'icecast',
+            fetchedAt: Date.now(),
+        };
+    }
+    const sc = body;
+    const title = str(sc.songtitle) ?? str(sc.streamtitle);
+    if (!title || (0, title_ts_1.isPlaceholder)(title))
+        return null;
+    return {
+        title,
+        ...(0, title_ts_1.splitTitle)(title),
+        listeners: int(sc.currentlisteners),
+        source: 'shoutcast',
+        fetchedAt: Date.now(),
+    };
+}
+async function readStatsTitle(url, mount, options = {}) {
+    const timeoutMs = options.timeoutMs ?? icy_ts_1.DEFAULT_TIMEOUT_MS;
+    const signal = (0, icy_ts_1.abortAfter)(timeoutMs, options.signal);
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: { 'User-Agent': options.userAgent ?? icy_ts_1.DEFAULT_USER_AGENT, Accept: 'application/json, */*' },
+            redirect: 'follow',
+            signal,
+        });
+    }
+    catch (cause) {
+        const timedOut = cause instanceof Error && cause.name === 'TimeoutError';
+        throw new types_ts_1.RadioError(timedOut ? 'timeout' : 'bad-response', timedOut ? `no response within ${timeoutMs}ms` : `request failed: ${cause.message}`, url, undefined, { cause });
+    }
+    if (!res.ok)
+        throw new types_ts_1.RadioError('http', `status endpoint answered ${res.status}`, url, res.status);
+    // Shoutcast serves this as text/html and Icecast as text/json, so the
+    // content type is no help; parse and find out.
+    let body;
+    try {
+        body = JSON.parse(await res.text());
+    }
+    catch (cause) {
+        throw new types_ts_1.RadioError('bad-response', 'status endpoint did not return JSON (a Shoutcast v1 server needs ?json=1)', url, res.status, { cause });
+    }
+    return parseStats(body, mount);
+}

package/dist/cjs/title.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Turning bytes on the wire into a title a person can read.
+ *
+ * Two problems, both of which every station gets to solve differently.
+ */
+/**
+ * ICY metadata carries no encoding declaration at all. In practice stations
+ * send UTF-8 or Windows-1252 (Latin-1 with the useful punctuation), and there
+ * is no header to tell you which.
+ *
+ * The trick that works: decode as UTF-8 with `fatal: false` and look for the
+ * replacement character. Valid UTF-8 essentially never produces one, and
+ * Windows-1252 text containing accented letters essentially always does — so
+ * a U+FFFD is a reliable signal that this was never UTF-8 to begin with.
+ */
+export declare function decodeMetadata(bytes: Uint8Array, encoding?: 'auto' | 'utf-8' | 'windows-1252'): string;
+/**
+ * Pull `StreamTitle` out of an ICY metadata block.
+ *
+ * The block is a series of `key='value';` pairs, and the format has no
+ * escaping whatsoever — a title containing an apostrophe is simply ambiguous.
+ * Matching up to `';` (quote followed by semicolon) rather than the first
+ * quote is what keeps "Guns N' Roses" intact, and is what every real client
+ * does. A trailing key with no `;` is tolerated because some stations omit it.
+ */
+export declare function parseStreamTitle(block: string): string | null;
+/** Also in the block on some stations, and occasionally the only useful field. */
+export declare function parseStreamUrl(block: string): string | null;
+/**
+ * Split "Artist - Song" on the FIRST separator.
+ *
+ * Splitting on the last one would mangle "Simon & Garfunkel - Scarborough
+ * Fair - Canticle"; splitting on the first mangles "Sunday - Bloody Sunday" by
+ * a band whose name has no dash. Neither is right, because the format carries
+ * no structure — first-separator matches what listeners expect and what other
+ * clients do, and the raw title is always kept alongside.
+ */
+export declare function splitTitle(title: string): {
+    artist: string | null;
+    song: string | null;
+};
+export declare function isPlaceholder(title: string): boolean;

package/dist/cjs/title.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Turning bytes on the wire into a title a person can read.
+ *
+ * Two problems, both of which every station gets to solve differently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeMetadata = decodeMetadata;
+exports.parseStreamTitle = parseStreamTitle;
+exports.parseStreamUrl = parseStreamUrl;
+exports.splitTitle = splitTitle;
+exports.isPlaceholder = isPlaceholder;
+/**
+ * ICY metadata carries no encoding declaration at all. In practice stations
+ * send UTF-8 or Windows-1252 (Latin-1 with the useful punctuation), and there
+ * is no header to tell you which.
+ *
+ * The trick that works: decode as UTF-8 with `fatal: false` and look for the
+ * replacement character. Valid UTF-8 essentially never produces one, and
+ * Windows-1252 text containing accented letters essentially always does — so
+ * a U+FFFD is a reliable signal that this was never UTF-8 to begin with.
+ */
+function decodeMetadata(bytes, encoding = 'auto') {
+    if (encoding !== 'auto')
+        return new TextDecoder(encoding).decode(bytes);
+    const utf8 = new TextDecoder('utf-8').decode(bytes);
+    if (!utf8.includes('�'))
+        return utf8;
+    try {
+        return new TextDecoder('windows-1252').decode(bytes);
+    }
+    catch {
+        // A Node build without full ICU has only UTF-8. Mojibake beats throwing.
+        return utf8;
+    }
+}
+/**
+ * Pull `StreamTitle` out of an ICY metadata block.
+ *
+ * The block is a series of `key='value';` pairs, and the format has no
+ * escaping whatsoever — a title containing an apostrophe is simply ambiguous.
+ * Matching up to `';` (quote followed by semicolon) rather than the first
+ * quote is what keeps "Guns N' Roses" intact, and is what every real client
+ * does. A trailing key with no `;` is tolerated because some stations omit it.
+ */
+function parseStreamTitle(block) {
+    const terminated = /StreamTitle='([\s\S]*?)';/.exec(block);
+    const unterminated = terminated ? null : /StreamTitle='([\s\S]*)$/.exec(block);
+    const raw = (terminated ?? unterminated)?.[1];
+    if (raw === undefined)
+        return null;
+    // Stations pad the block with NUL bytes to a 16-byte boundary. The trailing
+    // quote only needs removing in the unterminated case — with no `';` to
+    // anchor on, the greedy match swallows the closing quote too.
+    let title = raw.replace(/\0+$/, '');
+    if (unterminated)
+        title = title.replace(/'$/, '');
+    title = title.trim();
+    return title === '' ? null : title;
+}
+/** Also in the block on some stations, and occasionally the only useful field. */
+function parseStreamUrl(block) {
+    const m = /StreamUrl='([\s\S]*?)';/.exec(block);
+    const value = m?.[1]?.replace(/\0+$/, '').trim();
+    return value ? value : null;
+}
+/**
+ * Split "Artist - Song" on the FIRST separator.
+ *
+ * Splitting on the last one would mangle "Simon & Garfunkel - Scarborough
+ * Fair - Canticle"; splitting on the first mangles "Sunday - Bloody Sunday" by
+ * a band whose name has no dash. Neither is right, because the format carries
+ * no structure — first-separator matches what listeners expect and what other
+ * clients do, and the raw title is always kept alongside.
+ */
+function splitTitle(title) {
+    // Real separators are surrounded by spaces. A bare hyphen is usually inside
+    // a word ("Jay-Z", "re-mastered") and must not split.
+    const m = /^(.+?)\s+[-–—]\s+(.+)$/.exec(title);
+    if (!m)
+        return { artist: null, song: null };
+    const artist = m[1].trim();
+    const song = m[2].trim();
+    return artist && song ? { artist, song } : { artist: null, song: null };
+}
+/**
+ * Some stations park an advert, the station name, or a literal "Unknown" in
+ * the title slot between songs. Callers usually want to show the last real
+ * track instead of that, so the obvious placeholders are reported as empty.
+ */
+const PLACEHOLDERS = /^(unknown|unknown artist|n\/?a|none|no title|null|-|\.+)$/i;
+function isPlaceholder(title) {
+    return PLACEHOLDERS.test(title.trim());
+}

package/dist/cjs/types.d.ts

@@ -0,0 +1,63 @@
+/** How the title was obtained, which is worth knowing when one source lies. */
+export type Source = 'icy' | 'shoutcast' | 'icecast';
+export type NowPlaying = {
+    /** The raw `StreamTitle`, exactly as the station sent it. */
+    title: string;
+    /**
+     * `title` split on the first " - ". A heuristic, and a lossy one: stations
+     * are inconsistent, and a song legitimately called "Sunday - Bloody Sunday"
+     * splits wrongly. Always keep `title` for display and treat these as a hint.
+     */
+    artist: string | null;
+    song: string | null;
+    /** Current listeners, where the source reports it. Never available over ICY. */
+    listeners: number | null;
+    source: Source;
+    /** When this was read, as epoch milliseconds. */
+    fetchedAt: number;
+};
+export type Station = {
+    /** The stream URL a player would open. */
+    url: string;
+    /**
+     * A Shoutcast or Icecast status endpoint. Preferred when present: it is a
+     * small JSON request that does not occupy one of the station's listener
+     * slots, where reading the stream briefly does.
+     *
+     * Shoutcast: `http://host:8000/stats?sid=1&json=1`
+     * Icecast:   `http://host:8000/status-json.xsl`
+     */
+    statsUrl?: string;
+    /** Icecast serves every mount from one endpoint; this picks yours. */
+    mount?: string;
+};
+export type Options = {
+    /** Abandon the request after this many milliseconds. Default 6000. */
+    timeoutMs?: number;
+    /**
+     * Give up after reading this many bytes of audio while waiting for a
+     * metadata block. Default 262144 (256 KiB) — enough for any sane
+     * `icy-metaint`, and a hard stop on a station that advertises a huge one.
+     */
+    maxBytes?: number;
+    /**
+     * How to decode metadata bytes. ICY has no encoding field and stations
+     * disagree; the default tries UTF-8 and falls back to Windows-1252 when that
+     * produces replacement characters, which is right far more often than
+     * committing to either.
+     */
+    encoding?: 'auto' | 'utf-8' | 'windows-1252';
+    /** Sent as User-Agent. Some stations reject a blank or default one. */
+    userAgent?: string;
+    /** Cancel from outside; combined with `timeoutMs`, whichever fires first. */
+    signal?: AbortSignal;
+};
+/** Thrown for transport and protocol failures — never for "no title yet". */
+export declare class RadioError extends Error {
+    readonly code: 'timeout' | 'http' | 'no-metadata' | 'bad-response';
+    readonly url: string;
+    readonly status?: number;
+    constructor(code: RadioError['code'], message: string, url: string, status?: number, options?: {
+        cause?: unknown;
+    });
+}

package/dist/cjs/types.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RadioError = void 0;
+/** Thrown for transport and protocol failures — never for "no title yet". */
+class RadioError extends Error {
+    code;
+    url;
+    status;
+    constructor(code, message, url, status, options) {
+        super(message, options);
+        this.name = 'RadioError';
+        this.code = code;
+        this.url = url;
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+exports.RadioError = RadioError;

package/dist/esm/cache.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The shared cache — the reason this package exists as more than a parser.
+ *
+ * A web page showing "now playing" is polled by every visitor, and each of
+ * those polls must not become a request to the station. This collapses them:
+ * one upstream request per station per TTL, no matter how many callers arrive,
+ * including callers that arrive while a request is already in flight.
+ *
+ * It also never throws and never blanks a known title on failure. A dropped
+ * request does not mean the music stopped, and a UI that flickers to empty
+ * every time a station hiccups is worse than one that is fifteen seconds
+ * behind.
+ */
+import type { NowPlaying, Options, Station } from './types.ts';
+import { RadioError } from './types.ts';
+export type CacheEntry = {
+    /** The last title known, or null if none has ever been read. */
+    track: NowPlaying | null;
+    /** True when the most recent attempt failed, so `track` is older than `checkedAt`. */
+    stale: boolean;
+    /** Why the most recent attempt failed, if it did. */
+    error: RadioError | null;
+    /** When an attempt last finished, successful or not. Epoch milliseconds. */
+    checkedAt: number;
+};
+export type ClientOptions = Options & {
+    /** Never ask a station more often than this. Default 15000. */
+    ttlMs?: number;
+    /** See `nowPlaying`: read the stream when a status endpoint fails. Default false. */
+    fallbackToStream?: boolean;
+};
+export declare class NowPlayingClient {
+    #private;
+    readonly ttlMs: number;
+    constructor(options?: ClientOptions);
+    /**
+     * Never rejects. A station that is down, slow or lying yields the last good
+     * title with `stale: true` and the failure in `error`.
+     */
+    get(station: string | Station): Promise<CacheEntry>;
+    /** What is cached right now, without triggering a lookup. */
+    peek(station: string | Station): CacheEntry | undefined;
+    /** Forget everything, or one station. */
+    clear(station?: string | Station): void;
+}

package/dist/esm/icy.d.ts

@@ -0,0 +1,12 @@
+import type { NowPlaying, Options } from './types.ts';
+export declare const DEFAULT_TIMEOUT_MS = 6000;
+/** 256 KiB. A sane station uses 8–64 KiB; this is the stop for one that does not. */
+export declare const DEFAULT_MAX_BYTES = 262144;
+export declare const DEFAULT_USER_AGENT = "radio-now-playing (+https://www.npmjs.com/package/radio-now-playing)";
+/**
+ * Combines the caller's signal with a timeout. `AbortSignal.any` needs Node 20,
+ * which is this package's floor anyway, and unlike a hand-rolled listener it
+ * cannot leave a listener attached to a caller's long-lived signal.
+ */
+export declare function abortAfter(timeoutMs: number, external?: AbortSignal): AbortSignal;
+export declare function readIcyTitle(url: string, options?: Options): Promise<NowPlaying | null>;

package/dist/esm/icy.js

@@ -0,0 +1,125 @@
+/**
+ * Reading the current track out of the audio stream itself.
+ *
+ * A Shoutcast or Icecast stream asked with `Icy-MetaData: 1` answers with an
+ * `icy-metaint` header and then interleaves metadata into the audio: every
+ * `icy-metaint` bytes of audio are followed by one length byte (in units of
+ * 16) and that many bytes of `key='value';` text. So the whole job is: skip
+ * that much audio, read the block, hang up.
+ *
+ * "Hang up" is the part that matters and the part other libraries skip. A
+ * station has a finite number of listener slots — a few hundred, typically —
+ * and an open stream occupies one whether or not anyone is listening to it.
+ * This aborts the request as soon as the block is in hand, so a lookup holds a
+ * slot for well under a second instead of forever.
+ */
+import { RadioError } from "./types.js";
+import { decodeMetadata, parseStreamTitle, splitTitle, isPlaceholder } from "./title.js";
+export const DEFAULT_TIMEOUT_MS = 6000;
+/** 256 KiB. A sane station uses 8–64 KiB; this is the stop for one that does not. */
+export const DEFAULT_MAX_BYTES = 262_144;
+export const DEFAULT_USER_AGENT = 'radio-now-playing (+https://www.npmjs.com/package/radio-now-playing)';
+/** A metadata block is one length byte times 16, so at most 255 × 16 bytes. */
+const MAX_BLOCK = 255 * 16;
+/**
+ * Combines the caller's signal with a timeout. `AbortSignal.any` needs Node 20,
+ * which is this package's floor anyway, and unlike a hand-rolled listener it
+ * cannot leave a listener attached to a caller's long-lived signal.
+ */
+export function abortAfter(timeoutMs, external) {
+    const timer = AbortSignal.timeout(timeoutMs);
+    return external ? AbortSignal.any([timer, external]) : timer;
+}
+export async function readIcyTitle(url, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const signal = abortAfter(timeoutMs, options.signal);
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: {
+                'Icy-MetaData': '1',
+                'User-Agent': options.userAgent ?? DEFAULT_USER_AGENT,
+                // Without this some CDN-fronted mounts answer with a playlist.
+                Accept: '*/*',
+            },
+            redirect: 'follow',
+            signal,
+        });
+    }
+    catch (cause) {
+        const timedOut = cause instanceof Error && cause.name === 'TimeoutError';
+        throw new RadioError(timedOut ? 'timeout' : 'bad-response', timedOut ? `no response within ${timeoutMs}ms` : `request failed: ${cause.message}`, url, undefined, { cause });
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        throw new RadioError('http', `station answered ${res.status}`, url, res.status);
+    }
+    const interval = Number(res.headers.get('icy-metaint') ?? 0);
+    if (!Number.isInteger(interval) || interval <= 0 || !res.body) {
+        await res.body?.cancel().catch(() => { });
+        // Not an error the caller did anything wrong: plenty of streams simply
+        // carry no metadata. It is still not something a retry will fix, so it is
+        // distinguishable from "nothing playing".
+        throw new RadioError('no-metadata', 'stream does not send ICY metadata', url);
+    }
+    if (interval + 1 + MAX_BLOCK > maxBytes) {
+        await res.body.cancel().catch(() => { });
+        throw new RadioError('no-metadata', `icy-metaint is ${interval}, which needs more than the ${maxBytes}-byte budget`, url);
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (total < maxBytes) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            chunks.push(value);
+            total += value.length;
+            // The length byte lives at exactly `interval`, so there is nothing to
+            // look at until the audio ahead of it has all arrived.
+            if (total <= interval)
+                continue;
+            const buf = concat(chunks, total);
+            const length = buf[interval] * 16;
+            // A zero-length block is the station saying "nothing has changed". It is
+            // a valid answer meaning "no title right now", not a failure.
+            if (length === 0)
+                return null;
+            if (buf.length < interval + 1 + length)
+                continue;
+            const block = decodeMetadata(buf.subarray(interval + 1, interval + 1 + length), options.encoding);
+            const title = parseStreamTitle(block);
+            if (title === null || isPlaceholder(title))
+                return null;
+            return { title, ...splitTitle(title), listeners: null, source: 'icy', fetchedAt: Date.now() };
+        }
+        return null;
+    }
+    catch (cause) {
+        if (cause instanceof Error && (cause.name === 'TimeoutError' || cause.name === 'AbortError')) {
+            throw new RadioError('timeout', `stopped reading after ${timeoutMs}ms`, url, undefined, { cause });
+        }
+        throw new RadioError('bad-response', `stream ended badly: ${cause.message}`, url, undefined, { cause });
+    }
+    finally {
+        // Cancelling the reader closes the socket, which is what gives the
+        // listener slot back. Without it the connection lingers until the station
+        // times it out.
+        await reader.cancel().catch(() => { });
+    }
+}
+function concat(chunks, total) {
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.length;
+    }
+    return out;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * radio-now-playing — what is playing on an internet radio station, right now.
+ *
+ * Zero dependencies, native fetch, and it hangs up as soon as it has the
+ * answer so a lookup does not sit in one of the station's listener slots.
+ *
+ * ```ts
+ * import { nowPlaying, NowPlayingClient } from 'radio-now-playing';
+ *
+ * await nowPlaying('https://example.com/stream');
+ * // → { title: 'Miles Davis - So What', artist: 'Miles Davis', … }
+ *
+ * const radio = new NowPlayingClient({ ttlMs: 15_000 });
+ * await radio.get(station);   // a hundred callers, one request upstream
+ * ```
+ */
+export { nowPlaying } from './lookup.ts';
+export type { LookupOptions } from './lookup.ts';
+export { NowPlayingClient } from './cache.ts';
+export type { CacheEntry, ClientOptions } from './cache.ts';
+export { readIcyTitle, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_BYTES, DEFAULT_USER_AGENT } from './icy.ts';
+export { readStatsTitle, parseStats, pickSource } from './stats.ts';
+export { parseStreamTitle, parseStreamUrl, splitTitle, decodeMetadata, isPlaceholder } from './title.ts';
+export { RadioError } from './types.ts';
+export type { NowPlaying, Options, Source, Station } from './types.ts';

package/dist/esm/index.js

@@ -0,0 +1,24 @@
+/**
+ * radio-now-playing — what is playing on an internet radio station, right now.
+ *
+ * Zero dependencies, native fetch, and it hangs up as soon as it has the
+ * answer so a lookup does not sit in one of the station's listener slots.
+ *
+ * ```ts
+ * import { nowPlaying, NowPlayingClient } from 'radio-now-playing';
+ *
+ * await nowPlaying('https://example.com/stream');
+ * // → { title: 'Miles Davis - So What', artist: 'Miles Davis', … }
+ *
+ * const radio = new NowPlayingClient({ ttlMs: 15_000 });
+ * await radio.get(station);   // a hundred callers, one request upstream
+ * ```
+ */
+export { nowPlaying } from "./lookup.js";
+export { NowPlayingClient } from "./cache.js";
+export { readIcyTitle, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_BYTES, DEFAULT_USER_AGENT } from "./icy.js";
+export { readStatsTitle, parseStats, pickSource } from "./stats.js";
+// Exported because they are useful on their own: plenty of people already have
+// the metadata block or the title and only need it parsed properly.
+export { parseStreamTitle, parseStreamUrl, splitTitle, decodeMetadata, isPlaceholder } from "./title.js";
+export { RadioError } from "./types.js";

package/dist/esm/lookup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The single entry point most callers want: given a station, what is playing?
+ */
+import type { NowPlaying, Options, Station } from './types.ts';
+export type LookupOptions = Options & {
+    /**
+     * Read the stream when the status endpoint fails.
+     *
+     * Off by default, deliberately. Configuring `statsUrl` is how a caller says
+     * "do not take one of my station's listener slots"; silently taking one
+     * anyway the moment the endpoint hiccups would undo that at exactly the
+     * moment the station is already having a bad time.
+     */
+    fallbackToStream?: boolean;
+};
+export declare function nowPlaying(station: string | Station, options?: LookupOptions): Promise<NowPlaying | null>;

package/dist/esm/lookup.js

@@ -0,0 +1,15 @@
+import { readIcyTitle } from "./icy.js";
+import { readStatsTitle } from "./stats.js";
+export async function nowPlaying(station, options = {}) {
+    const target = typeof station === 'string' ? { url: station } : station;
+    if (!target.statsUrl)
+        return readIcyTitle(target.url, options);
+    try {
+        return await readStatsTitle(target.statsUrl, target.mount, options);
+    }
+    catch (err) {
+        if (!options.fallbackToStream)
+            throw err;
+        return readIcyTitle(target.url, options);
+    }
+}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/stats.d.ts

@@ -0,0 +1,24 @@
+import type { NowPlaying, Options } from './types.ts';
+/** Icecast: `/status-json.xsl`. */
+type IcecastSource = {
+    listenurl?: unknown;
+    title?: unknown;
+    yp_currently_playing?: unknown;
+    server_name?: unknown;
+    listeners?: unknown;
+};
+type IcecastStats = {
+    icestats?: {
+        source?: IcecastSource | IcecastSource[];
+    };
+};
+/**
+ * Icecast reports every mount from one endpoint, so a server with three
+ * streams answers with three sources and the caller has to say which. Matching
+ * on the tail of `listenurl` means the mount can be given as `/live`, `live`,
+ * or the whole URL, all of which people do.
+ */
+export declare function pickSource(stats: IcecastStats, mount?: string): IcecastSource | null;
+export declare function parseStats(body: unknown, mount?: string): NowPlaying | null;
+export declare function readStatsTitle(url: string, mount?: string, options?: Options): Promise<NowPlaying | null>;
+export {};