@camera.ui/server 0.0.48 → 0.0.50-internal.0

package/src/decoder/child.ts

@@ -0,0 +1,883 @@
+process.title = process.argv[2] ?? 'camera.ui - Frame Worker';
+
+import { Logger, SignalHandler, sleep } from '@camera.ui/common';
+import { ClientInstance } from '@camera.ui/rpc-client';
+import { rpc } from '@camera.ui/rpc-common';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { NamespaceManager } from '../rpc/namespaces.js';
+import { ImageUtils } from './imageUtils.js';
+import { createSingleConnectionServer } from './utils.js';
+
+import type { LoggerOptions } from '@camera.ui/common';
+import type { Promisify } from '@camera.ui/rpc-common';
+import type {
+  CameraFrameWorkerDecoder,
+  CameraFrameWorkerResolution,
+  CoreManager as CoreManagerInterface,
+  DecoderFormat,
+  FfmpegArgs,
+  FrameBuffer,
+  FrameData,
+  FrameMetadata,
+  ImageInformation,
+  ImageOptions,
+} from '@camera.ui/types';
+import type { ChildProcess } from 'node:child_process';
+import type { Socket } from 'node:net';
+import type { CoreManagerNamespaces, FrameWorkerNamespaces } from '../rpc/namespaces.js';
+import type { BaseFrameWorkerConfig, FrameWorkerInterface, PixelFormat, WorkerToMainMessage } from './types.js';
+import type { TCPConnectionDetails } from './utils.js';
+
+const PIXEL_FORMAT: PixelFormat = 'yuv420p';
+const METADATA_REGEX = /s:\s*(\d+x\d+)/;
+
+interface Frame {
+  data: Buffer;
+  timestamp: number;
+  metadata: FrameMetadata;
+}
+
+class FFmpegStream {
+  private readonly frameSize: number;
+  private readonly width: number;
+  private readonly height: number;
+
+  // Process Management
+  private ffmpegProcess?: ChildProcess;
+  private activeViewers = 0;
+  private ffmpegHwOptions?: FfmpegArgs;
+  private server?: TCPConnectionDetails;
+  public socket?: Socket;
+
+  // State
+  public streamActive = false;
+  public metadata?: FrameMetadata;
+  private isShuttingDown = false;
+  private streamStartTimeout = 60000;
+  private initializationPromise: Promise<void> | null = null;
+
+  // Reconnection Logic
+  private reconnectCount = 0;
+
+  // Frame Queue Management
+  private frameBuffer: Frame[] = [];
+  private lastFrame: Frame | null = null;
+  private queueConsumers = new Set<FrameConsumer>();
+  private frameProcessingActive = false;
+  private bufferDurationMs = 5000;
+
+  // Health Check
+  private healthCheckInterval?: NodeJS.Timeout;
+  private lastFrameTimestamp = 0;
+  private healthCheckTime = 5000;
+  private maxFrameTime = 15000;
+
+  // Consumer management
+  private nextConsumerId = 0;
+
+  private get bytesPerPixel(): number {
+    switch (this.pixelFormat) {
+      case 'yuv420p':
+      case 'nv12':
+        return 1.5;
+      case 'rgb24':
+        return 3;
+    }
+  }
+
+  private get pixelFormat(): PixelFormat {
+    if (this.worker.imageUtils.decoder === 'gpu') {
+      return 'nv12';
+    } else {
+      return PIXEL_FORMAT;
+    }
+  }
+
+  constructor(private worker: FrameWorkerChild) {
+    const [width, height] = worker.config.resolution.split('x').map(Number);
+    this.width = width;
+    this.height = height;
+    this.frameSize = width * height * this.bytesPerPixel;
+  }
+
+  public async initialize(): Promise<void> {
+    if (this.initializationPromise) {
+      return this.initializationPromise;
+    }
+
+    if (this.streamActive) {
+      return;
+    }
+
+    try {
+      this.initializationPromise = this.startStreamProcess();
+      await this.initializationPromise;
+    } finally {
+      this.initializationPromise = null;
+    }
+  }
+
+  public close(): void {
+    if (!this.streamActive) {
+      return;
+    }
+
+    this.worker.logger.trace('Closing FFmpeg stream');
+    this.cleanupResources();
+  }
+
+  public cleanup(): void {
+    this.isShuttingDown = true;
+    this.cleanupResources();
+  }
+
+  public registerViewer(): FrameConsumer {
+    this.activeViewers++;
+    const consumer = new FrameConsumer(this.nextConsumerId++, this);
+    this.queueConsumers.add(consumer);
+    return consumer;
+  }
+
+  public unregisterViewer(consumer: FrameConsumer): void {
+    this.queueConsumers.delete(consumer);
+    this.activeViewers--;
+    if (this.activeViewers <= 0) {
+      this.activeViewers = 0;
+      this.close();
+    }
+  }
+
+  public getNextFrame(timestamp: number): Frame | null {
+    if (!this.lastFrame) {
+      return null;
+    }
+
+    if (this.lastFrame.timestamp <= timestamp) {
+      return null;
+    }
+
+    return {
+      data: Buffer.from(this.lastFrame.data),
+      timestamp: this.lastFrame.timestamp,
+      metadata: this.lastFrame.metadata,
+    };
+  }
+
+  public getFrameByTimestamp(timestamp: number, maxDifference = 0): Frame | undefined {
+    if (this.frameBuffer.length === 0) {
+      return undefined;
+    }
+
+    // Quick boundary checks
+    const firstFrame = this.frameBuffer[0];
+    const lastFrame = this.frameBuffer[this.frameBuffer.length - 1];
+
+    // Check if timestamp is outside our buffer range (plus maxDifference)
+    if (timestamp < firstFrame.timestamp - maxDifference || timestamp > lastFrame.timestamp + maxDifference) {
+      return undefined;
+    }
+
+    // Binary search for closest frame
+    let left = 0;
+    let right = this.frameBuffer.length - 1;
+
+    while (left <= right) {
+      const mid = Math.floor((left + right) / 2);
+      const frame = this.frameBuffer[mid];
+      const diff = frame.timestamp - timestamp;
+
+      // Exact match
+      if (diff === 0) {
+        return frame;
+      }
+
+      if (diff < 0) {
+        left = mid + 1;
+      } else {
+        right = mid - 1;
+      }
+    }
+
+    // If we need exact match only
+    if (maxDifference === 0) {
+      return undefined;
+    }
+
+    // Find closest frame within maxDifference
+    // After binary search, 'left' points to the insertion point
+    // Check frames around this point
+    const candidates = [this.frameBuffer[Math.max(0, left - 1)], this.frameBuffer[Math.min(this.frameBuffer.length - 1, left)]];
+
+    let bestMatch: Frame | undefined;
+    let smallestDiff = Infinity;
+
+    for (const frame of candidates) {
+      const diff = Math.abs(frame.timestamp - timestamp);
+      if (diff <= maxDifference && diff < smallestDiff) {
+        smallestDiff = diff;
+        bestMatch = frame;
+      }
+    }
+
+    if (bestMatch) {
+      return bestMatch;
+    }
+
+    return undefined;
+  }
+
+  private async startStreamProcess(): Promise<void> {
+    try {
+      await this.launchStream();
+      this.reconnectCount = 0;
+    } catch (error) {
+      if (this.isShuttingDown || this.activeViewers === 0) {
+        return;
+      }
+
+      this.reconnectCount = this.reconnectCount < 10 ? this.reconnectCount + 1 : 10;
+      const delay = this.calculateReconnectDelay();
+      this.worker.logger.warn(`Connection failed, retrying in ${delay / 1000}s`);
+      this.worker.logger.debug('Error:', error.message);
+
+      await sleep(delay);
+      this.worker.logger.debug('Retrying connection...');
+      return this.startStreamProcess();
+    }
+  }
+
+  private async launchStream(): Promise<void> {
+    if (this.activeViewers === 0) {
+      this.worker.logger.debug('No active consumers, not starting stream');
+      return;
+    }
+
+    this.cleanupResources();
+
+    this.server = await createSingleConnectionServer('127.0.0.1', {
+      noDelay: true,
+      // keepAlive: true,
+      highWaterMark: this.frameSize * 10,
+    });
+
+    const ffmpegArguments = await this.prepareFfmpegArguments(this.server.serverUrl);
+    this.worker.logger.trace('Starting FFmpeg with args:', this.worker.config.ffmpegPath, ffmpegArguments.join(' '));
+
+    this.ffmpegProcess = spawn(this.worker.config.ffmpegPath, ffmpegArguments, {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+
+    this.ffmpegProcess.once('exit', async () => {
+      if (this.activeViewers > 0 && !this.isShuttingDown) {
+        this.cleanupResources();
+        this.worker.logger.warn('FFmpeg process exited unexpectedly, restarting in 10 seconds...');
+        await sleep(10000);
+        this.initialize();
+      } else {
+        this.worker.logger.debug('FFmpeg process exited');
+      }
+    });
+
+    try {
+      this.socket = await this.server.connectionPromise;
+      this.metadata = await this.extractMetadata();
+      this.ffmpegProcess.stderr?.destroy();
+      this.streamActive = true;
+      this.startFrameProcessing();
+      this.startHealthCheck();
+    } catch (error) {
+      this.cleanupResources();
+      throw error;
+    }
+  }
+
+  private startHealthCheck(): void {
+    clearInterval(this.healthCheckInterval);
+    this.healthCheckInterval = setInterval(() => {
+      if (!this.streamActive || this.activeViewers === 0) {
+        return;
+      }
+
+      const now = Date.now();
+      const timeSinceLastFrame = now - this.lastFrameTimestamp;
+
+      // If no frames for 30 seconds and we have active viewers, restart
+      if (this.lastFrameTimestamp > 0 && timeSinceLastFrame > this.maxFrameTime && this.activeViewers > 0) {
+        this.worker.logger.warn(`No frames received in ${timeSinceLastFrame / 1000}s! This may be due to a network issue, FFmpeg failure or high load on the system.`);
+        this.worker.logger.log('Restarting...');
+        this.cleanupResources();
+        this.initialize();
+      }
+    }, this.healthCheckTime);
+  }
+
+  private async startFrameProcessing(): Promise<void> {
+    if (this.frameProcessingActive || !this.socket || !this.metadata) {
+      return;
+    }
+
+    let firstChunkReceived = false;
+    let firstFrameReceived = false;
+    this.frameProcessingActive = true;
+    const metadata = this.metadata;
+    let buffer = Buffer.alloc(0);
+    let lastBufferSize = 0;
+
+    try {
+      for await (const chunk of this.socket as AsyncIterable<Buffer>) {
+        if (!this.frameProcessingActive) {
+          break;
+        }
+
+        if (!chunk.length) {
+          this.worker.logger.warn('Received empty chunk from FFmpeg');
+          continue;
+        }
+
+        if (buffer.length > metadata.frameSize * 10) {
+          this.worker.logger.warn(`Buffer growing: ${buffer.length} bytes (${(buffer.length / metadata.frameSize).toFixed(2)} frames)`);
+        }
+
+        if (!firstChunkReceived) {
+          this.worker.logger.trace('First chunk received');
+          firstChunkReceived = true;
+        }
+
+        buffer = Buffer.concat([buffer, chunk]);
+
+        while (buffer.length >= metadata.frameSize) {
+          const frameData = buffer.subarray(0, metadata.frameSize);
+          buffer = buffer.subarray(metadata.frameSize);
+
+          if (lastBufferSize === buffer.length && buffer.length > 0) {
+            this.worker.logger.warn(`Possible issue: Buffer size not changing: ${buffer.length} bytes`);
+            // buffer = Buffer.alloc(0);
+            break;
+          }
+
+          lastBufferSize = buffer.length;
+
+          if (!firstFrameReceived) {
+            this.worker.logger.trace('First frame received');
+            firstFrameReceived = true;
+          }
+
+          this.addFrameToQueue(frameData, this.metadata);
+        }
+      }
+    } catch (error) {
+      this.worker.logger.error('Error in frame processing:', error);
+    } finally {
+      this.frameProcessingActive = false;
+    }
+  }
+
+  private addFrameToQueue(frameData: Buffer, metadata: FrameMetadata): void {
+    const timestamp = Date.now();
+    this.lastFrameTimestamp = timestamp;
+
+    const newFrame: Frame = {
+      data: frameData,
+      timestamp,
+      metadata,
+    };
+
+    this.frameBuffer.push(newFrame);
+    this.lastFrame = newFrame;
+    this.cleanupOldFrames();
+
+    // Notify all consumers that a new frame is available
+    for (const consumer of this.queueConsumers) {
+      consumer.notifyNewFrame();
+    }
+  }
+
+  private cleanupOldFrames(): void {
+    const currentTime = Date.now();
+    const bufferThreshold = currentTime - this.bufferDurationMs;
+
+    while (this.frameBuffer.length > 1 && this.frameBuffer[0].timestamp < bufferThreshold) {
+      this.frameBuffer.shift();
+    }
+  }
+
+  private async extractMetadata(): Promise<FrameMetadata> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error('FFmpeg stream start timeout'));
+      }, this.streamStartTimeout);
+
+      const onData = (data: Buffer) => {
+        const metadata = this.parseMetadataFromStderr(data);
+        if (metadata) {
+          this.worker.logger.debug('Metadata received:', metadata);
+          cleanup();
+          resolve(metadata);
+        }
+      };
+
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.ffmpegProcess?.stderr?.removeListener('data', onData);
+      };
+
+      this.ffmpegProcess?.stderr?.on('data', onData);
+    });
+  }
+
+  private calculateReconnectDelay(): number {
+    if (this.reconnectCount === 10) {
+      return 60000;
+    } else {
+      return 10000;
+    }
+  }
+
+  private parseMetadataFromStderr(data: Buffer): FrameMetadata | undefined {
+    const stderrText = data.toString();
+    if (!stderrText) {
+      return;
+    }
+
+    const match = METADATA_REGEX.exec(stderrText);
+    if (!match?.[1]) {
+      return;
+    }
+
+    const [originalWidth, originalHeight] = match[1].split('x').map((v) => parseInt(v, 10));
+    const frameDataSize = this.width * this.height * this.bytesPerPixel;
+
+    const metadata: FrameMetadata = {
+      format: this.worker.imageUtils.decoder === 'gpu' ? 'nv12' : 'yuv420p',
+      frameSize: frameDataSize,
+      width: this.width,
+      height: this.height,
+      origHeight: originalHeight,
+      origWidth: originalWidth,
+    };
+
+    return metadata;
+  }
+
+  private async prepareFfmpegArguments(serverUrl: string): Promise<string[]> {
+    if (!this.ffmpegHwOptions) {
+      const coreManager = await this.coreManagerProxy();
+      this.ffmpegHwOptions = (
+        await coreManager.getHwaccelInfo({
+          targetCodec: 'h264',
+          keepOnHardware: true,
+          pixelFormat: this.pixelFormat,
+          scale: {
+            width: this.width,
+            height: this.height,
+          },
+        })
+      )[0];
+    }
+
+    const filterChain: string[] = ['showinfo=checksum=0', ...this.ffmpegHwOptions.hwaccelFilters];
+    if (this.worker.config.fps > 0) {
+      filterChain.push(`fps=fps=${this.worker.config.fps}`);
+    }
+
+    return [
+      '-hide_banner',
+      ...this.ffmpegHwOptions.hwaccelArgs,
+      '-fflags',
+      '+discardcorrupt+flush_packets+nobuffer',
+      '-flags',
+      'low_delay',
+      '-analyzeduration',
+      '0',
+      '-probesize',
+      '500000',
+      '-reorder_queue_size',
+      '0',
+      '-user_agent',
+      'camera.ui/frameworker',
+      '-timeout',
+      '5000000',
+      '-rtsp_transport',
+      'tcp',
+      '-re',
+      '-i',
+      this.worker.config.cameraSource,
+      ...this.ffmpegHwOptions.hwDeviceArgs,
+      '-fps_mode',
+      'cfr',
+      '-vf',
+      filterChain.join(','),
+      '-an',
+      '-dn',
+      '-sn',
+      '-f',
+      'rawvideo',
+      `${serverUrl}?tcp_nodelay=1`,
+    ];
+  }
+
+  private cleanupResources(): void {
+    this.streamActive = false;
+    this.metadata = undefined;
+    this.frameProcessingActive = false;
+
+    clearInterval(this.healthCheckInterval);
+    this.healthCheckInterval = undefined;
+
+    this.server?.terminate();
+    this.server = undefined;
+
+    this.ffmpegProcess?.stderr?.removeAllListeners();
+    this.ffmpegProcess?.stderr?.destroy();
+    this.ffmpegProcess?.removeAllListeners();
+    this.ffmpegProcess?.kill('SIGKILL');
+    this.ffmpegProcess = undefined;
+  }
+
+  private async coreManagerProxy(): Promise<Promisify<CoreManagerInterface>> {
+    return await this.worker.createRPCProxy<CoreManagerInterface>(this.worker.namespaces.coreManagerRpc);
+  }
+}
+
+class FrameConsumer {
+  private lastFrameTimestamp = 0;
+  private resolveNewFrame: (() => void) | null = null;
+
+  constructor(
+    public readonly id: number,
+    private stream: FFmpegStream,
+  ) {}
+
+  public notifyNewFrame(): void {
+    if (this.resolveNewFrame) {
+      const resolve = this.resolveNewFrame;
+      this.resolveNewFrame = null;
+      resolve();
+    }
+  }
+
+  public waitForNewFrame(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.resolveNewFrame = resolve;
+    });
+  }
+
+  public [Symbol.asyncIterator](): AsyncIterator<Frame> {
+    return {
+      next: async (): Promise<IteratorResult<Frame>> => {
+        while (true) {
+          const frame = this.stream.getNextFrame(this.lastFrameTimestamp);
+
+          if (frame) {
+            this.lastFrameTimestamp = frame.timestamp;
+            return { value: frame, done: false };
+          }
+
+          if (!this.stream.streamActive) {
+            return { value: undefined as any, done: true };
+          }
+
+          // Wait for notification of new frame
+          await this.waitForNewFrame();
+        }
+      },
+    };
+  }
+}
+
+class FrameWorkerChild extends ClientInstance implements FrameWorkerInterface {
+  public readonly config: BaseFrameWorkerConfig;
+  public readonly namespaces: FrameWorkerNamespaces & CoreManagerNamespaces;
+  public readonly logger: Logger;
+  public readonly imageUtils: ImageUtils;
+
+  private signalHandler: SignalHandler;
+  private ffmpegStream: FFmpegStream;
+
+  private stopped = false;
+
+  constructor() {
+    super('service', {
+      endpoints: process.env.PROXY_ENDPOINTS!.split(','),
+      auth: {
+        user: process.env.PROXY_USER!,
+        password: process.env.PROXY_PASSWORD!,
+      },
+      tls: {
+        cert: process.env.PROXY_CERT!,
+        key: process.env.PROXY_KEY!,
+        ca: process.env.PROXY_CA!,
+      },
+      metadata: {
+        id: NamespaceManager.frameWorkerNamespaces(process.env.CAMERA_ID!).frameWorkerChild,
+        name: 'Frame Worker',
+      },
+      connect: {
+        waitForServer: true,
+      },
+      reconnect: {
+        enabled: true,
+      },
+      bundledConnection: false,
+    });
+
+    this.namespaces = {
+      ...NamespaceManager.frameWorkerNamespaces(process.env.CAMERA_ID!),
+      ...NamespaceManager.coreManagerNamespaces(),
+    };
+
+    this.config = {
+      cameraId: process.env.CAMERA_ID!,
+      cameraName: process.env.CAMERA_NAME!,
+      cameraSource: process.env.CAMERA_SOURCE!,
+      ffmpegPath: process.env.FFMPEG_PATH!,
+      auth: { user: process.env.PROXY_USER!, password: process.env.PROXY_PASSWORD! },
+      proxyEndpoints: process.env.PROXY_ENDPOINTS!.split(','),
+      fps: parseInt(process.env.FPS!),
+      resolution: process.env.RESOLUTION! as CameraFrameWorkerResolution,
+      decoder: process.env.DECODER! as CameraFrameWorkerDecoder,
+    };
+
+    delete process.env.PROXY_USER;
+    delete process.env.PROXY_PASSWORD;
+    delete process.env.PROXY_ENDPOINTS;
+    delete process.env.PROXY_CERT;
+    delete process.env.PROXY_KEY;
+    delete process.env.PROXY_CA;
+
+    const loggerOptions: LoggerOptions = {
+      prefix: 'Frame Worker',
+      suffix: this.config.cameraName,
+      disableTimestamps: process.env.LOGGER_DISABLE_TIMESTAMPS === '1',
+      debugEnabled: process.env.LOGGER_LEVEL === 'debug' || process.env.LOGGER_LEVEL === 'trace',
+      traceEnabled: process.env.LOGGER_LEVEL === 'trace',
+    };
+
+    this.logger = new Logger(loggerOptions);
+    this.imageUtils = new ImageUtils(this.config.decoder, this.logger);
+    this.ffmpegStream = new FFmpegStream(this);
+    this.signalHandler = new SignalHandler({
+      displayName: '[Signal]',
+      timeoutDuration: 1000,
+      logger: this.logger,
+      closeFunction: this.close.bind(this),
+    });
+
+    this.start();
+  }
+
+  protected async onStart(): Promise<void> {
+    await this.imageUtils.initiate();
+    await this.registerRPCHandler(this.namespaces.frameWorkerChildRpc, this);
+    this.sendMessage({ message: 'started', data: {} });
+  }
+
+  protected onBeforeStop(): Promise<void> {
+    return this.close();
+  }
+
+  protected async onStop(): Promise<void> {}
+
+  @rpc({ public: true })
+  public async *generateFrames(options?: ImageOptions): AsyncGenerator<FrameData> {
+    let consumer: FrameConsumer | undefined;
+
+    try {
+      consumer = this.ffmpegStream.registerViewer();
+      await this.ffmpegStream.initialize();
+
+      if (!this.ffmpegStream.metadata) {
+        throw new Error('Stream metadata not available');
+      }
+
+      const metadata = this.ffmpegStream.metadata;
+
+      // Use the async iterator from the consumer to get frames
+      for await (const { data: frameData, timestamp } of consumer) {
+        options = this.validateOptions(metadata, options);
+
+        if (options) {
+          const processedFrame = await this.processFrame(frameData, metadata.width, metadata.height, metadata.format, options);
+          yield {
+            data: processedFrame.image,
+            metadata,
+            timestamp,
+            info: processedFrame.info,
+          };
+        } else {
+          const info = this.getImageInformation(metadata.width, metadata.height, metadata.format);
+          yield {
+            data: frameData,
+            metadata,
+            timestamp,
+            info,
+          };
+        }
+      }
+    } catch (error) {
+      this.logger.error('Error in frame generation:', error);
+    } finally {
+      if (consumer) {
+        this.ffmpegStream.unregisterViewer(consumer);
+      }
+    }
+  }
+
+  @rpc({ public: true })
+  public async getPrebufferedFrame(timestamp: number, options?: ImageOptions, maxDifference = 500): Promise<FrameData | undefined> {
+    const prebufferedFrame = this.ffmpegStream.getFrameByTimestamp(timestamp, maxDifference);
+    if (!prebufferedFrame) {
+      this.logger.debug(`No prebuffered frame found for timestamp ${timestamp}`);
+      return;
+    }
+
+    const validatedOptions = options && this.validateOptions(prebufferedFrame.metadata, options);
+
+    if (validatedOptions) {
+      const processedFrame = await this.processFrame(
+        prebufferedFrame.data,
+        prebufferedFrame.metadata.width,
+        prebufferedFrame.metadata.height,
+        prebufferedFrame.metadata.format,
+        validatedOptions,
+      );
+      return { data: processedFrame.image, metadata: prebufferedFrame.metadata, timestamp: prebufferedFrame.timestamp, info: processedFrame.info };
+    } else {
+      const info = this.getImageInformation(prebufferedFrame.metadata.width, prebufferedFrame.metadata.height, prebufferedFrame.metadata.format);
+      return { data: prebufferedFrame.data, metadata: prebufferedFrame.metadata, timestamp: prebufferedFrame.timestamp, info };
+    }
+  }
+
+  @rpc({ public: true })
+  public async processFrame(
+    frame: Buffer | Uint8Array,
+    width: number,
+    height: number,
+    format: DecoderFormat | 'rgba' | 'gray',
+    options: ImageOptions,
+  ): Promise<FrameBuffer> {
+    const newFrame = Buffer.isBuffer(frame) ? new Uint8Array(frame, frame.byteOffset, frame.byteLength) : frame;
+    const info = this.getImageInformation(width, height, format, options);
+
+    const image = await this.imageUtils.processImage(newFrame, width, height, format, options);
+
+    return {
+      image,
+      info,
+    };
+  }
+
+  private validateOptions(metadata: FrameMetadata, options: ImageOptions = {}): ImageOptions | undefined {
+    const validated: ImageOptions = {};
+
+    // Format conversion
+    const metadataFormat = metadata.format === 'rgb24' ? 'rgb' : metadata.format;
+    if (options.format?.to && options.format.to !== metadataFormat) {
+      validated.format = options.format;
+    }
+
+    // Cropping
+    if (options.crop) {
+      const left = options.crop.left || 0;
+      const top = options.crop.top || 0;
+
+      // Validate crop parameters
+      if (left >= metadata.width || top >= metadata.height) {
+        return undefined;
+      }
+
+      const width = Math.min(options.crop.width ?? metadata.width, metadata.width - left);
+      const height = Math.min(options.crop.height ?? metadata.height, metadata.height - top);
+
+      if (width <= 0 || height <= 0) {
+        return undefined;
+      }
+
+      // Skip full frame "crops"
+      if (left === 0 && top === 0 && width === metadata.width && height === metadata.height) {
+        // No need to include this crop as it's the full frame
+      } else {
+        validated.crop = {
+          left,
+          top,
+          width,
+          height,
+        };
+      }
+    }
+
+    // Resizing
+    if (options.resize) {
+      let targetWidth = options.resize.width;
+      let targetHeight = options.resize.height;
+
+      // Handle negative values (which mean "use original")
+      if (targetWidth < 0) targetWidth = metadata.width;
+      if (targetHeight < 0) targetHeight = metadata.height;
+
+      // Calculate missing dimension if only one is provided
+      if (targetWidth > 0 && targetHeight === 0) {
+        targetHeight = Math.round((targetWidth * metadata.height) / metadata.width);
+      } else if (targetHeight > 0 && targetWidth === 0) {
+        targetWidth = Math.round((targetHeight * metadata.width) / metadata.height);
+      }
+
+      // Skip if no resize needed
+      if ((targetWidth === 0 && targetHeight === 0) || (targetWidth === metadata.width && targetHeight === metadata.height)) {
+        // Skip as it's the same as original
+      } else {
+        validated.resize = {
+          width: targetWidth,
+          height: targetHeight,
+        };
+      }
+    }
+
+    // Return undefined if no transformations are needed
+    return Object.keys(validated).length > 0 ? validated : undefined;
+  }
+
+  private getImageInformation(inputWidth: number, inputHeight: number, inputFormat: DecoderFormat | 'rgba' | 'gray', options?: ImageOptions): ImageInformation {
+    // Calculate output width
+    const width = options?.resize?.width ?? (options?.crop ? Math.min(options.crop.width + (options.crop.left || 0), inputWidth - (options.crop.left || 0)) : inputWidth);
+
+    // Calculate output height
+    const height =
+      options?.resize?.height ?? (options?.crop ? Math.min(options.crop.height + (options.crop.top || 0), inputHeight - (options.crop.top || 0)) : inputHeight);
+
+    // Determine output format
+    let format = options?.format?.to ?? inputFormat;
+    format = format === 'rgb24' ? 'rgb' : format;
+
+    // Calculate channels based on format
+    const channels = format === 'rgba' ? 4 : format === 'rgb' ? 3 : format === 'gray' ? 1 : 1.5;
+
+    return {
+      width,
+      height,
+      channels,
+      format,
+    };
+  }
+
+  private sendMessage(message: WorkerToMainMessage): void {
+    this.sendToServer<WorkerToMainMessage>(message);
+  }
+
+  private async close(): Promise<void> {
+    if (this.stopped) {
+      return;
+    }
+
+    this.stopped = true;
+    this.ffmpegStream.cleanup();
+    await this.stop();
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  new FrameWorkerChild();
+}