nixamp 0.56.0 → 0.57.0

package/dist/channels.d.ts

@@ -247,6 +247,16 @@ export declare class Channel {
      * failure, so it does not count as a redial.
      */
     skip(): boolean;
+    /** How far listeners have got into this dial of a list, by the encoder's progress. */
+    private heard;
+    /** Where a list would pick up after what listeners hear now (PlaylistInputStream.resumePoint). */
+    resumePoint(): {
+        file: string;
+        upcoming: string[];
+        sinceBreak: number;
+    } | null;
+    /** Whether listeners would get sound (and, for a picture, its opening) if they joined now. */
+    get flowing(): boolean;
     /** An entry's tags, as read when it was put on. */
     tagsOf(file: string): {
         title: string;
@@ -539,6 +549,16 @@ export declare class Channels {
         artist: string;
         album: string;
     } | undefined;
+    /** Where a channel playing a list would pick up after what is on now; null when it is not one. */
+    resumePoint(id: string): {
+        file: string;
+        upcoming: string[];
+        sinceBreak: number;
+    } | null;
+    /** Whether a channel is up and has started sending. */
+    flowing(id: string): boolean;
+    /** Who is attached to one channel: listeners, relays, packagers. */
+    listenersOf(id: string): number;
     /** The next entry, now, on a channel playing a list of files. */
     skip(id: string): boolean;
     stop(id: string): boolean;

package/dist/channels.js

@@ -169,6 +169,16 @@ export class Channel {
             this.info.redials = redials;
         return done;
     }
+    /** How far listeners have got into this dial of a list, by the encoder's progress. */
+    heard = 0;
+    /** Where a list would pick up after what listeners hear now (PlaylistInputStream.resumePoint). */
+    resumePoint() {
+        return this.playlistInput?.resumePoint(this.heard) ?? null;
+    }
+    /** Whether listeners would get sound (and, for a picture, its opening) if they joined now. */
+    get flowing() {
+        return this.info.bytes > 0 && (!this.fragments || this.fragments.ready);
+    }
     /** An entry's tags, as read when it was put on. */
     tagsOf(file) {
         return this.playlistInput?.tags.get(file);
@@ -334,6 +344,7 @@ export class Channel {
                 ...resume.rotation,
             }) : null;
             this.playlistInput = playlistInput;
+            this.heard = 0;
             const through = this.outroOn ? null : playlistInput
                 ? { format: "mpegts", open: async (signal) => playlistInput.open(signal) }
                 : this.options.through?.(this.info, from, input, audio) ?? null;
@@ -413,6 +424,7 @@ export class Channel {
                     if (match) {
                         const seconds = Number(match[1]) / 1e6;
                         if (playlistInput) {
+                            this.heard = seconds;
                             const place = playlistInput.place(seconds);
                             // A break (-1) belongs to no list; a track's index belongs to its own.
                             if (place.at >= 0 && this.info.playlist !== place.list)
@@ -1283,6 +1295,18 @@ export class Channels {
     tagsOf(id, file) {
         return this.open.get(id)?.tagsOf(file);
     }
+    /** Where a channel playing a list would pick up after what is on now; null when it is not one. */
+    resumePoint(id) {
+        return this.open.get(id)?.resumePoint() ?? null;
+    }
+    /** Whether a channel is up and has started sending. */
+    flowing(id) {
+        return this.open.get(id)?.flowing ?? false;
+    }
+    /** Who is attached to one channel: listeners, relays, packagers. */
+    listenersOf(id) {
+        return this.open.get(id)?.listeners.size ?? 0;
+    }
     /** The next entry, now, on a channel playing a list of files. */
     skip(id) {
         return this.open.get(id)?.skip() ?? false;

package/dist/library.d.ts

@@ -21,7 +21,13 @@ export interface Config {
     limits?: Record<string, unknown>;
     /** Proxies whose X-Forwarded-For is believed for listener shares (`nixamp station shares trust ADDRESS`). */
     trustedProxies?: string[];
+    /** Seconds with nobody listening before a station sleeps; 0 never. 60 when unset. */
+    stationIdleSeconds?: number;
 }
+/** A station with nobody listening sleeps after this many seconds, unless config or NIXAMP_STATION_IDLE says otherwise. */
+export declare const DEFAULT_STATION_IDLE_SECONDS = 60;
+/** How long a station waits with nobody listening before it sleeps: env, then config, then 60; 0 is never. */
+export declare function stationIdleSeconds(env: Record<string, string | undefined>, config: Config): number;
 export declare function configPath(): string;
 export declare function readConfig(): Config;
 export declare function writeConfig(patch: Partial<Config>): void;

package/dist/library.js

@@ -19,6 +19,16 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stateDir } from "./daemon.js";
+/** A station with nobody listening sleeps after this many seconds, unless config or NIXAMP_STATION_IDLE says otherwise. */
+export const DEFAULT_STATION_IDLE_SECONDS = 60;
+/** How long a station waits with nobody listening before it sleeps: env, then config, then 60; 0 is never. */
+export function stationIdleSeconds(env, config) {
+    const raw = env["NIXAMP_STATION_IDLE"];
+    if (raw !== undefined && raw.trim() !== "" && Number.isFinite(Number(raw)) && Number(raw) >= 0)
+        return Number(raw);
+    const set = config.stationIdleSeconds;
+    return typeof set === "number" && Number.isFinite(set) && set >= 0 ? set : DEFAULT_STATION_IDLE_SECONDS;
+}
 export function configPath() {
     return join(stateDir(), "config.json");
 }
@@ -33,6 +43,7 @@ export function readConfig() {
             ...(typeof record["publish"] === "boolean" ? { publish: record["publish"] } : {}),
             ...(typeof record["autoStations"] === "object" && record["autoStations"] !== null ? { autoStations: record["autoStations"] } : {}),
             ...(typeof record["limits"] === "object" && record["limits"] !== null ? { limits: record["limits"] } : {}),
+            ...(typeof record["stationIdleSeconds"] === "number" ? { stationIdleSeconds: record["stationIdleSeconds"] } : {}),
             ...(Array.isArray(record["trustedProxies"]) ? { trustedProxies: record["trustedProxies"].filter((one) => typeof one === "string") } : {}),
             ...(Array.isArray(record["guideHosts"]) ? { guideHosts: record["guideHosts"].filter((one) => typeof one === "string") } : {}),
             ...(typeof record["guideAds"] === "object" && record["guideAds"] !== null ? { guideAds: record["guideAds"] } : {}),

package/dist/playlist-input.d.ts

@@ -37,6 +37,12 @@ export interface PlaylistInput {
     breaks?: {
         everySeconds: number | (() => number);
         next: () => Promise<string | null>;
+        /**
+         * Seconds of airtime since the last break when this stream opens, asked
+         * once per open: a station that slept with nobody listening carries its
+         * clock across, so breaks come every so often of time on the air.
+         */
+        sinceBreak?: () => number;
     };
     /** Told when an entry is passed over because it would not play. */
     onFailure?: (event: {
@@ -51,6 +57,19 @@ export interface PlaylistInput {
  * not a loop.
  */
 export declare const MAX_FAILURES_IN_A_ROW = 5;
+/** An entry that started: where it sits in the stream and in its pass. */
+interface Entry {
+    at: number;
+    file: string;
+    start: number;
+    position: number;
+    list: readonly string[];
+    /** The pass's order and how far into it the next entry is, for resumePoint. */
+    order: readonly number[];
+    step: number;
+    /** Where the break clock stood when it started. */
+    lastBreak: number;
+}
 /** Decode each file independently; feed one persistent muxer a fixed stream
  * profile and continuous timestamps. A concat demuxer cannot decode a list
  * whose input codecs differ. Only one entry is encoded at a time, with pipe
@@ -72,13 +91,7 @@ export declare class PlaylistInputStream {
     }>;
     constructor(options: PlaylistInput);
     /** Every entry that has started, in the order it started, with where it sits in the stream. */
-    get history(): ReadonlyArray<{
-        at: number;
-        file: string;
-        start: number;
-        position: number;
-        list: readonly string[];
-    }>;
+    get history(): ReadonlyArray<Entry>;
     /**
      * What is on at this point of the stream. `at` indexes `list`, the list as
      * it was when that entry started: a station re-reads its list at every
@@ -90,6 +103,17 @@ export declare class PlaylistInputStream {
         position: number;
         list: readonly string[];
     };
+    /**
+     * Where to pick up after this point of the stream, for a station that
+     * sleeps with nobody listening: the file that is on ("" in a break), the
+     * rest of this pass in the order it was going to play, and the seconds
+     * of airtime since the last break.
+     */
+    resumePoint(seconds: number): {
+        file: string;
+        upcoming: string[];
+        sinceBreak: number;
+    } | null;
     /** The decoder for the entry that is on, so skip() can end it early. */
     private stopCurrent;
     private skipping;
@@ -97,3 +121,4 @@ export declare class PlaylistInputStream {
     skip(): boolean;
     open(signal: AbortSignal): AsyncGenerator<Buffer>;
 }
+export {};

package/dist/playlist-input.js

@@ -40,6 +40,22 @@ export class PlaylistInputStream {
         return entry ? { at: entry.at, position: Math.max(0, seconds - entry.start + entry.position), list: entry.list }
             : { at: this.options.at, position: this.options.position, list: this.options.files };
     }
+    /**
+     * Where to pick up after this point of the stream, for a station that
+     * sleeps with nobody listening: the file that is on ("" in a break), the
+     * rest of this pass in the order it was going to play, and the seconds
+     * of airtime since the last break.
+     */
+    resumePoint(seconds) {
+        const entry = this.entries.findLast(one => seconds >= one.start) ?? this.entries[0];
+        if (!entry)
+            return null;
+        return {
+            file: entry.at >= 0 ? entry.file : "",
+            upcoming: entry.order.slice(entry.step).map((index) => entry.list[index]).filter((one) => typeof one === "string"),
+            sinceBreak: entry.at < 0 ? 0 : Math.max(0, seconds - entry.lastBreak),
+        };
+    }
     /** The decoder for the entry that is on, so skip() can end it early. */
     stopCurrent = null;
     skipping = false;
@@ -69,7 +85,9 @@ export class PlaylistInputStream {
             let step = Math.min(Math.max(0, o.at), order.length);
             let played = 0;
             let last = "";
-            let lastBreak = 0;
+            // Counted back from 0 by however long it had been, so a clock carried
+            // across a sleep comes due when it would have on the air.
+            let lastBreak = -Math.max(0, o.breaks?.sinceBreak?.() ?? 0);
             // A film cut for a break, to be picked up where it stopped.
             let resume = null;
             for (;;) {
@@ -146,7 +164,7 @@ export class PlaylistInputStream {
                         const room = o.video && !isBreak && o.breaks && every > 0 ? every - (offset - lastBreak) : Infinity;
                         const cut = room >= 1 && full - room > 5;
                         const duration = cut ? room : full;
-                        this.entries.push({ at, file, start: offset, position, list: files });
+                        this.entries.push({ at, file, start: offset, position, list: files, order, step, lastBreak });
                         const hasVideo = Boolean(codecs.video);
                         const extra = o.video && !hasVideo
                             ? ["-f", "lavfi", "-i", `color=c=black:s=${width}x${height}:r=30`]

package/dist/server.js

@@ -98,7 +98,7 @@ import { Porkbun, isIPv4, isIPv6 } from "./dns.js";
 import { NameError, Names } from "./names.js";
 import { AcmeIssuer, Certs } from "./certs.js";
 import { claimName, fetchCert, humanizeSource, labelFor, readCertFiles, writeCertFiles } from "./naming.js";
-import { forbiddenLibrary, readConfig, readLibrary, writeConfig } from "./library.js";
+import { forbiddenLibrary, readConfig, readLibrary, stationIdleSeconds, writeConfig } from "./library.js";
 import { createThrottle, presentedCredential } from "@profullstack/throttle";
 import { Durable } from "./durable.js";
 import { notifyAll, resendEmail, webPush } from "./notify.js";
@@ -5501,6 +5501,11 @@ export function createHandler(engine, options) {
                 response.end(request.method === "HEAD" ? undefined : bytes);
                 return;
             }
+            // A station asleep with nobody listening is woken by whoever asks for
+            // its channel here too, and they are held for its first bytes.
+            if ((action === "hls" || action === undefined) && request.method === "GET" && !channels.has(id) && stationOfChannel(id) && options.stations?.runner.isSleeping(stationOfChannel(id))) {
+                await options.stations.runner.awake(stationOfChannel(id));
+            }
             // The same channel as HLS: a playlist of short files, which is what
             // Safari on an iPhone plays live -- it will not take the endless MP4
             // below, and spun on it a few times before giving up. Packaged on
@@ -6956,6 +6961,8 @@ export async function serve(argv, version = "0.1.0") {
         onRestart: (id) => stationUsage.restarted(id),
         onFailure: (id) => stationUsage.failed(id),
         artistOf: (file) => trackFor(engine, file)?.artist ?? "",
+        // Nobody listening for this long and a station sleeps until somebody does.
+        idleSeconds: () => stationIdleSeconds(process.env, readConfig()),
         store: stationStore,
         channels,
         pull: async (channelId, name, files, known) => Boolean(await pullChannel(channels, tools.ffprobe, channelId, name, files[0], [], "", {
@@ -7245,6 +7252,7 @@ export async function serve(argv, version = "0.1.0") {
         });
     }
     stationRunner.restore();
+    stationRunner.watchIdle();
     // Where each film has got to, written down every so often, so a restart
     // picks it up from about there rather than from the start. Only when it
     // has changed: a server carrying nothing but live television writes

package/dist/station-routes.d.ts

@@ -112,6 +112,7 @@ export declare function guideEntries(ctx: StationContext): Array<PublicStation &
 export declare function ownerView(ctx: StationContext, station: Station): OwnerStation & {
     links: ReturnType<typeof links>;
     nowPlaying: string;
+    sleeping: boolean;
 };
 /** Answers anything under /api/v1/stations; false when the path is not one. */
 export declare function handleStations(request: IncomingMessage, response: ServerResponse, path: string, url: URL, ctx: StationContext): Promise<boolean>;

package/dist/station-routes.js

@@ -37,14 +37,16 @@ function nowPlayingFile(ctx, station) {
 }
 export function publicView(ctx, station) {
     const state = ctx.runner.observed(station.id);
-    const file = state === "live" || state === "recovering" ? nowPlayingFile(ctx, station) : "";
+    // Asleep, what it will wake on: the first listener hears that next.
+    const asleep = ctx.runner.isSleeping?.(station.id) ?? false;
+    const file = asleep ? ctx.runner.nextUp(station.id) : state === "live" || state === "recovering" ? nowPlayingFile(ctx, station) : "";
     // The tags the player read when it put this file on, else the library's.
     const track = file ? (ctx.channels.tagsOf(channelOf(station.id), file) ?? ctx.trackFor(file)) : null;
     // What the channel is carrying wins over the flag: a station made by hand
     // from films streams video whether or not anyone said so.
     const video = station.video || ctx.channels.kindOf(channelOf(station.id)) === "video";
     // How far into the song (or film) on the air, by the encoder's clock, and how long it is.
-    const position = file ? ctx.channels.info(channelOf(station.id))?.position : undefined;
+    const position = file && !asleep ? ctx.channels.info(channelOf(station.id))?.position : undefined;
     const duration = file && ctx.durationOf ? ctx.durationOf(file) : 0;
     const progress = typeof position === "number" && duration > 0 ? { position: Math.round(Math.min(position, duration) * 10) / 10, duration: Math.round(duration * 10) / 10 } : null;
     return {
@@ -86,6 +88,8 @@ export function ownerView(ctx, station) {
     return {
         ...rest,
         state: ctx.runner.observed(station.id),
+        // On the air with nobody listening: no encoder until somebody does.
+        sleeping: ctx.runner.isSleeping?.(station.id) ?? false,
         excluded: Object.entries(failures).filter(([, count]) => count >= 3).map(([file]) => file),
         listeners: ctx.runner.listeners(station.id),
         error: ctx.runner.error(station.id),
@@ -264,18 +268,32 @@ export async function handleStations(request, response, path, url, ctx) {
             return true;
         }
         const channelId = channelOf(station.id);
-        if (!ctx.channels.has(channelId)) {
-            ctx.json(response, 503, { error: "the station is not on the air", code: "not_live", state: ctx.runner.observed(station.id) });
+        // Asleep, a HEAD is told what it would get without waking it.
+        if (method === "HEAD" && ctx.runner.isSleeping?.(station.id)) {
+            response.writeHead(200, { ...ctx.headers, "content-type": station.video ? "video/mp4" : "audio/mpeg", "cache-control": "no-store" });
+            response.end();
             return true;
         }
         // Admitted only within the station's and the server's limits, and the
-        // month's allowance; refused with what to do about it.
+        // month's allowance; refused with what to do about it. Before waking it:
+        // a listener turned away is no reason to start the encoder.
         const refused = method === "GET" && ctx.usage && ctx.limits ? ctx.usage.admit(station.id, ctx.limits) : null;
         if (refused) {
             response.writeHead(refused.status, { ...ctx.headers, "content-type": "application/json; charset=utf-8", "retry-after": String(refused.retryAfter) });
             response.end(JSON.stringify({ error: refused.error, code: refused.code, retryAfter: refused.retryAfter }));
             return true;
         }
+        // The first listener wakes a sleeping station, and is held until it
+        // starts sending, so they hear it begin rather than a stream that ends.
+        let closed = false;
+        response.once("close", () => { closed = true; });
+        await ctx.runner.awake?.(station.id, undefined, () => closed);
+        if (closed)
+            return true;
+        if (!ctx.channels.has(channelId)) {
+            ctx.json(response, 503, { error: "the station is not on the air", code: "not_live", state: ctx.runner.observed(station.id) });
+            return true;
+        }
         // Signed in at nixamp.com: no breaks, starting a little behind live so
         // they can be left out without a gap. Radio only (Channel.listenWithoutBreaks).
         const pass = url.searchParams.get(PASS_PARAM) ?? "";

package/dist/station-runner.d.ts

@@ -8,6 +8,13 @@
  * long as it is still wanted, so a disk that comes back or a file put back in
  * place brings it back under the same id and link. A station its owner
  * stopped is never restarted by anything here.
+ *
+ * A station nobody is listening to sleeps: after `idleSeconds` with nobody
+ * attached to its channel, the channel (and its ffmpeg) is stopped, but the
+ * station stays wanted on and is still on the air to the guide. The first
+ * listener wakes it, and it carries on from the track after the one it slept
+ * on, with its break clock where it was. A sleep is not a failure: no
+ * recovery, no restart counted.
  */
 import type { Channels, ChannelInfo, PullResume } from "./channels.ts";
 import { type Observed, type Station, type StationStore } from "./stations.ts";
@@ -30,7 +37,11 @@ export interface RunnerDeps {
     breaks?: (video: boolean) => Promise<string | null>;
     /** Who a file is by, from the library's tags, for a shuffle that spreads artists out; "" when unknown. */
     artistOf?: (file: string) => string;
+    /** Seconds with nobody listening before a station sleeps; 0 (or unset) never. Asked at every sweep. */
+    idleSeconds?: () => number;
 }
+/** How long a listener waking a station is held for its first bytes. */
+export declare const WAKE_WAIT_MS = 10000;
 /**
  * Who a file is by when the tags do not say: "Artist - Album/track" names
  * them in the folder, and "Artist/Album/track" one folder up.
@@ -53,6 +64,14 @@ export declare class StationRunner {
     private down;
     /** The server is going down: its channels end because it is, not because a station failed. */
     private closing;
+    /** Wanted on, with nobody listening: no channel until somebody does. */
+    private asleep;
+    /** For a station asleep: the rest of the pass it was playing, in order. */
+    private parked;
+    /** Since when a station's channel has had nobody on it. */
+    private quietSince;
+    private waking;
+    private idleTimer;
     constructor(deps: RunnerDeps);
     /**
      * Called before the server stops every channel on its way out. Without it,
@@ -74,6 +93,35 @@ export declare class StationRunner {
     remove(id: string): void;
     /** Put back every station that was running when this server last stopped. */
     restore(): void;
+    /** Whether a station is asleep: wanted on, on the air to the guide, with no channel until somebody listens. */
+    isSleeping(id: string): boolean;
+    /** The file a sleeping station would wake on, "" when it cannot say. */
+    nextUp(id: string): string;
+    /** Look every so often for stations nobody is listening to. */
+    watchIdle(everyMs?: number): void;
+    /**
+     * Put to sleep every station whose channel has had nobody on it for the
+     * idle time. Anybody attached counts: a listener on the link or /radio, a
+     * class or room relaying it, an HLS packager, a peer pulling it. The
+     * now-playing events alone do not.
+     */
+    sweep(): void;
+    /** Off the air for now, still wanted on: remembers where it was, and is not a failure. */
+    sleep(id: string): void;
+    /** On again for a listener, if it was asleep. True when its channel is up (or coming up). */
+    wake(id: string): Promise<boolean>;
+    /**
+     * Wake it if it is asleep, and wait (up to `timeoutMs`) for its first
+     * bytes, so a listener hears it start rather than a stream that ends.
+     * True when the channel is up.
+     */
+    awake(id: string, timeoutMs?: number, gone?: () => boolean): Promise<boolean>;
+    /**
+     * Where a launch picks up: the rest of the pass it slept in, or (after the
+     * server restarted) the files after the one it was on; and the break
+     * clock. Taken once, by the next launch.
+     */
+    private takeResume;
     private launch;
     /** Told by the server when any channel ends. */
     onChannelEnd(info: ChannelInfo): void;