nixamp 0.9.7 → 0.9.9

package/dist/channels.d.ts

@@ -173,6 +173,8 @@ export declare class Channel {
     /** Write to everyone, and drop anybody whose socket has gone. */
     private send;
     listen(listener: Listener): () => void;
+    /** Stay up with nobody watching: no longer on demand. */
+    keep(): void;
     /** Nobody is watching an on-demand channel: give it a minute, then stop. */
     private idleOut;
     close(): void;
@@ -218,6 +220,16 @@ export declare class Channels {
     pulled(id: string): boolean;
     /** Mark a channel as on demand: it stops itself a minute after its last viewer leaves. */
     ephemeral(id: string): void;
+    /**
+     * The opposite: a channel that stays up with nobody watching.
+     *
+     * Going live with something from a catalog turns the on-demand channel it
+     * was being watched on into a broadcast -- listed, shareable, and still
+     * there when the person who started it closes their tab.
+     */
+    keep(id: string): boolean;
+    /** Whether a channel stops itself when its last viewer leaves. */
+    isEphemeral(id: string): boolean;
     /** How many on-demand channels are up, for a ceiling on decoders. */
     get ephemeralCount(): number;
     /** What a listener should be told this channel is. */

package/dist/channels.js

@@ -437,6 +437,13 @@ export class Channel {
                 this.idleOut();
         };
     }
+    /** Stay up with nobody watching: no longer on demand. */
+    keep() {
+        this.ephemeral = false;
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.idle = null;
+    }
     /** Nobody is watching an on-demand channel: give it a minute, then stop. */
     idleOut() {
         if (this.idle)
@@ -588,6 +595,24 @@ export class Channels {
         if (channel.listeners.size === 0)
             channel.listen({ write: () => true, end: () => undefined })();
     }
+    /**
+     * The opposite: a channel that stays up with nobody watching.
+     *
+     * Going live with something from a catalog turns the on-demand channel it
+     * was being watched on into a broadcast -- listed, shareable, and still
+     * there when the person who started it closes their tab.
+     */
+    keep(id) {
+        const channel = this.open.get(id);
+        if (!channel)
+            return false;
+        channel.keep();
+        return true;
+    }
+    /** Whether a channel stops itself when its last viewer leaves. */
+    isEphemeral(id) {
+        return this.open.get(id)?.ephemeral === true;
+    }
     /** How many on-demand channels are up, for a ceiling on decoders. */
     get ephemeralCount() {
         let total = 0;

package/dist/partyline.d.ts

@@ -99,6 +99,23 @@ export declare function roomCodeFrom(entered: unknown): string;
 export declare function pacificTime(at: number): string;
 /** How a code is read back: one digit at a time, because 482917 is not a number. */
 export declare function spokenCode(code: string): string;
+/**
+ * A track's name as it should be read out.
+ *
+ * What is playing is a filename more often than a title: "02 - ...And Justice
+ * For All.mp3" read aloud is "zero two dash dot dot dot", and the extension is
+ * a noise the caller does not need. The track number and extension go; what
+ * is left is close enough to a title to say.
+ */
+export declare function spokenTitle(nowPlaying: string): string;
+/**
+ * How many people are in a room, said to the one who just walked in.
+ *
+ * The count includes them: "there are 3 people in here" is what you say to the
+ * third person, and "you are the first one here" is what you say to the first,
+ * who would otherwise be told there is one person in an empty room.
+ */
+export declare function peopleHere(callers: number): string;
 export interface TelnyxEvent {
     event_type?: string;
     payload?: Record<string, unknown>;
@@ -119,6 +136,10 @@ export declare class PartyLine {
     private readonly legFrom;
     /** Legs that heard "press 1", and which stream they would be reminded about. */
     private readonly pendingReminder;
+    /** How many times each leg has been asked for a code, so it is not forever. */
+    private readonly asks;
+    /** Legs whose voice failed once, which hear the plain one from then on. */
+    private readonly plainVoice;
     /** Who to text when a stream returns, by stream code. */
     private readonly reminders;
     /**
@@ -216,9 +237,24 @@ export declare class PartyLine {
     }): Promise<number>;
     /** How many numbers are waiting to hear that a code is live. */
     waitingOn(code: string): number;
-    /** Put a leg into a room, making the conference if it is the first one there. */
+    /**
+     * Put a leg into a room, making the conference if it is the first one there.
+     *
+     * `welcome` is what the caller hears once they are in, before the count of
+     * who else is; a stream's room names the stream, an ordinary room reads its
+     * code back.
+     */
     private join;
     private enter;
+    /**
+     * Say hello to somebody who just joined, and only to them.
+     *
+     * Spoken into the conference rather than at the leg, because the leg is in
+     * the conference now and a speak on it is what the join interrupts. Telnyx
+     * addresses conference speech to particular participants, so the others in
+     * the room do not hear every arrival welcomed.
+     */
+    private greet;
     /**
      * How many people are on the phone for a stream.
      *
@@ -239,6 +275,8 @@ export declare class PartyLine {
      */
     private room;
     private get voice();
+    /** The voice for this leg: the good one, unless it has already failed them. */
+    private voiceFor;
     private get maxParticipants();
     /** One call-control command. True when Telnyx accepted it. */
     private command;

package/dist/partyline.js

@@ -40,6 +40,33 @@ const TELNYX_API = "https://api.telnyx.com/v2";
  * configuration rather than a constant for exactly that reason.
  */
 const DEFAULT_VOICE = "Telnyx.KokoroTTS.af";
+/**
+ * The voice a leg falls back to when the good one fails.
+ *
+ * Telnyx's Kokoro voice answered a prompt with a 500 once (2026-09-09), and
+ * what the caller got was a gather with no speech in it, ended at once with
+ * no digits, and asked again -- a line that "just repeats itself", silently,
+ * every ninety seconds. The plain Telnyx voice is older and worse and has not
+ * been seen to fail, which is the quality that matters on the second try.
+ */
+const FALLBACK_VOICE = "female";
+/**
+ * How long a caller has between digits before the code is treated as done.
+ *
+ * Telnyx's default is five seconds and did not fire: a caller who keyed five
+ * digits (one was lost in the keypad tone over the prompt) waited ten seconds
+ * in silence and hung up. Set explicitly so the partial code comes back to us
+ * quickly and we can say how many digits we got.
+ */
+const INTER_DIGIT_MS = 4000;
+/**
+ * How many times a caller is asked for a code before being let go.
+ *
+ * A gather that ends with nothing three times is a caller who cannot or will
+ * not key a code -- or a voice that is not being heard at all. Asking a
+ * fourth time is the loop that was reported; saying goodbye is not.
+ */
+const MAX_ASKS = 3;
 /** How long a signed webhook stays acceptable. Telnyx's own SDKs use five minutes. */
 const SIGNATURE_TOLERANCE_MS = 5 * 60 * 1000;
 /** A conference Telnyx will discard on its own, so we stop trusting ours first. */
@@ -92,6 +119,35 @@ export function pacificTime(at) {
 export function spokenCode(code) {
     return code.split("").join(", ");
 }
+/**
+ * A track's name as it should be read out.
+ *
+ * What is playing is a filename more often than a title: "02 - ...And Justice
+ * For All.mp3" read aloud is "zero two dash dot dot dot", and the extension is
+ * a noise the caller does not need. The track number and extension go; what
+ * is left is close enough to a title to say.
+ */
+export function spokenTitle(nowPlaying) {
+    return nowPlaying
+        .replace(/\.[a-z0-9]{2,4}$/i, "")
+        .replace(/^\s*\d{1,3}\s*[-._]\s*/, "")
+        .replace(/^[\s.]+/, "")
+        .trim();
+}
+/**
+ * How many people are in a room, said to the one who just walked in.
+ *
+ * The count includes them: "there are 3 people in here" is what you say to the
+ * third person, and "you are the first one here" is what you say to the first,
+ * who would otherwise be told there is one person in an empty room.
+ */
+export function peopleHere(callers) {
+    if (callers <= 1)
+        return "You are the first one here. Say hello when somebody joins.";
+    if (callers === 2)
+        return "There is one other person in here. Say hello.";
+    return `There are ${callers} people in here. Say hello.`;
+}
 /**
  * Telnyx signs `${timestamp}|${body}` with ed25519 and sends both back in
  * headers. Node will not take a bare 32-byte key, so it is wrapped in the
@@ -135,6 +191,10 @@ export class PartyLine {
     legFrom = new Map();
     /** Legs that heard "press 1", and which stream they would be reminded about. */
     pendingReminder = new Map();
+    /** How many times each leg has been asked for a code, so it is not forever. */
+    asks = new Map();
+    /** Legs whose voice failed once, which hear the plain one from then on. */
+    plainVoice = new Set();
     /** Who to text when a stream returns, by stream code. */
     reminders = new Map();
     /**
@@ -244,8 +304,20 @@ export class PartyLine {
             await this.ask(leg);
             return;
         }
+        if (type === "call.speak.failed") {
+            // The voice, not the caller, failed. Everything this leg hears from now
+            // on is in the plain voice; the gather this speech belonged to ends on
+            // its own and is asked again, audibly this time.
+            this.plainVoice.add(leg);
+            this.options.onEvent?.("  a prompt could not be spoken; using the plain voice.");
+            return;
+        }
         if (type === "call.gather.ended") {
             const digits = typeof payload["digits"] === "string" ? payload["digits"] : "";
+            // A gather that ended because the caller hung up is not an answer, and
+            // anything sent to that leg now is a 422 for the log.
+            if (payload["status"] === "call_hangup")
+                return;
             // A leg that was just offered a reminder is answering that, not keying a
             // room code -- the same event carries both, so the question we asked is
             // what decides how to read it.
@@ -259,9 +331,14 @@ export class PartyLine {
             if (!code) {
                 // Re-ask rather than guess. Anything that is not six digits is not a
                 // room, and picking the nearest one would be picking a stranger's.
-                await this.ask(leg, "That is not a six digit code. ");
+                // Say what we got: five digits and silence is a caller who thinks
+                // the line is broken, and a caller who keyed nothing does not need
+                // telling their nothing was not six digits.
+                const got = digits.replace(/\D/g, "").length;
+                await this.ask(leg, got > 0 ? `I only got ${got} digits. ` : "I did not get a code. ");
                 return;
             }
+            this.asks.delete(leg);
             // A code that belongs to a stream is answered as a stream. Anything else
             // is an ordinary room, which is what this line was before.
             if (await this.stream(leg, code))
@@ -273,6 +350,8 @@ export class PartyLine {
             this.release(leg);
             this.legFrom.delete(leg);
             this.pendingReminder.delete(leg);
+            this.asks.delete(leg);
+            this.plainVoice.delete(leg);
             return;
         }
     }
@@ -290,16 +369,33 @@ export class PartyLine {
      * to press anything after; # is there for the ones who do it anyway.
      */
     async ask(leg, prefix = "") {
-        const greeting = this.options.greeting ??
-            "Welcome to the party line. Enter a six digit room code. Anyone who enters the same code will be on the line with you.";
+        const asked = (this.asks.get(leg) ?? 0) + 1;
+        this.asks.set(leg, asked);
+        if (asked > MAX_ASKS) {
+            // Three gathers with no code in them is not a caller who needs a fourth
+            // prompt. Whatever is wrong -- their keypad, our voice -- repeating
+            // ourselves is the failure that was reported, so this ends instead.
+            await this.command(leg, "speak", {
+                payload: "I did not get a room code. Goodbye.",
+                voice: this.voiceFor(leg),
+            });
+            await this.command(leg, "hangup", {});
+            return;
+        }
+        // Short, because callers key the code over the prompt and a long one
+        // costs digits: a tone pressed as the speech starts was not heard. The
+        // first time gets the welcome; a re-ask has already been welcomed.
+        const greeting = this.options.greeting ?? "Welcome to the nixamp party line. Enter the six digit room code.";
+        const payload = asked === 1 ? `${prefix}${greeting}` : `${prefix}Enter the six digit room code.`;
         await this.command(leg, "gather_using_speak", {
-            payload: `${prefix}${greeting}`,
-            voice: this.voice,
+            payload,
+            voice: this.voiceFor(leg),
             valid_digits: "0123456789",
             minimum_digits: CODE_LENGTH,
             maximum_digits: CODE_LENGTH,
             terminating_digit: "#",
             timeout_millis: 20000,
+            inter_digit_timeout_millis: INTER_DIGIT_MS,
         });
     }
     /**
@@ -324,13 +420,13 @@ export class PartyLine {
             return false;
         const live = streams.liveByCode(code);
         if (live !== undefined) {
-            const what = live.nowPlaying ? ` of ${live.nowPlaying}` : "";
-            await this.command(leg, "speak", {
-                payload: `You're on the line for ${live.name}${what}. ` +
-                    "Everyone here is watching it too. Say hello.",
-                voice: this.voice,
-            });
-            await this.join(leg, code);
+            // The welcome is said once they are in the room, not before: a speak
+            // on the leg followed by the conference join was cut off by the join --
+            // Telnyx reported it started and ended in the same millisecond -- and
+            // the caller heard twenty seconds of nothing and hung up.
+            const title = spokenTitle(live.nowPlaying);
+            const what = title ? `, playing ${title}` : "";
+            await this.join(leg, code, `Welcome to the live room for ${live.name}${what}. `);
             return true;
         }
         const ended = streams.endedByCode(code);
@@ -345,7 +441,7 @@ export class PartyLine {
                 `The live stream ended at ${pacificTime(ended.endedAt)}. ` +
                 "Call back later when they stream again. " +
                 "Press 1 to get a text message when they do.",
-            voice: this.voice,
+            voice: this.voiceFor(leg),
             valid_digits: "1",
             minimum_digits: 1,
             maximum_digits: 1,
@@ -370,7 +466,7 @@ export class PartyLine {
         this.options.onEvent?.(`  a caller asked to be told when ${code} is live again.`);
         await this.command(leg, "speak", {
             payload: "Got it. We will text you when they are live again. Goodbye.",
-            voice: this.voice,
+            voice: this.voiceFor(leg),
         });
         await this.command(leg, "hangup", {});
     }
@@ -408,13 +504,19 @@ export class PartyLine {
     waitingOn(code) {
         return this.reminders.get(code)?.size ?? 0;
     }
-    /** Put a leg into a room, making the conference if it is the first one there. */
-    async join(leg, code) {
+    /**
+     * Put a leg into a room, making the conference if it is the first one there.
+     *
+     * `welcome` is what the caller hears once they are in, before the count of
+     * who else is; a stream's room names the stream, an ordinary room reads its
+     * code back.
+     */
+    async join(leg, code, welcome = `Welcome to room ${spokenCode(code)}. `) {
         const room = this.room(code);
         if (room.callers >= this.maxParticipants) {
             await this.command(leg, "speak", {
                 payload: "That room is full. Goodbye.",
-                voice: this.voice,
+                voice: this.voiceFor(leg),
             });
             await this.command(leg, "hangup", {});
             return;
@@ -427,6 +529,7 @@ export class PartyLine {
             const joined = await this.request(`/conferences/${encodeURIComponent(room.conferenceId)}/actions/join`, { call_control_id: leg, start_conference_on_enter: true });
             if (joined !== null) {
                 this.enter(room, leg);
+                await this.greet(room, leg, welcome);
                 return;
             }
             // The id was stale in a way the clock did not predict -- an operator
@@ -445,7 +548,7 @@ export class PartyLine {
         if (typeof id !== "string") {
             await this.command(leg, "speak", {
                 payload: "Sorry, that room could not be opened. Goodbye.",
-                voice: this.voice,
+                voice: this.voiceFor(leg),
             });
             await this.command(leg, "hangup", {});
             this.legRoom.delete(leg);
@@ -454,6 +557,7 @@ export class PartyLine {
         room.conferenceId = id;
         room.startedAt = this.now();
         this.enter(room, leg);
+        await this.greet(room, leg, welcome);
     }
     enter(room, leg) {
         if (room.legs.has(leg))
@@ -462,6 +566,23 @@ export class PartyLine {
         room.callers = room.legs.size;
         this.options.onEvent?.(`  a caller joined a room (${room.callers} on the line).`);
     }
+    /**
+     * Say hello to somebody who just joined, and only to them.
+     *
+     * Spoken into the conference rather than at the leg, because the leg is in
+     * the conference now and a speak on it is what the join interrupts. Telnyx
+     * addresses conference speech to particular participants, so the others in
+     * the room do not hear every arrival welcomed.
+     */
+    async greet(room, leg, welcome) {
+        if (room.conferenceId === null)
+            return;
+        await this.request(`/conferences/${encodeURIComponent(room.conferenceId)}/actions/speak`, {
+            payload: `${welcome}${peopleHere(room.callers)}`,
+            voice: this.voiceFor(leg),
+            call_control_ids: [leg],
+        });
+    }
     /**
      * How many people are on the phone for a stream.
      *
@@ -515,6 +636,10 @@ export class PartyLine {
     get voice() {
         return this.options.voice ?? DEFAULT_VOICE;
     }
+    /** The voice for this leg: the good one, unless it has already failed them. */
+    voiceFor(leg) {
+        return this.plainVoice.has(leg) ? FALLBACK_VOICE : this.voice;
+    }
     get maxParticipants() {
         return this.options.maxParticipants ?? 50;
     }

package/dist/server.d.ts

@@ -485,6 +485,12 @@ export interface HandlerOptions {
             error?: string;
         }>;
         stop: () => Promise<void>;
+        /**
+         * Tell the directory now rather than at the next heartbeat. A channel
+         * that just went on the air should be in the list before the person who
+         * put it there has looked, and a heartbeat is ninety seconds.
+         */
+        announce?: () => Promise<void>;
     };
     /**
      * Where OBS should point, one entry per stream this server will accept.

package/dist/server.js

@@ -2221,6 +2221,34 @@ export function createHandler(engine, options) {
                 json(response, 200, { kind: "live", channel: channelId, name: entry.title });
                 return;
             }
+            // Go live with it. The same channel a viewer would get on demand, but
+            // kept: it stays up with nobody watching, it is written down so a
+            // restart puts it back, and the directory hears about it now. A film
+            // goes on the air the same way -- read at its own pace from the start,
+            // so everybody who opens the link sees the same minute of it.
+            if (sub === "live" && request.method === "POST") {
+                if (!options.channels) {
+                    json(response, 503, { error: "this server cannot carry channels" });
+                    return;
+                }
+                const channelId = cleanId(`cat-${entry.id}`);
+                if (!options.channels.has(channelId)) {
+                    const started = await pullChannel(options.channels, options.ffprobe ?? ["ffprobe"], channelId, entry.title, entry.source);
+                    if (!started) {
+                        json(response, 409, { error: "that channel is already starting" });
+                        return;
+                    }
+                }
+                options.channels.keep(channelId);
+                if (options.rememberChannels) {
+                    options.rememberChannels(options.channels.list()
+                        .filter((one) => one.via === "pull" && one.source && !options.channels?.isEphemeral(one.id))
+                        .map((one) => ({ id: one.id, name: one.name, source: one.source })));
+                }
+                void options.live?.announce?.();
+                json(response, 200, { channel: channelId, name: entry.title, kind: entry.live ? "live" : "vod" });
+                return;
+            }
             if (sub === "stream" && request.method === "GET") {
                 if (!options.media) {
                     json(response, 403, { error: "media streaming is off" });
@@ -2332,6 +2360,27 @@ export function createHandler(engine, options) {
                 json(response, restarted ? 200 : 409, { ok: restarted });
                 return;
             }
+            /*
+             * Keep a channel that was started on demand. Something being watched
+             * from a catalog stops a minute after its last viewer leaves; going
+             * live with it is asking it not to, and asking the directory to list
+             * it now.
+             */
+            if (action === "keep") {
+                if (!channels.has(id)) {
+                    json(response, 404, { error: "nothing is playing on that channel" });
+                    return;
+                }
+                channels.keep(id);
+                if (options.rememberChannels) {
+                    options.rememberChannels(channels.list()
+                        .filter((one) => one.via === "pull" && one.source && !channels.isEphemeral(one.id))
+                        .map((one) => ({ id: one.id, name: one.name, source: one.source })));
+                }
+                void options.live?.announce?.();
+                json(response, 200, { ok: true });
+                return;
+            }
             /**
              * Carry a source of our own, rather than waiting to be sent one.
              *
@@ -3596,6 +3645,13 @@ export async function serve(argv, version = "0.1.0") {
                 publisher = null;
                 listing = null;
             },
+            announce: async () => {
+                if (publisher === null)
+                    return;
+                const renewed = await publisher.announce();
+                if (renewed)
+                    listing = renewed;
+            },
         },
         ...(ingest ? { ingest } : {}),
         broadcaster,

package/package.json

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

package/src/channels.ts

@@ -486,6 +486,13 @@ export class Channel {
     };
   }
 
+  /** Stay up with nobody watching: no longer on demand. */
+  keep(): void {
+    this.ephemeral = false;
+    if (this.idle) clearTimeout(this.idle);
+    this.idle = null;
+  }
+
   /** Nobody is watching an on-demand channel: give it a minute, then stop. */
   private idleOut(): void {
     if (this.idle) clearTimeout(this.idle);
@@ -649,6 +656,25 @@ export class Channels {
     if (channel.listeners.size === 0) channel.listen({ write: () => true, end: () => undefined })();
   }
 
+  /**
+   * The opposite: a channel that stays up with nobody watching.
+   *
+   * Going live with something from a catalog turns the on-demand channel it
+   * was being watched on into a broadcast -- listed, shareable, and still
+   * there when the person who started it closes their tab.
+   */
+  keep(id: string): boolean {
+    const channel = this.open.get(id);
+    if (!channel) return false;
+    channel.keep();
+    return true;
+  }
+
+  /** Whether a channel stops itself when its last viewer leaves. */
+  isEphemeral(id: string): boolean {
+    return this.open.get(id)?.ephemeral === true;
+  }
+
   /** How many on-demand channels are up, for a ceiling on decoders. */
   get ephemeralCount(): number {
     let total = 0;