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

package/src/decoder/python/child.py

@@ -0,0 +1,903 @@
+import asyncio
+import os
+import re
+import sys
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal, Optional, Union, cast
+
+import setproctitle
+
+from _camera_ui_tools.camera_ui_common import LoggerService, SignalHandler
+from _camera_ui_tools.camera_ui_rpc_client import ClientInstance
+from _camera_ui_tools.camera_ui_rpc_client.utils.rpc import rpc
+from _camera_ui_tools.camera_ui_types import (
+    CameraFrameWorkerDecoder,
+    CameraFrameWorkerResolution,
+    DecoderFormat,
+    FfmpegArgs,
+    FrameBuffer,
+    FrameData,
+    FrameMetadata,
+    ImageInformation,
+    ImageOptions,
+    ImageOutputFormat,
+)
+from decoder.python.image_utils import process_image_threaded
+from decoder.python.typings import (
+    BaseFrameWorkerConfig,
+    FrameWorkerInterface,
+    PixelFormat,
+    WorkerToMainMessage,
+)
+from decoder.python.utils import TCPConnectionDetails, create_single_connection_server
+from plugins.runtime.python.namespaces import FrameWorkerCoreManagerNamespaces, NamespaceManager
+from plugins.runtime.python.typings import CoreManagerInterface
+
+process_name = (
+    sys.argv[2] if len(sys.argv) > 2 else sys.argv[1] if len(sys.argv) > 1 else "camera.ui - Frame Worker"
+)
+setproctitle.setproctitle(process_name)
+
+PIXEL_FORMAT: PixelFormat = "yuv420p"
+METADATA_REGEX = r"s:\s*(\d+x\d+)"
+
+
+@dataclass
+class Frame:
+    data: bytes
+    timestamp: int
+    metadata: FrameMetadata
+
+
+class FrameConsumer:
+    def __init__(self, consumer_id: int, stream: "FFmpegStream") -> None:
+        self.id: int = consumer_id
+        self.stream: FFmpegStream = stream
+        self.last_frame_timestamp: int = 0
+        self.resolve_new_frame_future: Optional[asyncio.Future[None]] = None
+
+    def notify_new_frame(self) -> None:
+        if self.resolve_new_frame_future and not self.resolve_new_frame_future.done():
+            self.resolve_new_frame_future.set_result(None)
+            self.resolve_new_frame_future = None
+
+    async def wait_for_new_frame(self) -> None:
+        if self.resolve_new_frame_future is None or self.resolve_new_frame_future.done():
+            self.resolve_new_frame_future = asyncio.Future()
+            await self.resolve_new_frame_future
+
+    def __aiter__(self) -> "FrameConsumer":
+        return self
+
+    async def __anext__(self) -> Frame:
+        while True:
+            frame = self.stream.get_next_frame(self.last_frame_timestamp)
+
+            if frame:
+                self.last_frame_timestamp = frame.timestamp
+                return frame
+
+            if not self.stream.stream_active:
+                raise StopAsyncIteration
+
+            # Wait for notification of new frame
+            await self.wait_for_new_frame()
+
+
+class FFmpegStream:
+    def __init__(self, worker: "FrameWorkerChild"):
+        self.worker = worker
+
+        width, height = map(int, worker.config["resolution"].split("x"))
+        self.width = width
+        self.height = height
+
+        # Process Management
+        self.ffmpeg_process: Optional[asyncio.subprocess.Process] = None
+        self.active_viewers = 0
+        self.ffmpeg_hw_options: Optional[FfmpegArgs] = None
+        self.server: Optional[TCPConnectionDetails] = None
+        self.socket: Optional[tuple[asyncio.StreamReader, asyncio.StreamWriter]] = None
+        self.exit_task: Optional[asyncio.Task[Any]] = None
+        self.frame_processing_task: Optional[asyncio.Task[Any]] = None
+        self.stderr_task: Optional[asyncio.Task[Any]] = None
+
+        # State
+        self.stream_active = False
+        self.metadata: Optional[FrameMetadata] = None
+        self.is_shutting_down = False
+        self.stream_start_timeout_sec = 60.0  # Timeout in Sekunden
+        self.initialization_task: Optional[asyncio.Task[Any]] = None
+
+        # Reconnection Logic
+        self.reconnect_count = 0
+
+        # Frame Queue Management
+        self.frame_buffer: list[Frame] = []
+        self.last_frame: Optional[Frame] = None
+        self.queue_consumers: set[FrameConsumer] = set()
+        self.frame_processing_active = False
+        self.buffer_duration_ms = 5000
+
+        # Health Check
+        self.health_check_task: Optional[asyncio.Task[Any]] = None
+        self.last_frame_timestamp = 0
+        self.health_check_time = 5.0
+        self.max_frame_time = 15.0
+
+        # Consumer management
+        self.next_consumer_id = 0
+
+    @property
+    def bytes_per_pixel(self) -> float:
+        if self.pixel_format == "rgb24":
+            return 3.0
+        elif self.pixel_format in ["yuv420p", "nv12"]:
+            return 1.5
+        return 1.5
+
+    @property
+    def pixel_format(self) -> PixelFormat:
+        return PIXEL_FORMAT
+
+    @property
+    def frame_size(self) -> int:
+        return int(self.width * self.height * self.bytes_per_pixel)
+
+    async def initialize(self) -> None:
+        if self.initialization_task:
+            await self.initialization_task
+            return
+
+        if self.stream_active:
+            return
+
+        try:
+            self.initialization_task = asyncio.create_task(self._start_stream_process())
+            await self.initialization_task
+        finally:
+            self.initialization_task = None
+
+    def close(self) -> None:
+        if not self.stream_active:
+            return
+
+        self.worker.logger.trace("Closing FFmpeg stream")
+        self.cleanup_resources()
+
+    def cleanup(self) -> None:
+        self.is_shutting_down = True
+        self.cleanup_resources()
+
+    def register_viewer(self) -> FrameConsumer:
+        self.active_viewers += 1
+        consumer = FrameConsumer(self.next_consumer_id, self)
+        self.next_consumer_id += 1
+        self.queue_consumers.add(consumer)
+        return consumer
+
+    def unregister_viewer(self, consumer: FrameConsumer) -> None:
+        self.queue_consumers.discard(consumer)
+        self.active_viewers -= 1
+        if self.active_viewers <= 0:
+            self.active_viewers = 0
+            self.close()
+
+    def get_next_frame(self, timestamp: int) -> Optional[Frame]:
+        if not self.last_frame or self.last_frame.timestamp <= timestamp:
+            return None
+
+        return Frame(
+            data=bytes(self.last_frame.data),
+            timestamp=self.last_frame.timestamp,
+            metadata=self.last_frame.metadata,
+        )
+
+    def get_frame_by_timestamp(self, timestamp: int, max_difference: int = 0) -> Optional[Frame]:
+        if not self.frame_buffer:
+            return None
+
+        # Quick boundary checks
+        first_frame = self.frame_buffer[0]
+        last_frame = self.frame_buffer[-1]
+
+        # Check if timestamp is outside our buffer range (plus max_difference)
+        if (
+            timestamp < first_frame.timestamp - max_difference
+            or timestamp > last_frame.timestamp + max_difference
+        ):
+            return None
+
+        # Binary search for closest frame
+        left = 0
+        right = len(self.frame_buffer) - 1
+
+        while left <= right:
+            mid = (left + right) // 2
+            frame = self.frame_buffer[mid]
+            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 max_difference == 0:
+            return None
+
+        # Find closest frame within max_difference
+        # After binary search, 'left' points to the insertion point
+        # Check frames around this point
+        candidates = [
+            self.frame_buffer[max(0, left - 1)],
+            self.frame_buffer[min(len(self.frame_buffer) - 1, left)],
+        ]
+
+        best_match = None
+        smallest_diff = float("inf")
+
+        for frame in candidates:
+            diff = abs(frame.timestamp - timestamp)
+            if diff <= max_difference and diff < smallest_diff:
+                smallest_diff = diff
+                best_match = frame
+
+        if best_match:
+            return Frame(
+                data=bytes(best_match.data), timestamp=best_match.timestamp, metadata=best_match.metadata
+            )
+
+        return None
+
+    async def _start_stream_process(self) -> None:
+        try:
+            await self._launch_stream()
+            self.reconnect_count = 0
+        except Exception as error:
+            if self.is_shutting_down or self.active_viewers == 0:
+                return
+
+            self.reconnect_count = min(self.reconnect_count + 1, 10)
+            delay_sec = self._calculate_reconnect_delay_sec()
+
+            self.worker.logger.warn(f"Connection failed, retrying in {delay_sec}s")
+            self.worker.logger.debug(f"Error: {str(error)}")
+
+            await asyncio.sleep(delay_sec)
+            self.worker.logger.debug("Retrying connection...")
+            return await self._start_stream_process()
+
+    async def _launch_stream(self) -> None:
+        if self.active_viewers == 0:
+            self.worker.logger.debug("No active consumers, not starting stream")
+            return
+
+        self.cleanup_resources()
+
+        self.server = await create_single_connection_server("127.0.0.1", {"limit": self.frame_size * 10})
+
+        ffmpeg_arguments = await self._prepare_ffmpeg_arguments(self.server.server_url)
+        self.worker.logger.trace(
+            f"Starting FFmpeg with args: {self.worker.config['ffmpegPath']} {' '.join(ffmpeg_arguments)}"
+        )
+
+        self.ffmpeg_process = await asyncio.create_subprocess_exec(
+            self.worker.config["ffmpegPath"],
+            *ffmpeg_arguments,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        self.exit_task = asyncio.create_task(self._on_ffmpeg_exit())
+
+        try:
+            reader, writer = await self.server.connection_promise
+            self.socket = (reader, writer)
+            self.metadata = await self._extract_metadata()
+            self.stream_active = True
+            self.frame_processing_task = asyncio.create_task(self._process_frames())
+            self._start_health_check()
+
+        except Exception as error:
+            self.cleanup_resources()
+            raise error
+
+    async def _on_ffmpeg_exit(self) -> None:
+        if not self.ffmpeg_process:
+            return
+
+        await self.ffmpeg_process.wait()
+        if self.active_viewers > 0 and not self.is_shutting_down:
+            self.worker.logger.warn("FFmpeg process exited unexpectedly, restarting in 10 seconds...")
+            self.cleanup_resources()
+            await asyncio.sleep(10)
+            await self.initialize()
+        else:
+            self.worker.logger.debug("FFmpeg process exited")
+
+    def _start_health_check(self) -> None:
+        if self.health_check_task:
+            self.health_check_task.cancel()
+
+        async def health_check_loop() -> None:
+            while self.stream_active and not self.is_shutting_down:
+                await asyncio.sleep(self.health_check_time)
+
+                if self.active_viewers == 0:
+                    continue
+
+                now = int(datetime.now().timestamp() * 1000)
+                time_since_last_frame_sec = (now - self.last_frame_timestamp) / 1000
+
+                # If no frames for 30 seconds and we have active viewers, restart
+                if (
+                    self.last_frame_timestamp > 0
+                    and time_since_last_frame_sec > self.max_frame_time
+                    and self.active_viewers > 0
+                ):
+                    self.worker.logger.warn(
+                        f"No frames received in {time_since_last_frame_sec:.1f}s! This may be due to a network issue, FFmpeg failure or high load on the system."
+                    )
+                    self.worker.logger.log("Restarting...")
+                    self.cleanup_resources()
+                    asyncio.create_task(self.initialize())
+                    break
+
+        self.health_check_task = asyncio.create_task(health_check_loop())
+
+    async def _process_frames(self) -> None:
+        if self.frame_processing_active or not self.socket or not self.metadata:
+            return
+
+        first_chunk_received = False
+        first_frame_received = False
+        self.frame_processing_active = True
+        reader, _ = self.socket
+        metadata = self.metadata
+        buffer = bytearray()
+        last_buffer_size = 0
+
+        try:
+            while True:
+                chunk = await reader.read(8192)
+
+                if not self.frame_processing_active:
+                    break
+
+                if not chunk:
+                    continue
+
+                if len(buffer) > self.frame_size * 10:
+                    self.worker.logger.warn(
+                        f"Buffer growing: {len(buffer)} Bytes "
+                        f"({len(buffer) / metadata['frameSize']:.2f} frames)"
+                    )
+
+                if not first_chunk_received:
+                    self.worker.logger.trace("First chunk received")
+                    first_chunk_received = True
+
+                buffer.extend(chunk)
+
+                while len(buffer) >= self.frame_size:
+                    frame_data = bytes(buffer[: self.frame_size])
+                    buffer = buffer[self.frame_size :]
+
+                    if last_buffer_size == len(buffer) and len(buffer) > 0:
+                        self.worker.logger.warn(
+                            f"Possible issue: Buffer size not changing: {len(buffer)} bytes"
+                        )
+                        # buffer = bytearray()
+                        break
+
+                    last_buffer_size = len(buffer)
+
+                    if not first_frame_received:
+                        self.worker.logger.trace("First frame received")
+                        first_frame_received = True
+
+                    self._add_frame_to_queue(frame_data, self.metadata)
+        except Exception as error:
+            self.worker.logger.error(f"Error in frame processing: {str(error)}")
+        finally:
+            self.frame_processing_active = False
+
+    def _add_frame_to_queue(self, frame_data: bytes, metadata: FrameMetadata) -> None:
+        timestamp = int(datetime.now().timestamp() * 1000)
+        self.last_frame_timestamp = timestamp
+
+        new_frame = Frame(data=frame_data, timestamp=timestamp, metadata=metadata)
+
+        self.frame_buffer.append(new_frame)
+        self.last_frame = new_frame
+
+        self._cleanup_old_frames()
+
+        for consumer in self.queue_consumers:
+            consumer.notify_new_frame()
+
+    def _cleanup_old_frames(self) -> None:
+        current_time = int(datetime.now().timestamp() * 1000)
+        buffer_threshold = current_time - self.buffer_duration_ms
+
+        while len(self.frame_buffer) > 1 and self.frame_buffer[0].timestamp < buffer_threshold:
+            self.frame_buffer.pop(0)
+
+    async def _extract_metadata(self) -> FrameMetadata:
+        if not self.ffmpeg_process or not self.ffmpeg_process.stderr:
+            raise RuntimeError("FFmpeg process not started or stderr not available")
+
+        metadata_future: asyncio.Future[FrameMetadata] = asyncio.Future()
+
+        async def read_stderr() -> None:
+            try:
+                assert self.ffmpeg_process and self.ffmpeg_process.stderr
+
+                async for line in self.ffmpeg_process.stderr:
+                    if not metadata_future.done() and line:
+                        metadata = self._parse_metadata_from_stderr(line)
+                        if metadata:
+                            self.worker.logger.debug(f"Metadata received: {metadata}")
+                            metadata_future.set_result(metadata)
+            except Exception as e:
+                if not metadata_future.done():
+                    metadata_future.set_exception(e)
+
+        self.stderr_task = asyncio.create_task(read_stderr())
+
+        try:
+            return await asyncio.wait_for(metadata_future, self.stream_start_timeout_sec)
+        except asyncio.TimeoutError as e:
+            raise TimeoutError("FFmpeg stream start timeout") from e
+
+    def _calculate_reconnect_delay_sec(self) -> float:
+        if self.reconnect_count == 10:
+            return 60.0
+        else:
+            return 10.0
+
+    def _parse_metadata_from_stderr(self, data: bytes) -> Optional[FrameMetadata]:
+        stderr_text = data.decode("utf-8", errors="replace")
+
+        match = re.search(METADATA_REGEX, stderr_text)
+        if not match:
+            return None
+
+        resolution = match.group(1)
+        original_width, original_height = map(int, resolution.split("x"))
+        frame_data_size = self.frame_size
+
+        metadata: FrameMetadata = {
+            "format": "nv12" if self.worker.config["decoder"] == "gpu" else "yuv420p",
+            "frameSize": frame_data_size,
+            "width": self.width,
+            "height": self.height,
+            "origHeight": original_height,
+            "origWidth": original_width,
+        }
+
+        return metadata
+
+    async def _prepare_ffmpeg_arguments(self, server_url: str) -> list[str]:
+        if not self.ffmpeg_hw_options:
+            core_manager = await self._create_core_manager_proxy()
+            self.ffmpeg_hw_options = (
+                await core_manager.getHwaccelInfo(
+                    {
+                        "targetCodec": "h264",
+                        "keepOnHardware": True,
+                        "pixelFormat": self.pixel_format,
+                        "scale": {
+                            "width": self.width,
+                            "height": self.height,
+                        },
+                    }
+                )
+            )[0]
+
+        filter_chain = ["showinfo=checksum=0"] + self.ffmpeg_hw_options["hwaccelFilters"]
+        if self.worker.config["fps"] > 0:
+            filter_chain.append(f"fps=fps={self.worker.config['fps']}")
+
+        return [
+            "-hide_banner",
+            *self.ffmpeg_hw_options["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",
+            self.worker.config["cameraSource"],
+            *self.ffmpeg_hw_options["hwDeviceArgs"],
+            "-fps_mode",
+            "cfr",
+            "-vf",
+            ",".join(filter_chain),
+            "-an",
+            "-dn",
+            "-sn",
+            "-f",
+            "rawvideo",
+            f"{server_url}?tcp_nodelay=1",
+        ]
+
+    def cleanup_resources(self) -> None:
+        self.stream_active = False
+        self.metadata = None
+        self.frame_processing_active = False
+
+        if self.health_check_task:
+            self.health_check_task.cancel()
+            self.health_check_task = None
+
+        if self.exit_task:
+            self.exit_task.cancel()
+            self.exit_task = None
+
+        if self.frame_processing_task:
+            self.frame_processing_task.cancel()
+            self.frame_processing_task = None
+
+        if self.stderr_task:
+            self.stderr_task.cancel()
+            self.stderr_task = None
+
+        if self.server:
+            self.server.terminate()
+            self.server = None
+
+        if self.socket:
+            _, writer = self.socket
+            writer.close()
+            self.socket = None
+
+        if self.ffmpeg_process:
+            try:
+                self.ffmpeg_process.kill()
+                self.ffmpeg_process = None
+            except Exception:
+                pass
+
+    async def _create_core_manager_proxy(self) -> CoreManagerInterface:
+        return await self.worker.create_rpc_proxy(
+            CoreManagerInterface, self.worker.namespaces["coreManagerRpc"]
+        )
+
+
+class FrameWorkerChild(ClientInstance, FrameWorkerInterface):
+    def __init__(self) -> None:
+        super().__init__(
+            "service",
+            {
+                "endpoints": os.environ["PROXY_ENDPOINTS"].split(","),
+                "auth": {"user": os.environ["PROXY_USER"], "password": os.environ["PROXY_PASSWORD"]},
+                "tls": {
+                    "cert": os.environ["PROXY_CERT"],
+                    "key": os.environ["PROXY_KEY"],
+                    "ca": os.environ["PROXY_CA"],
+                },
+                "metadata": {
+                    "id": NamespaceManager.frame_worker_namespaces(os.environ["CAMERA_ID"])[
+                        "frameWorkerChild"
+                    ],
+                    "name": "Frame Worker",
+                },
+                "bundled_connection": False,
+            },
+        )
+
+        self.namespaces: FrameWorkerCoreManagerNamespaces = {
+            **NamespaceManager.frame_worker_namespaces(os.environ["CAMERA_ID"]),
+            **NamespaceManager.core_manager_namespaces(),
+        }
+
+        self.config: BaseFrameWorkerConfig = {
+            "cameraId": os.environ["CAMERA_ID"],
+            "cameraName": os.environ["CAMERA_NAME"],
+            "cameraSource": os.environ["CAMERA_SOURCE"],
+            "ffmpegPath": os.environ["FFMPEG_PATH"],
+            "auth": {"user": os.environ["PROXY_USER"], "password": os.environ["PROXY_PASSWORD"]},
+            "proxyEndpoints": os.environ["PROXY_ENDPOINTS"].split(","),
+            "fps": int(os.environ["FPS"]),
+            "resolution": cast(CameraFrameWorkerResolution, os.environ["RESOLUTION"]),
+            "decoder": cast(CameraFrameWorkerDecoder, os.environ["DECODER"]),
+        }
+
+        for key in ["PROXY_USER", "PROXY_PASSWORD", "PROXY_ENDPOINTS", "PROXY_CERT", "PROXY_KEY", "PROXY_CA"]:
+            if key in os.environ:
+                del os.environ[key]
+
+        self.logger = LoggerService(
+            {
+                "prefix": "Frame Worker",
+                "suffix": self.config["cameraName"],
+                "disable_timestamps": os.environ.get("LOGGER_DISABLE_TIMESTAMPS") == "1",
+                "debug_enabled": os.environ.get("LOGGER_LEVEL") in ["debug", "trace"],
+                "trace_enabled": os.environ.get("LOGGER_LEVEL") == "trace",
+            }
+        )
+
+        self.ffmpeg_stream = FFmpegStream(self)
+
+        self.signal_handler = SignalHandler(
+            {
+                "display_name": "[Signal]",
+                "timeout_duration": 1000,
+                "logger": self.logger,
+                "close_function": self._close,
+            }
+        )
+
+        self.stopped = False
+
+    async def run(self) -> None:
+        try:
+            self.signal_handler.setup_handlers()
+            await self.start()
+            await self.signal_handler.shutdown_event.wait()
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await self._close()
+
+    async def on_start(self) -> None:
+        await self.register_rpc_handler(self.namespaces["frameWorkerChildRpc"], self)
+        await self._send_message({"message": "started", "data": {}})
+
+    async def on_before_stop(self) -> None:
+        return await self._close()
+
+    async def on_stop(self) -> None:
+        pass
+
+    @rpc(public=True)
+    async def generateFrames(self, options: Optional[ImageOptions] = None) -> AsyncGenerator[FrameData, None]:
+        consumer = None
+
+        try:
+            consumer = self.ffmpeg_stream.register_viewer()
+            await self.ffmpeg_stream.initialize()
+
+            if not self.ffmpeg_stream.metadata:
+                raise RuntimeError("Stream-Metadaten nicht verfügbar")
+
+            metadata = self.ffmpeg_stream.metadata
+
+            async for frame in consumer:
+                validated_options = self._validate_options(metadata, options)
+
+                if validated_options:
+                    processed_frame = await self.processFrame(
+                        frame.data,
+                        metadata["width"],
+                        metadata["height"],
+                        metadata["format"],
+                        validated_options,
+                    )
+
+                    yield {
+                        "data": processed_frame["image"],
+                        "metadata": metadata,
+                        "timestamp": frame.timestamp,
+                        "info": processed_frame["info"],
+                    }
+                else:
+                    info = self._get_image_information(
+                        metadata["width"], metadata["height"], metadata["format"]
+                    )
+
+                    yield {
+                        "data": frame.data,
+                        "metadata": metadata,
+                        "timestamp": frame.timestamp,
+                        "info": info,
+                    }
+        except Exception as error:
+            self.logger.error(f"Error in frame generation: {error}")
+        finally:
+            if consumer:
+                self.ffmpeg_stream.unregister_viewer(consumer)
+
+    @rpc(public=True)
+    async def getPrebufferedFrame(
+        self,
+        timestamp: int,
+        options: Optional[ImageOptions] = None,
+        max_difference: int = 500,
+    ) -> Optional[FrameData]:
+        prebuffered_frame = self.ffmpeg_stream.get_frame_by_timestamp(timestamp, max_difference)
+        if not prebuffered_frame:
+            self.logger.debug(f"No prebuffered frame found for timestamp {timestamp}")
+            return None
+
+        validated_options = options and self._validate_options(prebuffered_frame.metadata, options)
+
+        if validated_options:
+            processed_frame = await self.processFrame(
+                prebuffered_frame.data,
+                prebuffered_frame.metadata["width"],
+                prebuffered_frame.metadata["height"],
+                prebuffered_frame.metadata["format"],
+                validated_options,
+            )
+
+            return {
+                "data": processed_frame["image"],
+                "metadata": prebuffered_frame.metadata,
+                "timestamp": prebuffered_frame.timestamp,
+                "info": processed_frame["info"],
+            }
+        else:
+            info = self._get_image_information(
+                prebuffered_frame.metadata["width"],
+                prebuffered_frame.metadata["height"],
+                prebuffered_frame.metadata["format"],
+            )
+
+            return {
+                "data": prebuffered_frame.data,
+                "metadata": prebuffered_frame.metadata,
+                "timestamp": prebuffered_frame.timestamp,
+                "info": info,
+            }
+
+    @rpc(public=True)
+    async def processFrame(
+        self,
+        frame: bytes,
+        width: int,
+        height: int,
+        format: Union[DecoderFormat, Literal["rgba"], Literal["gray"]],
+        options: ImageOptions,
+    ) -> FrameBuffer:
+        new_frame = frame if isinstance(frame, bytes) else bytes(frame)
+        info = self._get_image_information(width, height, format, options)
+
+        image = await process_image_threaded(new_frame, width, height, format, options)
+
+        return {"image": image, "info": info}
+
+    def _validate_options(
+        self, metadata: FrameMetadata, options: Optional[ImageOptions] = None
+    ) -> Optional[ImageOptions]:
+        if not options:
+            return None
+
+        validated: ImageOptions = {}
+
+        # Format conversion
+        metadata_format = "rgb" if metadata["format"] == "rgb24" else metadata["format"]
+
+        if "format" in options and "to" in options["format"] and options["format"]["to"] != metadata_format:
+            validated["format"] = options["format"]
+
+        # Cropping
+        if "crop" in options:
+            crop = options["crop"]
+            left = crop.get("left", 0)
+            top = crop.get("top", 0)
+
+            # Validate crop parameters
+            if left >= metadata["width"] or top >= metadata["height"]:
+                return None
+
+            width = min(crop.get("width", metadata["width"]), metadata["width"] - left)
+            height = min(crop.get("height", metadata["height"]), metadata["height"] - top)
+
+            if width <= 0 or height <= 0:
+                return None
+
+            # Skip full frame "crops"
+            if not (left == 0 and top == 0 and width == metadata["width"] and height == metadata["height"]):
+                validated["crop"] = {"left": left, "top": top, "width": width, "height": height}
+
+        # Resizing
+        if "resize" in options:
+            resize = options["resize"]
+            target_width = resize.get("width", 0)
+            target_height = resize.get("height", 0)
+
+            # Handle negative values (which mean "use original")
+            if target_width < 0:
+                target_width = metadata["width"]
+            if target_height < 0:
+                target_height = metadata["height"]
+
+            # Calculate missing dimension if only one is provided
+            if target_width > 0 and target_height == 0:
+                target_height = round((target_width * metadata["height"]) / metadata["width"])
+            elif target_height > 0 and target_width == 0:
+                target_width = round((target_height * metadata["width"]) / metadata["height"])
+
+            # Skip if no resize needed
+            if not (
+                (target_width == 0 and target_height == 0)
+                or (target_width == metadata["width"] and target_height == metadata["height"])
+            ):
+                validated["resize"] = {"width": target_width, "height": target_height}
+
+        # Return None if no transformations are needed
+        return validated if validated else None
+
+    def _get_image_information(
+        self,
+        input_width: int,
+        input_height: int,
+        input_format: Union[DecoderFormat, Literal["rgba"], Literal["gray"]],
+        options: Optional[ImageOptions] = None,
+    ) -> ImageInformation:
+        # Calculate output width
+        width = input_width
+        if options and "resize" in options and options["resize"].get("width"):
+            width = options["resize"]["width"]
+        elif options and "crop" in options:
+            crop = options["crop"]
+            left = crop.get("left", 0)
+            crop_width = crop.get("width", input_width)
+            width = min(crop_width, input_width - left)
+
+        # Calculate output height
+        height = input_height
+        if options and "resize" in options and options["resize"].get("height"):
+            height = options["resize"]["height"]
+        elif options and "crop" in options:
+            crop = options["crop"]
+            top = crop.get("top", 0)
+            crop_height = crop.get("height", input_height)
+            height = min(crop_height, input_height - top)
+
+        # Determine output format
+        format: Union[DecoderFormat, ImageOutputFormat] = input_format
+        if options and "format" in options and "to" in options["format"]:
+            format = options["format"]["to"]
+
+        format = "rgb" if format == "rgb24" else format
+
+        # Calculate channels based on format
+        channels = 1.5
+
+        if format == "rgba":
+            channels = 4
+        elif format == "rgb":
+            channels = 3
+        elif format == "gray":
+            channels = 1
+
+        return {"width": width, "height": height, "channels": channels, "format": format}
+
+    async def _send_message(self, message: WorkerToMainMessage) -> None:
+        await self.send_to_server(message)
+
+    async def _close(self) -> None:
+        if self.stopped:
+            return
+
+        self.stopped = True
+        self.ffmpeg_stream.cleanup()
+        await self.stop()
+
+
+if __name__ == "__main__":
+    worker = FrameWorkerChild()
+    asyncio.run(worker.run())