nixamp 0.5.10 → 0.5.12

package/dist/attach.js

@@ -23,7 +23,11 @@ import { KEY_HEADER } from "./share.js";
 const RECONNECT_MS = 1000;
 /** A remote track has no path, because no filesystem path leaves the machine. */
 export function applySnapshot(state, snapshot) {
-    state.tracks = snapshot.tracks.map((track) => ({ path: "", ...track }));
+    // A frame without a list is not an empty library, it is a frame with nothing
+    // new to say about it -- which is every frame but the first.
+    if (snapshot.tracks !== undefined) {
+        state.tracks = snapshot.tracks.map((track) => ({ path: "", ...track }));
+    }
     state.index = snapshot.index;
     state.playing = snapshot.playing;
     state.position = snapshot.position;

package/dist/main.js

@@ -72,6 +72,9 @@ Options for serve:
                    its own interfaces. Also NIXAMP_PUBLIC_URL
       --no-lookup  do not ask ipinfo.io what this machine's public address is
                    when nothing local looks public
+      --tls-cert FILE --tls-key FILE  serve https rather than http. Needed by
+                   anyone opening this from a page that is itself https, since
+                   a browser refuses every request from https to http
       --ingest     accept a live stream in at POST /api/ingest
       --rtmp-in N  also listen for RTMP publishers (OBS, Larix) from port N
       --rtmp-streams N  how many may publish at once (default 3, a port each)

package/dist/protocol.d.ts

@@ -25,7 +25,24 @@ export interface RemoteTrack {
 export interface Snapshot {
     /** Bumped on every push so a client can drop an out-of-order frame. */
     revision: number;
-    tracks: RemoteTrack[];
+    /**
+     * The library, sent when it is news and left out when it is not.
+     *
+     * It used to ride in every frame. At twelve frames a second over a library of
+     * five thousand, that is five megabytes a second of JSON for a client to
+     * parse on the thread that is also decoding the audio -- which is exactly
+     * what it sounded like. It is sent on the first frame of a subscription and
+     * again whenever the list actually changes; absent means "the same as
+     * before", and a client keeps what it had.
+     */
+    tracks?: RemoteTrack[];
+    /**
+     * How many tracks there are, in every frame.
+     *
+     * A client that has not received a list yet still has to draw something, and
+     * a count is four bytes rather than half a megabyte.
+     */
+    trackCount: number;
     index: number;
     playing: boolean;
     position: number;
@@ -61,4 +78,19 @@ export declare const COMMAND_TYPES: readonly ["play", "toggle", "stop", "next",
 export declare function parseCommand(input: unknown): Command | null;
 /** The name a remote shows for a track. */
 export declare function remoteName(track: RemoteTrack): string;
-export declare function emptySnapshot(): Snapshot;
+export declare function emptySnapshot(): FullSnapshot;
+/**
+ * Fold a frame into what the client already had.
+ *
+ * A frame without `tracks` is not a frame with no tracks: it is a frame that
+ * had nothing new to say about them. Every client needs this, so none of them
+ * should write it twice.
+ */
+export declare function merge(previous: FullSnapshot, incoming: Snapshot): FullSnapshot;
+/**
+ * A snapshot a client has already folded, so the library is known to be there.
+ * Every reader wants this one; only the wire carries the other.
+ */
+export type FullSnapshot = Snapshot & {
+    tracks: RemoteTrack[];
+};

package/dist/protocol.js

@@ -41,6 +41,7 @@ export function emptySnapshot() {
     return {
         revision: 0,
         tracks: [],
+        trackCount: 0,
         index: 0,
         playing: false,
         position: 0,
@@ -51,3 +52,13 @@ export function emptySnapshot() {
         root: "",
     };
 }
+/**
+ * Fold a frame into what the client already had.
+ *
+ * A frame without `tracks` is not a frame with no tracks: it is a frame that
+ * had nothing new to say about them. Every client needs this, so none of them
+ * should write it twice.
+ */
+export function merge(previous, incoming) {
+    return { ...incoming, tracks: incoming.tracks ?? previous.tracks };
+}

package/dist/server.d.ts

@@ -56,6 +56,18 @@ export interface ServeOptions {
      * listing is skipped and the printed links only work inside the house.
      */
     publicUrl: string;
+    /**
+     * A certificate and its key, to serve https rather than http.
+     *
+     * Needed by anybody whose nixamp is opened from a page that is itself https:
+     * a browser refuses every request from an https page to an http one --
+     * fetch, event stream and media alike -- and no header on either side lifts
+     * that. It is deliberately not required: a nixamp on 192.168.1.5 cannot have
+     * a certificate for that address, and forcing one would put a browser
+     * warning in front of everybody at home to fix a problem they do not have.
+     */
+    tlsCert: string;
+    tlsKey: string;
     /**
      * Ask an outside service what this machine's public address is, when no
      * interface holds one and none was given. Behind NAT that is the only way to
@@ -111,7 +123,8 @@ export declare function parseRange(header: string | undefined, size: number): By
 export declare function safeJoin(rootDir: string, urlPath: string): string | null;
 /** What the HTTP layer needs from a player. Tests hand it a fake. */
 export interface Engine {
-    snapshot(): Snapshot;
+    /** `withTracks` false leaves the library out, for a frame that is only motion. */
+    snapshot(withTracks?: boolean): Snapshot;
     command(command: Command): void;
     subscribe(listener: (snapshot: Snapshot) => void): () => void;
     /** Absolute path of a track, or undefined when the index is not one. */
@@ -161,7 +174,11 @@ export declare class PlayerEngine implements Engine {
     fps?: number);
     private readonly silent;
     private consume;
-    snapshot(): Snapshot;
+    /**
+     * The current state. `withTracks` carries the library, which is worth half a
+     * megabyte on a real one and is only news when it has changed.
+     */
+    snapshot(withTracks?: boolean): Snapshot;
     trackPath(index: number): string | undefined;
     command(command: Command): void;
     private clamp;
@@ -169,6 +186,13 @@ export declare class PlayerEngine implements Engine {
     private start;
     private halt;
     subscribe(listener: (snapshot: Snapshot) => void): () => void;
+    /**
+     * Send the state to everyone watching.
+     *
+     * The library goes only when `listChanged` says it has, which is what turned
+     * five megabytes a second into a few kilobytes: an analyser tick has nothing
+     * to say about the track list, and it fires twelve times a second.
+     */
     private push;
     stop(): void;
     replace(tracks: Track[], root: string): void;
@@ -238,6 +262,11 @@ export interface HandlerOptions {
     signIn?: SignIn;
     /** True when this instance is reached over https, for the cookie's Secure. */
     secureCookies?: boolean;
+    /** A certificate and key in PEM, when this server is to speak https itself. */
+    tls?: {
+        cert: string;
+        key: string;
+    };
     /**
      * True when a proxy sits in front, so `x-forwarded-for` names the caller.
      * False everywhere else on purpose: the header is trivially forged, and

package/dist/server.js

@@ -11,6 +11,7 @@
  */
 import { createReadStream, statSync } from "node:fs";
 import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
@@ -70,6 +71,8 @@ export function parseServeArgs(argv) {
         name: "",
         publicUrl: process.env["NIXAMP_PUBLIC_URL"] ?? "",
         lookup: true,
+        tlsCert: process.env["NIXAMP_TLS_CERT"] ?? "",
+        tlsKey: process.env["NIXAMP_TLS_KEY"] ?? "",
         x402: false,
         owner: "",
         ingest: false,
@@ -78,6 +81,11 @@ export function parseServeArgs(argv) {
         rtmp: [],
     };
     let sawRoot = false;
+    const bothOrNeither = () => {
+        if (Boolean(options.tlsCert) !== Boolean(options.tlsKey)) {
+            throw new Error("nixamp serve: --tls-cert and --tls-key go together");
+        }
+    };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         const value = () => {
@@ -130,6 +138,12 @@ export function parseServeArgs(argv) {
             }
             options.publicUrl = given.replace(/\/+$/, "");
         }
+        else if (arg === "--tls-cert") {
+            options.tlsCert = value();
+        }
+        else if (arg === "--tls-key") {
+            options.tlsKey = value();
+        }
         else if (arg === "--no-lookup") {
             options.lookup = false;
         }
@@ -175,6 +189,7 @@ export function parseServeArgs(argv) {
             sawRoot = true;
         }
     }
+    bothOrNeither();
     return options;
 }
 const TYPES = {
@@ -348,10 +363,15 @@ export class PlayerEngine {
         this.pending = joined.subarray(at);
         this.dirty = true;
     }
-    snapshot() {
+    /**
+     * The current state. `withTracks` carries the library, which is worth half a
+     * megabyte on a real one and is only news when it has changed.
+     */
+    snapshot(withTracks = true) {
         return {
             revision: this.revision,
-            tracks: toRemoteTracks(this.tracks),
+            ...(withTracks ? { tracks: toRemoteTracks(this.tracks) } : {}),
+            trackCount: this.tracks.length,
             index: this.state.index,
             playing: this.state.playing,
             position: this.state.position,
@@ -445,11 +465,18 @@ export class PlayerEngine {
             }
         };
     }
-    push() {
+    /**
+     * Send the state to everyone watching.
+     *
+     * The library goes only when `listChanged` says it has, which is what turned
+     * five megabytes a second into a few kilobytes: an analyser tick has nothing
+     * to say about the track list, and it fires twelve times a second.
+     */
+    push(listChanged = false) {
         this.revision++;
         if (this.listeners.size === 0)
             return;
-        const snapshot = this.snapshot();
+        const snapshot = this.snapshot(listChanged);
         for (const listener of this.listeners)
             listener(snapshot);
     }
@@ -468,7 +495,7 @@ export class PlayerEngine {
         this.state.index = 0;
         this.state.position = 0;
         this.state.note = "";
-        this.push();
+        this.push(true);
     }
     retag(tracks, root) {
         // Dropped rather than applied if the library moved underneath: somebody
@@ -480,8 +507,9 @@ export class PlayerEngine {
             return;
         this.tracks = tracks;
         // No stop, no index reset: the only thing that changes is what the titles
-        // say, and every remote finds out because a snapshot goes out.
-        this.push();
+        // say, and every remote finds out because a snapshot goes out -- carrying
+        // the list, since the titles are the whole point of this one.
+        this.push(true);
     }
 }
 /** An engine with no library behind it, for the hosted PWA. */
@@ -1540,7 +1568,7 @@ export function createHandler(engine, options) {
                 json(response, 404, { error: "no such track" });
                 return;
             }
-            watch(request, response, "media", engine.snapshot().tracks[index]?.title ?? file);
+            watch(request, response, "media", engine.snapshot().tracks?.[index]?.title ?? file);
             // A browser asks for every track here, and a matroska or an avi handed
             // to it raw is bytes it cannot play. Seeking is what this route is for
             // and transcoding gives it up, but an unseekable film beats a silent
@@ -1572,11 +1600,11 @@ export function createHandler(engine, options) {
                 return;
             }
             const current = engine.snapshot();
-            if (current.tracks.length === 0) {
+            if (current.trackCount === 0) {
                 json(response, 404, { error: "nothing is playing" });
                 return;
             }
-            watch(request, response, "stream", current.tracks[current.index]?.title ?? "live");
+            watch(request, response, "stream", current.tracks?.[current.index]?.title ?? "live");
             liveAudio(request, response, engine, options.ffmpeg ?? ["ffmpeg"]);
             return;
         }
@@ -1591,7 +1619,7 @@ export function createHandler(engine, options) {
                 json(response, 403, { error: "media streaming is off" });
                 return;
             }
-            watch(request, response, "stream", engine.snapshot().tracks[index]?.title ?? source);
+            watch(request, response, "stream", engine.snapshot().tracks?.[index]?.title ?? source);
             transcode(request, response, source, options.ffmpeg ?? ["ffmpeg"]);
             return;
         }
@@ -1885,14 +1913,20 @@ function sendFile(request, response, file) {
 }
 export function createServer(engine, options) {
     const handle = createHandler(engine, options);
-    return createHttpServer((request, response) => {
+    const onRequest = (request, response) => {
         handle(request, response).catch(() => {
             if (!response.headersSent)
                 json(response, 500, { error: "server error" });
             else
                 response.end();
         });
-    });
+    };
+    // https when there is a certificate to serve it with, and the same handler
+    // either way: nothing above this line knows or cares which it got.
+    if (options.tls) {
+        return createHttpsServer({ cert: options.tls.cert, key: options.tls.key }, onRequest);
+    }
+    return createHttpServer(onRequest);
 }
 export async function serve(argv, version = "0.1.0") {
     const options = parseServeArgs(argv);
@@ -2099,6 +2133,18 @@ export async function serve(argv, version = "0.1.0") {
             });
         });
     }
+    // Read before listening, so a missing or unreadable certificate is a sentence
+    // now rather than a connection that resets later.
+    const tls = options.tlsCert
+        ? (() => {
+            try {
+                return { cert: readFileSync(options.tlsCert, "utf8"), key: readFileSync(options.tlsKey, "utf8") };
+            }
+            catch (error) {
+                throw new Error(`nixamp serve: could not read the certificate: ${error.message}`);
+            }
+        })()
+        : undefined;
     const server = createServer(engine, {
         web,
         media: options.media,
@@ -2114,6 +2160,7 @@ export async function serve(argv, version = "0.1.0") {
         paywall,
         ffmpeg: tools.ffmpeg,
         ffprobe: tools.ffprobe,
+        ...(tls ? { tls } : {}),
         load: (next) => loadSource(tools, next),
         ...(directory ? { directory } : {}),
         ...(follows ? { follows, vapidPublicKey } : {}),
@@ -2168,12 +2215,12 @@ export async function serve(argv, version = "0.1.0") {
     // is and nothing local looks public, ask. What comes back is a fact about the
     // router and not about this port -- the port still has to be forwarded -- so
     // it is marked as a guess and everything that prints it says so.
-    const localAddresses = reachableAddresses(options.host, port, options.publicUrl);
+    const localAddresses = reachableAddresses(options.host, port, options.publicUrl, tls ? "https" : "http");
     const guessedPublic = options.lookup && !options.publicUrl && !localAddresses.some((a) => a.label === "on the internet")
         ? await lookupPublicIp()
         : "";
     const addresses = guessedPublic
-        ? reachableAddresses(options.host, port, `http://${guessedPublic.includes(":") ? `[${guessedPublic}]` : guessedPublic}:${port}`)
+        ? reachableAddresses(options.host, port, `${tls ? "https" : "http"}://${guessedPublic.includes(":") ? `[${guessedPublic}]` : guessedPublic}:${port}`, tls ? "https" : "http")
         : localAddresses;
     // Listening on every interface proves the socket is open here and nothing
     // about the path between here and the phone.
@@ -2341,7 +2388,7 @@ export async function serve(argv, version = "0.1.0") {
                 },
                 nowPlaying: () => {
                     const snapshot = engine.snapshot();
-                    return snapshot.tracks[snapshot.index]?.title ?? "";
+                    return snapshot.tracks?.[snapshot.index]?.title ?? "";
                 },
                 onConfig: (remote) => {
                     const next = applyRemoteConfig(paywallConfig, remote?.x402);

package/dist/share.d.ts

@@ -45,7 +45,7 @@ export declare function lookupPublicIp(send?: typeof fetch, timeoutMs?: number):
  * somewhere else can open. It is labelled for what it is, because the key in
  * the link is then the only thing between a stranger and the library.
  */
-export declare function reachableAddresses(host: string, port: number, publicUrl?: string): {
+export declare function reachableAddresses(host: string, port: number, publicUrl?: string, scheme?: "http" | "https"): {
     label: string;
     url: string;
 }[];

package/dist/share.js

@@ -115,11 +115,11 @@ export async function lookupPublicIp(send = fetch, timeoutMs = 2500) {
  * somewhere else can open. It is labelled for what it is, because the key in
  * the link is then the only thing between a stranger and the library.
  */
-export function reachableAddresses(host, port, publicUrl = "") {
+export function reachableAddresses(host, port, publicUrl = "", scheme = "http") {
     const link = (address) => {
         // A bare IPv6 address needs brackets before it is a URL.
         const authority = address.includes(":") ? `[${address}]` : address;
-        return `http://${authority}:${port}`;
+        return `${scheme}://${authority}:${port}`;
     };
     // An address somebody told us about, because it is one this machine cannot
     // know: a tunnel, a reverse proxy, or a router forwarding a port. It goes
@@ -145,7 +145,7 @@ export function reachableAddresses(host, port, publicUrl = "") {
     found.sort((x, y) => order[x.kind] - order[y.kind]);
     return [
         ...told,
-        { label: "here", url: `http://localhost:${port}` },
+        { label: "here", url: `${scheme}://localhost:${port}` },
         ...found.map(({ label, url }) => ({ label, url })),
     ];
 }

package/package.json

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

package/src/attach.ts

@@ -26,7 +26,11 @@ const RECONNECT_MS = 1000;
 
 /** A remote track has no path, because no filesystem path leaves the machine. */
 export function applySnapshot(state: State, snapshot: Snapshot): void {
-  state.tracks = snapshot.tracks.map((track) => ({ path: "", ...track }));
+  // A frame without a list is not an empty library, it is a frame with nothing
+  // new to say about it -- which is every frame but the first.
+  if (snapshot.tracks !== undefined) {
+    state.tracks = snapshot.tracks.map((track) => ({ path: "", ...track }));
+  }
   state.index = snapshot.index;
   state.playing = snapshot.playing;
   state.position = snapshot.position;

package/src/main.ts

@@ -96,6 +96,9 @@ Options for serve:
                    its own interfaces. Also NIXAMP_PUBLIC_URL
       --no-lookup  do not ask ipinfo.io what this machine's public address is
                    when nothing local looks public
+      --tls-cert FILE --tls-key FILE  serve https rather than http. Needed by
+                   anyone opening this from a page that is itself https, since
+                   a browser refuses every request from https to http
       --ingest     accept a live stream in at POST /api/ingest
       --rtmp-in N  also listen for RTMP publishers (OBS, Larix) from port N
       --rtmp-streams N  how many may publish at once (default 3, a port each)

package/src/protocol.ts

@@ -27,7 +27,24 @@ export interface RemoteTrack {
 export interface Snapshot {
   /** Bumped on every push so a client can drop an out-of-order frame. */
   revision: number;
-  tracks: RemoteTrack[];
+  /**
+   * The library, sent when it is news and left out when it is not.
+   *
+   * It used to ride in every frame. At twelve frames a second over a library of
+   * five thousand, that is five megabytes a second of JSON for a client to
+   * parse on the thread that is also decoding the audio -- which is exactly
+   * what it sounded like. It is sent on the first frame of a subscription and
+   * again whenever the list actually changes; absent means "the same as
+   * before", and a client keeps what it had.
+   */
+  tracks?: RemoteTrack[];
+  /**
+   * How many tracks there are, in every frame.
+   *
+   * A client that has not received a list yet still has to draw something, and
+   * a count is four bytes rather than half a megabyte.
+   */
+  trackCount: number;
   index: number;
   playing: boolean;
   position: number;
@@ -83,10 +100,11 @@ export function remoteName(track: RemoteTrack): string {
   return track.artist ? `${track.artist} — ${track.title}` : track.title;
 }
 
-export function emptySnapshot(): Snapshot {
+export function emptySnapshot(): FullSnapshot {
   return {
     revision: 0,
     tracks: [],
+    trackCount: 0,
     index: 0,
     playing: false,
     position: 0,
@@ -97,3 +115,20 @@ export function emptySnapshot(): Snapshot {
     root: "",
   };
 }
+
+/**
+ * Fold a frame into what the client already had.
+ *
+ * A frame without `tracks` is not a frame with no tracks: it is a frame that
+ * had nothing new to say about them. Every client needs this, so none of them
+ * should write it twice.
+ */
+export function merge(previous: FullSnapshot, incoming: Snapshot): FullSnapshot {
+  return { ...incoming, tracks: incoming.tracks ?? previous.tracks };
+}
+
+/**
+ * A snapshot a client has already folded, so the library is known to be there.
+ * Every reader wants this one; only the wire carries the other.
+ */
+export type FullSnapshot = Snapshot & { tracks: RemoteTrack[] };