nixamp 0.1.0 → 0.2.0

package/dist/sources.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Where a playlist comes from.
+ *
+ * A directory, a file, an .m3u, or a URL to any of those. ffmpeg reads a URL as
+ * happily as a path, so a remote track needs no special case once it is in the
+ * list; what needs care is telling the four apart, and telling an .m3u that
+ * lists tracks from an HLS playlist that *is* one track.
+ */
+/** http and https only. ffmpeg speaks more, but these are what a link is. */
+export declare function isRemote(source: string): boolean;
+export declare function isPlaylistFile(source: string): boolean;
+/**
+ * An HLS playlist describes one stream in segments; an .m3u describes a list of
+ * things to play. Both are "m3u8" on disk, and the tags are the only honest way
+ * to tell them apart. Expanding an HLS playlist into a track per segment would
+ * turn one song into four hundred.
+ */
+export declare function isHls(text: string): boolean;
+export interface Entry {
+    /** A path or a URL, whichever the playlist gave us. */
+    source: string;
+    title: string;
+    /** Seconds, from #EXTINF. Zero when it did not say, and for live. */
+    duration: number;
+}
+/** Resolve a playlist line against the playlist's own location. */
+export declare function resolveEntry(base: string, entry: string): string;
+/**
+ * Parse an .m3u or .m3u8. `#EXTINF:<seconds>,<title>` decorates the line after
+ * it; everything else beginning with # is a comment or a tag we do not need.
+ */
+export declare function parseM3u(text: string, base: string): Entry[];
+/** A .pls, which Shoutcast and Icecast hand out as often as an .m3u. */
+export declare function parsePls(text: string, base: string): Entry[];
+/** The last useful part of a path or URL, for when nothing named the track. */
+export declare function nameOf(source: string): string;
+export declare function playsInBrowser(source: string): boolean;

package/dist/sources.js

@@ -0,0 +1,125 @@
+/**
+ * Where a playlist comes from.
+ *
+ * A directory, a file, an .m3u, or a URL to any of those. ffmpeg reads a URL as
+ * happily as a path, so a remote track needs no special case once it is in the
+ * list; what needs care is telling the four apart, and telling an .m3u that
+ * lists tracks from an HLS playlist that *is* one track.
+ */
+/** http and https only. ffmpeg speaks more, but these are what a link is. */
+export function isRemote(source) {
+    return /^https?:\/\//i.test(source);
+}
+export function isPlaylistFile(source) {
+    const path = isRemote(source) ? new URL(source).pathname : source;
+    return /\.(m3u|m3u8|pls)$/i.test(path);
+}
+/**
+ * An HLS playlist describes one stream in segments; an .m3u describes a list of
+ * things to play. Both are "m3u8" on disk, and the tags are the only honest way
+ * to tell them apart. Expanding an HLS playlist into a track per segment would
+ * turn one song into four hundred.
+ */
+export function isHls(text) {
+    return /^#EXT-X-(?:STREAM-INF|TARGETDURATION|MEDIA-SEQUENCE|PLAYLIST-TYPE|ENDLIST)/im.test(text);
+}
+/** Resolve a playlist line against the playlist's own location. */
+export function resolveEntry(base, entry) {
+    if (isRemote(entry))
+        return entry;
+    if (isRemote(base))
+        return new URL(entry, base).toString();
+    if (entry.startsWith("/"))
+        return entry;
+    const dir = base.slice(0, Math.max(0, base.lastIndexOf("/")));
+    return dir ? `${dir}/${entry}` : entry;
+}
+/**
+ * Parse an .m3u or .m3u8. `#EXTINF:<seconds>,<title>` decorates the line after
+ * it; everything else beginning with # is a comment or a tag we do not need.
+ */
+export function parseM3u(text, base) {
+    const out = [];
+    let duration = 0;
+    let title = "";
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "")
+            continue;
+        if (line.startsWith("#")) {
+            const info = /^#EXTINF:\s*(-?[\d.]+)\s*(?:,(.*))?$/i.exec(line);
+            if (info) {
+                const seconds = Number(info[1]);
+                // -1 is the conventional "unknown", which is also what live means.
+                duration = Number.isFinite(seconds) && seconds > 0 ? seconds : 0;
+                title = (info[2] ?? "").trim();
+            }
+            continue;
+        }
+        const source = resolveEntry(base, line);
+        out.push({ source, duration, title: title || nameOf(source) });
+        duration = 0;
+        title = "";
+    }
+    return out;
+}
+/** A .pls, which Shoutcast and Icecast hand out as often as an .m3u. */
+export function parsePls(text, base) {
+    const files = new Map();
+    const titles = new Map();
+    const lengths = new Map();
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        const match = /^(File|Title|Length)(\d+)\s*=\s*(.*)$/i.exec(line);
+        if (!match)
+            continue;
+        const [, kind, index, value] = match;
+        if (/^file$/i.test(kind))
+            files.set(index, value);
+        else if (/^title$/i.test(kind))
+            titles.set(index, value);
+        else
+            lengths.set(index, Number(value));
+    }
+    return [...files.entries()]
+        .sort((a, b) => Number(a[0]) - Number(b[0]))
+        .map(([index, file]) => {
+        const source = resolveEntry(base, file);
+        const seconds = lengths.get(index) ?? 0;
+        return {
+            source,
+            title: titles.get(index)?.trim() || nameOf(source),
+            duration: Number.isFinite(seconds) && seconds > 0 ? seconds : 0,
+        };
+    });
+}
+/** The last useful part of a path or URL, for when nothing named the track. */
+export function nameOf(source) {
+    const remote = isRemote(source);
+    const path = remote ? new URL(source).pathname : source;
+    const last = path.split("/").filter(Boolean).pop() ?? source;
+    // Percent-decoding is a URL's business. A file on disk called
+    // `Some%20Song.mp3` is called exactly that, and renaming it in the display
+    // would be a lie about what is in the directory.
+    if (!remote)
+        return last || source;
+    try {
+        return decodeURIComponent(last) || source;
+    }
+    catch {
+        return last || source;
+    }
+}
+/**
+ * Formats a browser will play as-is. Anything else gets transcoded on the way
+ * out, which is the difference between a library that plays on a phone and one
+ * that plays on the machine it lives on.
+ */
+const WEB_READY = new Set([".mp3", ".m4a", ".aac", ".ogg", ".oga", ".opus", ".webm", ".mp4", ".wav"]);
+export function playsInBrowser(source) {
+    if (isRemote(source))
+        return false;
+    const path = source.toLowerCase();
+    const dot = path.lastIndexOf(".");
+    return dot > 0 && WEB_READY.has(path.slice(dot));
+}

package/package.json

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

package/src/admin.ts

@@ -0,0 +1,243 @@
+/**
+ * `nixamp admin` — what the daemon is doing, and who is listening to it.
+ *
+ * It talks to a running server over the same HTTP API a browser uses, so it
+ * works against the local daemon, against `nixamp serve` in another terminal,
+ * or against a nixamp on a different machine entirely.
+ */
+import { createApp, themes, type Container, type KeyEvent, type Theme } from "@profullstack/hqtui";
+import type { Color } from "@profullstack/hqtui";
+import type { Connection } from "./connections.ts";
+import { daemonUrl, readState } from "./daemon.ts";
+import { KEY_HEADER } from "./share.ts";
+
+interface Report {
+  connections: Connection[];
+  active: number;
+  startedAt: number;
+  now: number;
+}
+
+interface Snapshot {
+  tracks: { title: string; artist: string; duration: number }[];
+  index: number;
+  playing: boolean;
+  position: number;
+  root: string;
+  note: string;
+}
+
+export interface AdminOptions {
+  url: string;
+  key: string | null;
+}
+
+/** Where to point, from the flags or from the daemon that is running. */
+export function resolveTarget(argv: string[]): AdminOptions {
+  const at = argv.findIndex((a) => a === "--url" || a === "-u");
+  const keyAt = argv.findIndex((a) => a === "--key");
+  const url = at === -1 ? null : argv[at + 1];
+  const key = keyAt === -1 ? null : (argv[keyAt + 1] ?? null);
+
+  if (url) return { url: url.replace(/\/+$/, ""), key };
+
+  const state = readState();
+  if (state === null) {
+    throw new Error("nixamp: no daemon is running. Start one with `nixamp daemon start`, or pass --url.");
+  }
+  return { url: daemonUrl(state), key: key ?? state.key };
+}
+
+/** Seconds as something a person reads at a glance. */
+export function since(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ${minutes % 60}m`;
+  return `${Math.floor(hours / 24)}d ${hours % 24}h`;
+}
+
+export function bytes(value: number): string {
+  const units = ["B", "KiB", "MiB", "GiB"];
+  let n = value;
+  for (const unit of units) {
+    if (n < 1024 || unit === "GiB") return `${n < 10 && unit !== "B" ? n.toFixed(1) : Math.round(n)} ${unit}`;
+    n /= 1024;
+  }
+  return `${value} B`;
+}
+
+/** The colour a network deserves: the internet is the one worth noticing. */
+function networkColor(theme: Theme, network: Connection["network"]): number {
+  return network === "public"
+    ? theme.warning
+    : network === "cgnat"
+      ? theme.secondary
+      : network === "local"
+        ? theme.muted
+        : theme.success;
+}
+
+export async function admin(argv: string[]): Promise<void> {
+  const target = resolveTarget(argv);
+  const headers: Record<string, string> = target.key ? { [KEY_HEADER]: target.key } : {};
+
+  const ask = async <T,>(path: string): Promise<T | null> => {
+    try {
+      const response = await fetch(`${target.url}${path}`, { headers });
+      return response.ok ? ((await response.json()) as T) : null;
+    } catch {
+      return null;
+    }
+  };
+
+  let report: Report | null = null;
+  let snapshot: Snapshot | null = null;
+  let error = "";
+  let restreaming = "";
+  let typing = false;
+
+  const app = await createApp({ theme: themes.matrix, title: "nixamp admin", quitKeys: ["ctrl+c"] });
+
+  const refresh = async (): Promise<void> => {
+    const [next, state] = await Promise.all([ask<Report>("/api/connections"), ask<Snapshot>("/api/state")]);
+    error = next === null ? `cannot reach ${target.url}` : "";
+    if (next) report = next;
+    if (state) snapshot = state;
+    app.invalidate();
+  };
+
+  const timer = setInterval(() => void refresh(), 1000);
+  await refresh();
+
+  app.on("key", (event: KeyEvent) => {
+    const key = event.key;
+    if (typing) {
+      if (key === "escape") { typing = false; restreaming = ""; }
+      else if (key === "enter") {
+        const url = restreaming.trim();
+        typing = false;
+        restreaming = "";
+        if (url) void restream(target, headers, url).then(() => refresh());
+      } else if (key === "backspace") restreaming = restreaming.slice(0, -1);
+      // A printable key is a character; everything else is a name like "f1".
+      else if (key.length === 1) restreaming += key;
+      app.invalidate();
+      return;
+    }
+    if (key === "q") { app.quit(); return; }
+    if (key === "r") { typing = true; app.invalidate(); }
+  });
+
+  app.on("exit", () => clearInterval(timer));
+  app.render(({ ui, theme }) => draw(ui, theme, {
+    url: target.url, report, snapshot, error, typing, restreaming,
+  }));
+
+  await app.start();
+  clearInterval(timer);
+}
+
+/** Ask the server to play something else, which is what re-streaming is. */
+async function restream(target: AdminOptions, headers: Record<string, string>, url: string): Promise<void> {
+  try {
+    await fetch(`${target.url}/api/source`, {
+      method: "POST",
+      headers: { ...headers, "content-type": "application/json" },
+      body: JSON.stringify({ source: url }),
+    });
+  } catch {
+    // The next refresh reports the server being unreachable; this is not the
+    // place to make that noise.
+  }
+}
+
+export interface View {
+  url: string;
+  report: Report | null;
+  snapshot: Snapshot | null;
+  error: string;
+  typing: boolean;
+  restreaming: string;
+}
+
+export function draw(ui: Container, theme: Theme, view: View): void {
+  const { report, snapshot } = view;
+  const now = report?.now ?? Date.now();
+
+  ui.row({ size: 7, gap: 1 }, (row) => {
+    row.panel({ title: "Server" }, (p) => {
+      p.text(view.url, { fg: theme.primary });
+      p.label(snapshot?.root ?? "—");
+      p.keyValues([
+        { label: "Uptime", value: report ? since(now - report.startedAt) : "—", color: theme.accent },
+        { label: "Tracks", value: String(snapshot?.tracks.length ?? 0), color: theme.foreground },
+        { label: "Listeners", value: String(report?.active ?? 0), color: theme.success },
+      ]);
+    });
+
+    row.panel({ title: "Now playing" }, (p) => {
+      const track = snapshot ? snapshot.tracks[snapshot.index] : undefined;
+      p.text(track?.title ?? "nothing", { fg: theme.accent });
+      p.label(track?.artist || "—");
+      p.keyValues([
+        { label: "State", value: snapshot?.playing ? "playing" : "stopped", color: snapshot?.playing ? theme.success : theme.muted },
+        { label: "Position", value: snapshot ? since(snapshot.position * 1000) : "—", color: theme.foreground },
+      ]);
+    });
+  });
+
+  ui.panel({ title: `Connections (${report?.active ?? 0} live)` }, (p) => {
+    if (view.error) {
+      p.text(view.error, { fg: theme.danger });
+      return;
+    }
+    const rows = report?.connections ?? [];
+    if (rows.length === 0) {
+      p.label("Nobody is listening yet.");
+      return;
+    }
+
+    // A finished connection is drawn in muted colours rather than dropped: the
+    // most useful thing an admin view can say is "it stopped ten seconds ago".
+    const dim = (row: Connection, live: Color): Color => (row.endedAt === null ? live : theme.muted);
+
+    p.table<Connection>({
+      rows,
+      header: true,
+      headerColor: theme.muted,
+      zebra: false,
+      columns: [
+        { key: "address", title: "Where", min: 12, color: (row) => dim(row, theme.foreground) },
+        { key: "network", title: "Network", width: 9, color: (row) => dim(row, networkColor(theme, row.network)) },
+        { key: "kind", title: "Kind", width: 7, color: theme.muted },
+        { key: "agent", title: "Client", width: 12, color: theme.muted },
+        { key: "track", title: "Track", min: 16, color: (row) => dim(row, theme.primary),
+          render: (row) => row.track || "—" },
+        { key: "for", title: "For", width: 10, align: "right", color: theme.muted,
+          render: (row) => (row.endedAt === null
+            ? since(now - row.startedAt)
+            : `${since(row.endedAt - row.startedAt)} ago`) },
+        { key: "bytes", title: "Sent", width: 9, align: "right",
+          color: (row) => dim(row, theme.success), render: (row) => bytes(row.bytes) },
+      ],
+    });
+  });
+
+  if (view.typing) {
+    ui.panel({ title: "Re-stream a URL or a path", size: 4 }, (p) => {
+      p.text(`${view.restreaming}_`, { fg: theme.accent });
+      p.label("Enter plays it here. Escape forgets it.");
+    });
+  }
+
+  ui.statusBar({
+    items: [
+      { key: "r", label: "Re-stream" },
+      { key: "q", label: "Quit" },
+    ],
+    right: [{ key: "", label: report ? `${report.connections.length} seen` : "connecting" }],
+  });
+}

package/src/connections.ts

@@ -0,0 +1,145 @@
+/**
+ * Who is listening.
+ *
+ * A stream is a long-lived request, so the server can say exactly who is
+ * connected, to what, since when and how much has gone out. That is the whole
+ * point of the admin view: `ss -tn` tells you a socket exists, and nothing
+ * about which track is going down it.
+ */
+import type { IncomingMessage } from "node:http";
+import { classify } from "./share.ts";
+
+export type Kind = "stream" | "media" | "events" | "page";
+
+export interface Connection {
+  id: number;
+  kind: Kind;
+  /** The remote address, with an IPv4-mapped IPv6 prefix taken off. */
+  address: string;
+  /** Where that address lives: your network, tailscale, or the internet. */
+  network: "local" | "private" | "cgnat" | "public";
+  /** What is going down it, when we know. */
+  track: string;
+  /** Whatever the client called itself, trimmed to something printable. */
+  agent: string;
+  startedAt: number;
+  /**
+   * Bytes handed to the socket, which is not the same as bytes the listener
+   * has heard: the kernel buffers, and a slow client can be several seconds
+   * behind this number. It is the right figure for "is anything going out".
+   */
+  bytes: number;
+  /** Set when it ends, so the admin view can show what just finished. */
+  endedAt: number | null;
+}
+
+/** ::ffff:10.0.0.1 is 10.0.0.1 wearing a hat. */
+export function normaliseAddress(address: string | undefined): string {
+  if (!address) return "unknown";
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  return mapped?.[1] ?? address;
+}
+
+/** Loopback is not "your network"; it is this machine. */
+export function networkOf(address: string): Connection["network"] {
+  if (address === "127.0.0.1" || address === "::1" || address === "unknown") return "local";
+  if (!/^\d+\.\d+\.\d+\.\d+$/.test(address)) return "public";
+  return classify(address);
+}
+
+/**
+ * A user agent, cut to the part that identifies it. Browsers write a paragraph
+ * about every engine they have ever pretended to be.
+ */
+export function shortAgent(agent: string | undefined): string {
+  if (!agent) return "—";
+  const known = [
+    [/\bFirefox\/([\d.]+)/, "Firefox"],
+    [/\bEdg\/([\d.]+)/, "Edge"],
+    [/\bOPR\/([\d.]+)/, "Opera"],
+    [/\bChrome\/([\d.]+)/, "Chrome"],
+    [/\bVersion\/([\d.]+).*\bSafari\//, "Safari"],
+    [/\bVLC\/([\d.]+)/, "VLC"],
+    [/\bcurl\/([\d.]+)/, "curl"],
+    [/\bmpv\b/, "mpv"],
+    [/\bLavf\/([\d.]+)/, "ffmpeg"],
+  ] as const;
+  for (const [pattern, name] of known) {
+    const found = pattern.exec(agent);
+    if (found) return found[1] ? `${name} ${found[1].split(".")[0]}` : name;
+  }
+  return agent.slice(0, 24);
+}
+
+/**
+ * The live set. Finished connections are kept for a while, because "it stopped
+ * ten seconds ago" is the most useful thing an admin view can tell you when
+ * someone says the stream dropped.
+ */
+export class Connections {
+  private next = 1;
+  private readonly items = new Map<number, Connection>();
+  /** How many finished connections to remember. */
+  constructor(private readonly keep = 50) {}
+
+  open(request: IncomingMessage, kind: Kind, track: string): Connection {
+    const address = normaliseAddress(request.socket.remoteAddress);
+    const connection: Connection = {
+      id: this.next++,
+      kind,
+      address,
+      network: networkOf(address),
+      track,
+      agent: shortAgent(request.headers["user-agent"]),
+      startedAt: Date.now(),
+      bytes: 0,
+      endedAt: null,
+    };
+    this.items.set(connection.id, connection);
+    return connection;
+  }
+
+  close(id: number): void {
+    const found = this.items.get(id);
+    if (!found || found.endedAt !== null) return;
+    found.endedAt = Date.now();
+    this.prune();
+  }
+
+  add(id: number, bytes: number): void {
+    const found = this.items.get(id);
+    if (found) found.bytes += bytes;
+  }
+
+  /**
+   * Live first, oldest connection at the top; then the most recently finished.
+   *
+   * The id breaks ties because Date.now() has millisecond resolution and ten
+   * connections can easily end inside one, which left the order down to
+   * whatever the sort happened to do.
+   */
+  list(): Connection[] {
+    const all = [...this.items.values()];
+    const live = all
+      .filter((c) => c.endedAt === null)
+      .sort((a, b) => a.startedAt - b.startedAt || a.id - b.id);
+    const done = all
+      .filter((c) => c.endedAt !== null)
+      .sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0) || b.id - a.id);
+    return [...live, ...done];
+  }
+
+  get active(): number {
+    let count = 0;
+    for (const item of this.items.values()) if (item.endedAt === null) count++;
+    return count;
+  }
+
+  /** Drop the oldest finished entries once there are more than we keep. */
+  private prune(): void {
+    const done = [...this.items.values()]
+      .filter((c) => c.endedAt !== null)
+      .sort((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0) || a.id - b.id);
+    for (const item of done.slice(0, Math.max(0, done.length - this.keep))) this.items.delete(item.id);
+  }
+}