@volter/world-core 3.0.151 → 3.0.153

package/dist/src/live/flv.js

@@ -0,0 +1,148 @@
+// An FLV tag's body as RTMP carries it (FLV 10.1, Annex E.4.2 and E.4.3): video as AVC (codec 7, its packet type 0 the
+// AVCDecoderConfigurationRecord, 1 length-prefixed NAL units with a composition time offset), audio as AAC (format 10, its
+// packet type 0 the AudioSpecificConfig, 1 a raw frame). Anything else is named as the codec it is and not read: other
+// codecs, and Enhanced RTMP's ex-header (its first byte's high bit), which carries HEVC, AV1 and multitrack video.
+const VIDEO_CODECS = { 2: 'Sorenson H.263', 3: 'Screen video', 4: 'On2 VP6', 5: 'On2 VP6 with alpha', 6: 'Screen video 2', 12: 'HEVC', 13: 'AV1' };
+const AUDIO_FORMATS = { 0: 'linear PCM', 1: 'ADPCM', 2: 'MP3', 3: 'linear PCM (little-endian)', 4: 'Nellymoser 16 kHz', 5: 'Nellymoser 8 kHz', 6: 'Nellymoser', 7: 'G.711 A-law', 8: 'G.711 mu-law', 11: 'Speex', 14: 'MP3 8 kHz', 15: 'device-specific' };
+const hex2 = (n) => n.toString(16).padStart(2, '0');
+export function readVideoTag(p) {
+    if (p.length < 1)
+        return { kind: 'other' };
+    if (p[0] & 0x80) {
+        const fourcc = p.length >= 5 ? String.fromCharCode(p[1], p[2], p[3], p[4]) : '?';
+        return { kind: 'unsupported', codec: `Enhanced RTMP ${fourcc}` };
+    }
+    const frameType = p[0] >> 4;
+    const codec = p[0] & 0x0f;
+    if (codec !== 7)
+        return { kind: 'unsupported', codec: VIDEO_CODECS[codec] ?? `video codec ${codec}` };
+    // a video info/command frame (frame type 5) carries no picture
+    if (frameType === 5 || p.length < 5)
+        return { kind: 'other' };
+    const packetType = p[1];
+    const cts = ((p[2] << 16) | (p[3] << 8) | p[4]) << 8 >> 8;
+    const data = p.subarray(5);
+    if (packetType === 0)
+        return { kind: 'config', config: avcConfig(data) };
+    if (packetType === 1)
+        return { kind: 'frame', key: frameType === 1, cts, data };
+    return { kind: 'other' };
+}
+export function readAudioTag(p) {
+    if (p.length < 2)
+        return { kind: 'frame', data: new Uint8Array(0) };
+    const format = p[0] >> 4;
+    if (format !== 10)
+        return { kind: 'unsupported', codec: AUDIO_FORMATS[format] ?? `audio format ${format}` };
+    if (p[1] === 0)
+        return { kind: 'config', config: aacConfig(p.subarray(2)) };
+    return { kind: 'frame', data: p.subarray(2) };
+}
+function avcConfig(record) {
+    const copy = record.slice();
+    const codec = copy.length >= 4 ? `avc1.${hex2(copy[1])}${hex2(copy[2])}${hex2(copy[3])}` : 'avc1.42e01e';
+    let width = 0;
+    let height = 0;
+    // the first SPS: after the version, profile, compatibility, level, length size and SPS count
+    if (copy.length > 8 && (copy[5] & 0x1f) > 0) {
+        const length = (copy[6] << 8) | copy[7];
+        try {
+            ({ width, height } = spsSize(copy.subarray(8, 8 + length)));
+        }
+        catch { /* the metadata's size stands in */ }
+    }
+    return { record: copy, codec, width, height };
+}
+function aacConfig(asc) {
+    const copy = asc.slice();
+    const RATES = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350];
+    const bits = new Bits(copy);
+    let objectType = bits.u(5);
+    if (objectType === 31)
+        objectType = 32 + bits.u(6);
+    const index = bits.u(4);
+    const sampleRate = index === 15 ? bits.u(24) : RATES[index] ?? 44100;
+    const channels = bits.u(4);
+    return { asc: copy, codec: `mp4a.40.${objectType}`, objectType, sampleRate, channels };
+}
+/** A bit reader over bytes, MSB first; a read past the end reads zeros. */
+class Bits {
+    bytes;
+    at = 0;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+    bit() { const byte = this.bytes[this.at >> 3] ?? 0; const v = (byte >> (7 - (this.at & 7))) & 1; this.at++; return v; }
+    u(n) { let v = 0; for (let i = 0; i < n; i++)
+        v = v * 2 + this.bit(); return v; }
+    ue() { let zeros = 0; while (this.bit() === 0) {
+        if (++zeros > 31)
+            throw new Error('exp-Golomb code too long');
+    } return 2 ** zeros - 1 + this.u(zeros); }
+    se() { const k = this.ue(); return k % 2 ? (k + 1) / 2 : -(k / 2); }
+}
+/** A sequence parameter set's picture size (H.264 §7.3.2.1.1), its cropping applied. */
+function spsSize(nal) {
+    // the NAL unit's RBSP: its header byte off, each emulation-prevention byte (00 00 03) removed
+    const rbsp = [];
+    for (let i = 1; i < nal.length; i++) {
+        if (i >= 3 && nal[i] === 3 && nal[i - 1] === 0 && nal[i - 2] === 0)
+            continue;
+        rbsp.push(nal[i]);
+    }
+    const b = new Bits(Uint8Array.from(rbsp));
+    const profile = b.u(8);
+    b.u(16);
+    b.ue();
+    let chroma = 1;
+    if ([100, 110, 122, 244, 44, 83, 86, 118, 128, 138, 139, 134, 135].includes(profile)) {
+        chroma = b.ue();
+        if (chroma === 3)
+            b.bit();
+        b.ue();
+        b.ue();
+        b.bit();
+        if (b.bit()) {
+            for (let i = 0; i < (chroma === 3 ? 12 : 8); i++) {
+                if (!b.bit())
+                    continue;
+                let last = 8;
+                let next = 8;
+                for (let j = 0; j < (i < 6 ? 16 : 64); j++) {
+                    if (next !== 0)
+                        next = (last + b.se() + 256) % 256;
+                    last = next === 0 ? last : next;
+                }
+            }
+        }
+    }
+    b.ue();
+    const poc = b.ue();
+    if (poc === 0)
+        b.ue();
+    else if (poc === 1) {
+        b.bit();
+        b.se();
+        b.se();
+        const n = b.ue();
+        for (let i = 0; i < n; i++)
+            b.se();
+    }
+    b.ue();
+    b.bit();
+    const widthMbs = b.ue() + 1;
+    const heightUnits = b.ue() + 1;
+    const frameMbsOnly = b.bit();
+    if (!frameMbsOnly)
+        b.bit();
+    b.bit();
+    let crop = [0, 0, 0, 0];
+    if (b.bit())
+        crop = [b.ue(), b.ue(), b.ue(), b.ue()];
+    const unitX = chroma === 1 || chroma === 2 ? 2 : 1;
+    const unitY = (chroma === 1 ? 2 : 1) * (2 - frameMbsOnly);
+    return {
+        width: widthMbs * 16 - (crop[0] + crop[1]) * unitX,
+        height: (2 - frameMbsOnly) * heightUnits * 16 - (crop[2] + crop[3]) * unitY,
+    };
+}

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

@@ -0,0 +1,25 @@
+import type { AacConfig, AvcConfig } from './flv.js';
+export declare const VIDEO_TRACK = 1;
+export declare const AUDIO_TRACK = 2;
+export declare const VIDEO_TIMESCALE = 90000;
+/** The init segment for the tracks a publish carries. */
+export declare function initSegment(tracks: {
+    video?: AvcConfig & {
+        width: number;
+        height: number;
+    };
+    audio?: AacConfig;
+}): Uint8Array;
+export type Sample = {
+    duration: number;
+    data: Uint8Array;
+    key: boolean;
+    cts?: number;
+};
+export type Fragment = {
+    track: number;
+    baseTime: number;
+    samples: Sample[];
+};
+/** A media segment: one `moof` over the fragments, then their samples in one `mdat`, video's first. */
+export declare function mediaSegment(sequence: number, fragments: Fragment[]): Uint8Array;

package/dist/src/live/fmp4.js

@@ -0,0 +1,96 @@
+export const VIDEO_TRACK = 1;
+export const AUDIO_TRACK = 2;
+export const VIDEO_TIMESCALE = 90_000;
+const ascii = (s) => Array.from(s, (c) => c.charCodeAt(0));
+const u16 = (n) => [(n >> 8) & 0xff, n & 0xff];
+const u32 = (n) => [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+const u64 = (n) => [...u32(Math.floor(n / 2 ** 32)), ...u32(n % 2 ** 32)];
+const zeros = (n) => new Array(n).fill(0);
+function box(type, ...parts) {
+    const size = 8 + parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(size);
+    out.set(u32(size), 0);
+    out.set(ascii(type), 4);
+    let at = 8;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+const full = (type, version, flags, ...parts) => box(type, [version, (flags >> 16) & 0xff, (flags >> 8) & 0xff, flags & 0xff], ...parts);
+const MATRIX = [...u32(0x00010000), ...u32(0), ...u32(0), ...u32(0), ...u32(0x00010000), ...u32(0), ...u32(0), ...u32(0), ...u32(0x40000000)];
+function descriptor(tag, ...parts) {
+    const body = parts.flatMap((p) => Array.from(p));
+    // the size as four bytes of seven bits, as MP4 writers write it
+    const n = body.length;
+    return [tag, 0x80 | ((n >> 21) & 0x7f), 0x80 | ((n >> 14) & 0x7f), 0x80 | ((n >> 7) & 0x7f), n & 0x7f, ...body];
+}
+function trak(id, kind, timescale, width, height, entry) {
+    const tkhd = full('tkhd', 0, 3, u32(0), u32(0), u32(id), u32(0), u32(0), zeros(8), u16(0), u16(0), u16(kind === 'audio' ? 0x0100 : 0), u16(0), MATRIX, u32(width * 65536), u32(height * 65536));
+    const mdhd = full('mdhd', 0, 0, u32(0), u32(0), u32(timescale), u32(0), u16(0x55c4), u16(0));
+    const hdlr = full('hdlr', 0, 0, u32(0), ascii(kind === 'video' ? 'vide' : 'soun'), zeros(12), [...ascii(kind === 'video' ? 'VideoHandler' : 'SoundHandler'), 0]);
+    const header = kind === 'video' ? full('vmhd', 0, 1, u16(0), zeros(6)) : full('smhd', 0, 0, u16(0), u16(0));
+    const dinf = box('dinf', full('dref', 0, 0, u32(1), full('url ', 0, 1)));
+    const stbl = box('stbl', full('stsd', 0, 0, u32(1), entry), full('stts', 0, 0, u32(0)), full('stsc', 0, 0, u32(0)), full('stsz', 0, 0, u32(0), u32(0)), full('stco', 0, 0, u32(0)));
+    return box('trak', tkhd, box('mdia', mdhd, hdlr, box('minf', header, dinf, stbl)));
+}
+/** The init segment for the tracks a publish carries. */
+export function initSegment(tracks) {
+    const traks = [];
+    const trex = [];
+    const brands = ['isom', 'iso6', ...(tracks.video ? ['avc1'] : []), 'mp41'];
+    if (tracks.video) {
+        const v = tracks.video;
+        const avc1 = box('avc1', zeros(6), u16(1), u16(0), u16(0), zeros(12), u16(v.width), u16(v.height), u32(0x00480000), u32(0x00480000), u32(0), u16(1), zeros(32), u16(0x0018), u16(0xffff), box('avcC', v.record));
+        traks.push(trak(VIDEO_TRACK, 'video', VIDEO_TIMESCALE, v.width, v.height, avc1));
+        trex.push(full('trex', 0, 0, u32(VIDEO_TRACK), u32(1), u32(0), u32(0), u32(0)));
+    }
+    if (tracks.audio) {
+        const a = tracks.audio;
+        const esds = full('esds', 0, 0, descriptor(3, u16(0), [0], descriptor(4, [0x40, 0x15], zeros(3), u32(0), u32(0), descriptor(5, a.asc)), descriptor(6, [0x02])));
+        const mp4a = box('mp4a', zeros(6), u16(1), zeros(8), u16(Math.max(1, a.channels)), u16(16), u16(0), u16(0), u32((a.sampleRate > 0xffff ? 0 : a.sampleRate) * 65536), esds);
+        traks.push(trak(AUDIO_TRACK, 'audio', a.sampleRate, 0, 0, mp4a));
+        trex.push(full('trex', 0, 0, u32(AUDIO_TRACK), u32(1), u32(0), u32(0), u32(0)));
+    }
+    const mvhd = full('mvhd', 0, 0, u32(0), u32(0), u32(1000), u32(0), u32(0x00010000), u16(0x0100), u16(0), zeros(8), MATRIX, zeros(24), u32(3));
+    const ftyp = box('ftyp', ascii('isom'), u32(0x200), ...brands.map(ascii));
+    const moov = box('moov', mvhd, ...traks, box('mvex', ...trex));
+    const out = new Uint8Array(ftyp.length + moov.length);
+    out.set(ftyp, 0);
+    out.set(moov, ftyp.length);
+    return out;
+}
+/** A media segment: one `moof` over the fragments, then their samples in one `mdat`, video's first. */
+export function mediaSegment(sequence, fragments) {
+    const present = fragments.filter((f) => f.samples.length > 0);
+    const moofOf = (offsets) => box('moof', full('mfhd', 0, 0, u32(sequence)), ...present.map((f, i) => {
+        const video = f.track === VIDEO_TRACK;
+        // data offset, duration, size, flags and (video) composition offset per sample; version 1 for signed offsets
+        const flags = video ? 0x000f01 : 0x000301;
+        const rows = f.samples.flatMap((s) => [
+            ...u32(s.duration), ...u32(s.data.length),
+            ...(video ? [...u32(s.key ? 0x02000000 : 0x01010000), ...u32((s.cts ?? 0) | 0)] : []),
+        ]);
+        return box('traf', full('tfhd', 0, 0x020000, u32(f.track)), full('tfdt', 1, 0, u64(f.baseTime)), full('trun', video ? 1 : 0, flags, u32(f.samples.length), u32(offsets[i] | 0), rows));
+    }));
+    const sized = moofOf(present.map(() => 0)).length;
+    const offsets = [];
+    let at = sized + 8;
+    for (const f of present) {
+        offsets.push(at);
+        at += f.samples.reduce((n, s) => n + s.data.length, 0);
+    }
+    const moof = moofOf(offsets);
+    // one buffer for the whole segment, the samples written straight into its mdat: a segment's bytes are copied once
+    const out = new Uint8Array(at);
+    out.set(moof, 0);
+    out.set([...u32(at - moof.length), ...ascii('mdat')], moof.length);
+    let to = moof.length + 8;
+    for (const f of present)
+        for (const s of f.samples) {
+            out.set(s.data, to);
+            to += s.data.length;
+        }
+    return out;
+}

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

@@ -0,0 +1,22 @@
+import type { LiveAudio, LiveVideo } from './types.js';
+/** A segment as the recording keeps it. */
+export type HlsSegment = {
+    seq: number;
+    init: number;
+    duration: number;
+    size: number;
+};
+/** The media playlist: the last `window` segments while the recording is published, every segment once it ended (or
+ *  with `window: 'all'`, an event playlist). */
+export declare function mediaPlaylist(recording: {
+    state: 'publishing' | 'ended';
+    window?: number;
+}, segments: ReadonlyArray<HlsSegment>, options?: {
+    window?: number | 'all';
+    uri?: (file: string) => string;
+}): string;
+/** The multivariant playlist naming the recording's one rendition, its peak bandwidth measured from its segments. */
+export declare function masterPlaylist(recording: {
+    video?: LiveVideo;
+    audio?: LiveAudio;
+}, segments: ReadonlyArray<HlsSegment>, media: string): string;

package/dist/src/live/hls.js

@@ -0,0 +1,46 @@
+const DEFAULT_WINDOW = 6;
+/** The media playlist: the last `window` segments while the recording is published, every segment once it ended (or
+ *  with `window: 'all'`, an event playlist). */
+export function mediaPlaylist(recording, segments, options = {}) {
+    const uri = options.uri ?? ((file) => file);
+    const ended = recording.state === 'ended';
+    const window = options.window ?? recording.window ?? DEFAULT_WINDOW;
+    const listed = ended || window === 'all' ? [...segments] : segments.slice(Math.max(0, segments.length - Math.max(1, window)));
+    // every EXTINF, rounded, is at most the target (§4.3.3.1)
+    const target = Math.max(1, ...segments.map((s) => Math.round(s.duration)));
+    const first = listed[0];
+    const lines = ['#EXTM3U', '#EXT-X-VERSION:7', `#EXT-X-TARGETDURATION:${target}`, `#EXT-X-MEDIA-SEQUENCE:${first?.seq ?? 0}`];
+    // each init after the recording's first is one discontinuity: those before the window are its sequence (§4.3.3.3)
+    if (first && first.init > 0)
+        lines.push(`#EXT-X-DISCONTINUITY-SEQUENCE:${first.init}`);
+    if (ended)
+        lines.push('#EXT-X-PLAYLIST-TYPE:VOD');
+    else if (window === 'all')
+        lines.push('#EXT-X-PLAYLIST-TYPE:EVENT');
+    lines.push('#EXT-X-INDEPENDENT-SEGMENTS');
+    let init;
+    for (const s of listed) {
+        if (s.init !== init) {
+            if (init !== undefined)
+                lines.push('#EXT-X-DISCONTINUITY');
+            lines.push(`#EXT-X-MAP:URI="${uri(`init-${s.init}.mp4`)}"`);
+            init = s.init;
+        }
+        lines.push(`#EXTINF:${s.duration.toFixed(3)},`, uri(`seg-${s.seq}.m4s`));
+    }
+    if (ended)
+        lines.push('#EXT-X-ENDLIST');
+    return `${lines.join('\n')}\n`;
+}
+/** The multivariant playlist naming the recording's one rendition, its peak bandwidth measured from its segments. */
+export function masterPlaylist(recording, segments, media) {
+    const peak = Math.max(1, ...segments.filter((s) => s.duration > 0).map((s) => Math.ceil((s.size * 8) / s.duration)));
+    const codecs = [recording.video?.codec, recording.audio?.codec].filter(Boolean).join(',');
+    const attributes = [
+        `BANDWIDTH=${peak}`,
+        ...(codecs ? [`CODECS="${codecs}"`] : []),
+        ...(recording.video && recording.video.width && recording.video.height ? [`RESOLUTION=${recording.video.width}x${recording.video.height}`] : []),
+        ...(recording.video?.frameRate ? [`FRAME-RATE=${recording.video.frameRate.toFixed(3)}`] : []),
+    ];
+    return `#EXTM3U\n#EXT-X-VERSION:7\n#EXT-X-INDEPENDENT-SEGMENTS\n#EXT-X-STREAM-INF:${attributes.join(',')}\n${media}\n`;
+}

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

@@ -0,0 +1,9 @@
+export type { LiveAccess, LiveAdmission, LiveAudio, LiveDecl, LiveEngine, LivePublish, LiveRecording, LiveRefusal, LiveServeOptions, LiveVideo } from './types.js';
+export { liveIngest, type LiveIngestOptions, type LiveWorld } from './ingest.js';
+export { liveAccess, LIVE, LIVE_SEGMENT, type LiveReads } from './access.js';
+export { masterPlaylist, mediaPlaylist, type HlsSegment } from './hls.js';
+export { rtmpSession, type RtmpPublisher } from './rtmp.js';
+export { decodeAmf0, encodeAmf0, type Amf0Value } from './amf0.js';
+export { readAudioTag, readVideoTag, type AacConfig, type AudioTag, type AvcConfig, type VideoTag } from './flv.js';
+export { initSegment, mediaSegment, type Fragment, type Sample } from './fmp4.js';
+export { Segmenter, type Cut } from './segmenter.js';

package/dist/src/live/index.js

@@ -0,0 +1,8 @@
+export { liveIngest } from "./ingest.js";
+export { liveAccess, LIVE, LIVE_SEGMENT } from "./access.js";
+export { masterPlaylist, mediaPlaylist } from "./hls.js";
+export { rtmpSession } from "./rtmp.js";
+export { decodeAmf0, encodeAmf0 } from "./amf0.js";
+export { readAudioTag, readVideoTag } from "./flv.js";
+export { initSegment, mediaSegment } from "./fmp4.js";
+export { Segmenter } from "./segmenter.js";

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

@@ -0,0 +1,25 @@
+import type { TwinStream } from '../twin-fetch.js';
+import { type LiveReads } from './access.js';
+import type { LiveDecl, LiveEngine, LivePublish } from './types.js';
+/** What the ingest reads and writes of the World, bound by the pack's fetch to its service and root. */
+export type LiveWorld = LiveReads & {
+    /** a bookkeeping subject written (or, with `deleted: true`, deleted) at the World's time */
+    record(type: string, id: string, fields: Record<string, unknown>, operation: string): Promise<void>;
+    putBlob(key: string, bytes: Uint8Array): Promise<void>;
+    removeBlob(key: string): Promise<void>;
+    now(): string;
+};
+export type LiveIngestOptions<C> = {
+    /** the World this ingest's recordings are kept in (its service and root): one publisher per stream within it */
+    world: string;
+    decls: ReadonlyArray<LiveDecl>;
+    engines: Record<string, LiveEngine<C>>;
+    readOnly: boolean;
+    /** the handler contract's context a hook runs over, opened at the moment it runs */
+    open(decl: LiveDecl, ask: LivePublish): Promise<C>;
+    /** runs a hook and the writes it causes as the vendor's own move, one correlation */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    store: LiveWorld;
+    log?(line: string): void;
+};
+export declare function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream;

package/dist/src/live/ingest.js

@@ -0,0 +1,229 @@
+import { initBlob, LIVE, LIVE_SEGMENT, recordingOf, segmentBlob, segmentsOf } from "./access.js";
+import { readAudioTag, readVideoTag } from "./flv.js";
+import { RtmpRefusal, rtmpSession } from "./rtmp.js";
+import { LiveOverrun, Segmenter } from "./segmenter.js";
+const STREAM_ID = /^[A-Za-z0-9._-]{1,128}$/;
+/** Connections one ingest's listener takes at once: publishers and the connections still on their way to publishing. */
+const MAX_CONNECTIONS = 32;
+/** The streams being published now, per World: a second publisher to one is refused, as a vendor's ingest refuses it. */
+const publishing = new Map();
+export function liveIngest(options) {
+    for (const d of options.decls)
+        if (!options.engines[d.id])
+            throw new Error(`the manifest declares the ingest ${d.id}, and semantics/live.ts exports no ${d.id}`);
+    const log = options.log ?? ((line) => console.error(`live: ${line}`));
+    const store = options.store;
+    const active = publishing.get(options.world) ?? publishing.set(options.world, new Set()).get(options.world);
+    // the listener's cap (serveStream reads it): a World's publishers are its encoders, a few at once
+    return Object.assign((sink, peer) => {
+        let decl;
+        let ask;
+        let stream;
+        let admitted;
+        let segmenter;
+        let initIndex = -1;
+        let priorInit;
+        let started = false;
+        let metadata;
+        let refusedCodec;
+        const recording = () => {
+            const row = store.rows(LIVE).find((r) => r.id === stream);
+            return recordingOf(row, segmentsOf(store, stream));
+        };
+        const hook = async (name) => {
+            const engine = options.engines[decl.id];
+            const fn = engine[name];
+            if (!fn)
+                return;
+            try {
+                await options.run(async () => fn.call(engine, await options.open(decl, ask), recording()));
+            }
+            catch (error) {
+                log(`${decl.id}'s ${name} for ${stream} was not written: ${String(error?.message ?? error)}`);
+            }
+        };
+        /** A closed segment kept: its init first when it opens one, its bytes, its subject; then what `retain` lets go. */
+        const keep = async (cut) => {
+            if (!stream || !admitted)
+                return;
+            if (cut.init) {
+                // a publisher that reconnects with the encoder it had plays on under the recording's last init, its timeline
+                // carried on, so no player meets a discontinuity; a changed configuration opens the next init
+                const prior = initIndex < 0 && priorInit !== undefined ? await store.blob(initBlob(stream, priorInit)) : null;
+                if (prior && sameBytes(prior, cut.init.bytes))
+                    initIndex = priorInit;
+                else {
+                    initIndex = initIndex < 0 ? (priorInit ?? -1) + 1 : initIndex + 1;
+                    await store.putBlob(initBlob(stream, initIndex), cut.init.bytes);
+                }
+                await options.run(() => store.record(LIVE, stream, {
+                    ...(cut.init.video ? { video: cut.init.video } : {}),
+                    ...(cut.init.audio ? { audio: cut.init.audio } : {}),
+                    ...(metadata ? { metadata } : {}),
+                }, 'live.configure'));
+            }
+            const blob = segmentBlob(stream, cut.sequence);
+            await store.putBlob(blob, cut.bytes);
+            await options.run(() => store.record(LIVE_SEGMENT, `${stream}:${cut.sequence}`, {
+                stream, seq: cut.sequence, init: initIndex, start: round(cut.start), duration: round(cut.duration), size: cut.bytes.length, blob,
+            }, 'live.segment'));
+            if (admitted.retain !== undefined && admitted.retain > 0) {
+                for (const old of segmentsOf(store, stream).slice(0, -admitted.retain)) {
+                    await store.removeBlob(old.blob);
+                    await options.run(() => store.record(LIVE_SEGMENT, `${stream}:${old.seq}`, { deleted: true }, 'live.segment.expire'));
+                }
+            }
+            if (!started) {
+                started = true;
+                await hook('started');
+            }
+        };
+        const keepAll = async (cuts) => { for (const cut of cuts)
+            await keep(cut); };
+        return rtmpSession(sink, {
+            connect(app) {
+                decl = options.decls.find((d) => d.app === app);
+                return decl ? undefined : `There is no application ${app || '(none)'} here.`;
+            },
+            async publish(asked) {
+                if (!decl)
+                    return { code: 'NetStream.Publish.BadName', description: 'No application was connected.' };
+                if (options.readOnly)
+                    return { code: 'NetStream.Publish.Denied', description: 'This World is read-only: it records nothing.' };
+                const [key = '', query = ''] = splitOnce(asked.name, '?');
+                ask = {
+                    app: asked.app, key, query: Object.fromEntries(new URLSearchParams(query)), peer,
+                    ...(asked.tcUrl !== undefined ? { tcUrl: asked.tcUrl } : {}), ...(asked.flashVer !== undefined ? { flashVer: asked.flashVer } : {}), ...(asked.type !== undefined ? { type: asked.type } : {}),
+                };
+                const engine = options.engines[decl.id];
+                const ruling = await options.run(async () => engine.publish(await options.open(decl, ask), ask));
+                if ('refused' in ruling)
+                    return { code: ruling.refused, description: ruling.description };
+                if (!STREAM_ID.test(ruling.stream))
+                    throw new Error(`${decl.id}'s publish named the stream ${JSON.stringify(ruling.stream)}; a stream is 1-128 letters, digits, '.', '_' or '-'`);
+                if (active.has(ruling.stream))
+                    return { code: 'NetStream.Publish.BadName', description: `The stream ${ruling.stream} is already being published.` };
+                const named = ruling.stream;
+                active.add(named);
+                try {
+                    // a recording continued: its segments' numbers, its inits' and its timeline carry on from where it stood
+                    const prior = store.rows(LIVE).find((r) => r.id === named && r.deleted !== true);
+                    const kept = segmentsOf(store, named);
+                    const last = kept[kept.length - 1];
+                    const offsetMs = last ? Math.ceil((last.start + last.duration) * 1000) : 0;
+                    const now = store.now();
+                    await options.run(() => store.record(LIVE, named, {
+                        app: ask.app, key: ask.key, state: 'publishing', startedAt: typeof prior?.startedAt === 'string' ? prior.startedAt : now, endedAt: null,
+                        publishes: Number(prior?.publishes ?? 0) + 1, window: ruling.window ?? 6, segmentSeconds: ruling.segmentSeconds ?? 2, ...(ruling.retain !== undefined ? { retain: ruling.retain } : {}),
+                    }, 'live.publish'));
+                    priorInit = last?.init;
+                    segmenter = new Segmenter({ targetMs: Math.max(0.5, ruling.segmentSeconds ?? 2) * 1000, offsetMs, firstSequence: last ? last.seq + 1 : 0 });
+                    stream = named;
+                    admitted = ruling;
+                }
+                catch (error) {
+                    // the publish was not recorded: the stream is free again, and the publisher refused (rtmp.ts)
+                    active.delete(named);
+                    throw error;
+                }
+                return undefined;
+            },
+            metadata(meta) {
+                const flat = flatMetadata(meta);
+                metadata = { ...(metadata ?? {}), ...flat };
+                segmenter?.metadata(flat);
+            },
+            async video(timestamp, payload) {
+                if (!segmenter)
+                    return;
+                const tag = readVideoTag(payload);
+                if (tag.kind === 'unsupported') {
+                    if (refusedCodec !== tag.codec)
+                        log(`${stream}: ${tag.codec} video is not recorded (H.264 is)`);
+                    refusedCodec = tag.codec;
+                    return;
+                }
+                const s = segmenter;
+                if (tag.kind === 'config')
+                    await keepAll(s.videoConfig(tag.config));
+                else if (tag.kind === 'frame')
+                    await keepAll(overrun(() => s.videoFrame(timestamp, tag.key, tag.cts, tag.data)));
+            },
+            async audio(timestamp, payload) {
+                if (!segmenter)
+                    return;
+                const tag = readAudioTag(payload);
+                if (tag.kind === 'unsupported') {
+                    if (refusedCodec !== tag.codec)
+                        log(`${stream}: ${tag.codec} audio is not recorded (AAC is)`);
+                    refusedCodec = tag.codec;
+                    return;
+                }
+                const s = segmenter;
+                if (tag.kind === 'config')
+                    await keepAll(s.audioConfig(tag.config));
+                else
+                    await keepAll(overrun(() => s.audioFrame(timestamp, tag.data)));
+            },
+            async unpublish() {
+                if (!stream || !segmenter)
+                    return;
+                const s = segmenter;
+                segmenter = undefined;
+                // the recording always ends: what was cut is kept where it can be, and the end is written whatever the last
+                // segment did, so no playlist is left waiting on a publisher that is gone
+                try {
+                    await keepAll(s.flush());
+                }
+                catch (error) {
+                    log(`${stream}: the last segment was not kept: ${String(error?.message ?? error)}`);
+                }
+                try {
+                    await options.run(() => store.record(LIVE, stream, { state: 'ended', endedAt: store.now() }, 'live.end'));
+                }
+                catch (error) {
+                    log(`${stream}: its end was not written: ${String(error?.message ?? error)}`);
+                }
+                finally {
+                    active.delete(stream);
+                }
+                await hook('ended');
+            },
+        }, log);
+    }, { maxConnections: MAX_CONNECTIONS });
+}
+const round = (n) => Math.round(n * 1000) / 1000;
+/** What a segmenter refuses, as RTMP's refusal of the publish (rtmp.ts ends it and closes the connection). */
+function overrun(fn) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        throw error instanceof LiveOverrun ? new RtmpRefusal('NetStream.Failed', error.message) : error;
+    }
+}
+/** The publisher's metadata as the World keeps it: its flat values (`onMetaData` is one level: an encoder's name, sizes,
+ *  rates), at most 64 of them, a string at most 256 characters; nested values are not kept, so nothing it sent (a
+ *  reference back to itself among them) can make the recording's row unwritable. */
+function flatMetadata(meta) {
+    const out = {};
+    for (const [key, value] of Object.entries(meta).slice(0, 64)) {
+        if (typeof value === 'number' ? Number.isFinite(value) : typeof value === 'boolean')
+            out[key.slice(0, 64)] = value;
+        else if (typeof value === 'string')
+            out[key.slice(0, 64)] = value.slice(0, 256);
+    }
+    return out;
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function splitOnce(s, sep) {
+    const at = s.indexOf(sep);
+    return at < 0 ? [s, ''] : [s.slice(0, at), s.slice(at + 1)];
+}

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

@@ -0,0 +1,35 @@
+import type { TwinStreamConnection, TwinStreamSink } from '../twin-fetch.js';
+import { type Amf0Value } from './amf0.js';
+/** What the session asks of its caller. */
+export type RtmpPublisher = {
+    /** `connect`: the application the publisher names, and its command object; a string refuses it, with that reason */
+    connect(app: string, command: Record<string, Amf0Value>): string | undefined;
+    /** `publish`: whether the stream may be published, or RTMP's refusal (its code and description) */
+    publish(ask: {
+        app: string;
+        name: string;
+        type?: string;
+        tcUrl?: string;
+        flashVer?: string;
+    }): Promise<{
+        code: string;
+        description: string;
+    } | undefined>;
+    /** `@setDataFrame` / `onMetaData`, as published */
+    metadata(meta: Record<string, Amf0Value>): void | Promise<void>;
+    /** an FLV audio or video tag's body, at its RTMP timestamp (milliseconds); an `RtmpRefusal` thrown ends the publish */
+    audio(timestamp: number, payload: Uint8Array): void | Promise<void>;
+    video(timestamp: number, payload: Uint8Array): void | Promise<void>;
+    /** the publish ended (`FCUnpublish`, `closeStream`, `deleteStream`, the connection ended while publishing, or a
+     *  refusal of what was published) */
+    unpublish(): void | Promise<void>;
+};
+/** What a publisher's media can draw mid-publish: its `onStatus` error, then the publish ended and the connection closed. */
+export declare class RtmpRefusal extends Error {
+    readonly code: string;
+    constructor(code: string, description: string);
+}
+/** One publisher's connection: its bytes in, the server's answers out through the sink. */
+export declare function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log?: (line: string) => void): TwinStreamConnection & {
+    backlog(): number;
+};