@grundyjs/canvas-take 0.4.1 → 0.5.0

package/dist/video-webcodecs.d.ts

@@ -0,0 +1,3 @@
+import type { VideoEncoderFactory } from './video.js';
+/** First profile: H.264 Baseline, AVC framing, quality mode, one drained native input at a time. */
+export declare function createWebCodecsVideoEncoder(): VideoEncoderFactory;

package/dist/video-webcodecs.js

@@ -0,0 +1,149 @@
+/** First profile: H.264 Baseline, AVC framing, quality mode, one drained native input at a time. */
+export function createWebCodecsVideoEncoder() {
+    function nativeConfig(config) {
+        if (!/^avc1\.42[0-9a-f]{4}$/i.test(config.codec) || config.bitstreamFormat !== 'avc') {
+            throw new DOMException('WebCodecs adapter requires H.264 Baseline (avc1.42xxxx) with avc framing', 'NotSupportedError');
+        }
+        if (![config.width, config.height, config.bitrate].every(n => Number.isSafeInteger(n) && n > 0) || config.width % 2 || config.height % 2) {
+            throw new RangeError('H.264 requires positive even dimensions and a positive integer bitrate');
+        }
+        return { codec: config.codec, width: config.width, height: config.height, bitrate: config.bitrate,
+            latencyMode: 'quality', avc: { format: 'avc' },
+            ...(config.frameRateHint ? { framerate: config.frameRateHint.numerator / config.frameRateHint.denominator } : {}) };
+    }
+    return {
+        async checkSupport(config) {
+            try {
+                const native = nativeConfig(config);
+                if (typeof VideoEncoder === 'undefined' || typeof VideoFrame === 'undefined')
+                    return { supported: false, reason: 'WebCodecs VideoEncoder/VideoFrame unavailable (requires a secure context)' };
+                const support = await VideoEncoder.isConfigSupported(native);
+                return support.supported ? { supported: true } : { supported: false, reason: `WebCodecs does not support ${config.codec} at ${config.width}x${config.height}` };
+            }
+            catch (error) {
+                return { supported: false, reason: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        create(config, context) {
+            const native = nativeConfig(config);
+            let encoder, disposed = false, ended = false, error;
+            let pending;
+            let tail = Promise.resolve(), bytes = 0, events = 0, description;
+            let rejectFailure;
+            const failed = new Promise((_, reject) => { rejectFailure = reject; });
+            void failed.catch(() => { });
+            const guard = () => {
+                if (error !== undefined)
+                    throw error;
+                if (disposed || context.signal.aborted)
+                    throw context.signal.reason ?? new DOMException('Video encoder disposed', 'AbortError');
+            };
+            function fail(reason) {
+                if (disposed || error !== undefined)
+                    return;
+                error = reason instanceof Error ? reason : new Error('WebCodecs encoder failed', { cause: reason });
+                rejectFailure(error);
+                context.output.fail(error);
+            }
+            const wait = async (work) => { const value = await Promise.race([work, failed]); guard(); return value; };
+            function enqueue(event, cost) {
+                if (cost > context.maxPendingBytes - bytes || events >= context.maxPendingInputs + 1)
+                    throw new RangeError('WebCodecs maxPendingBytes/maxPendingInputs exceeded');
+                bytes += cost;
+                events++;
+                tail = tail.then(() => { guard(); return context.output.write(event); }).then(() => { bytes -= cost; events--; });
+                void tail.catch(fail);
+            }
+            function abort() { dispose(); }
+            function dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                context.signal.removeEventListener('abort', abort);
+                rejectFailure(context.signal.reason ?? new DOMException('Video encoder disposed', 'AbortError'));
+                if (encoder && encoder.state !== 'closed')
+                    encoder.close();
+                encoder = undefined;
+                pending = undefined;
+                description = undefined;
+            }
+            try {
+                guard();
+                encoder = new VideoEncoder({ error: fail, output(chunk, metadata) {
+                        if (disposed || error !== undefined)
+                            return;
+                        try {
+                            guard();
+                            if (!pending || chunk.timestamp !== pending.timestampUs || (pending.keyFrame && chunk.type !== 'key'))
+                                throw new Error('WebCodecs dropped, reordered or changed a requested key frame');
+                            // Baseline forbids B pictures. Also verify the actual avcC profile, not only callback order.
+                            if (metadata?.decoderConfig) {
+                                const c = metadata.decoderConfig, color = c.colorSpace;
+                                const d = c.description;
+                                const avcc = d ? (ArrayBuffer.isView(d) ? new Uint8Array(d.buffer, d.byteOffset, d.byteLength) : new Uint8Array(d)).slice() : undefined;
+                                if (!avcc || avcc.length < 7 || avcc[0] !== 1 || avcc[1] !== 66 || c.codec !== config.codec || c.codedWidth !== config.width || c.codedHeight !== config.height)
+                                    throw new Error('WebCodecs returned incompatible AVC Baseline decoder configuration');
+                                if (color?.primaries !== 'bt709' || !['bt709', 'iec61966-2-1'].includes(color.transfer ?? '') || color.matrix !== 'bt709' || typeof color.fullRange !== 'boolean')
+                                    throw new Error('WebCodecs returned unsupported or missing SDR color metadata');
+                                description = { codec: config.codec, bitstreamFormat: 'avc', width: config.width, height: config.height, description: avcc,
+                                    color: { primaries: color.primaries, transfer: color.transfer, matrix: color.matrix, fullRange: color.fullRange } };
+                                enqueue({ type: 'config', track: 'video', config: description }, avcc.byteLength + 64);
+                            }
+                            if (!description)
+                                throw new Error('WebCodecs did not provide an AVC decoder description');
+                            if (chunk.byteLength + 64 > context.maxPendingBytes - bytes)
+                                throw new RangeError('WebCodecs maxPendingBytes exceeded');
+                            const data = new Uint8Array(chunk.byteLength);
+                            chunk.copyTo(data);
+                            // Duration comes from the submitted interval, including a long final hold.
+                            enqueue({ type: 'packet', packet: { track: 'video', timestampUs: pending.timestampUs, decodeTimestampUs: pending.timestampUs,
+                                    durationUs: pending.durationUs, type: chunk.type, data } }, data.byteLength + 64);
+                            pending = undefined;
+                        }
+                        catch (reason) {
+                            fail(reason);
+                        }
+                    } });
+                encoder.configure(native);
+                context.signal.addEventListener('abort', abort, { once: true });
+                guard();
+            }
+            catch (reason) {
+                dispose();
+                throw reason;
+            }
+            return {
+                async encodeFrame(frame) {
+                    guard();
+                    if (ended || pending)
+                        throw new Error('Video encoder is ended or busy');
+                    pending = { timestampUs: frame.timestampUs, durationUs: frame.durationUs, keyFrame: frame.keyFrame === true };
+                    let input;
+                    try {
+                        input = new VideoFrame(frame.data, { format: 'RGBA', codedWidth: config.width, codedHeight: config.height,
+                            timestamp: frame.timestampUs, duration: frame.durationUs,
+                            colorSpace: { primaries: 'bt709', transfer: 'iec61966-2-1', matrix: 'rgb', fullRange: true } });
+                        encoder.encode(input, { keyFrame: frame.keyFrame });
+                    }
+                    finally {
+                        input?.close();
+                    }
+                    await wait(encoder.flush());
+                    if (pending)
+                        throw new Error('WebCodecs did not output the submitted frame');
+                    await wait(tail);
+                },
+                async flush() {
+                    guard();
+                    if (ended)
+                        throw new Error('Video encoder already ended');
+                    ended = true;
+                    await wait(encoder.flush());
+                    await wait(tail);
+                    await wait(context.output.write({ type: 'end', track: 'video' }));
+                },
+                dispose
+            };
+        }
+    };
+}

package/dist/video.d.ts

@@ -0,0 +1,215 @@
+/** Adapter-neutral offline video contracts. Concrete codecs and containers are supplied by the caller. */
+export type Awaitable<T> = T | Promise<T>;
+export type Support = {
+    readonly supported: true;
+} | {
+    readonly supported: false;
+    readonly reason: string;
+};
+export type Track = 'video' | 'audio';
+export interface VideoEncodeConfig {
+    readonly codec: string;
+    readonly bitstreamFormat: string;
+    readonly width: number;
+    readonly height: number;
+    readonly bitrate: number;
+    /** Encoder hint only. Timing always comes from submitted frame intervals. */
+    readonly frameRateHint?: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+}
+export interface AudioEncodeConfig {
+    readonly codec: string;
+    readonly bitstreamFormat: string;
+    readonly sampleRate: number;
+    readonly numberOfChannels: number;
+    readonly bitrate: number;
+}
+export interface FrameTiming {
+    readonly timestampUs: number;
+    readonly durationUs: number;
+    readonly keyFrame?: boolean;
+}
+export interface RawVideoFrame extends FrameTiming {
+    readonly width: number;
+    readonly height: number;
+    /** Exclusively owned opaque sRGB RGBA8 snapshot. */
+    readonly data: Uint8ClampedArray;
+}
+export interface PreparedAudio {
+    readonly sampleRate: number;
+    /** Equal-length planar float32 channels, copied before asynchronous initialization. */
+    readonly channels: readonly Float32Array[];
+}
+export interface RawAudioBlock {
+    readonly sampleRate: number;
+    readonly sampleOffset: number;
+    readonly timestampUs: number;
+    /** Exclusively owned block buffers; never aliases the retained source. */
+    readonly channels: readonly Float32Array[];
+}
+export interface DecoderDescription {
+    readonly codec: string;
+    readonly bitstreamFormat: string;
+    readonly description?: Uint8Array;
+}
+export interface VideoDescription extends DecoderDescription {
+    readonly width: number;
+    readonly height: number;
+    readonly color: {
+        readonly primaries: string;
+        readonly transfer: string;
+        readonly matrix: string;
+        readonly fullRange: boolean;
+    };
+}
+export interface AudioDescription extends DecoderDescription {
+    readonly sampleRate: number;
+    readonly numberOfChannels: number;
+}
+export interface EncodedPacket {
+    readonly track: Track;
+    /** Signed codec timestamps; presentation after trimming starts at zero. */
+    readonly timestampUs: number;
+    readonly decodeTimestampUs: number;
+    readonly durationUs: number;
+    readonly type: 'key' | 'delta';
+    readonly data: Uint8Array;
+}
+export type CodecEvent = {
+    readonly type: 'config';
+    readonly track: 'video';
+    readonly config: VideoDescription;
+} | {
+    readonly type: 'config';
+    readonly track: 'audio';
+    readonly config: AudioDescription;
+} | {
+    readonly type: 'packet';
+    readonly packet: EncodedPacket;
+} | {
+    readonly type: 'end';
+    readonly track: 'video';
+} | {
+    readonly type: 'end';
+    readonly track: 'audio';
+    readonly presentationSamples: number;
+    readonly leadingDiscardSamples: number;
+    readonly trailingDiscardSamples: number;
+};
+export interface CodecOutputSink {
+    /** Ordered per track. Promise settles after muxer consumption; bytes are borrowed until then. */
+    write(event: CodecEvent): Promise<void>;
+    /** Report a delayed callback/worker failure even when no encode call is pending. */
+    fail(error: unknown): void;
+}
+export interface SessionContext {
+    readonly signal: AbortSignal;
+    /** Adapter input bound; also caps video intervals awaiting packets in the controller. */
+    readonly maxPendingInputs: number;
+    /** Work-byte budget; the controller reserves 64 additional bytes per queued event. */
+    readonly maxPendingBytes: number;
+}
+export interface EncoderContext extends SessionContext {
+    readonly output: CodecOutputSink;
+}
+export interface MuxerContext extends SessionContext {
+    readonly maxOutputBytes?: number;
+}
+export interface OfflineVideoEncoder {
+    encodeFrame(frame: RawVideoFrame): Promise<void>;
+    /** Emits end after all delayed packets and waits for all output writes. */
+    flush(): Promise<void>;
+    dispose(): void;
+}
+export interface OfflineAudioEncoder {
+    encodeAudio(block: RawAudioBlock): Promise<void>;
+    flush(): Promise<void>;
+    dispose(): void;
+}
+export interface VideoEncoderFactory {
+    checkSupport(config: VideoEncodeConfig): Promise<Support>;
+    create(config: VideoEncodeConfig, context: EncoderContext): Awaitable<OfflineVideoEncoder>;
+}
+export interface AudioEncoderFactory {
+    checkSupport(config: AudioEncodeConfig): Promise<Support>;
+    create(config: AudioEncodeConfig, context: EncoderContext): Awaitable<OfflineAudioEncoder>;
+}
+export interface MuxerConfig {
+    readonly video: VideoEncodeConfig;
+    readonly audio?: AudioEncodeConfig;
+}
+export interface TimelineSummary {
+    readonly durationUs: number;
+    readonly videoFrames: number;
+    readonly audioPresentationSamples?: number;
+}
+export interface OfflineVideoMuxer {
+    /** Serial across tracks; must not wait for a future track/packet to resolve this write. */
+    write(event: CodecEvent): Promise<void>;
+    /** Returns one complete, playable container after both track-end events. */
+    finalize(timeline: TimelineSummary): Promise<Blob>;
+    dispose(): void;
+}
+export interface MuxerFactory {
+    readonly format: {
+        readonly mimeType: string;
+        readonly extension: string;
+    };
+    checkSupport(config: MuxerConfig): Promise<Support>;
+    create(config: MuxerConfig, context: MuxerContext): Awaitable<OfflineVideoMuxer>;
+}
+export interface OfflineVideoProgress {
+    readonly phase: 'initializing' | 'encoding' | 'finalizing' | 'finished' | 'failed' | 'aborted' | 'disposed';
+    readonly framesAccepted: number;
+    readonly durationUs: number;
+    readonly audioSamplesAccepted: number;
+    readonly videoPacketsWritten: number;
+    readonly audioPacketsWritten: number;
+    readonly encodedBytes: number;
+    readonly totalFrames?: number;
+    /** Known only after container finalization in the first implementation. */
+    readonly outputBytes?: number;
+}
+export interface OfflineVideoOptions {
+    readonly video: {
+        readonly encoder: VideoEncoderFactory;
+        readonly config: VideoEncodeConfig;
+    };
+    readonly audio?: {
+        readonly encoder: AudioEncoderFactory;
+        readonly config: AudioEncodeConfig;
+        readonly source: PreparedAudio;
+        readonly endPolicy: 'error' | 'trim-or-pad';
+    };
+    readonly muxer: MuxerFactory;
+    readonly signal?: AbortSignal;
+    readonly background?: readonly [number, number, number];
+    readonly totalFrames?: number;
+    readonly onProgress?: (progress: OfflineVideoProgress) => void;
+    readonly maxFramePixels?: number;
+    readonly maxFrames?: number;
+    readonly maxDurationUs?: number;
+    readonly maxAudioInputBytes?: number;
+    readonly maxOutputBytes?: number;
+    readonly maxPendingInputs?: number;
+    readonly maxPendingBytes?: number;
+}
+export interface OfflineVideoResult extends TimelineSummary {
+    readonly blob: Blob;
+    readonly mimeType: string;
+    readonly extension: string;
+    readonly videoCodec: string;
+    readonly audioCodec?: string;
+}
+export type OfflineVideoState = 'ready' | 'encoding' | 'finalizing' | 'finished' | 'failed' | 'aborted' | 'disposed';
+export interface OfflineVideoExporter {
+    readonly state: OfflineVideoState;
+    /** Snapshot immediately, before the first yield; await before the next operation. */
+    addFrame(canvas: HTMLCanvasElement | OffscreenCanvas, timing: FrameTiming): Promise<void>;
+    finish(): Promise<OfflineVideoResult>;
+    dispose(): void;
+}
+/** Offline timeline controller. Encoders and container implementation are always supplied. */
+export declare function createOfflineVideoExporter(options: OfflineVideoOptions): Promise<OfflineVideoExporter>;