radio-now-playing 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this package are documented here. This project follows
+[semantic versioning](https://semver.org/): the public surface is everything
+exported from `radio-now-playing`, and the shape of `NowPlaying`, `CacheEntry`
+and `RadioError`.
+
+## 1.0.0 — 2026-08-23
+
+First release.
+
+- `nowPlaying(station)` — read the current track from a stream's ICY metadata
+  or from a Shoutcast/Icecast status endpoint, closing the connection as soon
+  as the answer is in hand.
+- `NowPlayingClient` — a TTL cache with request coalescing that never rejects
+  and never blanks a known title on a failed refresh.
+- Windows-1252 fallback for metadata that is not UTF-8.
+- `parseStreamTitle`, `parseStreamUrl`, `splitTitle`, `decodeMetadata` and
+  `isPlaceholder` exported for callers who already have the bytes.
+- Dual ESM/CommonJS build with types for both.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kotatko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# radio-now-playing
+
+[![npm](https://img.shields.io/npm/v/radio-now-playing)](https://www.npmjs.com/package/radio-now-playing)
+[![ci](https://github.com/K0tatkoo/radio-now-playing/actions/workflows/ci.yml/badge.svg)](https://github.com/K0tatkoo/radio-now-playing/actions/workflows/ci.yml)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](./package.json)
+
+What is playing on an internet radio station, right now.
+
+Reads the track title from a Shoutcast or Icecast station — either out of the
+stream's own ICY metadata or from its status endpoint — and **hangs up as soon
+as it has the answer**, so a lookup does not sit in one of the station's
+listener slots. Ships a cache that collapses any number of callers into one
+request upstream.
+
+Zero dependencies. Native `fetch`. TypeScript types included. ESM and CommonJS.
+
+```bash
+npm install radio-now-playing
+```
+
+## Quick start
+
+```js
+import { nowPlaying } from 'radio-now-playing';
+
+const track = await nowPlaying('https://example.com/stream');
+console.log(track);
+// {
+//   title: 'Miles Davis - So What',
+//   artist: 'Miles Davis',
+//   song: 'So What',
+//   listeners: null,
+//   source: 'icy',
+//   fetchedAt: 1755960000000
+// }
+```
+
+`null` means the station answered and nothing is playing. A station that is
+unreachable, or that carries no metadata at all, **throws** a `RadioError` —
+those are different situations and you usually want to treat them differently.
+
+## Serving it to a web page
+
+Do not call `nowPlaying` per visitor. A page polled by a hundred people would
+be a hundred requests to a station that has a few hundred listener slots
+total. Use the client:
+
+```js
+import { NowPlayingClient } from 'radio-now-playing';
+
+const radio = new NowPlayingClient({ ttlMs: 15_000 });
+
+app.get('/api/now', async (req, res) => {
+  const { track, stale, checkedAt } = await radio.get(station);
+  res.json({ title: track?.title ?? null, stale, checkedAt });
+});
+```
+
+- At most one request upstream per station per `ttlMs`, however many callers
+  arrive — including callers that arrive *while a request is in flight*.
+- `get()` **never rejects**. If the station is down you get the last title you
+  had, with `stale: true` and the failure in `error`. A dropped request does
+  not mean the music stopped, and a UI that blanks every time a station
+  hiccups is worse than one that is fifteen seconds behind.
+
+## Use the status endpoint when the station has one
+
+Reading the stream, however briefly, takes one of the station's listener
+slots. A status endpoint does not. If you know the station's, give it:
+
+```js
+// Shoutcast v2
+await nowPlaying({
+  url: 'https://example.com/stream',
+  statsUrl: 'http://example.com:8000/stats?sid=1&json=1',
+});
+
+// Icecast — one endpoint serves every mount, so name yours
+await nowPlaying({
+  url: 'https://example.com/live',
+  statsUrl: 'http://example.com:8000/status-json.xsl',
+  mount: '/live',
+});
+```
+
+The two formats are told apart by the shape of the response, not by the URL,
+so you do not have to declare which server the station runs.
+
+Status endpoints also report **listener counts**, which ICY never does.
+
+If the status endpoint fails, this throws rather than quietly reading the
+stream instead — configuring `statsUrl` is how you say "do not take one of my
+listener slots", and undoing that at the exact moment the station is already
+struggling is not helpful. Opt in with `{ fallbackToStream: true }` if you
+would rather have the title.
+
+## API
+
+### `nowPlaying(station, options?): Promise<NowPlaying | null>`
+
+`station` is a URL string, or `{ url, statsUrl?, mount? }`.
+
+| Option | Default | |
+|---|---|---|
+| `timeoutMs` | `6000` | Abandon the request after this long. |
+| `maxBytes` | `262144` | Stop reading audio while waiting for a metadata block. |
+| `encoding` | `'auto'` | `'auto'`, `'utf-8'` or `'windows-1252'`. See below. |
+| `userAgent` | package name | Some stations reject a blank one. |
+| `signal` | — | An `AbortSignal` of your own, combined with `timeoutMs`. |
+| `fallbackToStream` | `false` | Read the stream if the status endpoint fails. |
+
+### `new NowPlayingClient(options?)`
+
+Takes everything above plus `ttlMs` (default `15000`).
+
+- `get(station)` → `Promise<CacheEntry>`, never rejects
+- `peek(station)` → `CacheEntry | undefined`, no lookup
+- `clear(station?)` → forget one station, or all of them
+
+```ts
+type CacheEntry = {
+  track: NowPlaying | null;
+  stale: boolean;          // the last attempt failed; track is older than checkedAt
+  error: RadioError | null;
+  checkedAt: number;       // when an attempt last finished, successful or not
+};
+```
+
+### Parsing helpers
+
+Exported because plenty of people already have the bytes and only need them
+read properly:
+
+```js
+import { parseStreamTitle, splitTitle, decodeMetadata } from 'radio-now-playing';
+
+parseStreamTitle("StreamTitle='Guns N' Roses - November Rain';");
+// → "Guns N' Roses - November Rain"
+
+splitTitle('Miles Davis - So What');
+// → { artist: 'Miles Davis', song: 'So What' }
+```
+
+### `RadioError`
+
+Thrown for transport and protocol failures, never for "nothing is playing".
+`error.code` is one of:
+
+| code | meaning |
+|---|---|
+| `timeout` | No answer, or no metadata block, in time. |
+| `http` | The station answered with an error status (see `error.status`). |
+| `no-metadata` | The stream sends no `icy-metaint` at all. Retrying will not help. |
+| `bad-response` | Connection failure, or a status endpoint that did not return JSON. |
+
+## Things that will bite you, and what this does about them
+
+**ICY has no encoding field.** Stations send UTF-8 or Windows-1252 and there
+is no header saying which, so naive UTF-8 decoding turns Björk into Bj�rk. The
+default `'auto'` decodes as UTF-8, and falls back to Windows-1252 if the result
+contains a replacement character — valid UTF-8 essentially never produces one,
+and Windows-1252 text with accented letters essentially always does.
+
+**"Artist - Song" is a convention, not a format.** `splitTitle` splits on the
+first *spaced* separator, so `Jay-Z` and `re-mastered` stay intact but
+`Scarborough Fair - Canticle` keeps its dash in the song rather than the
+artist. There is no parse that is right for every station, which is why the
+raw `title` is always there too — show that, and treat `artist`/`song` as a
+hint.
+
+**Stations park junk in the title between songs.** `Unknown`, `N/A`, `-` and
+friends are reported as nothing playing so you can keep showing the last real
+track.
+
+**A zero-length metadata block is not an error.** It is the station saying
+nothing has changed, and it means "no title right now".
+
+## Requirements and limits
+
+- **Node 20.3+.** Uses `fetch`, `AbortSignal.any` and `TextDecoder`. The
+  bundled types reference `AbortSignal`, so a TypeScript consumer needs
+  `@types/node` or `"lib": ["dom"]` — any Node project already has the first. No
+  browser build: browsers cannot set the `Icy-MetaData` header or read a
+  cross-origin stream body, so this is a server-side library by nature.
+- **Shoutcast v1 servers that answer `ICY 200 OK`** instead of an HTTP status
+  line cannot be read by `fetch` at all — nothing built on the platform HTTP
+  client can. Modern Shoutcast (v2, which answers `HTTP/1.0 200 OK`) and every
+  Icecast are fine. For a genuine v1 server, use its `/stats?json=1` endpoint.
+- Playlist URLs (`.m3u`, `.pls`) are not resolved. Point at the stream.
+
+## Prior art
+
+[`icy`](https://npmjs.com/package/icy) and
+[`icecast-parser`](https://npmjs.com/package/icecast-parser) give you a
+*streaming client* that stays connected and emits metadata as it changes.
+That is the right tool if you are playing or relaying the audio; it is the
+wrong one for a "what's playing" endpoint, because it holds a listener slot
+for as long as it runs.
+[`node-internet-radio`](https://npmjs.com/package/node-internet-radio) does the
+same one-shot job as this, with callbacks and a dependency on the deprecated
+`request`.
+
+## Contributing
+
+```bash
+npm install
+npm run check     # typecheck, 46 unit tests, 7 packaging tests
+```
+
+The tests run against a real HTTP server on loopback rather than a mocked
+`fetch` — this is a protocol reader, and mocking the transport would test the
+mock. `test/station.ts` is a fake station that serves genuine ICY-interleaved
+audio and the specific ways real stations misbehave.
+
+`npm run check` also runs in `prepublishOnly`, so a broken build cannot be
+published by accident.
+
+## Licence
+
+MIT

package/dist/cjs/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/cjs/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/cjs/icy.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_USER_AGENT = exports.DEFAULT_MAX_BYTES = exports.DEFAULT_TIMEOUT_MS = void 0;
+exports.abortAfter = abortAfter;
+exports.readIcyTitle = readIcyTitle;
+/**
+ * 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.
+ */
+const types_ts_1 = require("./types.js");
+const title_ts_1 = require("./title.js");
+exports.DEFAULT_TIMEOUT_MS = 6000;
+/** 256 KiB. A sane station uses 8–64 KiB; this is the stop for one that does not. */
+exports.DEFAULT_MAX_BYTES = 262_144;
+exports.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.
+ */
+function abortAfter(timeoutMs, external) {
+    const timer = AbortSignal.timeout(timeoutMs);
+    return external ? AbortSignal.any([timer, external]) : timer;
+}
+async function readIcyTitle(url, options = {}) {
+    const timeoutMs = options.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+    const maxBytes = options.maxBytes ?? exports.DEFAULT_MAX_BYTES;
+    const signal = abortAfter(timeoutMs, options.signal);
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: {
+                'Icy-MetaData': '1',
+                'User-Agent': options.userAgent ?? exports.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 types_ts_1.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 types_ts_1.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 types_ts_1.RadioError('no-metadata', 'stream does not send ICY metadata', url);
+    }
+    if (interval + 1 + MAX_BLOCK > maxBytes) {
+        await res.body.cancel().catch(() => { });
+        throw new types_ts_1.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 = (0, title_ts_1.decodeMetadata)(buf.subarray(interval + 1, interval + 1 + length), options.encoding);
+            const title = (0, title_ts_1.parseStreamTitle)(block);
+            if (title === null || (0, title_ts_1.isPlaceholder)(title))
+                return null;
+            return { title, ...(0, title_ts_1.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 types_ts_1.RadioError('timeout', `stopped reading after ${timeoutMs}ms`, url, undefined, { cause });
+        }
+        throw new types_ts_1.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/cjs/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/cjs/index.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RadioError = exports.isPlaceholder = exports.decodeMetadata = exports.splitTitle = exports.parseStreamUrl = exports.parseStreamTitle = exports.pickSource = exports.parseStats = exports.readStatsTitle = exports.DEFAULT_USER_AGENT = exports.DEFAULT_MAX_BYTES = exports.DEFAULT_TIMEOUT_MS = exports.readIcyTitle = exports.NowPlayingClient = exports.nowPlaying = void 0;
+/**
+ * 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
+ * ```
+ */
+var lookup_ts_1 = require("./lookup.js");
+Object.defineProperty(exports, "nowPlaying", { enumerable: true, get: function () { return lookup_ts_1.nowPlaying; } });
+var cache_ts_1 = require("./cache.js");
+Object.defineProperty(exports, "NowPlayingClient", { enumerable: true, get: function () { return cache_ts_1.NowPlayingClient; } });
+var icy_ts_1 = require("./icy.js");
+Object.defineProperty(exports, "readIcyTitle", { enumerable: true, get: function () { return icy_ts_1.readIcyTitle; } });
+Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: function () { return icy_ts_1.DEFAULT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "DEFAULT_MAX_BYTES", { enumerable: true, get: function () { return icy_ts_1.DEFAULT_MAX_BYTES; } });
+Object.defineProperty(exports, "DEFAULT_USER_AGENT", { enumerable: true, get: function () { return icy_ts_1.DEFAULT_USER_AGENT; } });
+var stats_ts_1 = require("./stats.js");
+Object.defineProperty(exports, "readStatsTitle", { enumerable: true, get: function () { return stats_ts_1.readStatsTitle; } });
+Object.defineProperty(exports, "parseStats", { enumerable: true, get: function () { return stats_ts_1.parseStats; } });
+Object.defineProperty(exports, "pickSource", { enumerable: true, get: function () { return stats_ts_1.pickSource; } });
+// 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.
+var title_ts_1 = require("./title.js");
+Object.defineProperty(exports, "parseStreamTitle", { enumerable: true, get: function () { return title_ts_1.parseStreamTitle; } });
+Object.defineProperty(exports, "parseStreamUrl", { enumerable: true, get: function () { return title_ts_1.parseStreamUrl; } });
+Object.defineProperty(exports, "splitTitle", { enumerable: true, get: function () { return title_ts_1.splitTitle; } });
+Object.defineProperty(exports, "decodeMetadata", { enumerable: true, get: function () { return title_ts_1.decodeMetadata; } });
+Object.defineProperty(exports, "isPlaceholder", { enumerable: true, get: function () { return title_ts_1.isPlaceholder; } });
+var types_ts_1 = require("./types.js");
+Object.defineProperty(exports, "RadioError", { enumerable: true, get: function () { return types_ts_1.RadioError; } });

package/dist/cjs/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/cjs/lookup.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nowPlaying = nowPlaying;
+const icy_ts_1 = require("./icy.js");
+const stats_ts_1 = require("./stats.js");
+async function nowPlaying(station, options = {}) {
+    const target = typeof station === 'string' ? { url: station } : station;
+    if (!target.statsUrl)
+        return (0, icy_ts_1.readIcyTitle)(target.url, options);
+    try {
+        return await (0, stats_ts_1.readStatsTitle)(target.statsUrl, target.mount, options);
+    }
+    catch (err) {
+        if (!options.fallbackToStream)
+            throw err;
+        return (0, icy_ts_1.readIcyTitle)(target.url, options);
+    }
+}

package/dist/cjs/package.json

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

package/dist/cjs/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 {};