@volter/world-core 3.0.151 → 3.0.153

package/dist/src/live/rtmp.js

@@ -0,0 +1,456 @@
+import { decodeAmf0, encodeAmf0 } from "./amf0.js";
+/** What a publisher's media can draw mid-publish: its `onStatus` error, then the publish ended and the connection closed. */
+export class RtmpRefusal extends Error {
+    code;
+    constructor(code, description) {
+        super(description);
+        this.code = code;
+    }
+}
+const HANDSHAKE = 1536;
+/** The largest message: the chunk header's 24-bit length, the wire's own ceiling. The largest video frame measured fits
+ *  under it: 11,781,334 bytes, a 2160p frame of noise at CRF 1 (ffmpeg 8.1.2, libx264 ultrafast, `ffmpeg -f lavfi -i
+ *  "testsrc2=size=3840x2160:rate=30,noise=alls=30:allf=t+u" -frames:v 6 -c:v libx264 -preset ultrafast -crf 1 -f flv`, the
+ *  largest `ffprobe -show_entries packet=size`), beside 320,672 bytes for 1080p60 at a Twitch-like 8 Mbit/s CBR and
+ *  2,964,434 for 1080p at CRF 1; measured on Windows 11, twin-world 5c01b42b, nothing else encoding. */
+const MAX_MESSAGE = 0xffffff;
+/** Before a publish is admitted only commands come, a few hundred bytes each (ffmpeg's and librtmp's `connect` object):
+ *  a message, and what a connection holds in reassembly, stay small until the dialect has admitted the stream key. */
+const MAX_MESSAGE_UNADMITTED = 64 * 1024;
+const MAX_HELD_UNADMITTED = 256 * 1024;
+/** Once publishing: one frame reassembling while audio interleaves on its own chunk stream. */
+const MAX_HELD = MAX_MESSAGE + 1024 * 1024;
+/** Chunk streams a connection may open: ffmpeg uses 2, 3, 4, 6 and 8 (libavformat/rtmppkt.h, `RTMPChannel`), librtmp 2
+ *  to 5 and 8 (rtmp.c's `m_nChannel`). */
+const MAX_CHUNK_STREAMS = 64;
+/** Whole messages waiting their turn: the listener pauses past a few megabytes (serveStream); a transport that cannot
+ *  pause (a bridged WebSocket) is closed past this. */
+const MAX_QUEUED = 64 * 1024 * 1024;
+/** A connection that has not published this long after it opened is closed: one that never gets as far as a stream
+ *  key holds its place no longer than an encoder needs to connect and be admitted. */
+const PUBLISH_DEADLINE_MS = 30_000;
+const WINDOW = 5_000_000;
+const OUT_CHUNK = 4096;
+const u24 = (b, at) => (b[at] << 16) | (b[at + 1] << 8) | b[at + 2];
+const u32 = (b, at) => ((b[at] << 24) >>> 0) + ((b[at + 1] << 16) | (b[at + 2] << 8) | b[at + 3]);
+const u32le = (b, at) => (b[at] | (b[at + 1] << 8) | (b[at + 2] << 16)) + ((b[at + 3] << 24) >>> 0);
+const be32 = (n) => [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+function join(parts, length) {
+    if (parts.length === 1 && parts[0].length === length)
+        return parts[0];
+    const out = new Uint8Array(length);
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+/** One publisher's connection: its bytes in, the server's answers out through the sink. */
+export function rtmpSession(sink, publisher, log = () => { }) {
+    let pending = new Uint8Array(0);
+    let phase = 'c0c1';
+    let inChunk = 128;
+    let received = 0;
+    let acked = 0;
+    let peerWindow = 0;
+    let app = '';
+    let tcUrl;
+    let flashVer;
+    let nextStream = 1;
+    let publishing = false;
+    let publishStream = 0;
+    let ended = false;
+    const chunks = new Map();
+    /** a chunk whose header was read and whose payload is still arriving */
+    let current;
+    /** bytes held in messages being reassembled, and in whole messages waiting their turn */
+    let held = 0;
+    let queued = 0;
+    let chain = Promise.resolve();
+    const deadline = setTimeout(() => { if (!publishing && !ended)
+        overrun(`it did not publish within ${PUBLISH_DEADLINE_MS / 1000} s`); }, PUBLISH_DEADLINE_MS);
+    deadline.unref?.();
+    let outChunk = 128;
+    const write = (bytes) => { if (phase !== 'closed')
+        sink.write(bytes); };
+    /** A message as chunks of the server's chunk size: a type-0 header, then type-3 continuations. */
+    const send = (csid, type, streamId, payload, timestamp = 0) => {
+        const head = [csid & 0x3f, ...be32(Math.min(timestamp, 0xffffff)).slice(1), ...be32(payload.length).slice(1), type, streamId & 0xff, (streamId >> 8) & 0xff, (streamId >> 16) & 0xff, (streamId >>> 24) & 0xff];
+        const parts = head;
+        for (let at = 0; at < payload.length; at += outChunk) {
+            if (at > 0)
+                parts.push(0xc0 | (csid & 0x3f));
+            for (const b of payload.subarray(at, at + outChunk))
+                parts.push(b);
+        }
+        write(Uint8Array.from(parts));
+    };
+    const control = (type, body) => send(2, type, 0, Uint8Array.from(body));
+    const command = (csid, streamId, ...values) => send(csid, 20, streamId, encodeAmf0(...values));
+    const status = (streamId, level, code, description, details) => command(5, streamId, 'onStatus', 0, null, { level, code, description, ...(details !== undefined ? { details } : {}) });
+    const close = () => {
+        if (phase === 'closed')
+            return;
+        phase = 'closed';
+        clearTimeout(deadline);
+        pending = new Uint8Array(0);
+        chunks.clear();
+        current = undefined;
+        held = 0;
+        try {
+            sink.end();
+        }
+        catch { /* the peer is gone */ }
+    };
+    /** A connection past a ceiling: said once, and closed. */
+    const overrun = (what) => { log(`closing a connection: ${what}`); close(); };
+    const stop = async () => {
+        if (!publishing || ended)
+            return;
+        ended = true;
+        publishing = false;
+        await publisher.unpublish();
+    };
+    const onCommand = async (message, values) => {
+        const [name, txnValue, object, ...args] = values;
+        const txn = typeof txnValue === 'number' ? txnValue : 0;
+        switch (name) {
+            case 'connect': {
+                const cmd = (object && typeof object === 'object' && !Array.isArray(object) && !(object instanceof Date) ? object : {});
+                app = String(cmd.app ?? '').replace(/^\/+|\/+$/g, '');
+                tcUrl = typeof cmd.tcUrl === 'string' ? cmd.tcUrl : undefined;
+                flashVer = typeof cmd.flashVer === 'string' ? cmd.flashVer : undefined;
+                const refused = publisher.connect(app, cmd);
+                if (refused !== undefined) {
+                    command(3, 0, '_error', txn, null, { level: 'error', code: 'NetConnection.Connect.Rejected', description: refused });
+                    close();
+                    return;
+                }
+                control(5, be32(WINDOW));
+                control(6, [...be32(WINDOW), 2]);
+                control(1, be32(OUT_CHUNK));
+                outChunk = OUT_CHUNK;
+                command(3, 0, '_result', txn, { fmsVer: 'FMS/3,0,1,123', capabilities: 31 }, { level: 'status', code: 'NetConnection.Connect.Success', description: 'Connection succeeded.', objectEncoding: 0 });
+                return;
+            }
+            case 'releaseStream':
+            case 'FCPublish':
+            case 'getStreamLength':
+            case '_checkbw':
+                if (txn > 0)
+                    command(3, 0, '_result', txn, null, undefined);
+                return;
+            case 'createStream':
+                command(3, 0, '_result', txn, null, nextStream++);
+                return;
+            case 'publish': {
+                const stream = message.streamId;
+                const named = typeof args[0] === 'string' ? args[0] : '';
+                if (publishing) {
+                    status(stream, 'error', 'NetStream.Publish.BadName', 'This connection is already publishing.', named);
+                    return;
+                }
+                const type = typeof args[1] === 'string' ? args[1] : undefined;
+                let refusal;
+                try {
+                    refusal = await publisher.publish({ app, name: named, ...(type !== undefined ? { type } : {}), ...(tcUrl !== undefined ? { tcUrl } : {}), ...(flashVer !== undefined ? { flashVer } : {}) });
+                }
+                catch (error) {
+                    log(`publish failed: ${String(error?.message ?? error)}`);
+                    refusal = { code: 'NetStream.Publish.Denied', description: 'The server could not take the stream.' };
+                }
+                if (refusal) {
+                    status(stream, 'error', refusal.code, refusal.description, named);
+                    close();
+                    return;
+                }
+                publishing = true;
+                publishStream = stream;
+                // user control StreamBegin (event 0) for the publish's stream, then its start
+                control(4, [0, 0, ...be32(stream)]);
+                status(stream, 'status', 'NetStream.Publish.Start', `${named.split('?')[0]} is now published.`, named.split('?')[0]);
+                return;
+            }
+            case 'FCUnpublish':
+            case 'closeStream':
+            case 'deleteStream':
+                await stop();
+                return;
+            case 'play':
+                status(message.streamId, 'error', 'NetStream.Play.Failed', 'This server takes published streams; it plays none over RTMP.');
+                close();
+                return;
+            default:
+                if (txn > 0)
+                    command(3, 0, '_error', txn, null, { level: 'error', code: 'NetConnection.Call.Failed', description: `${String(name)} is not a command this server answers.` });
+        }
+    };
+    /** What was published, handed on: a refusal of it ends the publish (its `onStatus` error first) and the connection. */
+    const media = async (hand) => {
+        try {
+            await hand();
+        }
+        catch (error) {
+            if (!(error instanceof RtmpRefusal))
+                throw error;
+            status(publishStream, 'error', error.code, error.message);
+            await stop();
+            close();
+        }
+    };
+    const onMessage = async (message) => {
+        const p = message.payload;
+        switch (message.type) {
+            case 3:
+            case 6: return;
+            case 4: {
+                const event = (p[0] << 8) | p[1];
+                // a ping request is answered with the same timestamp (event 7, PingResponse)
+                if (event === 6 && p.length >= 6)
+                    control(4, [0, 7, ...Array.from(p.subarray(2, 6))]);
+                return;
+            }
+            case 5:
+                peerWindow = u32(p, 0);
+                return;
+            case 8:
+                if (publishing)
+                    await media(() => publisher.audio(message.timestamp, p));
+                return;
+            case 9:
+                if (publishing)
+                    await media(() => publisher.video(message.timestamp, p));
+                return;
+            case 15:
+            case 18: {
+                const values = decodeAmf0(message.type === 15 ? p.subarray(1) : p);
+                const meta = values[0] === '@setDataFrame' ? values[2] : values[0] === 'onMetaData' ? values[1] : undefined;
+                if (publishing && meta && typeof meta === 'object' && !Array.isArray(meta) && !(meta instanceof Date))
+                    await media(() => publisher.metadata(meta));
+                return;
+            }
+            case 17:
+            case 20:
+                await onCommand(message, decodeAmf0(message.type === 17 ? p.subarray(1) : p));
+                return;
+            default: return;
+        }
+    };
+    /** A chunk's bytes taken into its message, within what the connection may hold; false when past it (closed). */
+    const absorb = (st, bytes) => {
+        if (bytes.length === 0)
+            return true;
+        const ceiling = publishing ? MAX_HELD : MAX_HELD_UNADMITTED;
+        if (held + bytes.length > ceiling) {
+            overrun(`it holds more than ${ceiling} bytes of unfinished messages`);
+            return false;
+        }
+        st.parts.push(bytes.slice());
+        st.received += bytes.length;
+        held += bytes.length;
+        return true;
+    };
+    /** A chunk ended: its message, when whole, handled; the chunk size and an abort take effect at once, before the next
+     *  chunk is read (RTMP 1.0 §5.4.1, §5.4.2). */
+    const finish = (st) => {
+        if (st.received < st.length)
+            return;
+        const payload = join(st.parts, st.length);
+        held -= st.received;
+        st.parts = [];
+        st.received = 0;
+        if (st.type === 1) {
+            inChunk = Math.max(1, u32(payload, 0) & 0x7fffffff);
+            return;
+        }
+        if (st.type === 2) {
+            const aborted = chunks.get(u32(payload, 0));
+            if (aborted) {
+                held -= aborted.received;
+                aborted.parts = [];
+                aborted.received = 0;
+                if (current?.st === aborted)
+                    current = undefined;
+            }
+            return;
+        }
+        const message = { type: st.type, streamId: st.streamId, timestamp: st.timestamp, payload };
+        queued += payload.length;
+        if (queued > MAX_QUEUED) {
+            overrun(`more than ${MAX_QUEUED} bytes of messages wait to be recorded`);
+            return;
+        }
+        chain = chain.then(() => (phase === 'closed' && message.type !== 20 ? undefined : onMessage(message))).catch((error) => {
+            log(`a message failed: ${String(error?.message ?? error)}`);
+            close();
+        }).finally(() => { queued -= payload.length; });
+    };
+    /** What the pending bytes give: the rest of a chunk under way, or a chunk's header and as much of its payload as came.
+     *  How many bytes it took, or 0 when no more can be read yet. */
+    const readChunk = () => {
+        const b = pending;
+        if (current) {
+            const n = Math.min(current.left, b.length);
+            if (n === 0)
+                return 0;
+            const { st } = current;
+            if (!absorb(st, b.subarray(0, n)))
+                return b.length;
+            current.left -= n;
+            if (current.left === 0) {
+                current = undefined;
+                finish(st);
+            }
+            return n;
+        }
+        if (b.length < 1)
+            return 0;
+        const fmt = b[0] >> 6;
+        let csid = b[0] & 0x3f;
+        let at = 1;
+        if (csid === 0) {
+            if (b.length < 2)
+                return 0;
+            csid = 64 + b[1];
+            at = 2;
+        }
+        else if (csid === 1) {
+            if (b.length < 3)
+                return 0;
+            csid = 64 + b[1] + b[2] * 256;
+            at = 3;
+        }
+        const headerLength = [11, 7, 3, 0][fmt];
+        if (b.length < at + headerLength)
+            return 0;
+        const prior = chunks.get(csid);
+        if (!prior && chunks.size >= MAX_CHUNK_STREAMS) {
+            overrun(`it opened more than ${MAX_CHUNK_STREAMS} chunk streams`);
+            return b.length;
+        }
+        const st = prior ?? { timestamp: 0, tsField: 0, extended: false, length: 0, type: 0, streamId: 0, parts: [], received: 0 };
+        let tsField = st.tsField;
+        let length = st.length;
+        let type = st.type;
+        let streamId = st.streamId;
+        if (fmt <= 2)
+            tsField = u24(b, at);
+        if (fmt <= 1) {
+            length = u24(b, at + 3);
+            type = b[at + 6];
+        }
+        if (fmt === 0)
+            streamId = u32le(b, at + 7);
+        at += headerLength;
+        // the extended timestamp: after a header whose field is 0xffffff, and in each type-3 chunk of a chunk stream whose
+        // last header had one (RTMP 1.0 §5.3.1.3), as ffmpeg and librtmp send it
+        const extended = fmt === 3 ? st.extended : tsField === 0xffffff;
+        let ts = tsField;
+        if (extended) {
+            if (b.length < at + 4)
+                return 0;
+            ts = u32(b, at);
+            at += 4;
+        }
+        const starting = st.received === 0;
+        const largest = publishing ? MAX_MESSAGE : MAX_MESSAGE_UNADMITTED;
+        if (starting && length > largest) {
+            overrun(`a message of ${length} bytes is past the ${largest} it may send now`);
+            return b.length;
+        }
+        if (!starting && length < st.received) {
+            overrun('a chunk header shortened the message under way');
+            return b.length;
+        }
+        // the header is the chunk stream's now
+        if (starting) {
+            // a type-0 header's timestamp is absolute; every other is a delta on the chunk stream's last (a type-3 header's is
+            // the last header's field, as ffmpeg reads it)
+            st.timestamp = fmt === 0 ? ts : st.timestamp + ts;
+        }
+        if (fmt <= 2) {
+            st.tsField = tsField;
+            st.extended = extended;
+        }
+        st.length = length;
+        st.type = type;
+        st.streamId = streamId;
+        if (!prior)
+            chunks.set(csid, st);
+        const take = Math.min(inChunk, length - st.received);
+        const n = Math.min(take, b.length - at);
+        if (!absorb(st, b.subarray(at, at + n)))
+            return b.length;
+        if (n < take)
+            current = { st, left: take - n };
+        else
+            finish(st);
+        return at + n;
+    };
+    const pump = () => {
+        for (;;) {
+            if (phase === 'closed') {
+                pending = new Uint8Array(0);
+                return;
+            }
+            if (phase === 'c0c1') {
+                if (pending.length < 1 + HANDSHAKE)
+                    return;
+                if (pending[0] !== 3) {
+                    log(`RTMP version ${pending[0]} is not 3`);
+                    close();
+                    return;
+                }
+                const c1 = pending.subarray(1, 1 + HANDSHAKE);
+                // S0 (version 3), S1 (time 0, zero, filler), S2 (C1 echoed): the simple handshake
+                const s = new Uint8Array(1 + HANDSHAKE * 2);
+                s[0] = 3;
+                s.set(c1, 1 + HANDSHAKE);
+                write(s);
+                pending = pending.slice(1 + HANDSHAKE);
+                phase = 'c2';
+                continue;
+            }
+            if (phase === 'c2') {
+                if (pending.length < HANDSHAKE)
+                    return;
+                pending = pending.slice(HANDSHAKE);
+                phase = 'chunks';
+                continue;
+            }
+            const took = readChunk();
+            if (took === 0)
+                return;
+            pending = pending.subarray(took);
+        }
+    };
+    return {
+        data(chunk) {
+            if (phase === 'closed')
+                return;
+            received += chunk.length;
+            // the acknowledgement the peer's window asks for (RTMP 1.0 §5.4.3)
+            if (peerWindow > 0 && received - acked >= peerWindow) {
+                acked = received;
+                control(3, be32(received >>> 0));
+            }
+            // what is left unread is at most a chunk header (a chunk's payload is taken as it comes), so the copy is small
+            const rest = pending;
+            pending = new Uint8Array(rest.length + chunk.length);
+            pending.set(rest, 0);
+            pending.set(chunk, rest.length);
+            pump();
+        },
+        settled: () => chain,
+        // what the twin's work has not reached: whole messages waiting and the few bytes not yet read. An unfinished
+        // message's bytes are not in it: only more bytes finish it, and what it may hold is bounded (MAX_HELD)
+        backlog: () => queued + pending.length,
+        close() {
+            clearTimeout(deadline);
+            // the connection ended: a publish still open ends with it, after every message already read
+            chain = chain.then(() => stop()).catch((error) => log(`the publish's end failed: ${String(error?.message ?? error)}`));
+            phase = 'closed';
+        },
+    };
+}

package/dist/src/live/segmenter.d.ts

@@ -0,0 +1,57 @@
+import type { LiveAudio, LiveVideo } from './types.js';
+import { type AacConfig, type AvcConfig } from './flv.js';
+/** A segment closed: its bytes, its media start and duration (seconds), and, when it opens a new init, that init. */
+export type Cut = {
+    /** the segment's number in its recording */
+    sequence: number;
+    bytes: Uint8Array;
+    start: number;
+    duration: number;
+    init?: {
+        bytes: Uint8Array;
+        video?: LiveVideo;
+        audio?: LiveAudio;
+    };
+};
+/** A stream the segmenter will not hold: its publish is ended with the reason (ingest.ts). */
+export declare class LiveOverrun extends Error {
+}
+export declare class Segmenter {
+    private readonly options;
+    private avc?;
+    private aac?;
+    private meta;
+    private freshInit;
+    private video;
+    private audio;
+    private start?;
+    private keyed;
+    private audioNext?;
+    private lastVideoDuration;
+    private sequence;
+    /** what the segment under way holds, and since when video has come with no keyframe to start on */
+    private bytes;
+    private frames;
+    private unkeyedSince?;
+    constructor(options: {
+        targetMs: number;
+        offsetMs: number;
+        firstSequence: number;
+    });
+    /** The publisher's metadata (`onMetaData`): the size and rate a stream's SPS does not say, and whether video comes. */
+    metadata(meta: Record<string, unknown>): void;
+    videoConfig(config: AvcConfig): Cut[];
+    audioConfig(config: AacConfig): Cut[];
+    /** A video frame at its decode time: the segment it closes, if it closes one. */
+    videoFrame(timestamp: number, key: boolean, cts: number, data: Uint8Array): Cut[];
+    audioFrame(timestamp: number, data: Uint8Array): Cut[];
+    /** The segment under way, closed (the publish's end, or a configuration change). */
+    flush(): Cut[];
+    private keyframeCeiling;
+    private noKeyframe;
+    /** A frame the segment under way may still take, or the refusal past its ceilings. */
+    private within;
+    private expectsVideo;
+    private audioOnlyStarted;
+    private cut;
+}