@synapse-sdk/media 0.3.0 → 0.3.3

package/dist/annexb.js

@@ -1,227 +0,0 @@
-/** NAL unit types this package cares about (H.264 Table 7-1). */
-export const NAL_TYPE = { SLICE: 1, SLICE_DPA: 2, SLICE_DPB: 3, SLICE_DPC: 4, IDR: 5, SEI: 6, SPS: 7, PPS: 8, AUD: 9 };
-/** SEI payload type of a recovery point (H.264 D.1.8). */
-export const SEI_RECOVERY_POINT = 6;
-/** `nal_unit_type` (low 5 bits of the header byte); 0 for an empty NAL. */
-export function nalType(n) { return n.bytes.length ? n.bytes[0] & 0x1f : 0; }
-/** Payload after the 1-byte NAL header (escaped RBSP). */
-export function nalPayload(n) { return n.bytes.subarray(1); }
-/** A VCL NAL type: a coded slice (types 1-5). */
-export function isVclType(t) { return t >= NAL_TYPE.SLICE && t <= NAL_TYPE.IDR; }
-export function nalIsVcl(n) { return isVclType(nalType(n)); }
-/** Start code plus NAL unit, as it sits in the stream (a view). */
-export function nalWithStartCode(buf, n) { return buf.subarray(n.offset, n.offset + n.startCodeLen + n.bytes.length); }
-/** Next Annex-B start code (`00 00 01` or `00 00 00 01`) at or after `from`: `[offset, len]`. */
-export function findStartCode(buf, from) {
-    const n = buf.length;
-    for (let i = from; i + 3 <= n; i++) {
-        if (buf[i] === 0 && buf[i + 1] === 0) {
-            if (buf[i + 2] === 1)
-                return [i, 3];
-            if (i + 4 <= n && buf[i + 2] === 0 && buf[i + 3] === 1)
-                return [i, 4];
-        }
-    }
-    return undefined;
-}
-/**
- * The NAL units of an Annex-B buffer, in order. Bytes before the first start code are skipped;
- * trailing zero bytes (`trailing_zero_8bits`) stay attached to the NAL before them, which is
- * harmless for type/flag decisions and keeps the bytes of a walked AU identical to the input.
- */
-export function nalUnits(buf) {
-    const out = [];
-    let sc = findStartCode(buf, 0);
-    while (sc) {
-        const [s, l] = sc;
-        const start = s + l;
-        const next = findStartCode(buf, start);
-        out.push({ offset: s, startCodeLen: l, bytes: buf.subarray(start, next ? next[0] : buf.length) });
-        sc = next;
-    }
-    return out;
-}
-/** The SPS + PPS NAL units of an access unit (with their start codes, in stream order), if it carries any. Defined ⇒ the AU deserves the `CONFIG` flag. */
-export function auParamSets(au) {
-    const parts = [];
-    for (const n of nalUnits(au)) {
-        const t = nalType(n);
-        if (t === NAL_TYPE.SPS || t === NAL_TYPE.PPS)
-            parts.push(nalWithStartCode(au, n));
-    }
-    return parts.length ? concatBytes(parts) : undefined;
-}
-/**
- * The sync points an Annex-B access unit offers.
- * - `idr`: an IDR slice (NAL type 5) is present → instantaneous start point (`KEY`).
- * - `recovery`: a recovery point SEI (NAL 6, payload type 6) is present → gradual start point,
- *   clean one refresh period later (`RECOVERY`; x264 and nvenc both emit it at each intra-refresh sweep).
- * Decided from the bitstream rather than the encoder's keyframe flag, which libx264 raises for
- * both kinds and nvenc only for IDRs.
- */
-export function auSyncPoints(au) {
-    let idr = false, recovery = false;
-    for (const n of nalUnits(au)) {
-        const t = nalType(n);
-        if (t === NAL_TYPE.IDR)
-            idr = true;
-        else if (t === NAL_TYPE.SEI)
-            recovery ||= seiHasRecoveryPoint(nalPayload(n));
-    }
-    return { idr, recovery };
-}
-/** An IDR is present: the AU is a keyframe in the `KEY` sense. */
-export function isKeyframe(au) { return auSyncPoints(au).idr; }
-/** The AU carries at least one coded slice (otherwise it is parameter sets / SEI only). */
-export function hasVcl(au) { return nalUnits(au).some(nalIsVcl); }
-/** Whether an SEI NAL payload (after the NAL header byte) contains a recovery point message (payload type 6). */
-export function seiHasRecoveryPoint(payload) { return seiPayloadTypes(payload).includes(SEI_RECOVERY_POINT); }
-/** The payload types of the SEI messages in an SEI NAL payload (D.1.1), in order. Emulation-prevention bytes are removed first. */
-export function seiPayloadTypes(payload) {
-    const rbsp = rbspUnescape(payload);
-    const out = [];
-    let i = 0;
-    // 0x80 is the rbsp_trailing_bits byte that ends the SEI NAL.
-    while (i < rbsp.length && rbsp[i] !== 0x80) {
-        // payloadType and payloadSize: runs of 0xFF each adding 255, then a final byte.
-        let ty = 0;
-        while (i < rbsp.length && rbsp[i] === 0xff) {
-            ty += 255;
-            i++;
-        }
-        if (i >= rbsp.length)
-            break;
-        ty += rbsp[i];
-        i++;
-        let sz = 0;
-        while (i < rbsp.length && rbsp[i] === 0xff) {
-            sz += 255;
-            i++;
-        }
-        if (i >= rbsp.length)
-            break;
-        sz += rbsp[i];
-        i++;
-        out.push(ty);
-        i += sz;
-    }
-    return out;
-}
-/** Strip H.264 emulation-prevention bytes (the `03` in `00 00 03`), giving the RBSP. */
-export function rbspUnescape(nal) {
-    const out = new Uint8Array(nal.length);
-    let o = 0, zeros = 0;
-    for (const b of nal) {
-        if (zeros >= 2 && b === 3) {
-            zeros = 0;
-            continue;
-        }
-        out[o++] = b;
-        zeros = b === 0 ? zeros + 1 : 0;
-    }
-    return out.subarray(0, o);
-}
-/** The SPS of an AU (NAL bytes without start code), if present. */
-export function findSps(au) {
-    for (const n of nalUnits(au))
-        if (nalType(n) === NAL_TYPE.SPS)
-            return n.bytes;
-    return undefined;
-}
-/** The WebCodecs / RFC 6381 codec string for an AU that carries an SPS: `avc1.` + profile_idc + constraint flags + level_idc as hex (e.g. `avc1.42c01e`). */
-export function codecStringFromSps(au) {
-    const sps = findSps(au);
-    if (!sps || sps.length < 4)
-        return undefined;
-    const hex = (b) => b.toString(16).padStart(2, "0");
-    return `avc1.${hex(sps[1])}${hex(sps[2])}${hex(sps[3])}`;
-}
-/** `parts` joined into one new buffer (a single part is copied too, so the result never aliases the input). */
-export function concatBytes(parts) {
-    let n = 0;
-    for (const p of parts)
-        n += p.length;
-    const out = new Uint8Array(n);
-    let o = 0;
-    for (const p of parts) {
-        out.set(p, o);
-        o += p.length;
-    }
-    return out;
-}
-/**
- * Splits a continuous Annex-B byte stream (a file, an encoder pipe) into access units. Rule
- * (dylithium's reader loop): an AU ends with its coded slice; the next NAL of any kind starts a
- * new AU, so non-VCL NALs (SPS, PPS, SEI, AUD) are attached to the picture that follows them.
- * Sufficient for one-slice-per-picture streams (x264 `slices=1`, nvenc, WebCodecs), which is what
- * the encoder options enforce.
- */
-export class AuSplitter {
-    #pending = new Uint8Array(0);
-    #au = [];
-    #auHasVcl = false;
-    /** Feeds bytes; returns every access unit completed by them (in order). */
-    push(bytes) {
-        this.#pending = this.#pending.length ? concatBytes([this.#pending, bytes]) : bytes.slice();
-        const out = [];
-        const p = this.#pending;
-        let pos = 0;
-        for (;;) {
-            const sc0 = findStartCode(p, pos);
-            if (!sc0)
-                break; // no start code yet (maybe a partial one): keep the bytes
-            const [s0, l0] = sc0;
-            // The NAL is complete only once the next start code is visible.
-            const sc1 = findStartCode(p, s0 + l0);
-            if (!sc1) {
-                pos = s0;
-                break;
-            }
-            const isVcl = s0 + l0 < p.length && isVclType(p[s0 + l0] & 0x1f);
-            if (this.#auHasVcl)
-                out.push(this.#take()); // the previous AU already has its slice: this NAL belongs to the next one
-            this.#au.push(p.slice(s0, sc1[0]));
-            if (isVcl)
-                this.#auHasVcl = true;
-            pos = sc1[0];
-        }
-        this.#pending = pos > 0 ? p.slice(pos) : p;
-        return out;
-    }
-    /** End of stream: the last NAL (whose end no start code marks) closes the last AU, or starts one more if the current AU already has its slice. */
-    finish() {
-        const out = [];
-        const sc0 = findStartCode(this.#pending, 0);
-        if (sc0) {
-            if (this.#auHasVcl)
-                out.push(this.#take());
-            this.#au.push(this.#pending.slice(sc0[0]));
-        }
-        if (this.#au.length)
-            out.push(this.#take());
-        this.#pending = new Uint8Array(0);
-        return out;
-    }
-    #take() {
-        const au = this.#au.length === 1 ? this.#au[0] : concatBytes(this.#au);
-        this.#au = [];
-        this.#auHasVcl = false;
-        return au;
-    }
-}
-/** Splits a whole Annex-B buffer into access units (see {@link AuSplitter}). */
-export function splitAccessUnits(stream) {
-    const sp = new AuSplitter();
-    const out = sp.push(stream);
-    out.push(...sp.finish());
-    return out;
-}
-/**
- * A `MediaFrame` for an H.264 Annex-B access unit with `key`/`config`/`recovery` derived from the
- * NAL units (IDR present / SPS+PPS present / recovery-point SEI present), so the header flags
- * always agree with the bytes (R27 §2 publisher rule). `tUs` is the capture time (0 = stamp at publish).
- */
-export function mediaFrameFromAnnexb(au, tUs = 0) {
-    const { idr, recovery } = auSyncPoints(au);
-    return { data: au, tUs, key: idr, config: auParamSets(au) !== undefined, recovery };
-}