nixamp 0.56.0 → 0.57.0

package/dist/station-runner.js

@@ -1,4 +1,6 @@
 import { EXCLUDE_AFTER, OFFLINE_RETRY_MS, RECOVERY_DELAYS_MS, StationError, channelOf, insideRoots, spreadByArtist, stationOfChannel, } from "./stations.js";
+/** How long a listener waking a station is held for its first bytes. */
+export const WAKE_WAIT_MS = 10_000;
 /**
  * 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.
@@ -26,6 +28,14 @@ export class StationRunner {
     down = new Map();
     /** The server is going down: its channels end because it is, not because a station failed. */
     closing = false;
+    /** Wanted on, with nobody listening: no channel until somebody does. */
+    asleep = new Set();
+    /** For a station asleep: the rest of the pass it was playing, in order. */
+    parked = new Map();
+    /** Since when a station's channel has had nobody on it. */
+    quietSince = new Map();
+    waking = new Map();
+    idleTimer = null;
     constructor(deps) {
         this.deps = deps;
     }
@@ -35,7 +45,21 @@ export class StationRunner {
      * busy day every station said "something keeps stopping it".
      */
     close() {
+        if (!this.closing) {
+            // Where each station on the air was, so after an update it wakes on
+            // the next track with its break clock, as it would from a sleep.
+            for (const station of this.deps.store.list()) {
+                if (station.desired !== "running" || this.asleep.has(station.id))
+                    continue;
+                const point = this.deps.channels.resumePoint(channelOf(station.id));
+                if (point)
+                    this.deps.store.setResume(station.id, { after: point.file || station.resume?.after || "", sinceBreak: point.sinceBreak });
+            }
+        }
         this.closing = true;
+        if (this.idleTimer)
+            clearInterval(this.idleTimer);
+        this.idleTimer = null;
         for (const timer of this.timers.values())
             clearTimeout(timer);
         this.timers.clear();
@@ -60,6 +84,7 @@ export class StationRunner {
             throw new StationError("nothing_playable", "none of this station's files can be found in the library", 409);
         }
         this.deps.store.setDesired(id, "running", this.now());
+        this.asleep.delete(id);
         this.cancelRecovery(id);
         this.attempts.delete(id);
         await this.launch(id);
@@ -68,6 +93,9 @@ export class StationRunner {
     /** Wanted off, and taken off. Stays off across restarts. */
     stop(id) {
         const station = this.deps.store.setDesired(id, "stopped", this.now());
+        this.asleep.delete(id);
+        this.parked.delete(id);
+        this.quietSince.delete(id);
         this.down.delete(id);
         this.cancelRecovery(id);
         this.attempts.delete(id);
@@ -83,6 +111,11 @@ export class StationRunner {
     skip(id) {
         if (!this.deps.store.get(id))
             throw new StationError("not_found", "no such station", 404);
+        // Asleep, the next track is the one after the one it will wake on.
+        if (this.asleep.has(id)) {
+            this.parked.get(id)?.shift();
+            return;
+        }
         if (!this.deps.channels.skip(channelOf(id)))
             throw new StationError("not_live", "the station is not playing", 409);
     }
@@ -96,13 +129,162 @@ export class StationRunner {
     }
     /** Put back every station that was running when this server last stopped. */
     restore() {
+        // Asleep until somebody listens, when stations sleep at all: putting
+        // every one on at once, to have each go back to sleep a minute later,
+        // is a storm of ffmpeg for nobody.
+        const sleepy = (this.deps.idleSeconds?.() ?? 0) > 0;
         for (const station of this.deps.store.list()) {
             if (station.desired !== "running")
                 continue;
+            if (sleepy) {
+                this.asleep.add(station.id);
+                continue;
+            }
             this.log(`  Putting station "${station.name}" back on the air.`);
             void this.launch(station.id);
         }
     }
+    /** Whether a station is asleep: wanted on, on the air to the guide, with no channel until somebody listens. */
+    isSleeping(id) {
+        return this.asleep.has(id);
+    }
+    /** The file a sleeping station would wake on, "" when it cannot say. */
+    nextUp(id) {
+        if (!this.asleep.has(id))
+            return "";
+        const parked = this.parked.get(id)?.[0];
+        if (parked)
+            return parked;
+        const station = this.deps.store.get(id);
+        if (!station || station.shuffle || !station.resume?.after)
+            return "";
+        const files = station.items;
+        const at = files.indexOf(station.resume.after);
+        return at >= 0 ? files[at + 1] ?? "" : "";
+    }
+    /** Look every so often for stations nobody is listening to. */
+    watchIdle(everyMs = 5_000) {
+        if (this.idleTimer)
+            return;
+        this.idleTimer = setInterval(() => this.sweep(), everyMs);
+        this.idleTimer.unref?.();
+    }
+    /**
+     * 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() {
+        const idle = this.deps.idleSeconds?.() ?? 0;
+        if (idle <= 0 || this.closing)
+            return;
+        const now = this.now();
+        for (const station of this.deps.store.list()) {
+            const id = station.id;
+            const channelId = channelOf(id);
+            if (station.desired !== "running" || this.asleep.has(id) || this.starting.has(id) || !this.deps.channels.has(channelId)) {
+                this.quietSince.delete(id);
+                continue;
+            }
+            if (this.deps.channels.listenersOf(channelId) > 0) {
+                this.quietSince.delete(id);
+                continue;
+            }
+            const since = this.quietSince.get(id);
+            if (since === undefined)
+                this.quietSince.set(id, now);
+            else if (now - since >= idle * 1000)
+                this.sleep(id);
+        }
+    }
+    /** Off the air for now, still wanted on: remembers where it was, and is not a failure. */
+    sleep(id) {
+        const station = this.deps.store.get(id);
+        const channelId = channelOf(id);
+        if (!station || station.desired !== "running" || this.asleep.has(id))
+            return;
+        const point = this.deps.channels.resumePoint(channelId);
+        this.deps.store.setResume(id, {
+            after: point?.file || station.resume?.after || "",
+            sinceBreak: point ? point.sinceBreak : station.resume?.sinceBreak ?? 0,
+        });
+        this.parked.set(id, point?.upcoming ?? []);
+        this.asleep.add(id);
+        this.quietSince.delete(id);
+        this.cancelRecovery(id);
+        this.attempts.delete(id);
+        this.errors.delete(id);
+        this.down.delete(id);
+        if (this.deps.channels.has(channelId)) {
+            this.stopping.add(channelId);
+            this.deps.channels.stop(channelId);
+        }
+        this.log(`  Station "${station.name}" is asleep until somebody listens.`);
+    }
+    /** On again for a listener, if it was asleep. True when its channel is up (or coming up). */
+    wake(id) {
+        const pending = this.waking.get(id);
+        if (pending)
+            return pending;
+        if (!this.asleep.has(id))
+            return Promise.resolve(this.deps.channels.has(channelOf(id)) || this.starting.has(id));
+        this.asleep.delete(id);
+        this.quietSince.delete(id);
+        const station = this.deps.store.get(id);
+        if (station)
+            this.log(`  Station "${station.name}" woke for a listener.`);
+        const woken = this.launch(id).finally(() => this.waking.delete(id));
+        this.waking.set(id, woken);
+        return woken;
+    }
+    /**
+     * 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.
+     */
+    async awake(id, timeoutMs = WAKE_WAIT_MS, gone = () => false) {
+        const channelId = channelOf(id);
+        const deadline = Date.now() + timeoutMs;
+        const woke = this.asleep.has(id) || this.waking.has(id);
+        if (!woke)
+            return this.deps.channels.has(channelId);
+        let timer;
+        const up = await Promise.race([
+            this.wake(id),
+            new Promise((done) => { timer = setTimeout(() => done(false), timeoutMs); }),
+        ]);
+        clearTimeout(timer);
+        if (!up && !this.deps.channels.has(channelId))
+            return false;
+        while (!this.deps.channels.flowing(channelId) && Date.now() < deadline && !gone()) {
+            if (!this.deps.channels.has(channelId) && !this.starting.has(id))
+                return false;
+            await new Promise((done) => setTimeout(done, 50));
+        }
+        return this.deps.channels.has(channelId);
+    }
+    /**
+     * 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.
+     */
+    takeResume(id, station, files) {
+        const parked = this.parked.get(id);
+        this.parked.delete(id);
+        let upcoming = parked && parked.length > 0 ? parked : null;
+        const after = station.resume?.after ?? "";
+        if (!parked && after && !station.shuffle) {
+            const at = files.indexOf(after);
+            if (at >= 0 && at + 1 < files.length)
+                upcoming = files.slice(at + 1);
+        }
+        const sinceBreak = station.resume?.sinceBreak ?? 0;
+        // Used once: a recovery later is a start like any other.
+        if (station.resume)
+            this.deps.store.setResume(id, null);
+        return { upcoming, sinceBreak };
+    }
     async launch(id) {
         const station = this.deps.store.get(id);
         if (!station || station.desired !== "running")
@@ -118,6 +300,10 @@ export class StationRunner {
         }
         this.starting.add(id);
         const store = this.deps.store;
+        const resume = this.takeResume(id, station, files);
+        // The first pass after a sleep is the rest of the one it slept in.
+        let carryOn = resume.upcoming;
+        let clock = resume.sinceBreak;
         try {
             const ok = await this.deps.pull(channelId, station.name, files, {
                 audioBitrate: station.bitrate,
@@ -125,9 +311,19 @@ export class StationRunner {
                     repeat: station.repeat,
                     passOver: true,
                     // Read at every pass, so turning shuffle on or off lands then.
-                    order: (length, files) => (store.get(id)?.shuffle
-                        ? spreadByArtist(files, (file) => this.deps.artistOf?.(file) || artistFromPath(file))
-                        : [...Array(length).keys()]),
+                    order: (length, files) => {
+                        if (carryOn) {
+                            const wanted = carryOn;
+                            carryOn = null;
+                            const index = new Map(files.map((file, at) => [file, at]));
+                            const picked = wanted.map((file) => index.get(file)).filter((at) => at !== undefined && !store.isExcluded(id, files[at]));
+                            if (picked.length > 0)
+                                return picked;
+                        }
+                        return store.get(id)?.shuffle
+                            ? spreadByArtist(files, (file) => this.deps.artistOf?.(file) || artistFromPath(file))
+                            : [...Array(length).keys()];
+                    },
                     // Read at every track, so an edit lands on the next one.
                     current: () => {
                         const now = store.get(id);
@@ -137,7 +333,12 @@ export class StationRunner {
                     // Read at every boundary, so setting breaks on a running station
                     // lands without a restart; 0 is none.
                     ...(this.deps.breaks
-                        ? { breaks: { everySeconds: () => store.get(id)?.breaksEvery ?? 0, next: () => this.deps.breaks(station.video) } }
+                        ? { breaks: {
+                                everySeconds: () => store.get(id)?.breaksEvery ?? 0,
+                                next: () => this.deps.breaks(station.video),
+                                // Once: a redial later in the day starts its own clock, as it always has.
+                                sinceBreak: () => { const was = clock; clock = 0; return was; },
+                            } }
                         : {}),
                     onFailure: ({ file, reason }) => {
                         this.errors.set(id, reason);
@@ -218,6 +419,9 @@ export class StationRunner {
             return "stopped";
         if (station.desired === "stopped")
             return "stopped";
+        // On the air to anyone asking: the first listener wakes it.
+        if (this.asleep.has(id))
+            return "live";
         if (this.starting.has(id))
             return "starting";
         const info = this.deps.channels.info(channelOf(id));

package/dist/stations.d.ts

@@ -41,6 +41,15 @@ export interface Station {
     idempotencyKey: string;
     createdAt: number;
     updatedAt: number;
+    /**
+     * Where it was when it last went to sleep with nobody listening: the file
+     * that was on, so it carries on after it, and the seconds of airtime since
+     * its last break, so breaks keep their spacing across sleeps.
+     */
+    resume?: {
+        after: string;
+        sinceBreak: number;
+    };
 }
 /** Times an item may fail in a row before rotation leaves it out. */
 export declare const EXCLUDE_AFTER = 3;
@@ -97,6 +106,11 @@ export declare class StationStore {
     /** Name, words, files and rotation. Who may listen is changed by publish/unpublish. */
     update(id: string, input: StationInput, items: string[] | null, now?: number): Station;
     remove(id: string): boolean;
+    /** Where it was when it went to sleep (Station.resume); null forgets it. */
+    setResume(id: string, resume: {
+        after: string;
+        sinceBreak: number;
+    } | null): void;
     setDesired(id: string, desired: Desired, now?: number): Station;
     /**
      * Who may hear it, and whether the directory lists it. Public needs a

package/dist/stations.js

@@ -262,6 +262,17 @@ export class StationStore {
             this.save();
         return had;
     }
+    /** Where it was when it went to sleep (Station.resume); null forgets it. */
+    setResume(id, resume) {
+        const station = this.stations.get(id);
+        if (!station)
+            return;
+        if (resume)
+            station.resume = { after: resume.after, sinceBreak: Math.max(0, Math.round(resume.sinceBreak)) };
+        else
+            delete station.resume;
+        this.save();
+    }
     setDesired(id, desired, now = Date.now()) {
         const station = this.require(id);
         station.desired = desired;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/channels.ts

@@ -325,6 +325,19 @@ export class Channel {
     return done;
   }
 
+  /** How far listeners have got into this dial of a list, by the encoder's progress. */
+  private heard = 0;
+
+  /** Where a list would pick up after what listeners hear now (PlaylistInputStream.resumePoint). */
+  resumePoint(): { file: string; upcoming: string[]; sinceBreak: number } | null {
+    return this.playlistInput?.resumePoint(this.heard) ?? null;
+  }
+
+  /** Whether listeners would get sound (and, for a picture, its opening) if they joined now. */
+  get flowing(): boolean {
+    return this.info.bytes > 0 && (!this.fragments || this.fragments.ready);
+  }
+
   /** An entry's tags, as read when it was put on. */
   tagsOf(file: string): { title: string; artist: string; album: string } | undefined {
     return this.playlistInput?.tags.get(file);
@@ -503,6 +516,7 @@ export class Channel {
         ...resume.rotation,
       }) : null;
       this.playlistInput = playlistInput;
+      this.heard = 0;
       const through = this.outroOn ? null : playlistInput
         ? { format: "mpegts", open: async (signal: AbortSignal) => playlistInput.open(signal) }
         : this.options.through?.(this.info, from, input, audio) ?? null;
@@ -585,6 +599,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) this.info.playlist = place.list as string[];
@@ -1450,6 +1465,21 @@ export class Channels {
     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: string): { file: string; upcoming: string[]; sinceBreak: number } | null {
+    return this.open.get(id)?.resumePoint() ?? null;
+  }
+
+  /** Whether a channel is up and has started sending. */
+  flowing(id: string): boolean {
+    return this.open.get(id)?.flowing ?? false;
+  }
+
+  /** Who is attached to one channel: listeners, relays, packagers. */
+  listenersOf(id: string): number {
+    return this.open.get(id)?.listeners.size ?? 0;
+  }
+
   /** The next entry, now, on a channel playing a list of files. */
   skip(id: string): boolean {
     return this.open.get(id)?.skip() ?? false;

package/src/library.ts

@@ -39,6 +39,19 @@ 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 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: Record<string, string | undefined>, config: Config): number {
+  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(): string {
@@ -55,6 +68,7 @@ export function readConfig(): Config {
       ...(typeof record["publish"] === "boolean" ? { publish: record["publish"] } : {}),
       ...(typeof record["autoStations"] === "object" && record["autoStations"] !== null ? { autoStations: record["autoStations"] as Record<string, unknown> } : {}),
       ...(typeof record["limits"] === "object" && record["limits"] !== null ? { limits: record["limits"] as Record<string, unknown> } : {}),
+      ...(typeof record["stationIdleSeconds"] === "number" ? { stationIdleSeconds: record["stationIdleSeconds"] } : {}),
       ...(Array.isArray(record["trustedProxies"]) ? { trustedProxies: (record["trustedProxies"] as unknown[]).filter((one): one is string => typeof one === "string") } : {}),
       ...(Array.isArray(record["guideHosts"]) ? { guideHosts: (record["guideHosts"] as unknown[]).filter((one): one is string => typeof one === "string") } : {}),
       ...(typeof record["guideAds"] === "object" && record["guideAds"] !== null ? { guideAds: record["guideAds"] as Config["guideAds"] } : {}),

package/src/playlist-input.ts

@@ -39,7 +39,16 @@ export interface PlaylistInput {
    * `next` answers a file to play (an advert, an ident) or null for no break
    * this time. The break is outside the rotation and the station's history.
    */
-  breaks?: { everySeconds: number | (() => number); next: () => Promise<string | null> };
+  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: { at: number; file: string; reason: string }) => void;
 }
@@ -51,12 +60,26 @@ export interface PlaylistInput {
  */
 export 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
  * backpressure bounding read-ahead independently of the directory's size. */
 export class PlaylistInputStream {
-  private entries: { at: number; file: string; start: number; position: number; list: readonly string[] }[] = [];
+  private entries: Entry[] = [];
   error: Error | null = null;
   complete = false;
   /**
@@ -68,7 +91,7 @@ export class PlaylistInputStream {
   constructor(private readonly 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> {
     return this.entries;
   }
 
@@ -84,6 +107,22 @@ export class PlaylistInputStream {
       : { 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: number): { file: string; upcoming: string[]; sinceBreak: number } | null {
+    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): one is string => 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. */
   private stopCurrent: (() => void) | null = null;
   private skipping = false;
@@ -114,7 +153,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: { at: number; file: string; position: number } | null = null;
       for (;;) {
@@ -179,7 +220,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/src/server.ts

@@ -122,7 +122,7 @@ import { Porkbun, isIPv4, isIPv6, type DnsZone } from "./dns.ts";
 import { NameError, Names } from "./names.ts";
 import { AcmeIssuer, Certs } from "./certs.ts";
 import { claimName, fetchCert, humanizeSource, labelFor, readCertFiles, writeCertFiles } from "./naming.ts";
-import { forbiddenLibrary, readConfig, readLibrary, writeConfig } from "./library.ts";
+import { forbiddenLibrary, readConfig, readLibrary, stationIdleSeconds, writeConfig } from "./library.ts";
 import { createThrottle, presentedCredential, type Throttle } from "@profullstack/throttle";
 import { Durable } from "./durable.ts";
 import { notifyAll, resendEmail, webPush, type Notification } from "./notify.ts";
@@ -5940,6 +5940,12 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
         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
@@ -7455,6 +7461,8 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     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) =>
@@ -7729,6 +7737,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     });
   }
   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/src/station-routes.ts

@@ -114,14 +114,16 @@ function nowPlayingFile(ctx: StationContext, station: Station): string {
 
 export function publicView(ctx: StationContext, station: Station): PublicStation {
   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 {
@@ -161,11 +163,13 @@ export function guideEntries(ctx: StationContext): Array<PublicStation & { page:
   return [...names].map(([slug, one]) => ({ ...publicView(ctx, one), page: links(ctx, one, base).page, m3u: links(ctx, one, base).m3u, group: guideGroup(one), radio: `${radioBase}/radio/${slug}` }));
 }
 
-export function ownerView(ctx: StationContext, station: Station): OwnerStation & { links: ReturnType<typeof links>; nowPlaying: string } {
+export function ownerView(ctx: StationContext, station: Station): OwnerStation & { links: ReturnType<typeof links>; nowPlaying: string; sleeping: boolean } {
   const { failures, idempotencyKey: _key, ...rest } = 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),
@@ -348,18 +352,31 @@ export async function handleStations(
       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) ?? "";