@volter/world-core 3.0.151 → 3.0.152

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;
+};