@grundyjs/canvas-take 0.4.1 → 0.5.0

package/dist/video.js

@@ -0,0 +1,503 @@
+function deferred() {
+    let resolve, reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    void promise.catch(() => { });
+    return { promise, resolve, reject };
+}
+function integer(value, name, minimum = 0) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new RangeError(`${name} must be a safe integer >= ${minimum}`);
+    return value;
+}
+function text(value, name) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(`${name} must be a nonempty string`);
+    return value;
+}
+function rounded(value, multiplier, divisor) {
+    const n = (BigInt(value) * BigInt(multiplier) * 2n + BigInt(divisor)) / (BigInt(divisor) * 2n);
+    return integer(Number(n), 'sample/timestamp arithmetic');
+}
+function snapshot(options) {
+    const limits = {
+        maxFramePixels: options.maxFramePixels, maxFrames: options.maxFrames, maxDurationUs: options.maxDurationUs,
+        maxAudioInputBytes: options.maxAudioInputBytes, maxOutputBytes: options.maxOutputBytes,
+        maxPendingInputs: options.maxPendingInputs === undefined ? 4 : options.maxPendingInputs,
+        maxPendingBytes: options.maxPendingBytes === undefined ? 16 * 1024 * 1024 : options.maxPendingBytes
+    };
+    for (const [name, value] of Object.entries(limits))
+        if (value !== undefined)
+            integer(value, name, 1);
+    if (options.totalFrames !== undefined)
+        integer(options.totalFrames, 'totalFrames', 1);
+    const v = options.video.config;
+    const videoConfig = Object.freeze({ codec: text(v.codec, 'video.codec'), bitstreamFormat: text(v.bitstreamFormat, 'video.bitstreamFormat'),
+        width: integer(v.width, 'width', 1), height: integer(v.height, 'height', 1), bitrate: integer(v.bitrate, 'video.bitrate', 1),
+        ...(v.frameRateHint === undefined ? {} : { frameRateHint: Object.freeze({ numerator: integer(v.frameRateHint.numerator, 'frameRateHint.numerator', 1), denominator: integer(v.frameRateHint.denominator, 'frameRateHint.denominator', 1) }) }) });
+    integer(v.width * v.height * 4, 'frame byte size', 1);
+    const background = [...(options.background ?? [255, 255, 255])];
+    if (background.length !== 3 || background.some(n => !Number.isInteger(n) || n < 0 || n > 255))
+        throw new RangeError('background must contain three RGB bytes');
+    const format = Object.freeze({ mimeType: text(options.muxer.format.mimeType, 'mimeType').trim().toLowerCase(), extension: text(options.muxer.format.extension, 'extension') });
+    if (!format.mimeType.startsWith('video/'))
+        throw new TypeError('muxer MIME must be video/*');
+    let audioConfig, planes = [], sourceLength = 0;
+    const a = options.audio;
+    if (a) {
+        if (a.endPolicy !== 'error' && a.endPolicy !== 'trim-or-pad')
+            throw new TypeError('audio.endPolicy must be error or trim-or-pad');
+        audioConfig = Object.freeze({ codec: text(a.config.codec, 'audio.codec'), bitstreamFormat: text(a.config.bitstreamFormat, 'audio.bitstreamFormat'),
+            sampleRate: integer(a.config.sampleRate, 'sampleRate', 1), numberOfChannels: integer(a.config.numberOfChannels, 'numberOfChannels', 1), bitrate: integer(a.config.bitrate, 'audio.bitrate', 1) });
+        if (a.source.sampleRate !== audioConfig.sampleRate || a.source.channels.length !== audioConfig.numberOfChannels)
+            throw new RangeError('PCM configuration mismatch');
+        sourceLength = integer(a.source.channels[0]?.length, 'PCM sample count', 1);
+        const bytes = integer(sourceLength * audioConfig.numberOfChannels * 4, 'PCM byte size', 1);
+        if (limits.maxAudioInputBytes !== undefined && bytes > limits.maxAudioInputBytes)
+            throw new RangeError('maxAudioInputBytes exceeded');
+        for (const plane of a.source.channels) {
+            if (!(plane instanceof Float32Array) || !(plane.buffer instanceof ArrayBuffer) || plane.length !== sourceLength)
+                throw new TypeError('PCM channels must be equal-length nonshared Float32Arrays');
+            if (plane.some(sample => !Number.isFinite(sample) || sample < -1 || sample > 1))
+                throw new RangeError('PCM samples must be finite in [-1, 1]');
+        }
+        if (audioConfig.numberOfChannels * 4 > limits.maxPendingBytes)
+            throw new RangeError('maxPendingBytes cannot hold one audio sample');
+        planes = a.source.channels.map(plane => plane.slice());
+    }
+    return { limits: Object.freeze(limits), videoConfig, audioConfig, planes, sourceLength, background,
+        videoFactory: options.video.encoder, audioFactory: a?.encoder, audioPolicy: a?.endPolicy,
+        muxerFactory: options.muxer, format, signal: options.signal, onProgress: options.onProgress, totalFrames: options.totalFrames };
+}
+/** Offline timeline controller. Encoders and container implementation are always supplied. */
+export async function createOfflineVideoExporter(options) {
+    if (options.signal?.aborted)
+        throw options.signal.reason ?? new DOMException('Export aborted', 'AbortError');
+    const cfg = snapshot(options); // Includes the PCM copy, before the first await.
+    const controller = new AbortController(), cancelled = deferred();
+    let state = 'initializing', failure;
+    let muxer, video, audio;
+    const owned = new Set(), disposed = new WeakSet();
+    let frames = 0, submittedFrames = 0, duration = 0, samples = 0, videoPackets = 0, audioPackets = 0, encodedBytes = 0;
+    let videoSeen = 0, videoOutputEnd = 0, audioOutputStart, audioOutputEnd;
+    let queuedBytes = 0, draining = false, inFlight;
+    let finishPromise;
+    const expectedVideo = new Map();
+    const queue = [], idle = new Set();
+    const tracks = { video: { config: undefined, ended: false, flushing: false },
+        audio: { config: undefined, ended: false, flushing: false } };
+    const terminal = () => ['finished', 'failed', 'aborted', 'disposed'].includes(state);
+    const guard = () => { if (terminal())
+        throw failure ?? new Error(`Offline video exporter is ${state}`); };
+    const wait = async (promise) => { const value = await Promise.race([Promise.resolve(promise), cancelled.promise]); guard(); return value; };
+    function report(phase, outputBytes) {
+        try {
+            cfg.onProgress?.(Object.freeze({ phase, framesAccepted: frames, durationUs: duration, audioSamplesAccepted: samples,
+                videoPacketsWritten: videoPackets, audioPacketsWritten: audioPackets, encodedBytes,
+                ...(cfg.totalFrames === undefined ? {} : { totalFrames: cfg.totalFrames }), ...(outputBytes === undefined ? {} : { outputBytes }) }));
+        }
+        catch { }
+    }
+    function release(instance) {
+        if (disposed.has(instance))
+            return;
+        disposed.add(instance);
+        try {
+            instance.dispose();
+        }
+        catch { }
+    }
+    function cleanup() {
+        cfg.signal?.removeEventListener('abort', onAbort);
+        for (const instance of owned)
+            release(instance);
+        owned.clear();
+        cfg.planes.length = 0;
+        expectedVideo.clear();
+        tracks.video.config = tracks.audio.config = undefined;
+        muxer = undefined;
+        video = undefined;
+        audio = undefined;
+    }
+    function end(next, error) {
+        if (terminal())
+            return;
+        state = next;
+        failure = error;
+        cancelled.reject(error);
+        controller.abort(error);
+        inFlight?.done.reject(error);
+        for (const item of queue.splice(0))
+            item.done.reject(error);
+        for (const pending of idle)
+            pending.reject(error);
+        idle.clear();
+        queuedBytes = 0;
+        cleanup();
+        report(next);
+    }
+    function onAbort() { end('aborted', cfg.signal?.reason ?? new DOMException('Export aborted', 'AbortError')); }
+    const protocol = (message) => new Error(`Offline video protocol: ${message}`);
+    function wrap(component, error) { return new Error(`${component} failed`, { cause: error }); }
+    async function invoke(component, work) {
+        try {
+            guard();
+            return await wait(work());
+        }
+        catch (error) {
+            if (terminal())
+                throw failure ?? error;
+            throw wrap(component, error);
+        }
+    }
+    async function acquire(component, methods, create) {
+        guard();
+        return invoke(component, () => Promise.resolve().then(() => { guard(); return create(); }).then(instance => {
+            if (terminal()) {
+                release(instance);
+                return instance;
+            }
+            if (!instance || typeof instance.dispose !== 'function' || owned.has(instance) || disposed.has(instance))
+                throw protocol('factory must return a fresh disposable instance');
+            owned.add(instance);
+            if (methods.some(name => typeof instance[name] !== 'function'))
+                throw protocol(`${component} returned missing methods`);
+            return instance;
+        }));
+    }
+    function sameConfig(a, b) {
+        const { description: ad, ...ar } = a, { description: bd, ...br } = b;
+        return JSON.stringify(ar) === JSON.stringify(br) && (ad === undefined ? bd === undefined : bd !== undefined && ad.length === bd.length && ad.every((n, i) => n === bd[i]));
+    }
+    function cloneEvent(track, event) {
+        const t = tracks[track];
+        const actualTrack = event.type === 'packet' ? event.packet.track : event.track;
+        if (track !== actualTrack || t.ended)
+            throw protocol('wrong track or output after end');
+        if (event.type === 'config') {
+            const c = event.config, expected = track === 'video' ? cfg.videoConfig : cfg.audioConfig;
+            if (c.codec !== expected.codec || c.bitstreamFormat !== expected.bitstreamFormat)
+                throw protocol('codec/framing mismatch');
+            let copy;
+            if (track === 'video') {
+                const v = c;
+                if (v.width !== cfg.videoConfig.width || v.height !== cfg.videoConfig.height || !v.color ||
+                    [v.color.primaries, v.color.transfer, v.color.matrix].some(value => typeof value !== 'string' || !value) || typeof v.color.fullRange !== 'boolean')
+                    throw protocol('video description mismatch');
+                copy = { type: 'config', track: 'video', config: { codec: c.codec, bitstreamFormat: c.bitstreamFormat,
+                        width: v.width, height: v.height, color: Object.freeze({ primaries: v.color.primaries, transfer: v.color.transfer, matrix: v.color.matrix, fullRange: v.color.fullRange }), ...(c.description === undefined ? {} : { description: c.description.slice() }) } };
+            }
+            else {
+                const a = c;
+                if (a.sampleRate !== cfg.audioConfig.sampleRate || a.numberOfChannels !== cfg.audioConfig.numberOfChannels)
+                    throw protocol('audio description mismatch');
+                copy = { type: 'config', track: 'audio', config: { codec: c.codec, bitstreamFormat: c.bitstreamFormat,
+                        sampleRate: a.sampleRate, numberOfChannels: a.numberOfChannels, ...(c.description === undefined ? {} : { description: c.description.slice() }) } };
+            }
+            if (c.description !== undefined && (!(c.description instanceof Uint8Array) || !(c.description.buffer instanceof ArrayBuffer)))
+                throw protocol('invalid decoder description bytes');
+            if (t.config && !sameConfig(t.config, copy.config))
+                throw protocol('midstream configuration change');
+            t.config = copy.config;
+            return { event: copy, bytes: copy.config.description?.byteLength ?? 0 };
+        }
+        if (!t.config)
+            throw protocol('output before decoder config');
+        if (event.type === 'packet') {
+            const p = event.packet;
+            if (!Number.isSafeInteger(p.timestampUs) || !Number.isSafeInteger(p.decodeTimestampUs) || p.decodeTimestampUs !== p.timestampUs)
+                throw protocol('invalid/reordered timestamps');
+            integer(p.durationUs, 'packet durationUs', 1);
+            integer(p.timestampUs + p.durationUs, 'packet end', -Number.MAX_SAFE_INTEGER);
+            if (!(p.data instanceof Uint8Array) || !(p.data.buffer instanceof ArrayBuffer) || !p.data.byteLength || !['key', 'delta'].includes(p.type))
+                throw protocol('invalid packet');
+            if (track === 'video') {
+                if (p.timestampUs !== videoOutputEnd || expectedVideo.get(p.timestampUs) !== p.durationUs || (!videoSeen && p.type !== 'key'))
+                    throw protocol('missing, duplicated, reordered or non-key first video frame');
+                expectedVideo.delete(p.timestampUs);
+                videoOutputEnd += p.durationUs;
+                videoSeen++;
+            }
+            else {
+                if (audioOutputEnd !== undefined && p.timestampUs !== audioOutputEnd)
+                    throw protocol('noncontiguous audio packets');
+                audioOutputStart ??= p.timestampUs;
+                audioOutputEnd = p.timestampUs + p.durationUs;
+            }
+            return { event: { type: 'packet', packet: Object.freeze({ ...p, data: p.data.slice() }) }, bytes: p.data.byteLength };
+        }
+        if (event.type !== 'end' || !t.flushing)
+            throw protocol('track ended outside flush');
+        if (track === 'video') {
+            if (expectedVideo.size || videoSeen !== submittedFrames)
+                throw protocol('video frames missing at end');
+        }
+        else {
+            if (event.track !== 'audio')
+                throw protocol('invalid audio end');
+            integer(event.presentationSamples, 'presentationSamples');
+            integer(event.leadingDiscardSamples, 'leadingDiscardSamples');
+            integer(event.trailingDiscardSamples, 'trailingDiscardSamples');
+            if (event.presentationSamples !== samples)
+                throw protocol('audio presentation count mismatch');
+            const endSamples = integer(samples + event.trailingDiscardSamples, 'audio sample end');
+            integer(endSamples + event.leadingDiscardSamples, 'audio total samples');
+            const first = -rounded(event.leadingDiscardSamples, 1_000_000, cfg.audioConfig.sampleRate);
+            const last = rounded(endSamples, 1_000_000, cfg.audioConfig.sampleRate);
+            if (audioOutputStart === undefined || audioOutputEnd === undefined || Math.abs(audioOutputStart - first) > 1 || Math.abs(audioOutputEnd - last) > 1)
+                throw protocol('audio packets do not match declared trimming');
+        }
+        t.ended = true;
+        return { event: Object.freeze({ ...event }), bytes: 0 };
+    }
+    async function drain() {
+        if (draining)
+            return;
+        draining = true;
+        try {
+            while (queue.length && !terminal()) {
+                const item = inFlight = queue.shift();
+                try {
+                    await wait(muxer.write(item.event));
+                }
+                catch (error) {
+                    if (!terminal())
+                        end('failed', wrap('muxer.write', error));
+                    item.done.reject(failure);
+                    break;
+                }
+                queuedBytes -= item.cost;
+                if (item.event.type === 'packet') {
+                    if (item.event.packet.track === 'video')
+                        videoPackets++;
+                    else
+                        audioPackets++;
+                    encodedBytes += item.bytes;
+                }
+                item.done.resolve();
+                inFlight = undefined;
+                report(state === 'initializing' ? 'initializing' : state === 'finalizing' ? 'finalizing' : 'encoding');
+            }
+        }
+        finally {
+            draining = false;
+            inFlight = undefined;
+            if (!queue.length) {
+                for (const pending of idle)
+                    pending.resolve();
+                idle.clear();
+            }
+        }
+    }
+    function sink(track) {
+        return Object.freeze({
+            write(event) {
+                const done = deferred();
+                try {
+                    guard();
+                    const bytes = event.type === 'packet' ? event.packet.data.byteLength : event.type === 'config' ? event.config.description?.byteLength ?? 0 : 0;
+                    const cost = bytes + 64; // Reserve metadata space even for empty config/end events.
+                    if (cost > cfg.limits.maxPendingBytes - queuedBytes)
+                        throw new RangeError('maxPendingBytes exceeded');
+                    const item = cloneEvent(track, event);
+                    queuedBytes += cost;
+                    queue.push({ ...item, cost, done });
+                    void drain();
+                }
+                catch (error) {
+                    if (!terminal())
+                        end('failed', error);
+                    done.reject(failure ?? error);
+                }
+                return done.promise;
+            },
+            fail(error) { if (!terminal())
+                end('failed', wrap(`${track} encoder`, error)); }
+        });
+    }
+    async function queueIdle() {
+        if (!draining && !queue.length)
+            return;
+        const pending = deferred();
+        idle.add(pending);
+        await wait(pending.promise);
+    }
+    async function feedAudio(target) {
+        if (!audio || !cfg.audioConfig)
+            return;
+        const channels = cfg.audioConfig.numberOfChannels, rate = cfg.audioConfig.sampleRate;
+        const blockSize = Math.min(2048, Math.floor(cfg.limits.maxPendingBytes / (channels * 4)));
+        let blocks = 0;
+        while (samples < target) {
+            guard();
+            const size = Math.min(blockSize, target - samples), offset = samples;
+            const channelsData = cfg.planes.map(plane => {
+                const data = new Float32Array(size);
+                if (offset < cfg.sourceLength)
+                    data.set(plane.subarray(offset, Math.min(offset + size, cfg.sourceLength)));
+                return data;
+            });
+            await invoke('audio encoder.encodeAudio', () => audio.encodeAudio(Object.freeze({ sampleRate: rate, sampleOffset: offset, timestampUs: rounded(offset, 1_000_000, rate), channels: channelsData })));
+            samples += size;
+            if (++blocks % 8 === 0)
+                await wait(new Promise(resolve => setTimeout(resolve, 0)));
+        }
+    }
+    cfg.signal?.addEventListener('abort', onAbort, { once: true });
+    if (cfg.signal?.aborted)
+        onAbort();
+    try {
+        guard();
+        report('initializing');
+        guard();
+        const muxerConfig = Object.freeze({ video: cfg.videoConfig, ...(cfg.audioConfig ? { audio: cfg.audioConfig } : {}) });
+        for (const [name, check] of [
+            ['video', () => cfg.videoFactory.checkSupport(cfg.videoConfig)],
+            ...(cfg.audioConfig ? [['audio', () => cfg.audioFactory.checkSupport(cfg.audioConfig)]] : []),
+            ['muxer', () => cfg.muxerFactory.checkSupport(muxerConfig)]
+        ]) {
+            const support = await invoke(`${name}.checkSupport`, check);
+            if (!support || typeof support.supported !== 'boolean' || (!support.supported && typeof support.reason !== 'string'))
+                throw protocol(`${name} returned invalid support information`);
+            if (!support.supported)
+                throw new DOMException(`${name} unsupported: ${support.reason}`, 'NotSupportedError');
+        }
+        const context = Object.freeze({ signal: controller.signal, maxPendingInputs: cfg.limits.maxPendingInputs, maxPendingBytes: cfg.limits.maxPendingBytes });
+        muxer = await acquire('muxer.create', ['write', 'finalize'], () => cfg.muxerFactory.create(muxerConfig, Object.freeze({ ...context, ...(cfg.limits.maxOutputBytes === undefined ? {} : { maxOutputBytes: cfg.limits.maxOutputBytes }) })));
+        video = await acquire('video encoder.create', ['encodeFrame', 'flush'], () => cfg.videoFactory.create(cfg.videoConfig, Object.freeze({ ...context, output: sink('video') })));
+        if (cfg.audioConfig)
+            audio = await acquire('audio encoder.create', ['encodeAudio', 'flush'], () => cfg.audioFactory.create(cfg.audioConfig, Object.freeze({ ...context, output: sink('audio') })));
+        await queueIdle();
+        guard();
+        state = 'ready';
+    }
+    catch (error) {
+        if (!terminal())
+            end('failed', error);
+        throw failure ?? error;
+    }
+    return Object.freeze({
+        get state() { return state; },
+        addFrame(canvas, timing) {
+            if (state !== 'ready')
+                return Promise.reject(failure ?? new Error(`Cannot addFrame in ${state} state`));
+            state = 'encoding';
+            return (async () => {
+                try {
+                    const timestampUs = integer(timing.timestampUs, 'timestampUs'), frameDuration = integer(timing.durationUs, 'durationUs', 1);
+                    const endUs = integer(timestampUs + frameDuration, 'frame end');
+                    if (timestampUs !== duration)
+                        throw new RangeError('Frame timeline must start at zero and remain contiguous');
+                    if (timing.keyFrame !== undefined && typeof timing.keyFrame !== 'boolean')
+                        throw new TypeError('keyFrame must be boolean');
+                    const keyFrame = timing.keyFrame === true;
+                    if (canvas.width !== cfg.videoConfig.width || canvas.height !== cfg.videoConfig.height)
+                        throw new RangeError('Canvas dimensions must match video configuration');
+                    const pixels = cfg.videoConfig.width * cfg.videoConfig.height;
+                    if (cfg.limits.maxFramePixels !== undefined && pixels > cfg.limits.maxFramePixels)
+                        throw new RangeError('maxFramePixels exceeded');
+                    if (cfg.limits.maxFrames !== undefined && frames >= cfg.limits.maxFrames)
+                        throw new RangeError('maxFrames exceeded');
+                    if (cfg.limits.maxDurationUs !== undefined && endUs > cfg.limits.maxDurationUs)
+                        throw new RangeError('maxDurationUs exceeded');
+                    if (expectedVideo.size >= cfg.limits.maxPendingInputs)
+                        throw new RangeError('maxPendingInputs video look-ahead exceeded');
+                    if (pixels * 4 > cfg.limits.maxPendingBytes)
+                        throw new RangeError('maxPendingBytes cannot hold the frame snapshot');
+                    const audioTarget = cfg.audioConfig ? rounded(endUs, cfg.audioConfig.sampleRate, 1_000_000) : 0;
+                    if (cfg.audioPolicy === 'error' && audioTarget > cfg.sourceLength)
+                        throw new RangeError('Prepared audio is shorter than the video timeline');
+                    const ctx = canvas.getContext('2d');
+                    if (!ctx)
+                        throw new TypeError('Offline video requires a 2D canvas');
+                    const data = new Uint8ClampedArray(ctx.getImageData(0, 0, canvas.width, canvas.height, { colorSpace: 'srgb' }).data);
+                    if (data.length !== pixels * 4)
+                        throw new RangeError('Invalid frame pixel data');
+                    for (let i = 0; i < data.length; i += 4) {
+                        if (data[i + 3] === 255)
+                            continue;
+                        const alpha = data[i + 3] / 255;
+                        for (let c = 0; c < 3; c++)
+                            data[i + c] = Math.round(data[i + c] * alpha + cfg.background[c] * (1 - alpha));
+                        data[i + 3] = 255;
+                    }
+                    await wait(new Promise(resolve => setTimeout(resolve, 0)));
+                    expectedVideo.set(timestampUs, frameDuration);
+                    submittedFrames++;
+                    await invoke('video encoder.encodeFrame', () => video.encodeFrame(Object.freeze({ width: cfg.videoConfig.width, height: cfg.videoConfig.height, data,
+                        timestampUs, durationUs: frameDuration, keyFrame: frames === 0 || keyFrame })));
+                    await feedAudio(audioTarget);
+                    guard();
+                    frames++;
+                    duration = endUs;
+                    report('encoding');
+                    guard();
+                    state = 'ready';
+                }
+                catch (error) {
+                    if (!terminal())
+                        end('failed', error);
+                    throw failure ?? error;
+                }
+            })();
+        },
+        finish() {
+            if (state === 'finished' || state === 'finalizing')
+                return finishPromise;
+            if (state !== 'ready')
+                return Promise.reject(failure ?? new Error(`Cannot finish in ${state} state`));
+            state = 'finalizing';
+            const completion = deferred();
+            finishPromise = completion.promise;
+            void (async () => {
+                try {
+                    if (!frames)
+                        throw new RangeError('Offline video requires at least one frame');
+                    if (cfg.audioConfig && !samples)
+                        throw new RangeError('Audio presentation requires at least one sample');
+                    if (cfg.audioPolicy === 'error' && samples !== cfg.sourceLength)
+                        throw new RangeError('Prepared audio is longer than the video timeline');
+                    report('finalizing');
+                    guard();
+                    tracks.video.flushing = true;
+                    if (audio)
+                        tracks.audio.flushing = true;
+                    const encoders = [video, ...(audio ? [audio] : [])];
+                    await wait(Promise.all(encoders.map((encoder, i) => Promise.resolve().then(() => invoke(i === 0 ? 'video encoder.flush' : 'audio encoder.flush', () => encoder.flush())))));
+                    await queueIdle();
+                    guard();
+                    if (!tracks.video.ended || (cfg.audioConfig && !tracks.audio.ended))
+                        throw protocol('flush completed without track end');
+                    const timeline = Object.freeze({ durationUs: duration, videoFrames: frames, ...(cfg.audioConfig ? { audioPresentationSamples: samples } : {}) });
+                    const blob = await invoke('muxer.finalize', () => muxer.finalize(timeline));
+                    if (!(blob instanceof Blob) || !blob.size || blob.type !== cfg.format.mimeType)
+                        throw protocol('muxer returned an empty or mismatched container');
+                    if (cfg.limits.maxOutputBytes !== undefined && blob.size > cfg.limits.maxOutputBytes)
+                        throw new RangeError('maxOutputBytes exceeded');
+                    const result = Object.freeze({ ...timeline, blob, ...cfg.format, videoCodec: cfg.videoConfig.codec,
+                        ...(cfg.audioConfig ? { audioCodec: cfg.audioConfig.codec } : {}) });
+                    state = 'finished';
+                    cleanup();
+                    report('finished', blob.size);
+                    return result;
+                }
+                catch (error) {
+                    if (!terminal())
+                        end('failed', error);
+                    throw failure ?? error;
+                }
+            })().then(completion.resolve, completion.reject);
+            return finishPromise;
+        },
+        dispose() {
+            if (state === 'disposed')
+                return;
+            if (!terminal())
+                end('disposed', new DOMException('Offline video disposed', 'AbortError'));
+            else {
+                state = 'disposed';
+                controller.abort(new DOMException('Offline video disposed', 'AbortError'));
+                cleanup();
+            }
+        }
+    });
+}

package/docs/drafts/offline-video-api.d.ts

@@ -0,0 +1,2 @@
+/** Compatibility reference to the implemented controller's canonical declarations. */
+export * from '@grundyjs/canvas-take/video';

package/docs/drafts/offline-video-example.ts

@@ -0,0 +1,38 @@
+// Compile-only usage example; the caller supplies the canvas, renderer and prepared narration.
+import { createOfflineVideoExporter } from '@grundyjs/canvas-take/video';
+import type { PreparedAudio } from '@grundyjs/canvas-take/video';
+import { createWebCodecsVideoEncoder } from '@grundyjs/canvas-take/video/webcodecs';
+import { createAacAudioEncoder } from '@grundyjs/canvas-take/video/aac';
+import { createMp4Muxer } from '@grundyjs/canvas-take/video/mp4';
+
+const videoEncoder = createWebCodecsVideoEncoder();
+const audioEncoder = createAacAudioEncoder();
+const mp4Muxer = createMp4Muxer();
+declare const canvas: HTMLCanvasElement;
+declare const narration: PreparedAudio;
+declare function drawFrame(index: number): void;
+
+export async function exportShort(signal: AbortSignal) {
+    const exporter = await createOfflineVideoExporter({
+        video: { encoder: videoEncoder, config: {
+            codec: 'avc1.42E028', bitstreamFormat: 'avc', width: 1080, height: 1920,
+            bitrate: 8_000_000, frameRateHint: { numerator: 30, denominator: 1 }
+        } },
+        audio: { encoder: audioEncoder, config: {
+            codec: 'mp4a.40.2', bitstreamFormat: 'aac', sampleRate: narration.sampleRate,
+            numberOfChannels: narration.channels.length, bitrate: 192_000
+        }, source: narration, endPolicy: 'trim-or-pad' },
+        muxer: mp4Muxer, signal, totalFrames: 300,
+        maxFramePixels: 1080 * 1920, maxFrames: 300, maxDurationUs: 10_000_000,
+        onProgress(progress) { console.log(progress.phase, progress.framesAccepted, progress.durationUs); }
+    });
+    try {
+        // Absolute rounded boundaries prevent accumulated 1/30-second rounding error.
+        const boundary = (index: number) => Math.round(index * 1_000_000 / 30);
+        for (let i = 0; i < 300; i++) {
+            drawFrame(i);
+            await exporter.addFrame(canvas, { timestampUs: boundary(i), durationUs: boundary(i + 1) - boundary(i) });
+        }
+        return await exporter.finish();
+    } finally { exporter.dispose(); }
+}

package/docs/drafts/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": [],
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noEmit": true
+  },
+  "files": ["offline-video-example.ts"]
+}