@driftengine/media 3.61.0

package/dist/clipSupport.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What this browser will encode, asked before anything is built.
+ *
+ * One responsibility: turn a frame size into the codec strings an encode is negotiated with, and
+ * answer whether this browser accepts them. `ClipEncoder.open` configures from the same ladder,
+ * so a caller greying out a control and a caller pressing Export are asking one question rather
+ * than two copies of it.
+ *
+ * **That was not the arrangement, and the gap shipped.** Both rungs used to be level 4.0 written
+ * into the string by hand, and a level is a promise about frame *size*: 4.0 holds 8192
+ * macroblocks, which is 1920x1080 with 32 to spare and nothing above it. So `isConfigSupported`
+ * refused 2560x1440, 2160x2160 and 3840x2160 outright, `VideoEncoder.configure` was never reached
+ * at those sizes, and a 4K export ended in "this browser cannot encode video at that size" on a
+ * card that encodes 4K. A second consumer found it by copying the two strings into its own
+ * repository to grey out a panel with, which is the shape of a decision that has no home.
+ */
+/**
+ * Whether this browser can render a clip offline rather than record one.
+ *
+ * Both halves are needed: frames without a score is a silent clip and a score without
+ * frames is nothing. A browser missing either falls back to the recorder.
+ *
+ * Says nothing about a *size*, deliberately: it is about the API being present at all, and it
+ * answers the same for a 64x64 frame and a 4K one. `clipEncodingSupported` is the size question.
+ */
+export declare function offlineEncodingSupported(): boolean;
+/**
+ * The four numbers an encode is negotiated with, before there is anything to encode.
+ *
+ * `ClipEncoderOptions` extends it, so the question a gate asks is the options the export opens
+ * with rather than a paraphrase of them.
+ */
+export interface ClipEncodeRequest {
+    readonly width: number;
+    readonly height: number;
+    readonly fps: number;
+    /** Bits per second for video. See `clipBitrate` for a figure worth passing. */
+    readonly bitrate: number;
+}
+/**
+ * The codec strings to try for a frame this size, best first.
+ *
+ * High profile first, constrained baseline as the fallback, both at the smallest level that can
+ * represent the frame. High is what every phone decodes in hardware and what a transcoder
+ * prefers; baseline exists because a machine without hardware AVC will refuse the first and
+ * encode the second in software rather than refuse to export. **Both rungs move together**: a
+ * baseline rung pinned to 4.0 is no fallback at 4K, it is a second refusal.
+ *
+ * Empty when no level can hold the frame, which is a frame past 139,264 macroblocks. The caller
+ * turns that into the same refusal it gives when the browser says no, one round trip earlier.
+ *
+ * Not on the barrel on purpose. The ladder is the engine's decision, and a consumer that can read
+ * it is a consumer that can pin a codec string in its own repository, which is how one decision
+ * became two copies the last time.
+ */
+export declare function clipCodecs(width: number, height: number): readonly string[];
+/**
+ * Whether this browser will encode a clip of this size, at this rate, at this bitrate.
+ *
+ * The question `ClipEncoder.open` is about to ask, asked early enough to grey out a control
+ * instead of failing an export somebody already chose. It walks the same ladder `open` walks, so
+ * the two cannot drift; a gate built from a copied codec string offered ten sizes the export
+ * would refuse, which is the fault this exists to make unrepeatable.
+ *
+ * Memoised on the whole request, because the answer is a property of the machine rather than of
+ * the moment: a panel asking about nine sizes at two rates costs eighteen probes at boot and
+ * nothing afterwards. The promise is stored rather than the result, so eighteen concurrent asks
+ * about one size are one probe.
+ *
+ * False when WebCodecs is absent, which is the same answer from the caller's point of view. What
+ * it does **not** answer: whether the frames arrive once encoding starts. See `framesReachEncoder`.
+ */
+export declare function clipEncodingSupported(request: ClipEncodeRequest): Promise<boolean>;

package/dist/clipSupport.js

@@ -0,0 +1,139 @@
+/**
+ * What this browser will encode, asked before anything is built.
+ *
+ * One responsibility: turn a frame size into the codec strings an encode is negotiated with, and
+ * answer whether this browser accepts them. `ClipEncoder.open` configures from the same ladder,
+ * so a caller greying out a control and a caller pressing Export are asking one question rather
+ * than two copies of it.
+ *
+ * **That was not the arrangement, and the gap shipped.** Both rungs used to be level 4.0 written
+ * into the string by hand, and a level is a promise about frame *size*: 4.0 holds 8192
+ * macroblocks, which is 1920x1080 with 32 to spare and nothing above it. So `isConfigSupported`
+ * refused 2560x1440, 2160x2160 and 3840x2160 outright, `VideoEncoder.configure` was never reached
+ * at those sizes, and a 4K export ended in "this browser cannot encode video at that size" on a
+ * card that encodes 4K. A second consumer found it by copying the two strings into its own
+ * repository to grey out a panel with, which is the shape of a decision that has no home.
+ */
+/**
+ * Whether this browser can render a clip offline rather than record one.
+ *
+ * Both halves are needed: frames without a score is a silent clip and a score without
+ * frames is nothing. A browser missing either falls back to the recorder.
+ *
+ * Says nothing about a *size*, deliberately: it is about the API being present at all, and it
+ * answers the same for a 64x64 frame and a 4K one. `clipEncodingSupported` is the size question.
+ */
+export function offlineEncodingSupported() {
+    return (typeof VideoEncoder === 'function' &&
+        typeof AudioEncoder === 'function' &&
+        typeof VideoFrame === 'function' &&
+        typeof AudioData === 'function' &&
+        typeof OfflineAudioContext === 'function');
+}
+/**
+ * H.264 levels, smallest first, with the largest frame each can represent.
+ *
+ * `maxMacroblocks` is the spec's MaxFS, and on Chrome 149 it is exactly what
+ * `isConfigSupported` enforces: measured over 9 sizes, 2 rates and 7 levels on an RX 9070 XT,
+ * every level at or above the one whose MaxFS holds the frame answered yes and every level below
+ * it answered no, in all 252 cells. Profile never moved an answer and neither did frame rate.
+ *
+ * **The rate bound is deliberately not part of the choice**, and that is the compromise here.
+ * The spec's MaxMBPS says 1920x1080 at 60 needs level 4.2 and at 120 needs 5.1; this asks 4.0 for
+ * both. It is defensible because the level in a codec string is a floor for the negotiation
+ * rather than a description of the file: asked for 4.0 at 1920x1080, Chrome wrote **level 4.2**
+ * into the file, and asked for 5.1 at 3840x2160 it wrote 5.2. What would make it wrong is a
+ * browser that honours the floor literally and encodes a stream its own level cannot carry, which
+ * nothing here has met. The rungs are worth having anyway for the size wall, which is real.
+ *
+ * Levels that hold no more than the one below are left out rather than listed: 4.1 has 4.0's
+ * 8192, 5.2 has 5.1's 36864, 6.1 and 6.2 have 6.0's 139264. Asking for one of them buys a bigger
+ * number in the string and no frame. Measured, at 3840x2160: a 5.1 request and a 5.2 request
+ * produced the same byte count and the same level in the file.
+ *
+ * The table starts at 4.0 rather than at 1.0 because nothing below it changes an answer. A 720p
+ * fallback frame is 3600 macroblocks and level 4.0 carries it, the encoder writes its own level
+ * regardless, and lowering the floor would only put a smaller number in front of a browser that
+ * has never been measured caring.
+ */
+const AVC_LEVELS = [
+    { id: 0x28, maxMacroblocks: 8192 }, // 4.0
+    { id: 0x2a, maxMacroblocks: 8704 }, // 4.2
+    { id: 0x32, maxMacroblocks: 22_080 }, // 5.0
+    { id: 0x33, maxMacroblocks: 36_864 }, // 5.1
+    { id: 0x3c, maxMacroblocks: 139_264 }, // 6.0
+];
+/**
+ * The codec strings to try for a frame this size, best first.
+ *
+ * High profile first, constrained baseline as the fallback, both at the smallest level that can
+ * represent the frame. High is what every phone decodes in hardware and what a transcoder
+ * prefers; baseline exists because a machine without hardware AVC will refuse the first and
+ * encode the second in software rather than refuse to export. **Both rungs move together**: a
+ * baseline rung pinned to 4.0 is no fallback at 4K, it is a second refusal.
+ *
+ * Empty when no level can hold the frame, which is a frame past 139,264 macroblocks. The caller
+ * turns that into the same refusal it gives when the browser says no, one round trip earlier.
+ *
+ * Not on the barrel on purpose. The ladder is the engine's decision, and a consumer that can read
+ * it is a consumer that can pin a codec string in its own repository, which is how one decision
+ * became two copies the last time.
+ */
+export function clipCodecs(width, height) {
+    /* Whole macroblocks: 1080 is 67.5 columns of 16 and costs 68 of them. */
+    const macroblocks = Math.ceil(width / 16) * Math.ceil(height / 16);
+    const level = AVC_LEVELS.find((rung) => macroblocks <= rung.maxMacroblocks);
+    if (level === undefined)
+        return [];
+    const hex = level.id.toString(16).toUpperCase().padStart(2, '0');
+    return [`avc1.6400${hex}`, `avc1.42E0${hex}`];
+}
+/** One answer per distinct request, kept for the session. See `clipEncodingSupported`. */
+const answers = new Map();
+/**
+ * Whether this browser will encode a clip of this size, at this rate, at this bitrate.
+ *
+ * The question `ClipEncoder.open` is about to ask, asked early enough to grey out a control
+ * instead of failing an export somebody already chose. It walks the same ladder `open` walks, so
+ * the two cannot drift; a gate built from a copied codec string offered ten sizes the export
+ * would refuse, which is the fault this exists to make unrepeatable.
+ *
+ * Memoised on the whole request, because the answer is a property of the machine rather than of
+ * the moment: a panel asking about nine sizes at two rates costs eighteen probes at boot and
+ * nothing afterwards. The promise is stored rather than the result, so eighteen concurrent asks
+ * about one size are one probe.
+ *
+ * False when WebCodecs is absent, which is the same answer from the caller's point of view. What
+ * it does **not** answer: whether the frames arrive once encoding starts. See `framesReachEncoder`.
+ */
+export async function clipEncodingSupported(request) {
+    const { width, height, fps, bitrate } = request;
+    const key = `${width}x${height}@${fps}/${bitrate}`;
+    const known = answers.get(key);
+    if (known !== undefined)
+        return known;
+    const asking = ask(request);
+    answers.set(key, asking);
+    return asking;
+}
+async function ask({ width, height, fps, bitrate }) {
+    if (typeof VideoEncoder !== 'function')
+        return false;
+    for (const codec of clipCodecs(width, height)) {
+        try {
+            const support = await VideoEncoder.isConfigSupported({
+                codec,
+                width,
+                height,
+                bitrate,
+                framerate: fps,
+            });
+            if (support.supported === true)
+                return true;
+        }
+        catch {
+            // A codec string this build will not parse is one it cannot encode. Try the next rung.
+        }
+    }
+    return false;
+}

package/dist/frameDelivery.d.ts

@@ -0,0 +1,24 @@
+/** What the probe found. `unknown` is the answer that changes nothing. */
+export type FrameDelivery = 'carries' | 'empty' | 'unknown';
+/**
+ * What a decoded probe colour means.
+ *
+ * **Only a positive reading of an empty frame refuses anything.** A probe that could not run, a
+ * decoder that returned nothing, a colour this does not recognise: all `unknown`, and a caller
+ * lets the export through on all of them. The two mistakes are not equal. A false negative costs
+ * somebody a file they can already see is wrong; a false positive costs them every clip they were
+ * going to make, on a machine where nothing was ever broken.
+ */
+export declare function deliveryVerdict(decoded: readonly [number, number, number] | null): FrameDelivery;
+/**
+ * Paint a known colour, encode it, decode it back, and report what came out.
+ *
+ * Memoised for the session: the fault is a property of how the browser was started, so a second
+ * answer cannot differ from the first, and an export path that asks before every attempt should
+ * pay for one encode rather than one per press.
+ *
+ * Every failure path answers `unknown` rather than throwing, including the timeout. This runs in
+ * front of an export, and a capability probe that can itself stop one has become a liability
+ * rather than a check.
+ */
+export declare function framesReachEncoder(): Promise<FrameDelivery>;

package/dist/frameDelivery.js

@@ -0,0 +1,186 @@
+/**
+ * Whether the pictures this browser encodes are the pictures it was given.
+ *
+ * Every other capability call asks whether the browser *says* it can do something. This one asks
+ * whether it did, and it is the only one that has caught a file going out wrong.
+ *
+ * **The fault it exists for.** Chrome 149 with `chrome://flags#enable-vulkan` on, under Wayland,
+ * composites through Vulkan while ANGLE stays on GL, and in that arrangement a `VideoFrame` built
+ * from a canvas reaches the encoder empty. Nothing reports it: `VideoEncoder.error` never fires,
+ * `encodeQueueSize` drains, `flush` resolves, the muxer finalises, and the app hands somebody a
+ * clip that is solid green from end to end with its audio intact. Four went out that way from a
+ * consuming app on 2026-08-14 before anybody opened one.
+ *
+ * Reproduced here from this repository's own harness, on an RX 9070 XT on RADV, with the flags as
+ * the only variable: twelve frames of 1920x1080 encoded to 114,157 bytes with them off and 8,747
+ * bytes with them on, and `ffprobe` read every frame of the second file back as YAVG 0, UAVG 0,
+ * VAVG 0. All-zero YUV is green rather than black once a decoder applies the limited range.
+ * `--headless=new` does not reproduce it at all, with or without Vulkan, which is consistent with
+ * it taking the compositor and the ozone platform together.
+ *
+ * **So the check is a round trip rather than an inspection**, and three things that look like
+ * witnesses are not: `getImageData` on the same canvas returns the right pixels in every run,
+ * `VideoFrame.copyTo` reported full buffers for a case that went on to encode green, and every
+ * capability call answers yes. What would make this module wrong is a browser that fails delivery
+ * for some frames and not others, in which case one probe at the start is not enough; the fault
+ * measured here is a property of the browser's configuration and does not vary frame to frame.
+ */
+import { clipCodecs } from './clipSupport.js';
+/** Side of the probe frame. The smallest thing worth asking; it encodes to 39 bytes. */
+const PROBE_SIZE = 64;
+/**
+ * The colour the probe paints: full red and full blue, no green.
+ *
+ * Chosen to be the opposite of the failure. An all-zero frame decodes to green with no red and no
+ * blue in either colour space a browser might tag it with, BT.709 putting it at `0,77,0` and
+ * BT.601 at `0,135,0`, so a picture that survived and a picture that did not cannot be confused
+ * by a decoder's choice of matrix. A grey probe would have to tell them apart by brightness,
+ * which is a threshold somebody has to guess at.
+ */
+const PROBE_COLOR = 'rgb(255 0 255)';
+/** How long the round trip gets before it is abandoned. Far longer than it has ever taken. */
+const PROBE_TIMEOUT_MS = 2000;
+/**
+ * What a decoded probe colour means.
+ *
+ * **Only a positive reading of an empty frame refuses anything.** A probe that could not run, a
+ * decoder that returned nothing, a colour this does not recognise: all `unknown`, and a caller
+ * lets the export through on all of them. The two mistakes are not equal. A false negative costs
+ * somebody a file they can already see is wrong; a false positive costs them every clip they were
+ * going to make, on a machine where nothing was ever broken.
+ */
+export function deliveryVerdict(decoded) {
+    if (decoded === null)
+        return 'unknown';
+    const [red, , blue] = decoded;
+    /* Both channels the probe painted came back. Generous, because the round trip goes through a
+       4:2:0 chroma subsample and a colour space conversion and neither is lossless. */
+    if (red > 128 && blue > 128)
+        return 'carries';
+    /* Neither did, which no encode of this colour can produce. */
+    if (red < 32 && blue < 32)
+        return 'empty';
+    return 'unknown';
+}
+/** One answer per session. See `framesReachEncoder`. */
+let asked = null;
+/**
+ * Paint a known colour, encode it, decode it back, and report what came out.
+ *
+ * Memoised for the session: the fault is a property of how the browser was started, so a second
+ * answer cannot differ from the first, and an export path that asks before every attempt should
+ * pay for one encode rather than one per press.
+ *
+ * Every failure path answers `unknown` rather than throwing, including the timeout. This runs in
+ * front of an export, and a capability probe that can itself stop one has become a liability
+ * rather than a check.
+ */
+export function framesReachEncoder() {
+    asked ??= run();
+    return asked;
+}
+async function run() {
+    if (typeof document === 'undefined' ||
+        typeof VideoEncoder !== 'function' ||
+        typeof VideoDecoder !== 'function' ||
+        typeof VideoFrame !== 'function') {
+        return 'unknown';
+    }
+    try {
+        return await Promise.race([
+            roundTrip(),
+            new Promise((resolve) => {
+                setTimeout(() => resolve('unknown'), PROBE_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    catch {
+        return 'unknown';
+    }
+}
+async function roundTrip() {
+    const codec = clipCodecs(PROBE_SIZE, PROBE_SIZE)[0];
+    if (codec === undefined)
+        return 'unknown';
+    const canvas = document.createElement('canvas');
+    canvas.width = PROBE_SIZE;
+    canvas.height = PROBE_SIZE;
+    const ctx = canvas.getContext('2d', { alpha: false });
+    if (ctx === null)
+        return 'unknown';
+    ctx.fillStyle = PROBE_COLOR;
+    ctx.fillRect(0, 0, PROBE_SIZE, PROBE_SIZE);
+    const chunks = [];
+    /* The type the decoder's own config field takes, which is wider than `BufferSource`: it
+       accommodates a `SharedArrayBuffer`, and narrowing it here would only be a cast back. */
+    let description;
+    let failed = false;
+    const config = {
+        codec,
+        width: PROBE_SIZE,
+        height: PROBE_SIZE,
+        bitrate: 1_000_000,
+        framerate: 30,
+    };
+    const support = await VideoEncoder.isConfigSupported(config);
+    if (support.supported !== true)
+        return 'unknown';
+    const encoder = new VideoEncoder({
+        output: (chunk, meta) => {
+            if (description === undefined && meta?.decoderConfig?.description !== undefined) {
+                description = meta.decoderConfig.description;
+            }
+            chunks.push(chunk);
+        },
+        error: () => {
+            failed = true;
+        },
+    });
+    encoder.configure(config);
+    const frame = new VideoFrame(canvas, { timestamp: 0, duration: 33_333 });
+    try {
+        encoder.encode(frame, { keyFrame: true });
+    }
+    finally {
+        frame.close();
+    }
+    await encoder.flush();
+    encoder.close();
+    if (failed || chunks.length === 0)
+        return 'unknown';
+    let decoded = null;
+    const decoder = new VideoDecoder({
+        output: (picture) => {
+            try {
+                const read = document.createElement('canvas');
+                read.width = PROBE_SIZE;
+                read.height = PROBE_SIZE;
+                const readCtx = read.getContext('2d', { alpha: false });
+                if (readCtx !== null) {
+                    readCtx.drawImage(picture, 0, 0);
+                    const px = readCtx.getImageData(PROBE_SIZE / 2, PROBE_SIZE / 2, 1, 1).data;
+                    decoded = [px[0] ?? 0, px[1] ?? 0, px[2] ?? 0];
+                }
+            }
+            finally {
+                picture.close();
+            }
+        },
+        error: () => {
+            failed = true;
+        },
+    });
+    decoder.configure({
+        codec,
+        codedWidth: PROBE_SIZE,
+        codedHeight: PROBE_SIZE,
+        ...(description === undefined ? {} : { description }),
+    });
+    for (const chunk of chunks)
+        decoder.decode(chunk);
+    await decoder.flush();
+    decoder.close();
+    if (failed)
+        return 'unknown';
+    return deliveryVerdict(decoded);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Recording what the engine draws: encoding a clip, and delivering frames to it.
+ *
+ * The muxer dependency lives here rather than in core, which is the point — a game that
+ * records nothing installs no muxer.
+ */
+export { ClipEncoder, frameTimestampUs } from './clipEncoder.ts';
+export type { ClipAudioCodec, ClipEncoderOptions } from './clipEncoder.ts';
+export { clipEncodingSupported, offlineEncodingSupported } from './clipSupport.ts';
+export type { ClipEncodeRequest } from './clipSupport.ts';
+export { framesReachEncoder } from './frameDelivery.ts';
+export type { FrameDelivery } from './frameDelivery.ts';

package/dist/index.js

@@ -0,0 +1,10 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Recording what the engine draws: encoding a clip, and delivering frames to it.
+ *
+ * The muxer dependency lives here rather than in core, which is the point — a game that
+ * records nothing installs no muxer.
+ */
+export { ClipEncoder, frameTimestampUs } from './clipEncoder.js';
+export { clipEncodingSupported, offlineEncodingSupported } from './clipSupport.js';
+export { framesReachEncoder } from './frameDelivery.js';

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@driftengine/media",
+  "version": "3.61.0",
+  "description": "Clip encoding and frame delivery for recording what the engine draws",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "mp4-muxer": "5.2.2"
+  },
+  "peerDependencies": {
+    "@driftengine/core": "3.61.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/media"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "video",
+    "recording",
+    "mp4",
+    "encoding"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}