nixamp 0.16.0 → 0.17.0

package/README.md

@@ -136,6 +136,64 @@ DATABASE_URL=postgres://user:pass@host/nixamp NIXAMP_JWT_SECRET=… nixamp serve
 Accounts live where the directory lives and nowhere else: a nixamp on a laptop
 has nobody to be an account of.
 
+## Watch parties, and signing in with nixamp
+
+A watch party lives on the site that has the film. bittorrented.com has them:
+a six-character code, a host, and everybody at the same second. nixamp has
+rooms, chat, invitations, a directory, and five clients that can already open
+one. A bridged party is both.
+
+The identity link is **OAuth 2.1**, with nixamp.com as the authorization
+server. The site sends somebody here, they approve it once, and the site holds
+a token that acts on their nixamp account. It is 2.1 and not 2.0, so:
+
+- authorization code only, with PKCE (S256) required of every client, public
+  or confidential. No implicit grant, no password grant.
+- redirect URIs match the registered string exactly; only a loopback port may
+  vary, because a CLI cannot know its port before it listens.
+- a code is spent once; presenting it twice withdraws everything it produced.
+- refresh tokens rotate, and a retired one presented again withdraws the whole
+  family.
+
+The endpoints are where RFC 8414 says to look for them:
+
+```
+GET  /.well-known/oauth-authorization-server
+GET  /api/v1/oauth/authorize      the consent page
+POST /api/v1/oauth/token          authorization_code, refresh_token
+POST /api/v1/oauth/revoke
+GET  /api/v1/oauth/userinfo
+```
+
+Scopes are `profile`, `email`, `parties` and `offline_access`. The Account
+panel on nixamp.com lists what is connected and takes it away again.
+
+bittorrented.com is registered out of the box. Another client is added with
+`NIXAMP_OAUTH_CLIENTS`, a JSON list:
+
+```
+NIXAMP_OAUTH_CLIENTS='[{"id":"example","name":"Example","redirectUris":["https://example.com/cb"]}]'
+```
+
+Once a party is bridged it is an ordinary live event with a room, so every
+surface already knows what to do with it:
+
+```
+nixamp party list                    the ones you could join right now
+nixamp party join ABC123 --open      the room here, the film where it lives
+nixamp party host ABC123 --url URL   put one on the air as a nixamp room
+nixamp party sync ABC123 --at 930    where playback is (hosts only)
+```
+
+and an agent reaches the same five actions over the Model Context Protocol:
+
+```
+nixamp mcp     a stdio MCP server: list, get, host, sync, end
+```
+
+It acts as whoever the machine is signed in as, so `nixamp login` comes first.
+The film never crosses over: what nixamp carries is the room.
+
 ## BackToSchool.help
 
 BackToSchool.help is a branded, mobile-first client for NixAmp live events. It
@@ -172,6 +230,41 @@ on first use in the configured PostgreSQL database. `RESEND_API_KEY` and
 `NIXAMP_MAIL_FROM` are optional if invitation email should be sent rather than
 only returning a shareable link.
 
+## Live shows, and tickets
+
+A live event carries a **kind**: `talk`, `class`, or `concert`. The kind is
+what a branded client reads to pick a layout, and what `/api/v1/events?kind=`
+filters the directory by, so one NixAmp serves a school and a venue without
+either knowing about the other. `concert` brings its own presets
+(`concert-viewer`, `concert-ticketholder`, `concert-artist`) with a stage,
+a setlist, a tip jar, a merch shelf and a till.
+
+A concert also has doors and an encore. `POST /api/v1/events/:id/doors` opens
+the room before the music, `.../start` begins it, `.../encore` says the band
+came back, and `.../end` closes it. Opening, playing and coming back on are
+allowed to everyone on the stage; cancelling and archiving stay with the host.
+An **artist** is an invitation role beside moderator: they perform without
+being handed the guest list.
+
+**A ticket is a paid pass to one room**, over x402 and settled by CoinPay,
+exactly like the crawler paywall but scoped to a single event:
+
+```
+POST /api/v1/events/:id/tickets          # X-PAYMENT proof in, ticket out
+GET  /api/v1/events/:id/tickets          # what it costs and whether you hold one
+POST /api/v1/events/:id/tickets/comp     # the guest list, hosts only
+```
+
+Set `ticketPriceCents` and a `payTo` address on the event and the room answers
+402 to anyone without a ticket, quoting the price; the money goes to the
+event's own address, never to the platform. The ticket rides in
+`x-nixamp-ticket`, or in `?ticket=` for an `<audio>` or `<video>` element that
+cannot set a header. `COINPAY_X402_KEY` switches sales on; without it every
+event is simply a free one. `NIXAMP_TICKET_SECRET` signs the passes (it
+defaults to the CoinPay key), and each event's tickets are signed with a
+secret derived from it and the event id, so a ticket to Friday is not a ticket
+to Saturday.
+
 ## The directory
 
 [nixamp.com/directory](https://nixamp.com/directory) lists nixamps that agreed
@@ -223,6 +316,39 @@ is the whole point.
 Publishing is administering the server, so it needs the control link or the
 owner's account. Listening only needs the share link, like any other audio.
 
+### Relaying a channel to another nixamp, compressed
+
+A channel can be carried from one nixamp to another with fewer bytes on the
+wire and every byte restored at the far end. It is off until you turn it on,
+per channel, and nothing about ordinary playback changes when you do.
+
+```
+nixamp compression analyze --channel cnn          what a codec would make of it
+nixamp compression set --channel cnn --mode auto  compress when it pays, store when it does not
+nixamp compression status --channel cnn           what it is doing, in bytes
+nixamp compression off                            the whole server, at once
+```
+
+On the receiving nixamp:
+
+```
+nixamp compression pull --channel cnn --from https://host:4321/api/channels/cnn/relay --from-key KEY
+```
+
+and `cnn` is a channel there, heard at `/api/channels/cnn` like any other.
+The relay is `GET /api/channels/<id>/relay` as `application/vnd.nixamp.stream`,
+a framed stream of Zstandard blocks each carrying the length and SHA-256 of
+what it stands for, ending in a marker; a block that would not shrink is
+sent as it is, and the metrics say so rather than claiming a saving. A
+library file gets the same treatment at `/api/media/<n>/relay`, built once
+and kept. `nixamp compression analyze FILE` measures a file here with no
+server at all. The wire format, the policy, the limits and the switch are
+in [docs/stream-compression.md](docs/stream-compression.md).
+
+HLS can be packaged as fragmented MP4 instead of MPEG-TS
+(`--hls fmp4` on `compression set`, or server-wide): the same boxes the
+channel already carries, copied into files, never re-encoded.
+
 ## Streaming into it
 
 A nixamp can be the thing you broadcast *to*, not just from.
@@ -512,6 +638,19 @@ A bare `ffmpeg` on `PATH` is used when there is one; `mise` shims are detected a
 
 Whatever your ffmpeg was built with: mp3, flac, ogg, opus, m4a, aac, wav, wma, aiff, alac, and the audio track of mp4 and webm.
 
+Video too, including raw transport streams — a `.ts`, `.m2ts` or `.mts` off a
+capture card, a receiver or an IPTV recorder, at 1080p or 4K. H.264 is copied
+into the fragmented MP4 a browser is sent, at whatever size it already is, so
+a 4K recording costs no encoding to watch or to put on the air. H.265 is
+copied too when the browser asking for it says it can decode one, and
+otherwise re-encoded down to 1080p, because a 4K encode does not keep up with
+playing it. A channel, which has one encode and a whole audience, re-encodes
+H.265 by default; `NIXAMP_HEVC_CHANNELS=1` copies it through instead, for an
+audience of phones and televisions.
+
+A `.ts` is opened rather than taken on its name: it is as often a TypeScript
+file as a transport stream, and a checkout is not a playlist.
+
 ## Status
 
 Early. It plays a directory, shows tags and timings, and draws what it hears —

package/dist/audio.d.ts

@@ -98,6 +98,19 @@ export interface Codecs {
      * restart; a live channel is wherever it is now.
      */
     duration?: number;
+    /**
+     * The size of the picture, when there is one.
+     *
+     * It decides the one thing that costs real money: whether a re-encode is
+     * asked to do 4K. Measured on this machine, 3840x2160 through libx264
+     * -preset veryfast runs at about half of real time, so a 4K film re-encoded
+     * at its own size arrives slower than it plays -- a stream that falls
+     * further behind every second. The same source scaled to 1080p runs at
+     * about 1.6x real time and keeps up. Copying, of course, costs nothing at
+     * any size, which is why what is inside matters more than how big it is.
+     */
+    width?: number;
+    height?: number;
 }
 /**
  * Ask ffprobe what the streams are, without holding the event loop.
@@ -107,6 +120,57 @@ export interface Codecs {
  * the whole library came to be tagged with the process wedged solid.
  */
 export declare function codecsOf(tools: Tools, path: string, input?: string[]): Promise<Codecs>;
+/** How much of a transport stream is read before deciding what is in it. */
+export declare const TRANSPORT_PROBE_BYTES: number;
+export declare const TRANSPORT_ANALYSE_US = 10000000;
+/**
+ * What to tell ffmpeg or ffprobe before it opens a transport stream.
+ *
+ * A `.ts` has no index and no header: it is packets, and the tracks are
+ * whatever turns up in them. The defaults are tuned for a file that describes
+ * itself, so a 4K recording -- padded with null packets, seconds between
+ * keyframes, sometimes several programmes -- gets read as having no picture,
+ * or no sound, or neither. Reading twenty megabytes before deciding costs a
+ * fraction of a second on a local disk and is the difference between a
+ * television recording and "nothing to play here".
+ *
+ * `+genpts` is for the other half of it: a recording that starts mid-stream
+ * has no timestamp on its first frames, and a fragmented MP4 built out of
+ * those has a duration of nothing and a seek bar that does not move.
+ * `+discardcorrupt` drops the half-packet at a cut rather than passing
+ * rubbish to the decoder.
+ */
+export declare function transportProbeArgs(path: string, container?: string): string[];
+/** The same, for a decode rather than a probe: the timestamps matter too. */
+export declare function transportInputArgs(path: string, container?: string): string[];
+/** How the two sides of `-c:v copy` are told apart in a name a person reads. */
+export interface VideoOptions {
+    /**
+     * Whether the thing at the other end can decode H.265.
+     *
+     * Safari and most televisions can; Chrome on a desktop cannot, and hands
+     * back nothing at all rather than an error anybody sees. So HEVC is only
+     * ever copied when the client said it could take it -- which is worth
+     * asking, because the alternative for a 4K HEVC film is an encode that does
+     * not keep up with playback.
+     */
+    allowHevc?: boolean;
+    /**
+     * The tallest picture a re-encode may produce. A copy is never resized: a
+     * 4K stream a browser can already decode is handed over as it is.
+     */
+    maxHeight?: number;
+}
+/**
+ * The tallest re-encode that keeps up with playback.
+ *
+ * Measured on this box (8 cores, libx264 -preset veryfast, a 4K HEVC source):
+ * 4K out ran at 0.52x real time, 1080p out at 1.65x. An encode slower than
+ * real time is a live channel that falls behind for ever and a film that
+ * stalls every few seconds, so a re-encode of anything taller comes down to
+ * this. Copying is exempt, and copying is the ordinary case.
+ */
+export declare const MAX_TRANSCODE_HEIGHT = 1080;
 /**
  * How to get this file into a browser, given what is inside it.
  *
@@ -115,8 +179,13 @@ export declare function codecsOf(tools: Tools, path: string, input?: string[]):
  * is wrong. Rewrapping that costs nothing and looks identical; re-encoding it
  * would cost a core per viewer and look worse. So the streams decide, one part
  * at a time -- a film can have its video copied and only its DTS re-encoded.
+ *
+ * Resolution is deliberately not one of the deciders for a copy. 1080p and 4K
+ * H.264 out of a transport stream are copied exactly as 720p is, because the
+ * work of copying does not grow with the picture and a browser that can decode
+ * 4K should be given 4K.
  */
-export declare function videoArgs(codecs: Codecs, capKbps?: number): string[];
+export declare function videoArgs(codecs: Codecs, capKbps?: number, options?: VideoOptions): string[];
 /**
  * The width that suits a bitrate.
  *

package/dist/audio.js

@@ -10,6 +10,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { isTransportStream } from "./sources.js";
 export const RATE = 44100;
 export const CHANNELS = 2;
 function works(argv, flag = "-version") {
@@ -364,7 +365,14 @@ export async function codecsOf(tools, path, input = []) {
             ...rest,
             "-v", "quiet",
             "-print_format", "json",
-            "-show_entries", "format=format_name,duration:stream=codec_type,codec_name",
+            "-show_entries", "format=format_name,duration:stream=codec_type,codec_name,width,height",
+            // A transport stream needs looking further into than a file with an
+            // index does: there is no header listing the tracks, only packets, and
+            // a 4K recording can carry a second of null padding and a long gap to
+            // its first keyframe. ffprobe's default gives up before the picture on
+            // exactly the recordings this is for, and "no video stream" is how a
+            // film comes back as its own soundtrack.
+            ...transportProbeArgs(path),
             // Headers the source's site expects, for a link resolved by yt-dlp.
             ...input,
             path,
@@ -381,11 +389,14 @@ export async function codecsOf(tools, path, input = []) {
                 // ffprobe prints seconds as a string, and "N/A" for a stream with no
                 // end; both of those read as 0.
                 const seconds = Number(parsed.format?.duration ?? 0);
+                const picture = streams.find((s) => s.codec_type === "video");
                 return done({
-                    video: streams.find((s) => s.codec_type === "video")?.codec_name ?? "",
+                    video: picture?.codec_name ?? "",
                     audio: streams.find((s) => s.codec_type === "audio")?.codec_name ?? "",
                     container: parsed.format?.format_name ?? "",
                     duration: Number.isFinite(seconds) && seconds > 0 ? seconds : 0,
+                    ...(typeof picture?.width === "number" && picture.width > 0 ? { width: picture.width } : {}),
+                    ...(typeof picture?.height === "number" && picture.height > 0 ? { height: picture.height } : {}),
                 });
             }
             catch {
@@ -394,6 +405,57 @@ export async function codecsOf(tools, path, input = []) {
         });
     });
 }
+/** How much of a transport stream is read before deciding what is in it. */
+export const TRANSPORT_PROBE_BYTES = 20 * 1024 * 1024;
+export const TRANSPORT_ANALYSE_US = 10_000_000;
+/**
+ * What to tell ffmpeg or ffprobe before it opens a transport stream.
+ *
+ * A `.ts` has no index and no header: it is packets, and the tracks are
+ * whatever turns up in them. The defaults are tuned for a file that describes
+ * itself, so a 4K recording -- padded with null packets, seconds between
+ * keyframes, sometimes several programmes -- gets read as having no picture,
+ * or no sound, or neither. Reading twenty megabytes before deciding costs a
+ * fraction of a second on a local disk and is the difference between a
+ * television recording and "nothing to play here".
+ *
+ * `+genpts` is for the other half of it: a recording that starts mid-stream
+ * has no timestamp on its first frames, and a fragmented MP4 built out of
+ * those has a duration of nothing and a seek bar that does not move.
+ * `+discardcorrupt` drops the half-packet at a cut rather than passing
+ * rubbish to the decoder.
+ */
+export function transportProbeArgs(path, container = "") {
+    if (!isTransportSource(path, container))
+        return [];
+    return ["-probesize", String(TRANSPORT_PROBE_BYTES), "-analyzeduration", String(TRANSPORT_ANALYSE_US)];
+}
+/** The same, for a decode rather than a probe: the timestamps matter too. */
+export function transportInputArgs(path, container = "") {
+    if (!isTransportSource(path, container))
+        return [];
+    return [...transportProbeArgs(path, container), "-fflags", "+genpts+discardcorrupt"];
+}
+/**
+ * Whether this source is a transport stream, by its name or by what a probe
+ * already found in it. The container is the better answer where there is one:
+ * an IPTV URL ending in `/301` is an mpegts and says so nowhere in its name.
+ */
+function isTransportSource(path, container = "") {
+    if (container.includes("mpegts"))
+        return true;
+    return isTransportStream(path);
+}
+/**
+ * The tallest re-encode that keeps up with playback.
+ *
+ * Measured on this box (8 cores, libx264 -preset veryfast, a 4K HEVC source):
+ * 4K out ran at 0.52x real time, 1080p out at 1.65x. An encode slower than
+ * real time is a live channel that falls behind for ever and a film that
+ * stalls every few seconds, so a re-encode of anything taller comes down to
+ * this. Copying is exempt, and copying is the ordinary case.
+ */
+export const MAX_TRANSCODE_HEIGHT = 1080;
 /**
  * How to get this file into a browser, given what is inside it.
  *
@@ -402,14 +464,21 @@ export async function codecsOf(tools, path, input = []) {
  * is wrong. Rewrapping that costs nothing and looks identical; re-encoding it
  * would cost a core per viewer and look worse. So the streams decide, one part
  * at a time -- a film can have its video copied and only its DTS re-encoded.
+ *
+ * Resolution is deliberately not one of the deciders for a copy. 1080p and 4K
+ * H.264 out of a transport stream are copied exactly as 720p is, because the
+ * work of copying does not grow with the picture and a browser that can decode
+ * 4K should be given 4K.
  */
-export function videoArgs(codecs, capKbps = 0) {
+export function videoArgs(codecs, capKbps = 0, options = {}) {
     // A ceiling means re-encoding whatever is there, because you cannot cap the
     // bitrate of a stream you are copying: copying is what "unchanged" means.
     if (capKbps > 0)
         return cappedArgs(capKbps);
-    // What a browser can play inside MP4 without help.
-    const keepVideo = codecs.video === "h264";
+    // What a browser can play inside MP4 without help -- and H.265, when the
+    // other end has said it can decode it, which saves re-encoding 4K.
+    const keepHevc = codecs.video === "hevc" && options.allowHevc === true;
+    const keepVideo = codecs.video === "h264" || keepHevc;
     // A transport stream's audio is never copied. Its AAC is ADTS-framed, which
     // MP4 refuses without a bitstream filter -- ffmpeg writes nothing at all and
     // says "Malformed AAC bitstream detected" -- and the track ffmpeg picks off
@@ -417,13 +486,23 @@ export function videoArgs(codecs, capKbps = 0) {
     // no browser plays. Re-encoding audio is cheap; this failing is total.
     const transportStream = codecs.container.includes("mpegts");
     const keepAudio = !transportStream && (codecs.audio === "aac" || codecs.audio === "mp3");
+    // A re-encode of something taller than this comes down to it, because an
+    // encode slower than real time is not a stream. A copy keeps its size.
+    const ceiling = options.maxHeight ?? MAX_TRANSCODE_HEIGHT;
+    const tooTall = !keepVideo && (codecs.height ?? 0) > ceiling;
     return [
         "-c:v", keepVideo ? "copy" : "libx264",
+        // H.265 in MP4 is `hvc1` to Safari and to every television; ffmpeg writes
+        // `hev1` by default, which Safari opens and then plays as a black panel.
+        ...(keepHevc ? ["-tag:v", "hvc1"] : []),
         // A keyframe every two seconds when encoding. A fragment starts on a
         // keyframe, so this is how soon a joiner sees a picture -- and an HLS
         // segment, which is cut on keyframes too, was ten seconds long on
         // x264's default and made a phone wait thirty before it played.
         ...(keepVideo ? [] : ["-preset", "veryfast", "-crf", "23", "-pix_fmt", "yuv420p", "-g", "48", "-keyint_min", "48", "-sc_threshold", "0"]),
+        // -2 keeps the aspect ratio and an even height, which H.264 requires; the
+        // min() never enlarges, so a 720p source asked for 1080p stays 720p.
+        ...(tooTall ? ["-vf", `scale=-2:'min(${ceiling},ih)'`] : []),
         "-c:a", keepAudio ? "copy" : "aac",
         ...(keepAudio ? [] : ["-b:a", "160k", "-ac", "2"]),
         "-f", "mp4",

package/dist/channels.d.ts

@@ -3,6 +3,12 @@ import type { Readable } from "node:stream";
 export interface Listener {
     write(chunk: Buffer): boolean;
     end(): void;
+    /**
+     * How many bytes it has accepted and not yet sent, when it can say. A
+     * response's writableLength. Without it a listener that stopped reading
+     * is a buffer that grows until the channel ends.
+     */
+    pending?(): number;
 }
 export interface ChannelInfo {
     id: string;
@@ -10,8 +16,8 @@ export interface ChannelInfo {
     name: string;
     /** The container it is sending, e.g. webm from a browser, flv over RTMP. */
     format: string;
-    /** How it arrived. */
-    via: "http" | "rtmp" | "pull";
+    /** How it arrived. `relay` is another nixamp's channel, decoded from its envelope. */
+    via: "http" | "rtmp" | "pull" | "relay";
     startedAt: number;
     bytes: number;
     listeners: number;
@@ -40,7 +46,18 @@ export interface ChannelInfo {
         audio: string;
         container: string;
         duration?: number;
+        width?: number;
+        height?: number;
     };
+    /**
+     * What the channel itself is producing, which is not always what its source
+     * holds: an H.265 source is usually re-encoded to H.264 on the way out,
+     * because a channel has one encode and an audience that does not all
+     * decode the same things. Anything downstream -- the HLS packager above
+     * all, which has to choose between transport and fMP4 segments -- has to
+     * ask this rather than the source's codecs.
+     */
+    emits?: string;
     /**
      * The nixamp.com account that put it on the air, when a member did rather
      * than the owner. Theirs to take off again, and counted against how many
@@ -83,6 +100,38 @@ export declare const IDLE = 60000;
  */
 export declare const BACKLOG_VIDEO: number;
 export declare const BACKLOG_AUDIO: number;
+/**
+ * How far behind a listener may fall before it is let go. Sixteen
+ * megabytes is half a minute of 720p television that a socket has accepted
+ * and not delivered: nobody is watching that, and every byte of it was
+ * sitting in this process. Before this a stalled listener's buffer grew
+ * until the channel ended, however long that was.
+ */
+export declare const LISTENER_QUEUE: number;
+/**
+ * The backlog is really a number of seconds, and four megabytes was that
+ * number for the stream we happened to have.
+ *
+ * Six seconds of 720p is about 4 MB. Six seconds of a 1080p transport stream
+ * copied straight through is nearer 12, and of 4K nearer 30 -- so a fixed
+ * 4 MB hands a 4K joiner under a second of video, which is the live edge with
+ * no cushion, which is the play-wait-play loop the backlog exists to prevent.
+ * So the cap follows the stream: seconds times the rate it is actually
+ * running at, between the old floor and a ceiling that keeps a channel's
+ * memory bounded whatever it is carrying.
+ */
+export declare const BACKLOG_SECONDS = 6;
+export declare const BACKLOG_VIDEO_MAX: number;
+/**
+ * How long a rate is measured over before it is believed.
+ *
+ * The first seconds of a pull are not a bitrate: ffmpeg opens the source,
+ * reads ahead, and empties what it has as fast as the pipe takes it. Sizing a
+ * buffer off that burst would reserve tens of megabytes for a stream that
+ * turns out to be a podcast. A window is measured, and until one has closed
+ * the floor stands.
+ */
+export declare const RATE_WINDOW_MS = 5000;
 /** A name that can sit in a URL and be read back in a list. */
 export declare function cleanId(value: unknown, fallback?: string): string;
 export interface ChannelOptions {
@@ -91,6 +140,10 @@ export interface ChannelOptions {
     onEnd?: (info: ChannelInfo) => void;
     /** How long an on-demand channel outlives its last viewer. Tests shorten it. */
     idleMs?: number;
+    /** Unsent bytes a listener may hold before it is dropped. Tests shrink it. */
+    maxListenerQueueBytes?: number;
+    /** How long a rate is measured over before the backlog is sized off it. Tests shorten it. */
+    rateWindowMs?: number;
 }
 /**
  * One live source, and its audience.
@@ -128,6 +181,10 @@ export declare class Channel {
      */
     private recent;
     private recentBytes;
+    /** The rate window: when it opened, what has arrived in it, and what the last closed one measured. */
+    private rateStart;
+    private rateBytes;
+    private rate;
     /**
      * Started for whoever asked and stopped when nobody is left. A catalog
      * channel is one of thousands; keeping every one that was ever clicked
@@ -193,6 +250,15 @@ export declare class Channel {
      * make sense.
      */
     private emit;
+    /** Watch how fast this channel is actually running, a window at a time. */
+    private measure;
+    /**
+     * Six seconds of whatever this channel turned out to be, within bounds.
+     *
+     * Unmeasured -- the first window of a pull, or a channel that has only just
+     * started -- means the floor, which is what every channel had before.
+     */
+    private backlogCap;
     /** Keep this for the next arrival, and let the oldest go once it is too much. */
     private remember;
     /** Feed the source. */
@@ -204,8 +270,34 @@ export declare class Channel {
      * simply a different process that did it.
      */
     feed(chunk: Buffer): void;
-    /** Write to everyone, and drop anybody whose socket has gone. */
+    /**
+     * Write to everyone, and drop anybody whose socket has gone -- or has
+     * stopped taking anything. A write that returns false is ordinary: the
+     * socket is a little behind and will catch up. One that returns false
+     * with a queue past the limit is a listener that is not reading, and
+     * ending it is the only thing that stops its queue growing.
+     */
     private send;
+    /**
+     * What a new listener is written before the live bytes: the opening
+     * boxes when there are any, then the recent backlog. The same rule as
+     * `listen`, handed out so a relay can compress it for one receiver.
+     */
+    opening(): Buffer[];
+    /**
+     * Bytes decoded from another nixamp's relay: the channel's own output as
+     * it was there, so they go out here exactly as ffmpeg's would, whole
+     * boxes at a time with the backlog kept.
+     */
+    receive(chunk: Buffer): void;
+    /** Ready a channel that will be fed by `receive`: pictures need their boxes tracked. */
+    prepare(): void;
+    /**
+     * The feed behind `receive` started over: a new generation upstream, with
+     * new opening boxes. Everybody listening is ended, as they are when our
+     * own ffmpeg is dialled again, and a newcomer gets the new beginning.
+     */
+    rollover(): void;
     listen(listener: Listener): () => void;
     /** Stay up with nobody watching: no longer on demand. */
     keep(): void;
@@ -282,6 +374,16 @@ export declare class Channels {
      * decoded would double the work to arrive at the same bytes.
      */
     attach(id: string, name: string, format: string, via: ChannelInfo["via"]): Channel | null;
+    /**
+     * A channel carried in from another nixamp's relay. Like `attach`, no
+     * ffmpeg of our own; unlike it, the kind is known up front, so a picture
+     * gets its fragment tracking and a newcomer gets the opening boxes.
+     */
+    relayIn(id: string, name: string, kind: "audio" | "video", source: string): Channel | null;
+    /** What a new listener would be written first, for a relay's preface. */
+    opening(id: string): Buffer[];
+    /** The kind of a channel, for a relay to say what it is carrying. */
+    kindOf(id: string): "audio" | "video" | undefined;
     stop(id: string): boolean;
     stopAll(): void;
 }
@@ -314,6 +416,8 @@ export interface RememberedChannel {
         audio: string;
         container: string;
         duration?: number;
+        width?: number;
+        height?: number;
     };
     /** Where a film had got to, in seconds, so it picks up there. */
     position?: number;