radio-now-playing 1.0.0

package/dist/esm/stats.js

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+import { RadioError } from "./types.js";
+import { splitTitle, isPlaceholder } from "./title.js";
+import { abortAfter, DEFAULT_TIMEOUT_MS, DEFAULT_USER_AGENT } from "./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.
+ */
+export 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;
+}
+export 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 || isPlaceholder(title))
+            return null;
+        return {
+            title,
+            ...splitTitle(title),
+            listeners: int(source.listeners),
+            source: 'icecast',
+            fetchedAt: Date.now(),
+        };
+    }
+    const sc = body;
+    const title = str(sc.songtitle) ?? str(sc.streamtitle);
+    if (!title || isPlaceholder(title))
+        return null;
+    return {
+        title,
+        ...splitTitle(title),
+        listeners: int(sc.currentlisteners),
+        source: 'shoutcast',
+        fetchedAt: Date.now(),
+    };
+}
+export async function readStatsTitle(url, mount, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const signal = abortAfter(timeoutMs, options.signal);
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: { 'User-Agent': options.userAgent ?? DEFAULT_USER_AGENT, Accept: 'application/json, */*' },
+            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)
+        throw new 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 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/esm/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/esm/title.js

@@ -0,0 +1,87 @@
+/**
+ * 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 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.
+ */
+export 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. */
+export 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.
+ */
+export 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;
+export function isPlaceholder(title) {
+    return PLACEHOLDERS.test(title.trim());
+}

package/dist/esm/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/esm/types.js

@@ -0,0 +1,14 @@
+/** Thrown for transport and protocol failures — never for "no title yet". */
+export 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;
+    }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "radio-now-playing",
+  "version": "1.0.0",
+  "description": "What is playing on an internet radio station, right now. Reads ICY stream metadata or a Shoutcast/Icecast status endpoint, hangs up immediately, and caches so a hundred callers cost one request. Zero dependencies.",
+  "keywords": [
+    "icy",
+    "icecast",
+    "shoutcast",
+    "now-playing",
+    "metadata",
+    "streamtitle",
+    "internet-radio",
+    "radio",
+    "stream"
+  ],
+  "license": "MIT",
+  "author": "kotatko",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/K0tatkoo/radio-now-playing.git"
+  },
+  "bugs": {
+    "url": "https://github.com/K0tatkoo/radio-now-playing/issues"
+  },
+  "homepage": "https://github.com/K0tatkoo/radio-now-playing#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.3.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "test:dist": "npm run build && node --test \"test/dist/*.test.mjs\"",
+    "smoke": "node scripts/smoke.mjs",
+    "check": "npm run typecheck && npm test && npm run test:dist",
+    "prepublishOnly": "npm run clean && npm run check"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "typescript": "^5.7.2"
+  }
+}