@joewinke/jatui 0.46.0 → 0.48.0

package/dist/ambience/scapes/playlist.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Ambience scape — playlist (phase 2): a host-supplied manifest of
+ * public-domain recordings, streamed through the shared master chain.
+ *
+ * The HOST owns the manifest and its licensing claims: pass `tracks` inline or
+ * a `manifestUrl` that is fetched once, lazily, on the first play — nothing
+ * loads at import time, and no audio ever ships in jatui (see
+ * src/lib/ambience/README.md for a Musopen-shaped example manifest).
+ *
+ * Audio streams through
+ *
+ *   HTMLAudioElement → MediaElementAudioSourceNode → per-track gain → mix → ctx.input
+ *
+ * so the engine's warm tilt + soft-clip limiter apply, and every crossfade is
+ * a native gain-node ramp — no per-sample JS, no decoded buffers held.
+ *
+ * Two ping-pong "slots" (element + MediaElementAudioSourceNode + gain each)
+ * are built ONCE per play and reused for every track: while the current track
+ * nears its end (stateless per-tick check in the lookahead) the idle slot —
+ * already preloaded with the next track — starts and the two gains ramp
+ * against each other. A stream that never reports a duration advances on the
+ * element's own `ended` event instead, with a short ramp. The per-tick check
+ * fires at most ONE transition per tick, always at that tick's `now`, so a
+ * returning background tab (setInterval throttled to ~1/min while the audio
+ * clock runs on) cannot burst missed transitions.
+ *
+ * Teardown is WALL-CLOCK, never a lookahead tick: the engine retires a stopped
+ * instance's lookahead callbacks fade*1000 + 250 ms after stop (engine.ts
+ * retireCbs) — a tick-based disconnect could be dropped with nodes still
+ * wired into the shared input. stop() ramps the gains to zero on the audio
+ * clock and disconnects via setTimeout(fade*1000 + 50).
+ *
+ * The returned object is a plain Scape for the engine plus a UI surface
+ * (state/subscribe/skip/setShuffle) so a toggle can show the current track's
+ * attribution — composer, performer, license and a link back to the source.
+ * Nothing is registered globally; the integration task wires the default
+ * registry (jatui-poq30).
+ */
+import type { Scape } from '../types';
+export declare const PLAYLIST: Readonly<{
+    /** Crossfade between consecutive tracks (s). */
+    CROSSFADE: 3;
+    /** Fade-in for the playlist's very first track (s). */
+    START_RAMP: 0.5;
+    /** Ramp when a track ends/fails with no crossfade window (s). */
+    END_RAMP: 0.25;
+    /** Start the next track when at most this much of the current track is
+     *  left ON TOP of the crossfade (s). */
+    END_MARGIN: 0.25;
+    /** setParam('gain') ramp (s). */
+    GAIN_RAMP: 0.15;
+    /** Disconnect + pause this many ms after a stop fade ends — before the
+     *  engine's lookahead retirement (fade*1000 + 250) can drop anything. */
+    TEARDOWN_DELAY_MS: 50;
+    /** Pause an outgoing (crossfaded-out) element this many ms after its fade. */
+    PAUSE_MARGIN_MS: 100;
+    /** Silent-out ramp when the playlist gives up (s). */
+    FAIL_FADE: 0.3;
+}>;
+export interface PlaylistTrack {
+    /** Track title. */
+    title: string;
+    /** Composer — the attribution line the toggle shows. */
+    composer: string;
+    /** Performer / recording artist (optional second attribution line). */
+    performer?: string;
+    /** Streamable audio URL. The host must serve it with CORS headers. */
+    url: string;
+    /** License string, e.g. "Public domain" or "CC0 1.0" — shown in the UI. */
+    license: string;
+    /** Page where the recording lives — the attribution link target. */
+    sourceUrl?: string;
+}
+export interface PlaylistManifest {
+    title?: string;
+    tracks: PlaylistTrack[];
+}
+export type PlaylistStatus = 'idle' | 'loading' | 'playing' | 'error';
+export interface PlaylistState {
+    status: PlaylistStatus;
+    /** The track sounding right now (null while idle/loading or on error). */
+    track: PlaylistTrack | null;
+    /** Position of the current track in the play order (0-based). */
+    index: number;
+    /** Number of tracks in the resolved playlist (0 until resolved). */
+    count: number;
+    /** Present on error. */
+    error?: string;
+}
+export interface PlaylistScapeOptions {
+    id: string;
+    label: string;
+    description?: string;
+    /** Manifest URL — fetched lazily, ONCE, on the first play. A failed fetch
+     *  is retried on the next play. */
+    manifestUrl?: string;
+    /** Tracks inline — skips the fetch entirely. */
+    tracks?: PlaylistTrack[];
+    /** Track crossfade (s), 0–30. Default 3. */
+    crossfade?: number;
+    /** Randomized play order (Fisher–Yates over the engine's per-scape rand).
+     *  Default false. Takes effect for the running order immediately. */
+    shuffle?: boolean;
+    /** Initial gain of the scape mix into the master chain, 0..1. Default 1. */
+    gain?: number;
+    /** Injectable for tests (default `fetch`). */
+    fetchFn?: (url: string) => Promise<Response>;
+    /** Injectable for tests (default `new Audio(url)`). */
+    createMediaElement?: (url: string) => HTMLAudioElement;
+}
+/** A Scape plus the playlist UI surface. Cast a registered Scape to this in
+ *  the toggle to reach state()/subscribe()/skip()/setShuffle(). */
+export interface PlaylistScape extends Scape {
+    group: 'music';
+    /** Current snapshot (also the initial value subscribe() fires with). */
+    state(): PlaylistState;
+    /** Subscribe to playlist state changes; fires immediately. */
+    subscribe(fn: (s: PlaylistState) => void): () => void;
+    /** Crossfade to the next track now. No-op while loading/released. */
+    skip(): void;
+    /** Toggle shuffle; the current track stays, the rest reorder at once. */
+    setShuffle(on: boolean): void;
+    /** The resolved track list, or null until the manifest resolved. */
+    tracks(): PlaylistTrack[] | null;
+}
+export declare function createPlaylistScape(options: PlaylistScapeOptions): PlaylistScape;
+/** Fisher–Yates over an injected rand (the engine's per-scape PRNG), so the
+ *  play order is deterministic for tests. */
+export declare function shuffledOrder(n: number, rand: () => number): number[];

package/dist/ambience/scapes/playlist.js

@@ -0,0 +1,569 @@
+export const PLAYLIST = Object.freeze({
+    /** Crossfade between consecutive tracks (s). */
+    CROSSFADE: 3,
+    /** Fade-in for the playlist's very first track (s). */
+    START_RAMP: 0.5,
+    /** Ramp when a track ends/fails with no crossfade window (s). */
+    END_RAMP: 0.25,
+    /** Start the next track when at most this much of the current track is
+     *  left ON TOP of the crossfade (s). */
+    END_MARGIN: 0.25,
+    /** setParam('gain') ramp (s). */
+    GAIN_RAMP: 0.15,
+    /** Disconnect + pause this many ms after a stop fade ends — before the
+     *  engine's lookahead retirement (fade*1000 + 250) can drop anything. */
+    TEARDOWN_DELAY_MS: 50,
+    /** Pause an outgoing (crossfaded-out) element this many ms after its fade. */
+    PAUSE_MARGIN_MS: 100,
+    /** Silent-out ramp when the playlist gives up (s). */
+    FAIL_FADE: 0.3
+});
+export function createPlaylistScape(options) {
+    if (!options?.id)
+        throw new Error('createPlaylistScape: id is required');
+    if (!options.label)
+        throw new Error('createPlaylistScape: label is required');
+    const crossfade = Math.min(30, Math.max(0, options.crossfade ?? PLAYLIST.CROSSFADE));
+    const mixGain0 = Math.min(1, Math.max(0, options.gain ?? 1));
+    const fetchFn = options.fetchFn ?? ((url) => fetch(url));
+    let shuffle = options.shuffle ?? false;
+    /** Resolved track list — cached across plays (the manifest is fetched once,
+     *  on the first play). null = unresolved; a FAILED fetch stays null so the
+     *  next play retries. Inline tracks resolve eagerly (a pure local filter —
+     *  no I/O), so a manifest-less playlist starts synchronously on play. */
+    let resolved = null;
+    let resolveError = null;
+    /** In-flight resolve; nulled on failure so a later play can retry. */
+    let pending = null;
+    if (options.tracks) {
+        const tracks = options.tracks.filter(isValidTrack);
+        if (tracks.length > 0) {
+            resolved = tracks;
+            pending = Promise.resolve(null);
+        }
+    }
+    /** Shared UI snapshot + subscribers. Only the latest build writes it. */
+    let snap = { status: 'idle', track: null, index: 0, count: 0 };
+    const subs = new Set();
+    /** Handle to the most recent build — skip()/setShuffle() route here. */
+    let latest = null;
+    let instanceSeq = 0;
+    function setSnap(patch) {
+        snap = { ...snap, ...patch };
+        for (const fn of subs)
+            fn(snap);
+    }
+    /** Fetch + validate the manifest (or pick up inline tracks). Resolves with
+     *  an error message instead of rejecting so every awaiting instance can
+     *  fail the same way. */
+    function ensureTracks() {
+        if (resolved)
+            return Promise.resolve(null);
+        pending ??= (async () => {
+            try {
+                if (options.tracks) {
+                    const tracks = options.tracks.filter(isValidTrack);
+                    if (tracks.length === 0)
+                        throw new Error('The supplied track list has no valid entries');
+                    resolved = tracks;
+                }
+                else if (options.manifestUrl) {
+                    const res = await fetchFn(options.manifestUrl);
+                    if (!res.ok)
+                        throw new Error(`Manifest fetch failed (HTTP ${res.status})`);
+                    const tracks = extractTracks(await res.json()).filter(isValidTrack);
+                    if (tracks.length === 0)
+                        throw new Error('Manifest contains no valid tracks');
+                    resolved = tracks;
+                }
+                else {
+                    throw new Error('createPlaylistScape needs manifestUrl or tracks');
+                }
+                resolveError = null;
+                return null;
+            }
+            catch (err) {
+                pending = null; // failed fetches are not cached — next play retries
+                resolveError = err instanceof Error ? err.message : String(err);
+                return resolveError;
+            }
+        })();
+        return pending;
+    }
+    /** One media element, CORS-anonymous so a cross-origin source actually
+     *  delivers audio into the graph (a tainted element would play silence). */
+    function makeElement(url) {
+        const el = options.createMediaElement ? options.createMediaElement(url) : new Audio(url);
+        try {
+            el.preload = 'auto';
+            el.crossOrigin = 'anonymous';
+        }
+        catch {
+            /* exotic environments */
+        }
+        return el;
+    }
+    function buildInstance(scapeCtx) {
+        const ctx = scapeCtx.audio;
+        const instId = ++instanceSeq;
+        let released = false;
+        let started = false;
+        const timers = new Set();
+        let unsub = null;
+        // The scape graph — built once per play, reused for every track:
+        //   el → MediaElementSource → track gain → mix → ctx.input (master chain)
+        const mix = ctx.createGain();
+        mix.gain.value = mixGain0;
+        mix.connect(scapeCtx.input);
+        const slots = [0, 1].map(() => {
+            const el = makeElement('');
+            const source = ctx.createMediaElementSource(el);
+            const gain = ctx.createGain();
+            gain.gain.value = 0;
+            source.connect(gain);
+            gain.connect(mix);
+            return { el, gain, source, trackIndex: -1 };
+        });
+        /** Position in `order` of the track sounding now; order[pos] = track idx. */
+        let active = -1; // active slot index
+        let order = [];
+        let pos = 0;
+        let failures = 0;
+        const isLive = () => instId === instanceSeq && !released;
+        function atTimer(ms, fn) {
+            if (released)
+                return;
+            const t = setTimeout(() => {
+                timers.delete(t);
+                if (!released)
+                    fn();
+            }, Math.max(0, ms));
+            timers.add(t);
+        }
+        function wireSlotEvents(slot) {
+            const el = slot.el;
+            // A stream without metadata never triggers the end-detection tick —
+            // the element's own `ended` is the fallback advance.
+            el.addEventListener('ended', () => {
+                if (released || !isLive() || active < 0 || slots[active] !== slot)
+                    return;
+                const ni = nextIdx();
+                if (ni !== -1 && ni !== slot.trackIndex)
+                    startTrack(ni, 'ended');
+            });
+            el.addEventListener('error', () => {
+                if (released || !isLive())
+                    return;
+                if (active < 0 || slots[active] !== slot) {
+                    // A PRELOAD failed — drop it; the crossfade path re-srcs.
+                    slot.trackIndex = -1;
+                    return;
+                }
+                onTrackFailed();
+            });
+            // Audible playback started — the failure streak is over.
+            el.addEventListener('playing', () => {
+                if (released || active < 0 || slots[active] !== slot)
+                    return;
+                failures = 0;
+            });
+        }
+        for (const slot of slots)
+            wireSlotEvents(slot);
+        function wireLookahead() {
+            unsub = scapeCtx.lookahead((_now) => {
+                if (released || active < 0)
+                    return;
+                const slot = slots[active];
+                if (slot.trackIndex < 0)
+                    return;
+                const el = slot.el;
+                const d = el.duration;
+                // Stateless per-tick check (no while-loop to re-anchor): at most ONE
+                // transition per tick, always anchored at THIS tick's now, so a
+                // returning throttled tab cannot burst missed transitions.
+                if (Number.isFinite(d) &&
+                    d > 0 &&
+                    el.currentTime > 0 &&
+                    d - el.currentTime <= crossfade + PLAYLIST.END_MARGIN) {
+                    const ni = nextIdx();
+                    if (ni !== -1 && ni !== slot.trackIndex)
+                        startTrack(ni, 'cross');
+                }
+            });
+        }
+        function start(_at) {
+            if (started || released)
+                return;
+            started = true;
+            setSnap({ status: 'loading', track: null, index: 0, count: resolved?.length ?? 0 });
+            if (resolved) {
+                begin();
+                return;
+            }
+            void ensureTracks().then((err) => {
+                if (!isLive())
+                    return; // replaced or torn down while fetching
+                if (err)
+                    fail(err);
+                else
+                    begin();
+            });
+        }
+        function begin() {
+            if (released)
+                return;
+            if (!resolved || resolved.length === 0) {
+                fail(resolveError ?? 'Playlist has no playable tracks');
+                return;
+            }
+            order = shuffle ? shuffledOrder(resolved.length, scapeCtx.rand) : plainOrder(resolved.length);
+            pos = 0;
+            startTrack(order[0], 'first');
+        }
+        /** Load a track into the idle slot, fade it in, fade the outgoing slot
+         *  out against it, and update the attribution state. */
+        function startTrack(trackIdx, mode) {
+            if (released)
+                return;
+            const track = resolved?.[trackIdx];
+            if (!track)
+                return;
+            const slotIdx = active < 0 ? 0 : 1 - active;
+            const slot = slots[slotIdx];
+            const now = ctx.currentTime;
+            const fadeIn = mode === 'first' ? PLAYLIST.START_RAMP : mode === 'cross' ? crossfade : PLAYLIST.END_RAMP;
+            // Reuse the preloaded media when the slot already holds this track.
+            if (slot.trackIndex !== trackIdx) {
+                slot.el.src = track.url;
+                slot.el.loop = (resolved?.length ?? 0) === 1; // a one-track playlist loops
+                slot.trackIndex = trackIdx;
+            }
+            const g = slot.gain.gain;
+            g.cancelScheduledValues(now);
+            if (fadeIn > 0) {
+                g.setValueAtTime(0, now);
+                g.linearRampToValueAtTime(1, now + fadeIn);
+            }
+            else {
+                g.setValueAtTime(1, now);
+            }
+            if (mode !== 'first') {
+                const old = slots[1 - slotIdx];
+                if (old.trackIndex !== -1) {
+                    const og = old.gain.gain;
+                    const out = Math.max(fadeIn, 0.01);
+                    og.cancelScheduledValues(now);
+                    og.setValueAtTime(og.value, now);
+                    og.linearRampToValueAtTime(0, now + out);
+                    // Silence lands on the audio clock (the gain ramp); the element
+                    // pause is wall-clock hygiene — never a lookahead tick.
+                    atTimer(out * 1000 + PLAYLIST.PAUSE_MARGIN_MS, () => {
+                        if (released || active === slots.indexOf(old))
+                            return;
+                        quietSlot(old);
+                    });
+                }
+            }
+            active = slotIdx;
+            try {
+                const p = slot.el.play();
+                if (p)
+                    p.catch(() => onTrackFailed());
+            }
+            catch {
+                onTrackFailed();
+            }
+            setSnap({ status: 'playing', track, index: pos, count: resolved.length, error: undefined });
+            preloadNext();
+        }
+        function quietSlot(slot) {
+            try {
+                slot.el.pause();
+                slot.el.currentTime = 0;
+            }
+            catch {
+                /* element already unusable */
+            }
+        }
+        function onTrackFailed() {
+            if (released || !isLive())
+                return;
+            failures++;
+            const n = resolved?.length ?? 0;
+            if (failures >= n) {
+                fail(`All ${n} playlist tracks failed to load`);
+                return;
+            }
+            const ni = nextIdx();
+            if (ni !== -1)
+                startTrack(ni, 'ended'); // the failed slot is already silent
+        }
+        /** Advance the play order (wrapping, reshuffling a shuffled cycle);
+         *  returns the next track index or -1. */
+        function nextIdx() {
+            if (order.length === 0)
+                return -1;
+            const lastPlayed = order[pos];
+            pos += 1;
+            if (pos >= order.length) {
+                order = wrapOrder(lastPlayed);
+                pos = 0;
+            }
+            return order[pos];
+        }
+        /** The track that would play next, WITHOUT advancing (for preload). */
+        function peekNextIdx() {
+            if (order.length === 0)
+                return -1;
+            return pos + 1 < order.length ? order[pos + 1] : order[0];
+        }
+        /** Order for the next cycle; never opens with the track that just
+         *  ended when a swap can avoid it. */
+        function wrapOrder(lastPlayed) {
+            const idx = plainOrder(resolved?.length ?? 0);
+            if (shuffle) {
+                shuffleInPlace(idx, scapeCtx.rand);
+                if (idx.length > 1 && idx[0] === lastPlayed) {
+                    const t = idx[0];
+                    idx[0] = idx[1];
+                    idx[1] = t;
+                }
+            }
+            return idx;
+        }
+        /** Preload the next track into the idle slot so the crossfade starts
+         *  without a buffering gap. */
+        function preloadNext() {
+            const idx = peekNextIdx();
+            const track = resolved?.[idx];
+            if (!track || active < 0 || idx === slots[active].trackIndex)
+                return;
+            const idle = slots[1 - active];
+            if (idle.trackIndex !== idx) {
+                idle.el.src = track.url;
+                idle.el.loop = (resolved?.length ?? 0) === 1;
+                idle.trackIndex = idx;
+            }
+        }
+        function stop(at, fade) {
+            if (released)
+                return;
+            // The playlist is going away (user stop or the engine crossfading to
+            // another scape) — the UI drops the attribution now; the silence
+            // follows on the audio clock.
+            setSnap({
+                status: 'idle',
+                track: null,
+                index: 0,
+                count: resolved?.length ?? 0,
+                error: undefined
+            });
+            const f = Math.max(0, fade);
+            for (const slot of slots) {
+                if (slot.trackIndex === -1)
+                    continue;
+                const g = slot.gain.gain;
+                g.cancelScheduledValues(at);
+                g.setValueAtTime(g.value, at);
+                g.linearRampToValueAtTime(0, at + f);
+            }
+            // Stop scheduling sound immediately, then tear down WALL-CLOCK —
+            // never on a lookahead tick: the engine retires stopped instances'
+            // lookahead callbacks at fade*1000 + 250 ms, so a tick-based teardown
+            // can be dropped with nodes still connected to the shared input.
+            unsub?.();
+            unsub = null;
+            if (f <= 0) {
+                release();
+            }
+            else {
+                atTimer(f * 1000 + PLAYLIST.TEARDOWN_DELAY_MS, release);
+            }
+        }
+        /** Everything down: elements paused + de-src'd, every node disconnected.
+         *  Idempotent — a second stop()/kill() is a no-op. */
+        function release() {
+            if (released)
+                return;
+            released = true;
+            for (const t of timers)
+                clearTimeout(t);
+            timers.clear();
+            unsub?.();
+            unsub = null;
+            for (const slot of slots) {
+                try {
+                    slot.el.pause();
+                    slot.el.currentTime = 0;
+                }
+                catch {
+                    /* element already unusable */
+                }
+                try {
+                    slot.el.removeAttribute('src');
+                    slot.el.load();
+                }
+                catch {
+                    /* older engines */
+                }
+                try {
+                    slot.source.disconnect();
+                    slot.gain.disconnect();
+                }
+                catch {
+                    /* already torn down */
+                }
+            }
+            try {
+                mix.disconnect();
+            }
+            catch {
+                /* already torn down */
+            }
+        }
+        /** Manifest missing/failed, no valid tracks, or every track failed to
+         *  load: report, go silent on the audio clock, tear down wall-clock. */
+        function fail(message) {
+            if (released)
+                return;
+            setSnap({
+                status: 'error',
+                error: message,
+                track: null,
+                index: 0,
+                count: resolved?.length ?? 0
+            });
+            const now = ctx.currentTime;
+            const g = mix.gain;
+            g.cancelScheduledValues(now);
+            g.setValueAtTime(g.value, now);
+            g.linearRampToValueAtTime(0, now + PLAYLIST.FAIL_FADE);
+            unsub?.();
+            unsub = null;
+            atTimer(PLAYLIST.FAIL_FADE * 1000 + PLAYLIST.TEARDOWN_DELAY_MS, release);
+        }
+        /** setParam — scape-defined keys. 'gain': the scape mix level (0..1). */
+        function setParam(key, value) {
+            if (key !== 'gain' || released)
+                return;
+            const v = Math.min(1, Math.max(0, value));
+            const now = ctx.currentTime;
+            const g = mix.gain;
+            g.cancelScheduledValues(now);
+            g.setValueAtTime(g.value, now);
+            g.linearRampToValueAtTime(v, now + PLAYLIST.GAIN_RAMP);
+        }
+        function skipInternal() {
+            if (released || !started || order.length === 0)
+                return;
+            const ni = nextIdx();
+            if (ni !== -1)
+                startTrack(ni, 'cross');
+        }
+        /** setShuffle mid-play: with shuffle the rest reorder (current first);
+         *  without, the natural order resumes from the current track. */
+        function reshuffle() {
+            if (released || !started || !resolved || resolved.length < 2)
+                return;
+            const current = order[pos] ?? 0;
+            if (shuffle) {
+                const rest = plainOrder(resolved.length).filter((i) => i !== current);
+                shuffleInPlace(rest, scapeCtx.rand);
+                order = [current, ...rest];
+                pos = 0;
+            }
+            else {
+                order = plainOrder(resolved.length);
+                pos = current; // pointer at the current track — next is its successor
+            }
+        }
+        wireLookahead();
+        return {
+            api: { start, stop, setParam },
+            skip: skipInternal,
+            reshuffle,
+            isReleased: () => released
+        };
+    }
+    const scape = {
+        id: options.id,
+        label: options.label,
+        group: 'music',
+        description: options.description,
+        build(scapeCtx) {
+            const inst = buildInstance(scapeCtx);
+            latest = inst;
+            return inst.api;
+        },
+        state: () => snap,
+        subscribe(fn) {
+            subs.add(fn);
+            fn(snap);
+            return () => {
+                subs.delete(fn);
+            };
+        },
+        skip() {
+            if (latest && !latest.isReleased())
+                latest.skip();
+        },
+        setShuffle(on) {
+            shuffle = on;
+            if (latest && !latest.isReleased())
+                latest.reshuffle();
+        },
+        tracks: () => (resolved ? [...resolved] : null)
+    };
+    return scape;
+}
+// ---- pure helpers ------------------------------------------------------------
+/** Sequential order 0..n-1. */
+function plainOrder(n) {
+    return Array.from({ length: n }, (_, i) => i);
+}
+/** Fisher–Yates over an injected rand (the engine's per-scape PRNG), so the
+ *  play order is deterministic for tests. */
+export function shuffledOrder(n, rand) {
+    const idx = plainOrder(n);
+    shuffleInPlace(idx, rand);
+    return idx;
+}
+function shuffleInPlace(idx, rand) {
+    for (let i = idx.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        const t = idx[i];
+        idx[i] = idx[j];
+        idx[j] = t;
+    }
+}
+/** Accept `{ tracks: [...] }` or a bare [...] manifest. */
+function extractTracks(json) {
+    if (Array.isArray(json))
+        return json;
+    if (typeof json === 'object' && json !== null) {
+        const tracks = json.tracks;
+        if (Array.isArray(tracks))
+            return tracks;
+    }
+    return [];
+}
+/** A track needs title, composer, url and license — the attribution the UI
+ *  promises. performer/sourceUrl are optional strings. Anything else is
+ *  filtered out rather than failing the whole playlist. */
+function isValidTrack(t) {
+    if (typeof t !== 'object' || t === null)
+        return false;
+    const o = t;
+    return (typeof o.title === 'string' &&
+        o.title.trim() !== '' &&
+        typeof o.composer === 'string' &&
+        o.composer.trim() !== '' &&
+        typeof o.url === 'string' &&
+        o.url.trim() !== '' &&
+        typeof o.license === 'string' &&
+        o.license.trim() !== '' &&
+        (o.performer === undefined || typeof o.performer === 'string') &&
+        (o.sourceUrl === undefined ||
+            (typeof o.sourceUrl === 'string' && o.sourceUrl.trim() !== '')));
+}