From 9c6c14f5ddb86b9ca5d74159c3a9849e22aecf62 Mon Sep 17 00:00:00 2001 From: cottongin Date: Thu, 19 Nov 2026 13:40:11 -0500 Subject: [PATCH] feat(cam-helper): add decoupled czcamera-cam picamera2 worker and CZFR/JSON protocol --- cam-helper/bin/czcamera-cam | 77 ++ cam-helper/czcamera_cam/__init__.py | 35 + cam-helper/czcamera_cam/picam2_worker.py | 901 +++++++++++++++++++++++ cam-helper/czcamera_cam/protocol.py | 321 ++++++++ cam-helper/tests/test_picam2_worker.py | 417 +++++++++++ cam-helper/tests/test_protocol.py | 338 +++++++++ 6 files changed, 2089 insertions(+) create mode 100755 cam-helper/bin/czcamera-cam create mode 100644 cam-helper/czcamera_cam/__init__.py create mode 100644 cam-helper/czcamera_cam/picam2_worker.py create mode 100644 cam-helper/czcamera_cam/protocol.py create mode 100644 cam-helper/tests/test_picam2_worker.py create mode 100644 cam-helper/tests/test_protocol.py diff --git a/cam-helper/bin/czcamera-cam b/cam-helper/bin/czcamera-cam new file mode 100755 index 0000000..77c2749 --- /dev/null +++ b/cam-helper/bin/czcamera-cam @@ -0,0 +1,77 @@ +#!/usr/bin/python3 +"""CLI entrypoint for czcamera-cam foreground camera worker.""" + +from __future__ import annotations + +import argparse +import os +import signal +import sys +from typing import Optional + +# Support both source-tree execution (cam-helper/bin/czcamera-cam) +# and packaged installation (/usr/bin/czcamera-cam + /usr/lib/czcamera/czcamera_cam). +_SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__)) +_LOCAL_HELPER_DIR = os.path.dirname(_SCRIPT_DIR) +_SYSTEM_LIB_DIR = "/usr/lib/czcamera" +for _candidate in (_LOCAL_HELPER_DIR, _SYSTEM_LIB_DIR): + if os.path.isdir(os.path.join(_candidate, "czcamera_cam")) and _candidate not in sys.path: + sys.path.insert(0, _candidate) + +from czcamera_cam.picam2_worker import MockCameraDriver, Picam2Worker # noqa: E402 +from czcamera_cam.protocol import FramePipeWriter, JsonProtocolServer # noqa: E402 + + +def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace: + parser = argparse.ArgumentParser( + prog="czcamera-cam", + description="Decoupled camera worker speaking Wire Protocol v1 + CZFR framing.", + ) + parser.add_argument( + "--frame-fd", + type=int, + required=True, + help="Open writable file descriptor for CZFR binary preview frames.", + ) + parser.add_argument( + "--mock-driver", + action="store_true", + help="Use synthetic MockCameraDriver instead of picamera2/libcamera.", + ) + return parser.parse_args(argv) + + +def main(argv: Optional[list[str]] = None) -> int: + args = parse_args(argv) + frame_writer = FramePipeWriter(args.frame_fd, owns_fd=True) + frame_writer.start() + + def build_worker(emit_event): + if args.mock_driver: + return MockCameraDriver(frame_writer=frame_writer, emit_event=emit_event) + return Picam2Worker(frame_writer=frame_writer, emit_event=emit_event) + + server = JsonProtocolServer( + worker_factory=build_worker, + stdin=sys.stdin, + stdout=sys.stdout, + ) + + def _handle_signal(_signum: int, _frame: object) -> None: + server.request_shutdown() + try: + sys.stdin.close() + except OSError: + pass + + signal.signal(signal.SIGTERM, _handle_signal) + signal.signal(signal.SIGINT, _handle_signal) + + try: + return server.run() + finally: + frame_writer.stop() + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/cam-helper/czcamera_cam/__init__.py b/cam-helper/czcamera_cam/__init__.py new file mode 100644 index 0000000..ac3609d --- /dev/null +++ b/cam-helper/czcamera_cam/__init__.py @@ -0,0 +1,35 @@ +"""Decoupled camera helper worker and wire protocol for czcamera.""" + +from .picam2_worker import ( + MockCameraDriver, + Picam2Worker, + compute_scaler_crop, + resolve_transform, +) +from .protocol import ( + CZFR_HEADER_STRUCT, + CZFR_MAGIC, + FLAG_ASPECT_16_9, + PIXFMT_RGB24, + PIXFMT_YUV420, + PROTOCOL_VERSION, + FramePipeWriter, + JsonProtocolServer, + pack_czfr_header, +) + +__all__ = [ + "CZFR_HEADER_STRUCT", + "CZFR_MAGIC", + "FLAG_ASPECT_16_9", + "FramePipeWriter", + "JsonProtocolServer", + "MockCameraDriver", + "PIXFMT_RGB24", + "PIXFMT_YUV420", + "PROTOCOL_VERSION", + "Picam2Worker", + "compute_scaler_crop", + "pack_czfr_header", + "resolve_transform", +] diff --git a/cam-helper/czcamera_cam/picam2_worker.py b/cam-helper/czcamera_cam/picam2_worker.py new file mode 100644 index 0000000..1963637 --- /dev/null +++ b/cam-helper/czcamera_cam/picam2_worker.py @@ -0,0 +1,901 @@ +"""Picamera2 dual-stream worker and MockCameraDriver for czcamera-cam.""" + +from __future__ import annotations + +import os +import shlex +import struct +import threading +import time +from typing import Any, Callable, Optional + +from .protocol import ( + FLAG_ASPECT_16_9, + PIXFMT_YUV420, + PROTOCOL_VERSION, + FramePipeWriter, +) + +# Standard JPEG Annex K Huffman tables for 3-component baseline DCT JPEGs. +_DC_LUM_BITS = bytes([0, 1, 5, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0]) +_DC_LUM_VALS = bytes([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]) +_DC_CHROM_BITS = bytes([0, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0]) +_DC_CHROM_VALS = bytes([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]) + +_AC_LUM_BITS = bytes([0, 2, 1, 3, 3, 2, 4, 3, 5, 5, 4, 4, 0, 0, 1, 0x7D]) +_AC_LUM_VALS = bytes( + [ + 0x01, 0x02, 0x03, 0x00, 0x04, 0x11, 0x05, 0x12, 0x21, 0x31, 0x41, 0x06, + 0x13, 0x51, 0x61, 0x07, 0x22, 0x71, 0x14, 0x32, 0x81, 0x91, 0xA1, 0x08, + 0x23, 0x42, 0xB1, 0xC1, 0x15, 0x52, 0xD1, 0xF0, 0x24, 0x33, 0x62, 0x72, + 0x82, 0x09, 0x0A, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x25, 0x26, 0x27, 0x28, + 0x29, 0x2A, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, + 0x46, 0x47, 0x48, 0x49, 0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, + 0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75, + 0x76, 0x77, 0x78, 0x79, 0x7A, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, + 0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, + 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, + 0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, + 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE1, 0xE2, + 0xE3, 0xE4, 0xE5, 0xE6, 0xE7, 0xE8, 0xE9, 0xEA, 0xF1, 0xF2, 0xF3, 0xF4, + 0xF5, 0xF6, 0xF7, 0xF8, 0xF9, 0xFA, + ] +) + +_AC_CHROM_BITS = bytes([0, 2, 1, 2, 4, 4, 3, 4, 7, 5, 4, 4, 0, 1, 2, 0x77]) +_AC_CHROM_VALS = bytes( + [ + 0x00, 0x01, 0x02, 0x03, 0x11, 0x04, 0x05, 0x21, 0x31, 0x06, 0x12, 0x41, + 0x51, 0x07, 0x61, 0x71, 0x13, 0x22, 0x32, 0x81, 0x08, 0x14, 0x42, 0x91, + 0xA1, 0xB1, 0xC1, 0x09, 0x23, 0x33, 0x52, 0xF0, 0x15, 0x62, 0x72, 0xD1, + 0x0A, 0x16, 0x24, 0x34, 0xE1, 0x25, 0xF1, 0x17, 0x18, 0x19, 0x1A, 0x26, + 0x27, 0x28, 0x29, 0x2A, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, + 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, + 0x59, 0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, + 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, + 0x88, 0x89, 0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, + 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, + 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, + 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA, + 0xE2, 0xE3, 0xE4, 0xE5, 0xE6, 0xE7, 0xE8, 0xE9, 0xEA, 0xF2, 0xF3, 0xF4, + 0xF5, 0xF6, 0xF7, 0xF8, 0xF9, 0xFA, + ] +) + +# 4 consecutive solid-color MCUs (zero DC diff, EOB AC) pack cleanly into 7 bytes +# without any 0xFF bytes: 4 * (00 1010 00 00 00 00) = 56 bits. +_FOUR_ZERO_MCUS = bytes([0x28, 0x00, 0xA0, 0x02, 0x80, 0x0A, 0x00]) + + +def compute_scaler_crop( + pixel_array_size: tuple[int, int], + aspect_w: int, + aspect_h: int, + zoom: float, +) -> tuple[int, int, int, int]: + """Compute even-aligned ScalerCrop (x, y, w, h) centered within sensor bounds.""" + sensor_w, sensor_h = int(pixel_array_size[0]), int(pixel_array_size[1]) + if sensor_w < 2 or sensor_h < 2: + raise ValueError(f"Invalid pixel_array_size: {pixel_array_size}") + if aspect_w <= 0 or aspect_h <= 0: + raise ValueError(f"Invalid aspect ratio: {aspect_w}:{aspect_h}") + + z = max(1.0, float(zoom)) + sensor_aspect = sensor_w / sensor_h + target_aspect = aspect_w / aspect_h + if abs(target_aspect - sensor_aspect) < 0.01: + base_w = float(sensor_w) + base_h = float(sensor_h) + elif aspect_w * sensor_h >= aspect_h * sensor_w: + base_w = float(sensor_w) + base_h = sensor_w * (aspect_h / aspect_w) + else: + base_h = float(sensor_h) + base_w = sensor_h * (aspect_w / aspect_h) + + crop_w = max(2, int(base_w / z) & ~1) + crop_h = max(2, int(base_h / z) & ~1) + crop_w = min(crop_w, sensor_w & ~1) + crop_h = min(crop_h, sensor_h & ~1) + + x = max(0, ((sensor_w - crop_w) // 2) & ~1) + y = max(0, ((sensor_h - crop_h) // 2) & ~1) + return (x, y, crop_w, crop_h) + + +def resolve_transform( + transform_str: str, + camera_properties: Optional[dict[str, Any]], + transform_cls: Any = None, +) -> Any: + """Resolve Wire Protocol v1 transform string into a libcamera.Transform.""" + if transform_cls is None: + from libcamera import Transform # type: ignore[import-not-found] + + transform_cls = Transform + + key = (transform_str or "auto").strip().lower() + if key == "auto": + rotation = int((camera_properties or {}).get("Rotation", 0)) + if rotation == 180: + hflip, vflip = 1, 1 + else: + hflip, vflip = 0, 0 + elif key == "0": + hflip, vflip = 0, 0 + elif key == "180": + hflip, vflip = 1, 1 + elif key == "hflip": + hflip, vflip = 1, 0 + elif key == "vflip": + hflip, vflip = 0, 1 + else: + raise ValueError(f"Unsupported transform: {transform_str}") + + return transform_cls(hflip=hflip, vflip=vflip) + + +def _is_16_9_mode(mode: str, main_w: int, main_h: int) -> bool: + if mode == "video": + return True + if main_h > 0 and abs((main_w / main_h) - (16.0 / 9.0)) < 0.05: + return True + return False + + +def _probe_alsa_available() -> bool: + cards_path = "/proc/asound/cards" + if not os.path.exists(cards_path): + return False + try: + with open(cards_path, "r", encoding="utf-8", errors="ignore") as f: + text = f.read() + return bool(text.strip()) and "no soundcards" not in text.lower() + except OSError: + return False + + +def _write_minimal_jpeg(path: str, width: int, height: int, ev: float = 0.0) -> int: + """Write a valid baseline 3-component JFIF JPEG readable by libjpeg.""" + w = max(1, min(65535, int(width))) + h = max(1, min(65535, int(height))) + + def dht_segment(tc_th: int, bits: bytes, vals: bytes) -> bytes: + payload = bytes([tc_th]) + bits + vals + return b"\xff\xc4" + struct.pack(">H", len(payload) + 2) + payload + + # Quantization tables (uniform 8s) + qtable = bytes([8] * 64) + dqt0 = b"\xff\xdb" + struct.pack(">H", 67) + b"\x00" + qtable + dqt1 = b"\xff\xdb" + struct.pack(">H", 67) + b"\x01" + qtable + + # JFIF APP0 + app0 = ( + b"\xff\xe0\x00\x10JFIF\x00\x01\x01\x00\x00\x01\x00\x01\x00\x00" + ) + + # SOF0 (Baseline DCT, 8-bit, 3 components 1x1 4:4:4) + sof0 = ( + b"\xff\xc0\x00\x11\x08" + + struct.pack(">HH", h, w) + + b"\x03\x01\x11\x00\x02\x11\x01\x03\x11\x01" + ) + + dht = ( + dht_segment(0x00, _DC_LUM_BITS, _DC_LUM_VALS) + + dht_segment(0x01, _DC_CHROM_BITS, _DC_CHROM_VALS) + + dht_segment(0x10, _AC_LUM_BITS, _AC_LUM_VALS) + + dht_segment(0x11, _AC_CHROM_BITS, _AC_CHROM_VALS) + ) + + sos = b"\xff\xda\x00\x0c\x03\x01\x00\x02\x11\x03\x11\x00\x3f\x00" + + # Encode MCUs: 8x8 blocks in 4:4:4 + mcu_cols = (w + 7) // 8 + mcu_rows = (h + 7) // 8 + total_mcus = mcu_cols * mcu_rows + + # Shift Y DC slightly by EV while keeping all remaining MCUs zero-diff + # (For simplicity and speed, use DC diff 0 when EV == 0, or a small valid DC diff). + dc_y_delta = max(-60, min(60, int(round(ev * 25.0)))) + scan = bytearray() + bit_buf = 0 + bit_count = 0 + + def emit_bits(val: int, length: int) -> None: + nonlocal bit_buf, bit_count + bit_buf = (bit_buf << length) | (val & ((1 << length) - 1)) + bit_count += length + while bit_count >= 8: + bit_count -= 8 + byte = (bit_buf >> bit_count) & 0xFF + scan.append(byte) + if byte == 0xFF: + scan.append(0x00) + bit_buf &= (1 << bit_count) - 1 + + # First MCU: Y DC diff (shifted by ev), AC EOB (1010); Cb/Cr DC=0 (00), AC EOB (00) + if dc_y_delta == 0: + emit_bits(0b00, 2) + else: + mag = abs(dc_y_delta) + cat = mag.bit_length() + # Standard DC lum Huffman codes for categories 1..8 + dc_lum_codes = { + 1: (0b010, 3), + 2: (0b011, 3), + 3: (0b100, 3), + 4: (0b101, 3), + 5: (0b110, 3), + 6: (0b1110, 4), + 7: (0b11110, 5), + 8: (0b111110, 6), + } + code, clen = dc_lum_codes[cat] + emit_bits(code, clen) + bits_val = dc_y_delta if dc_y_delta > 0 else ((1 << cat) - 1 + dc_y_delta) + emit_bits(bits_val, cat) + emit_bits(0b1010, 4) # Y AC EOB + emit_bits(0b00, 2) # Cb DC diff 0 + emit_bits(0b00, 2) # Cb AC EOB + emit_bits(0b00, 2) # Cr DC diff 0 + emit_bits(0b00, 2) # Cr AC EOB + + # Remaining MCUs are all 14-bit zero-diff + EOB (`00 1010 00 00 00 00`). + rem = total_mcus - 1 + if bit_count == 0 and rem >= 4: + chunks = rem // 4 + scan.extend(_FOUR_ZERO_MCUS * chunks) + rem %= 4 + + for _ in range(rem): + emit_bits(0b00101000000000, 14) + + if bit_count > 0: + pad = 8 - bit_count + emit_bits((1 << pad) - 1, pad) + + jpeg_bytes = b"\xff\xd8" + app0 + dqt0 + dqt1 + sof0 + dht + sos + bytes(scan) + b"\xff\xd9" + with open(path, "wb") as f: + f.write(jpeg_bytes) + f.flush() + return len(jpeg_bytes) + + +def _write_minimal_mp4_stub(path: str) -> int: + """Write a minimal ISO BMFF MP4 header stub for mock video testing.""" + ftyp = b"\x00\x00\x00\x18ftypmp42\x00\x00\x00\x00mp42isom" + free = b"\x00\x00\x00\x08free" + mdat = b"\x00\x00\x00\x10mdat\x00\x00\x00\x00\x00\x00\x00\x00" + data = ftyp + free + mdat + with open(path, "wb") as f: + f.write(data) + f.flush() + return len(data) + + +class Picam2Worker: + """Real Picamera2 dual-stream (main + lores) worker.""" + + def __init__( + self, + frame_writer: FramePipeWriter, + emit_event: Callable[[dict[str, Any]], None], + picamera2_cls: Any = None, + transform_cls: Any = None, + encoder_cls: Any = None, + ffmpeg_output_cls: Any = None, + audio_probe: Optional[Callable[[], bool]] = None, + ) -> None: + self._frame_writer = frame_writer + self._emit_event = emit_event + self._picamera2_cls = picamera2_cls + self._transform_cls = transform_cls + self._encoder_cls = encoder_cls + self._ffmpeg_output_cls = ffmpeg_output_cls + self._audio_probe = audio_probe or _probe_alsa_available + + self._picam2: Any = None + self._camera_properties: dict[str, Any] = {} + self._sensor_size: tuple[int, int] = (3280, 2464) + self._started = False + self._paused = False + self._recording = False + + self._mode = "photo" + self._main_size = (3280, 2464) + self._preview_size = (226, 170) + self._fps = 30 + self._zoom = 1.0 + self._ev = 0.0 + self._transform_str = "auto" + self._is_16_9 = False + self._last_config_kwargs: Optional[dict[str, Any]] = None + + self._video_tmp_path = "" + self._video_start_monotonic = 0.0 + self._audio_recorded = False + + def _ensure_picamera2_imports(self) -> None: + if self._picamera2_cls is None: + from picamera2 import Picamera2 # type: ignore[import-not-found] + + self._picamera2_cls = Picamera2 + if self._transform_cls is None: + from libcamera import Transform # type: ignore[import-not-found] + + self._transform_cls = Transform + if self._encoder_cls is None: + from picamera2.encoders import H264Encoder # type: ignore[import-not-found] + + self._encoder_cls = H264Encoder + if self._ffmpeg_output_cls is None: + from picamera2.outputs import FfmpegOutput # type: ignore[import-not-found] + + self._ffmpeg_output_cls = FfmpegOutput + + def _open_camera(self) -> None: + self._ensure_picamera2_imports() + self._picam2 = self._picamera2_cls() + self._camera_properties = dict(getattr(self._picam2, "camera_properties", {}) or {}) + raw_size = self._camera_properties.get("PixelArraySize", (3280, 2464)) + self._sensor_size = (int(raw_size[0]), int(raw_size[1])) + + def start(self) -> None: + self._open_camera() + sensor = str(self._camera_properties.get("Model", "imx219")) + has_audio = bool(self._audio_probe()) + self._emit_event( + { + "event": "ready", + "protocol": PROTOCOL_VERSION, + "backend": "picamera2", + "sensor": sensor, + "has_audio": has_audio, + } + ) + + def _extract_lores_yuv420(self, request: Any, width: int, height: int) -> bytes: + if hasattr(request, "make_buffer"): + raw = request.make_buffer("lores") + else: + raw = request.make_array("lores").tobytes() + + mv = memoryview(raw).cast("B") + expected = width * height * 3 // 2 + if len(mv) == expected: + return bytes(mv) + + total_rows = height * 3 // 2 + if total_rows <= 0 or len(mv) < expected: + return bytes(mv[:expected]) + + stride = len(mv) // total_rows + if stride <= width: + return bytes(mv[:expected]) + + out = bytearray(expected) + pos = 0 + # Y plane + for r in range(height): + row_start = r * stride + out[pos : pos + width] = mv[row_start : row_start + width] + pos += width + + # U and V planes + uv_w = width // 2 + uv_h = height // 2 + uv_stride = stride // 2 + u_base = height * stride + v_base = u_base + uv_h * uv_stride + for r in range(uv_h): + u_start = u_base + r * uv_stride + out[pos : pos + uv_w] = mv[u_start : u_start + uv_w] + pos += uv_w + for r in range(uv_h): + v_start = v_base + r * uv_stride + out[pos : pos + uv_w] = mv[v_start : v_start + uv_w] + pos += uv_w + + return bytes(out) + + def _on_request(self, request: Any) -> None: + if self._paused or not self._started: + return + pw, ph = self._preview_size + try: + payload = self._extract_lores_yuv420(request, pw, ph) + except Exception: + return + flags = FLAG_ASPECT_16_9 if self._is_16_9 else 0 + self._frame_writer.push_frame(pw, ph, PIXFMT_YUV420, flags, payload) + + def configure( + self, + mode: str, + main_w: int, + main_h: int, + preview_w: int, + preview_h: int, + fps: int, + zoom: float, + ev: float, + transform: str, + ) -> dict[str, Any]: + if self._recording: + raise RuntimeError("camera_recording") + if self._picam2 is None: + self._open_camera() + + pw = max(2, int(preview_w) & ~1) + ph = max(2, int(preview_h) & ~1) + mw = max(2, int(main_w) & ~1) + mh = max(2, int(main_h) & ~1) + + self._mode = mode + self._main_size = (mw, mh) + self._preview_size = (pw, ph) + self._fps = max(1, int(fps)) + self._transform_str = transform + self._is_16_9 = _is_16_9_mode(mode, mw, mh) + self._last_config_kwargs = { + "mode": mode, + "main_w": mw, + "main_h": mh, + "preview_w": pw, + "preview_h": ph, + "fps": self._fps, + "zoom": float(zoom), + "ev": float(ev), + "transform": transform, + } + + if self._started: + self._picam2.post_callback = None + self._picam2.stop() + self._started = False + + transform_obj = resolve_transform( + transform, + self._camera_properties, + transform_cls=self._transform_cls, + ) + lores_cfg = {"size": (pw, ph), "format": "YUV420"} + if mode == "video": + config = self._picam2.create_video_configuration( + main={"size": (mw, mh), "format": "YUV420"}, + lores=lores_cfg, + transform=transform_obj, + controls={"FrameRate": self._fps}, + ) + else: + config = self._picam2.create_still_configuration( + main={"size": (mw, mh), "format": "RGB888"}, + lores=lores_cfg, + transform=transform_obj, + ) + + self._picam2.configure(config) + self._picam2.post_callback = self._on_request + self._picam2.start() + self._started = True + self._paused = False + + self.set_controls(zoom=zoom, ev=ev) + return { + "mode": self._mode, + "main_w": mw, + "main_h": mh, + "preview_w": pw, + "preview_h": ph, + } + + def set_controls( + self, + zoom: Optional[float] = None, + ev: Optional[float] = None, + ) -> dict[str, Any]: + if zoom is not None: + self._zoom = max(1.0, min(4.0, float(zoom))) + if ev is not None: + self._ev = max(-2.0, min(2.0, float(ev))) + + if self._last_config_kwargs is not None: + self._last_config_kwargs["zoom"] = self._zoom + self._last_config_kwargs["ev"] = self._ev + + if self._picam2 is not None and self._started: + aspect = (16, 9) if self._is_16_9 else (4, 3) + crop = compute_scaler_crop(self._sensor_size, aspect[0], aspect[1], self._zoom) + self._picam2.set_controls( + { + "ScalerCrop": crop, + "ExposureValue": float(self._ev), + } + ) + return {"zoom": self._zoom, "ev": self._ev} + + def capture_still(self, tmp_path: str, width: int, height: int) -> dict[str, Any]: + if self._picam2 is None or not self._started: + raise RuntimeError("camera_not_started") + if self._recording: + raise RuntimeError("camera_busy") + + req_w = max(2, int(width) & ~1) + req_h = max(2, int(height) & ~1) + if (req_w, req_h) != self._main_size and hasattr( + self._picam2, "switch_mode_and_capture_file" + ): + transform_obj = resolve_transform( + self._transform_str, + self._camera_properties, + transform_cls=self._transform_cls, + ) + still_cfg = self._picam2.create_still_configuration( + main={"size": (req_w, req_h), "format": "RGB888"}, + lores={"size": self._preview_size, "format": "YUV420"}, + transform=transform_obj, + ) + self._picam2.switch_mode_and_capture_file(still_cfg, tmp_path, format="jpeg") + self._main_size = (req_w, req_h) + else: + self._picam2.capture_file(tmp_path, format="jpeg") + + file_bytes = os.path.getsize(tmp_path) if os.path.exists(tmp_path) else 0 + return {"width": req_w, "height": req_h, "bytes": file_bytes} + + def start_video( + self, + tmp_path: str, + width: int, + height: int, + fps: int, + bitrate: int, + audio: bool, + ) -> dict[str, Any]: + if self._picam2 is None or self._paused: + raise RuntimeError("camera_not_started") + if self._recording: + raise RuntimeError("already_recording") + + req_w = max(2, int(width) & ~1) + req_h = max(2, int(height) & ~1) + req_fps = max(1, int(fps)) + + if ( + not self._started + or self._mode != "video" + or self._main_size != (req_w, req_h) + or self._fps != req_fps + ): + self.configure( + mode="video", + main_w=req_w, + main_h=req_h, + preview_w=self._preview_size[0], + preview_h=self._preview_size[1], + fps=req_fps, + zoom=self._zoom, + ev=self._ev, + transform=self._transform_str, + ) + + self._ensure_picamera2_imports() + # Ruling 3: staging files end in .mp4.part so ffmpeg needs -f mp4 explicitly. + output_target = f"-f mp4 -movflags +faststart {shlex.quote(tmp_path)}" + + audio_recorded = False + if audio: + encoder = self._encoder_cls(bitrate=int(bitrate)) + output = self._ffmpeg_output_cls( + output_target, + audio=True, + audio_device="default", + audio_samplerate=48000, + audio_codec="aac", + audio_bitrate=128000, + ) + try: + self._picam2.start_recording(encoder, output) + audio_recorded = True + except Exception as exc: # noqa: BLE001 + self._emit_event( + { + "event": "warn", + "code": "audio_unavailable", + "message": f"ALSA capture failed; recording video muted ({exc})", + } + ) + encoder = self._encoder_cls(bitrate=int(bitrate)) + muted_output = self._ffmpeg_output_cls(output_target, audio=False) + self._picam2.start_recording(encoder, muted_output) + audio_recorded = False + else: + encoder = self._encoder_cls(bitrate=int(bitrate)) + muted_output = self._ffmpeg_output_cls(output_target, audio=False) + self._picam2.start_recording(encoder, muted_output) + audio_recorded = False + + self._recording = True + self._video_tmp_path = tmp_path + self._video_start_monotonic = time.monotonic() + self._audio_recorded = audio_recorded + return {"audio_recorded": audio_recorded} + + def stop_video(self) -> dict[str, Any]: + if not self._recording: + raise RuntimeError("not_recording") + self._picam2.stop_recording() + duration_sec = round(max(0.0, time.monotonic() - self._video_start_monotonic), 3) + size_bytes = ( + os.path.getsize(self._video_tmp_path) + if self._video_tmp_path and os.path.exists(self._video_tmp_path) + else 0 + ) + audio_recorded = self._audio_recorded + self._recording = False + self._video_tmp_path = "" + return { + "duration_sec": duration_sec, + "bytes": size_bytes, + "audio_recorded": audio_recorded, + } + + def pause(self) -> dict[str, Any]: + if self._recording: + self.stop_video() + if self._picam2 is not None: + self._picam2.post_callback = None + if self._started: + self._picam2.stop() + self._started = False + self._picam2.close() + self._picam2 = None + self._paused = True + return {} + + def resume(self) -> dict[str, Any]: + if not self._paused and self._picam2 is not None: + return {} + self._open_camera() + self._paused = False + if self._last_config_kwargs is not None: + self.configure(**self._last_config_kwargs) + return {} + + def shutdown(self) -> None: + if self._recording: + try: + self.stop_video() + except Exception: + self._recording = False + if self._picam2 is not None: + try: + self._picam2.post_callback = None + if self._started: + self._picam2.stop() + self._started = False + self._picam2.close() + finally: + self._picam2 = None + self._frame_writer.stop() + + +class MockCameraDriver: + """Synthetic animated camera driver for --mock-driver tests without hardware.""" + + def __init__( + self, + frame_writer: FramePipeWriter, + emit_event: Callable[[dict[str, Any]], None], + has_audio: bool = True, + ) -> None: + self._frame_writer = frame_writer + self._emit_event = emit_event + self._has_audio = has_audio + + self._lock = threading.Lock() + self._stop_event = threading.Event() + self._thread: Optional[threading.Thread] = None + + self._configured = False + self._paused = False + self._recording = False + self._mode = "photo" + self._main_size = (3280, 2464) + self._preview_size = (226, 170) + self._fps = 30 + self._zoom = 1.0 + self._ev = 0.0 + self._transform = "auto" + self._is_16_9 = False + self._frame_counter = 0 + + self._video_tmp_path = "" + self._video_start_monotonic = 0.0 + self._audio_recorded = False + + def start(self) -> None: + self._emit_event( + { + "event": "ready", + "protocol": PROTOCOL_VERSION, + "backend": "mock", + "sensor": "mock-imx219", + "has_audio": self._has_audio, + } + ) + self._stop_event.clear() + self._thread = threading.Thread( + target=self._preview_loop, + name="mock-camera-preview", + daemon=True, + ) + self._thread.start() + + def _build_synthetic_yuv420(self, width: int, height: int, tick: int) -> bytes: + y_size = width * height + uv_size = (width // 2) * (height // 2) + ev_shift = int(round(self._ev * 24.0)) + base_y = max(16, min(235, 110 + ev_shift)) + + y_plane = bytearray(y_size) + bar_x = (tick * 4) % max(1, width) + zoom_band = max(4, int(round(16 * self._zoom))) + for row in range(height): + row_val = max(16, min(235, base_y + ((row * 40) // max(1, height)) - 20)) + offset = row * width + y_plane[offset : offset + width] = bytes([row_val]) * width + # Animated vertical marker moving horizontally + for dx in range(min(zoom_band, width)): + y_plane[offset + (bar_x + dx) % width] = 225 + + u_plane = bytes([118]) * uv_size + v_plane = bytes([142]) * uv_size + return bytes(y_plane) + u_plane + v_plane + + def _preview_loop(self) -> None: + while not self._stop_event.is_set(): + with self._lock: + active = self._configured and not self._paused + pw, ph = self._preview_size + fps = max(1, min(60, self._fps)) + is_16_9 = self._is_16_9 + tick = self._frame_counter + if active: + self._frame_counter += 1 + payload = self._build_synthetic_yuv420(pw, ph, tick) + else: + payload = b"" + if active: + flags = FLAG_ASPECT_16_9 if is_16_9 else 0 + self._frame_writer.push_frame(pw, ph, PIXFMT_YUV420, flags, payload) + self._stop_event.wait(1.0 / fps) + + def configure( + self, + mode: str, + main_w: int, + main_h: int, + preview_w: int, + preview_h: int, + fps: int, + zoom: float, + ev: float, + transform: str, + ) -> dict[str, Any]: + with self._lock: + if self._recording: + raise RuntimeError("camera_recording") + pw = max(2, int(preview_w) & ~1) + ph = max(2, int(preview_h) & ~1) + mw = max(2, int(main_w) & ~1) + mh = max(2, int(main_h) & ~1) + self._mode = mode + self._main_size = (mw, mh) + self._preview_size = (pw, ph) + self._fps = max(1, int(fps)) + self._zoom = max(1.0, min(4.0, float(zoom))) + self._ev = max(-2.0, min(2.0, float(ev))) + self._transform = transform + self._is_16_9 = _is_16_9_mode(mode, mw, mh) + self._configured = True + self._paused = False + return { + "mode": self._mode, + "main_w": mw, + "main_h": mh, + "preview_w": pw, + "preview_h": ph, + } + + def set_controls( + self, + zoom: Optional[float] = None, + ev: Optional[float] = None, + ) -> dict[str, Any]: + with self._lock: + if zoom is not None: + self._zoom = max(1.0, min(4.0, float(zoom))) + if ev is not None: + self._ev = max(-2.0, min(2.0, float(ev))) + return {"zoom": self._zoom, "ev": self._ev} + + def capture_still(self, tmp_path: str, width: int, height: int) -> dict[str, Any]: + with self._lock: + if not self._configured or self._paused: + raise RuntimeError("camera_not_started") + if self._recording: + raise RuntimeError("camera_busy") + ev = self._ev + req_w = max(2, int(width) & ~1) + req_h = max(2, int(height) & ~1) + file_bytes = _write_minimal_jpeg(tmp_path, req_w, req_h, ev=ev) + return {"width": req_w, "height": req_h, "bytes": file_bytes} + + def start_video( + self, + tmp_path: str, + width: int, + height: int, + fps: int, + bitrate: int, + audio: bool, + ) -> dict[str, Any]: + del bitrate # Unused in mock driver + with self._lock: + if self._paused: + raise RuntimeError("camera_not_started") + if self._recording: + raise RuntimeError("already_recording") + self._mode = "video" + self._main_size = (max(2, int(width) & ~1), max(2, int(height) & ~1)) + self._fps = max(1, int(fps)) + self._is_16_9 = True + self._configured = True + self._recording = True + self._video_tmp_path = tmp_path + self._video_start_monotonic = time.monotonic() + self._audio_recorded = bool(audio) and self._has_audio + _write_minimal_mp4_stub(tmp_path) + return {"audio_recorded": self._audio_recorded} + + def stop_video(self) -> dict[str, Any]: + with self._lock: + if not self._recording: + raise RuntimeError("not_recording") + duration_sec = round(max(0.001, time.monotonic() - self._video_start_monotonic), 3) + size_bytes = ( + os.path.getsize(self._video_tmp_path) + if self._video_tmp_path and os.path.exists(self._video_tmp_path) + else 0 + ) + audio_recorded = self._audio_recorded + self._recording = False + self._video_tmp_path = "" + return { + "duration_sec": duration_sec, + "bytes": size_bytes, + "audio_recorded": audio_recorded, + } + + def pause(self) -> dict[str, Any]: + with self._lock: + self._paused = True + if self._recording: + self._recording = False + self._video_tmp_path = "" + return {} + + def resume(self) -> dict[str, Any]: + with self._lock: + self._paused = False + return {} + + def shutdown(self) -> None: + self._stop_event.set() + thread = self._thread + if thread is not None and thread.is_alive(): + thread.join(timeout=1.0) + self._thread = None + self._frame_writer.stop() diff --git a/cam-helper/czcamera_cam/protocol.py b/cam-helper/czcamera_cam/protocol.py new file mode 100644 index 0000000..1d47bf2 --- /dev/null +++ b/cam-helper/czcamera_cam/protocol.py @@ -0,0 +1,321 @@ +"""Wire Protocol v1: CZFR binary frame pipe writer and newline-JSON control server.""" + +from __future__ import annotations + +import json +import os +import select +import struct +import threading +from typing import Any, Callable, Optional, TextIO + +PROTOCOL_VERSION = 1 +CZFR_MAGIC = b"CZFR" +CZFR_HEADER_STRUCT = struct.Struct("<4sHHBBHI") + +PIXFMT_YUV420 = 1 +PIXFMT_RGB24 = 2 + +FLAG_ASPECT_16_9 = 0x01 + + +def pack_czfr_header( + width: int, + height: int, + pixfmt: int, + flags: int, + payload_bytes: int, +) -> bytes: + """Pack the 16-byte little-endian CZFR frame header.""" + if not (0 <= width <= 0xFFFF and 0 <= height <= 0xFFFF): + raise ValueError(f"Frame dimensions out of uint16 range: {width}x{height}") + if pixfmt not in (PIXFMT_YUV420, PIXFMT_RGB24): + raise ValueError(f"Unsupported pixfmt: {pixfmt}") + if not (0 <= flags <= 0xFF): + raise ValueError(f"Flags out of uint8 range: {flags}") + if not (0 <= payload_bytes <= 0xFFFFFFFF): + raise ValueError(f"Payload length out of uint32 range: {payload_bytes}") + return CZFR_HEADER_STRUCT.pack( + CZFR_MAGIC, + width, + height, + pixfmt, + flags, + 0, + payload_bytes, + ) + + +class FramePipeWriter: + """Single-slot latest-frame writer for the dedicated CZFR frame pipe. + + push_frame() never blocks on pipe backpressure: if a previous unconsumed frame + is still queued, it is discarded and replaced by the newest frame. + """ + + def __init__(self, frame_fd: int, owns_fd: bool = False) -> None: + if frame_fd < 0: + raise ValueError(f"Invalid frame_fd: {frame_fd}") + self._fd = frame_fd + self._owns_fd = owns_fd + self._cond = threading.Condition() + self._pending: Optional[tuple[int, int, int, int, bytes]] = None + self._stop = False + self._started = False + self._thread: Optional[threading.Thread] = None + self._frames_pushed = 0 + self._frames_dropped = 0 + self._frames_written = 0 + + try: + os.set_blocking(self._fd, False) + except OSError: + pass + + @property + def frames_pushed(self) -> int: + with self._cond: + return self._frames_pushed + + @property + def frames_dropped(self) -> int: + with self._cond: + return self._frames_dropped + + @property + def frames_written(self) -> int: + with self._cond: + return self._frames_written + + def start(self) -> None: + with self._cond: + if self._started: + return + self._stop = False + self._started = True + self._thread = threading.Thread( + target=self._writer_loop, + name="czfr-pipe-writer", + daemon=True, + ) + self._thread.start() + + def push_frame( + self, + width: int, + height: int, + pixfmt: int, + flags: int, + payload: bytes | bytearray | memoryview, + ) -> None: + """Queue the latest frame without blocking; drop any stale queued frame.""" + data = bytes(payload) + with self._cond: + if self._stop: + return + if self._pending is not None: + self._frames_dropped += 1 + self._pending = (width, height, pixfmt, flags, data) + self._frames_pushed += 1 + self._cond.notify() + + def stop(self, timeout: float = 1.0) -> None: + with self._cond: + self._stop = True + self._pending = None + self._cond.notify_all() + thread = self._thread + if thread is not None and thread.is_alive(): + thread.join(timeout=timeout) + with self._cond: + self._thread = None + self._started = False + if self._owns_fd and self._fd >= 0: + try: + os.close(self._fd) + except OSError: + pass + self._fd = -1 + + def _write_packet(self, packet: bytes) -> bool: + mv = memoryview(packet) + offset = 0 + total = len(packet) + try: + while offset < total: + with self._cond: + if self._stop: + return False + try: + written = os.write(self._fd, mv[offset:]) + except BlockingIOError: + select.select([], [self._fd], [], 0.05) + continue + except (BrokenPipeError, OSError): + return False + if written <= 0: + return False + offset += written + return True + finally: + mv.release() + + def _writer_loop(self) -> None: + while True: + with self._cond: + while self._pending is None and not self._stop: + self._cond.wait() + if self._stop: + return + frame = self._pending + self._pending = None + + assert frame is not None + width, height, pixfmt, flags, payload = frame + header = pack_czfr_header(width, height, pixfmt, flags, len(payload)) + if not self._write_packet(header + payload): + with self._cond: + self._stop = True + return + with self._cond: + self._frames_written += 1 + + +class JsonProtocolServer: + """Newline-delimited JSON control channel on stdin/stdout.""" + + def __init__( + self, + worker_factory: Callable[[Callable[[dict[str, Any]], None]], Any], + stdin: TextIO, + stdout: TextIO, + ) -> None: + self._stdin = stdin + self._stdout = stdout + self._write_lock = threading.Lock() + self._shutdown_requested = False + self._worker = worker_factory(self.emit_event) + + def emit_event(self, payload: dict[str, Any]) -> None: + self._write_json(payload) + + def request_shutdown(self) -> None: + self._shutdown_requested = True + + def _write_json(self, payload: dict[str, Any]) -> None: + line = json.dumps(payload, separators=(",", ":")) + "\n" + with self._write_lock: + try: + self._stdout.write(line) + self._stdout.flush() + except (BrokenPipeError, OSError, ValueError): + self._shutdown_requested = True + + def _reply_ok(self, cmd_id: Any, extra: Optional[dict[str, Any]] = None) -> None: + reply: dict[str, Any] = {"id": cmd_id, "ok": True} + if extra: + reply.update(extra) + self._write_json(reply) + + def _reply_err(self, cmd_id: Any, error: str) -> None: + self._write_json({"id": cmd_id, "ok": False, "error": error}) + + def _handle_command(self, msg: dict[str, Any]) -> None: + cmd_id = msg.get("id") + cmd = msg.get("cmd") + if not isinstance(cmd, str): + self._reply_err(cmd_id, "missing_cmd") + return + + try: + if cmd == "configure": + res = self._worker.configure( + mode=str(msg.get("mode", "photo")), + main_w=int(msg["main_w"]), + main_h=int(msg["main_h"]), + preview_w=int(msg.get("preview_w", 226)), + preview_h=int(msg.get("preview_h", 170)), + fps=int(msg.get("fps", 30)), + zoom=float(msg.get("zoom", 1.0)), + ev=float(msg.get("ev", 0.0)), + transform=str(msg.get("transform", "auto")), + ) + self._reply_ok(cmd_id, res) + elif cmd == "set_controls": + res = self._worker.set_controls( + zoom=float(msg["zoom"]) if "zoom" in msg else None, + ev=float(msg["ev"]) if "ev" in msg else None, + ) + self._reply_ok(cmd_id, res) + elif cmd == "capture_still": + res = self._worker.capture_still( + tmp_path=str(msg["tmp_path"]), + width=int(msg["width"]), + height=int(msg["height"]), + ) + self._reply_ok(cmd_id, res) + elif cmd == "start_video": + res = self._worker.start_video( + tmp_path=str(msg["tmp_path"]), + width=int(msg["width"]), + height=int(msg["height"]), + fps=int(msg.get("fps", 30)), + bitrate=int(msg.get("bitrate", 4000000)), + audio=bool(msg.get("audio", True)), + ) + self._reply_ok(cmd_id, res) + elif cmd == "stop_video": + res = self._worker.stop_video() + self._reply_ok(cmd_id, res) + elif cmd == "pause": + res = self._worker.pause() + self._reply_ok(cmd_id, res) + elif cmd == "resume": + res = self._worker.resume() + self._reply_ok(cmd_id, res) + elif cmd == "shutdown": + self._worker.shutdown() + self._reply_ok(cmd_id) + self._shutdown_requested = True + else: + self._reply_err(cmd_id, f"unknown_cmd:{cmd}") + except Exception as exc: # noqa: BLE001 + self._reply_err(cmd_id, str(exc)) + + def run(self) -> int: + self._worker.start() + try: + while not self._shutdown_requested: + try: + raw_line = self._stdin.readline() + except (OSError, ValueError): + break + if not raw_line: + break + line = raw_line.strip() + if not line: + continue + try: + msg = json.loads(line) + except json.JSONDecodeError as exc: + self.emit_event( + { + "event": "warn", + "code": "bad_command", + "message": f"Invalid JSON command: {exc}", + } + ) + continue + if not isinstance(msg, dict): + self.emit_event( + { + "event": "warn", + "code": "bad_command", + "message": "Command must be a JSON object", + } + ) + continue + self._handle_command(msg) + finally: + self._worker.shutdown() + return 0 diff --git a/cam-helper/tests/test_picam2_worker.py b/cam-helper/tests/test_picam2_worker.py new file mode 100644 index 0000000..26bd43e --- /dev/null +++ b/cam-helper/tests/test_picam2_worker.py @@ -0,0 +1,417 @@ +import os +import tempfile +import unittest + +from czcamera_cam.picam2_worker import ( + Picam2Worker, + compute_scaler_crop, + resolve_transform, +) +from czcamera_cam.protocol import FLAG_ASPECT_16_9, PIXFMT_YUV420 + + +class FakeTransform: + def __init__(self, hflip=0, vflip=0): + self.hflip = int(hflip) + self.vflip = int(vflip) + + def __eq__(self, other): + return ( + isinstance(other, FakeTransform) + and self.hflip == other.hflip + and self.vflip == other.vflip + ) + + def __repr__(self): + return f"FakeTransform(hflip={self.hflip}, vflip={self.vflip})" + + +class FakeFrameWriter: + def __init__(self): + self.frames = [] + + def push_frame(self, width, height, pixfmt, flags, payload): + self.frames.append((width, height, pixfmt, flags, bytes(payload))) + + +class FakeRequest: + def __init__(self, width, height, stride=None): + self.width = width + self.height = height + self.stride = stride or width + + def make_buffer(self, name): + assert name == "lores" + # Produce Y plane (height rows of stride) + U (height//2 rows of stride//2) + V + y_rows = b"".join(bytes([100] * self.width + [255] * (self.stride - self.width)) for _ in range(self.height)) + u_stride = self.stride // 2 + u_w = self.width // 2 + u_rows = b"".join(bytes([128] * u_w + [255] * (u_stride - u_w)) for _ in range(self.height // 2)) + v_rows = b"".join(bytes([129] * u_w + [255] * (u_stride - u_w)) for _ in range(self.height // 2)) + return y_rows + u_rows + v_rows + + +class FakeH264Encoder: + def __init__(self, bitrate=4000000): + self.bitrate = bitrate + + +class FakeFfmpegOutput: + def __init__( + self, + output_filename, + audio=False, + audio_device="default", + audio_samplerate=48000, + audio_codec="aac", + audio_bitrate=128000, + ): + self.output_filename = output_filename + self.audio = audio + self.audio_device = audio_device + self.audio_samplerate = audio_samplerate + self.audio_codec = audio_codec + self.audio_bitrate = audio_bitrate + + +class FakePicamera2: + instances = [] + fail_audio_on_start = False + + def __init__(self, rotation=180): + self.camera_properties = { + "PixelArraySize": (3280, 2464), + "Model": "imx219", + "Rotation": rotation, + } + self.configured = None + self.started = False + self.closed = False + self.controls_history = [] + self.post_callback = None + self.pre_callback = None + self.recording = False + self.recording_attempts = [] + self.captured_files = [] + self.encoder = None + self.output = None + FakePicamera2.instances.append(self) + + def create_still_configuration(self, main=None, lores=None, transform=None, **kwargs): + return { + "type": "still", + "main": main, + "lores": lores, + "transform": transform, + **kwargs, + } + + def create_video_configuration(self, main=None, lores=None, transform=None, controls=None, **kwargs): + return { + "type": "video", + "main": main, + "lores": lores, + "transform": transform, + "controls": controls, + **kwargs, + } + + def configure(self, config): + self.configured = config + + def start(self): + self.started = True + + def stop(self): + self.started = False + + def close(self): + self.closed = True + + def set_controls(self, controls): + self.controls_history.append(dict(controls)) + + def capture_file(self, file_output, name="main", format=None): + self.captured_files.append((file_output, name, format)) + with open(file_output, "wb") as f: + f.write(b"\xff\xd8\xff\xe0MOCKJPEG\xff\xd9") + + def switch_mode_and_capture_file(self, camera_config, file_output, name="main", format=None): + self.configured = camera_config + self.capture_file(file_output, name=name, format=format) + + def start_recording(self, encoder, output): + self.recording_attempts.append((encoder, output)) + if FakePicamera2.fail_audio_on_start and getattr(output, "audio", False): + raise RuntimeError("ALSA device hw:0,0 unavailable") + self.encoder = encoder + self.output = output + self.recording = True + # Extract real path from output_filename string (after -f mp4 -movflags +faststart ) + path = output.output_filename.split()[-1].strip("'\"") + with open(path, "wb") as f: + f.write(b"\x00\x00\x00\x18ftypmp42MOCKMP4") + + def stop_recording(self): + self.recording = False + + def emit_lores_frame(self, stride=None): + lores = self.configured["lores"] + w, h = lores["size"] + req = FakeRequest(w, h, stride=stride) + cb = self.post_callback or self.pre_callback + if cb is not None: + cb(req) + + +class Picam2WorkerTest(unittest.TestCase): + def setUp(self): + FakePicamera2.instances.clear() + FakePicamera2.fail_audio_on_start = False + + def _make_worker(self, rotation=180): + writer = FakeFrameWriter() + events = [] + + def picam_factory(): + return FakePicamera2(rotation=rotation) + + worker = Picam2Worker( + frame_writer=writer, + emit_event=events.append, + picamera2_cls=picam_factory, + transform_cls=FakeTransform, + encoder_cls=FakeH264Encoder, + ffmpeg_output_cls=FakeFfmpegOutput, + audio_probe=lambda: True, + ) + return worker, writer, events + + def test_scaler_crop_4_3_and_16_9_zoom_bounds(self): + sensor = (3280, 2464) + + # 4:3 zoom=1.0 -> full sensor + self.assertEqual(compute_scaler_crop(sensor, 4, 3, 1.0), (0, 0, 3280, 2464)) + + # 16:9 zoom=1.0 -> centered 16:9 within full 3280 width + self.assertEqual(compute_scaler_crop(sensor, 16, 9, 1.0), (0, 310, 3280, 1844)) + + # zoom=2.0 halves dimensions centered + self.assertEqual(compute_scaler_crop(sensor, 4, 3, 2.0), (820, 616, 1640, 1232)) + x16, y16, w16, h16 = compute_scaler_crop(sensor, 16, 9, 2.0) + self.assertEqual((w16, h16), (1640, 922)) + self.assertEqual(x16, 820) + self.assertEqual(y16 % 2, 0) + self.assertGreaterEqual(y16, 310) + + # zoom=4.0 -> even-aligned non-negative bounds within sensor + for aspect in ((4, 3), (16, 9)): + x, y, w, h = compute_scaler_crop(sensor, aspect[0], aspect[1], 4.0) + self.assertGreaterEqual(x, 0) + self.assertGreaterEqual(y, 0) + self.assertGreater(w, 0) + self.assertGreater(h, 0) + self.assertLessEqual(x + w, sensor[0]) + self.assertLessEqual(y + h, sensor[1]) + self.assertEqual(x % 2, 0) + self.assertEqual(y % 2, 0) + self.assertEqual(w % 2, 0) + self.assertEqual(h % 2, 0) + + def test_resolve_transform_auto_and_explicit(self): + self.assertEqual( + resolve_transform("auto", {"Rotation": 180}, transform_cls=FakeTransform), + FakeTransform(hflip=1, vflip=1), + ) + self.assertEqual( + resolve_transform("auto", {"Rotation": 0}, transform_cls=FakeTransform), + FakeTransform(hflip=0, vflip=0), + ) + self.assertEqual( + resolve_transform("180", {"Rotation": 0}, transform_cls=FakeTransform), + FakeTransform(hflip=1, vflip=1), + ) + self.assertEqual( + resolve_transform("0", {"Rotation": 180}, transform_cls=FakeTransform), + FakeTransform(hflip=0, vflip=0), + ) + self.assertEqual( + resolve_transform("hflip", {"Rotation": 0}, transform_cls=FakeTransform), + FakeTransform(hflip=1, vflip=0), + ) + self.assertEqual( + resolve_transform("vflip", {"Rotation": 0}, transform_cls=FakeTransform), + FakeTransform(hflip=0, vflip=1), + ) + + def test_dual_stream_preview_continues_during_video_recording(self): + worker, writer, events = self._make_worker() + worker.start() + self.assertEqual(events[0]["event"], "ready") + self.assertEqual(events[0]["protocol"], 1) + self.assertEqual(events[0]["backend"], "picamera2") + + picam = FakePicamera2.instances[-1] + worker.configure( + mode="video", + main_w=1280, + main_h=720, + preview_w=226, + preview_h=128, + fps=30, + zoom=1.0, + ev=0.0, + transform="auto", + ) + self.assertEqual(picam.configured["type"], "video") + self.assertEqual(picam.configured["lores"], {"size": (226, 128), "format": "YUV420"}) + self.assertEqual(picam.configured["transform"], FakeTransform(hflip=1, vflip=1)) + + with tempfile.TemporaryDirectory() as tmpdir: + video_path = os.path.join(tmpdir, ".VID_20261119_124000.mp4.part") + res = worker.start_video( + tmp_path=video_path, + width=1280, + height=720, + fps=30, + bitrate=4000000, + audio=True, + ) + self.assertTrue(res["audio_recorded"]) + self.assertTrue(picam.recording) + self.assertIsInstance(picam.encoder, FakeH264Encoder) + self.assertEqual(picam.encoder.bitrate, 4000000) + self.assertIsInstance(picam.output, FakeFfmpegOutput) + # Ruling 3: explicit MP4 muxer flags for .mp4.part staging path + self.assertIn("-f mp4", picam.output.output_filename) + self.assertIn("-movflags +faststart", picam.output.output_filename) + self.assertIn(video_path, picam.output.output_filename) + + # Simulate lores callbacks firing during active recording with padded stride 256 + picam.emit_lores_frame(stride=256) + picam.emit_lores_frame(stride=256) + self.assertEqual(len(writer.frames), 2) + w, h, pixfmt, flags, payload = writer.frames[-1] + self.assertEqual((w, h, pixfmt, flags), (226, 128, PIXFMT_YUV420, FLAG_ASPECT_16_9)) + self.assertEqual(len(payload), 226 * 128 * 3 // 2) + # Verify stride padding (0xFF bytes) was stripped out cleanly + self.assertNotIn(255, payload) + + stop_res = worker.stop_video() + self.assertFalse(picam.recording) + self.assertTrue(stop_res["audio_recorded"]) + self.assertGreater(stop_res["bytes"], 0) + self.assertGreaterEqual(stop_res["duration_sec"], 0.0) + + def test_audio_init_failure_falls_back_to_muted_and_emits_warn(self): + FakePicamera2.fail_audio_on_start = True + worker, _, events = self._make_worker() + worker.start() + worker.configure( + mode="video", + main_w=1280, + main_h=720, + preview_w=226, + preview_h=128, + fps=30, + zoom=1.0, + ev=0.0, + transform="0", + ) + + with tempfile.TemporaryDirectory() as tmpdir: + video_path = os.path.join(tmpdir, ".VID_muted.mp4.part") + res = worker.start_video( + tmp_path=video_path, + width=1280, + height=720, + fps=30, + bitrate=4000000, + audio=True, + ) + self.assertFalse(res["audio_recorded"]) + + picam = FakePicamera2.instances[-1] + self.assertEqual(len(picam.recording_attempts), 2) + self.assertTrue(picam.recording_attempts[0][1].audio) + self.assertFalse(picam.recording_attempts[1][1].audio) + self.assertTrue(picam.recording) + + warns = [e for e in events if e.get("event") == "warn"] + self.assertEqual(len(warns), 1) + self.assertEqual(warns[0]["code"], "audio_unavailable") + + stop_res = worker.stop_video() + self.assertFalse(stop_res["audio_recorded"]) + + def test_pause_and_resume_release_and_reacquire_camera(self): + worker, _, _ = self._make_worker() + worker.start() + first_picam = FakePicamera2.instances[-1] + + worker.configure( + mode="photo", + main_w=3280, + main_h=2464, + preview_w=226, + preview_h=170, + fps=30, + zoom=2.0, + ev=0.5, + transform="hflip", + ) + self.assertTrue(first_picam.started) + self.assertIn( + {"ScalerCrop": (820, 616, 1640, 1232), "ExposureValue": 0.5}, + first_picam.controls_history, + ) + + worker.pause() + self.assertFalse(first_picam.started) + self.assertTrue(first_picam.closed) + + worker.resume() + self.assertEqual(len(FakePicamera2.instances), 2) + second_picam = FakePicamera2.instances[-1] + self.assertTrue(second_picam.started) + self.assertEqual(second_picam.configured["main"]["size"], (3280, 2464)) + self.assertEqual(second_picam.configured["lores"]["size"], (226, 170)) + self.assertEqual(second_picam.configured["transform"], FakeTransform(hflip=1, vflip=0)) + self.assertIn( + {"ScalerCrop": (820, 616, 1640, 1232), "ExposureValue": 0.5}, + second_picam.controls_history, + ) + + def test_capture_still_uses_jpeg_format_for_tmp_extension(self): + worker, _, _ = self._make_worker() + worker.start() + picam = FakePicamera2.instances[-1] + worker.configure( + mode="photo", + main_w=3280, + main_h=2464, + preview_w=226, + preview_h=170, + fps=30, + zoom=1.0, + ev=0.0, + transform="auto", + ) + + with tempfile.TemporaryDirectory() as tmpdir: + still_a = os.path.join(tmpdir, ".IMG_1.jpg.tmp") + res_a = worker.capture_still(still_a, 3280, 2464) + self.assertEqual(res_a["width"], 3280) + self.assertEqual(res_a["height"], 2464) + self.assertGreater(res_a["bytes"], 0) + self.assertEqual(picam.captured_files[-1], (still_a, "main", "jpeg")) + + still_b = os.path.join(tmpdir, ".IMG_2.jpg.tmp") + res_b = worker.capture_still(still_b, 1640, 1232) + self.assertEqual(res_b["width"], 1640) + self.assertEqual(res_b["height"], 1232) + self.assertEqual(picam.captured_files[-1], (still_b, "main", "jpeg")) + + +if __name__ == "__main__": + unittest.main() diff --git a/cam-helper/tests/test_protocol.py b/cam-helper/tests/test_protocol.py new file mode 100644 index 0000000..e06c08d --- /dev/null +++ b/cam-helper/tests/test_protocol.py @@ -0,0 +1,338 @@ +import json +import os +import select +import struct +import subprocess +import sys +import tempfile +import threading +import time +import unittest + +from czcamera_cam.protocol import ( + CZFR_HEADER_STRUCT, + CZFR_MAGIC, + FLAG_ASPECT_16_9, + PIXFMT_RGB24, + PIXFMT_YUV420, + FramePipeWriter, + pack_czfr_header, +) + + +def _read_exact(fd: int, n: int, timeout: float = 5.0) -> bytes: + buf = bytearray() + deadline = time.monotonic() + timeout + while len(buf) < n: + remaining = deadline - time.monotonic() + if remaining <= 0: + raise TimeoutError(f"Timed out reading {n} bytes from fd {fd} (got {len(buf)})") + rlist, _, _ = select.select([fd], [], [], remaining) + if not rlist: + continue + chunk = os.read(fd, n - len(buf)) + if not chunk: + raise EOFError(f"EOF on fd {fd} after {len(buf)}/{n} bytes") + buf.extend(chunk) + return bytes(buf) + + +def _read_czfr_frame(fd: int, timeout: float = 5.0): + hdr = _read_exact(fd, CZFR_HEADER_STRUCT.size, timeout=timeout) + magic, width, height, pixfmt, flags, reserved, payload_len = CZFR_HEADER_STRUCT.unpack(hdr) + payload = _read_exact(fd, payload_len, timeout=timeout) + return magic, width, height, pixfmt, flags, reserved, payload + + +class ProtocolTest(unittest.TestCase): + def test_czfr_frame_header_packing(self): + payload_len = 226 * 170 * 3 // 2 + hdr = pack_czfr_header(226, 170, PIXFMT_YUV420, 0, payload_len) + self.assertEqual(len(hdr), 16) + self.assertEqual( + hdr, + struct.pack("<4sHHBBHI", b"CZFR", 226, 170, 1, 0, 0, payload_len), + ) + magic, w, h, pixfmt, flags, reserved, plen = struct.unpack("<4sHHBBHI", hdr) + self.assertEqual(magic, CZFR_MAGIC) + self.assertEqual(w, 226) + self.assertEqual(h, 170) + self.assertEqual(pixfmt, PIXFMT_YUV420) + self.assertEqual(flags, 0) + self.assertEqual(reserved, 0) + self.assertEqual(plen, payload_len) + + hdr_16_9 = pack_czfr_header(226, 128, PIXFMT_RGB24, FLAG_ASPECT_16_9, 226 * 128 * 3) + self.assertEqual(struct.unpack("<4sHHBBHI", hdr_16_9)[3:5], (2, 1)) + + def test_frame_pipe_writer_drops_stale_frames_under_backpressure(self): + r_fd, w_fd = os.pipe() + writer = FramePipeWriter(w_fd, owns_fd=False) + writer.start() + try: + # Fill the pipe buffer first by writing directly to w_fd or pushing + # large frames without reading from r_fd. + # Each frame is 128 KiB, so after 1-2 frames the OS pipe buffer fills. + frame_size = 128 * 1024 + + # Push frame 0 to get the writer thread blocked in os.write / select. + writer.push_frame(226, 170, PIXFMT_YUV420, 0, b"\x00" * frame_size) + time.sleep(0.05) + + # Now push 20 frames in a tight loop while consumer is stalled. + t0 = time.monotonic() + for idx in range(1, 21): + payload = bytes([idx]) * frame_size + writer.push_frame(226, 170, PIXFMT_YUV420, 0, payload) + elapsed = time.monotonic() - t0 + + # push_frame() must never block on the stalled pipe. + self.assertLess(elapsed, 0.2, f"push_frame stalled for {elapsed:.3f}s") + self.assertGreater(writer.frames_dropped, 0) + + # Drain all frames available until we see the latest (idx == 20). + seen_markers = [] + deadline = time.monotonic() + 5.0 + while time.monotonic() < deadline: + magic, w, h, pixfmt, flags, reserved, payload = _read_czfr_frame(r_fd, timeout=2.0) + self.assertEqual(magic, b"CZFR") + self.assertEqual((w, h, pixfmt, flags, reserved), (226, 170, PIXFMT_YUV420, 0, 0)) + self.assertEqual(len(payload), frame_size) + seen_markers.append(payload[0]) + if payload[0] == 20: + break + + self.assertIn(20, seen_markers) + self.assertLess(len(seen_markers), 21) + finally: + writer.stop() + os.close(r_fd) + os.close(w_fd) + + def test_cli_mock_driver_end_to_end(self): + repo_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + bin_path = os.path.join(repo_root, "cam-helper", "bin", "czcamera-cam") + self.assertTrue(os.path.isfile(bin_path), f"Missing executable {bin_path}") + self.assertTrue(os.access(bin_path, os.X_OK), f"{bin_path} must be executable") + + r_fd, w_fd = os.pipe() + os.set_inheritable(w_fd, True) + + with tempfile.TemporaryDirectory() as tmpdir: + still_tmp = os.path.join(tmpdir, ".IMG_test.jpg.tmp") + video_tmp = os.path.join(tmpdir, ".VID_test.mp4.part") + + proc = subprocess.Popen( + [bin_path, "--frame-fd", str(w_fd), "--mock-driver"], + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + pass_fds=(w_fd,), + text=True, + bufsize=1, + ) + os.close(w_fd) + + def send_cmd(obj: dict) -> dict: + assert proc.stdin is not None and proc.stdout is not None + proc.stdin.write(json.dumps(obj) + "\n") + proc.stdin.flush() + while True: + line = proc.stdout.readline() + self.assertTrue(line, "Unexpected EOF from czcamera-cam stdout") + msg = json.loads(line) + if "id" in msg and msg["id"] == obj["id"]: + return msg + + try: + assert proc.stdout is not None + ready_line = proc.stdout.readline() + self.assertTrue(ready_line, "Expected ready event on startup") + ready = json.loads(ready_line) + self.assertEqual(ready["event"], "ready") + self.assertEqual(ready["protocol"], 1) + self.assertEqual(ready["backend"], "mock") + self.assertIn("has_audio", ready) + + # Configure 4:3 photo mode + rep = send_cmd( + { + "id": 1, + "cmd": "configure", + "mode": "photo", + "main_w": 3280, + "main_h": 2464, + "preview_w": 226, + "preview_h": 170, + "fps": 30, + "zoom": 1.0, + "ev": 0.0, + "transform": "auto", + } + ) + self.assertTrue(rep["ok"]) + + # Expect at least one CZFR frame on frame_fd + magic, w, h, pixfmt, flags, reserved, payload = _read_czfr_frame(r_fd, timeout=3.0) + self.assertEqual(magic, b"CZFR") + self.assertEqual((w, h), (226, 170)) + self.assertEqual(pixfmt, PIXFMT_YUV420) + self.assertEqual(flags, 0) + self.assertEqual(reserved, 0) + self.assertEqual(len(payload), 226 * 170 * 3 // 2) + + # Live set_controls + rep = send_cmd({"id": 2, "cmd": "set_controls", "zoom": 2.0, "ev": -0.5}) + self.assertTrue(rep["ok"]) + + # Still capture writes valid JPEG to tmp_path + rep = send_cmd( + { + "id": 3, + "cmd": "capture_still", + "tmp_path": still_tmp, + "width": 640, + "height": 480, + } + ) + self.assertTrue(rep["ok"]) + self.assertEqual(rep["width"], 640) + self.assertEqual(rep["height"], 480) + self.assertGreater(rep["bytes"], 100) + self.assertTrue(os.path.isfile(still_tmp)) + with open(still_tmp, "rb") as f: + jpg = f.read() + self.assertTrue(jpg.startswith(b"\xff\xd8")) + self.assertTrue(jpg.endswith(b"\xff\xd9")) + + # Video configure + start_video -> stop_video + rep = send_cmd( + { + "id": 4, + "cmd": "configure", + "mode": "video", + "main_w": 1280, + "main_h": 720, + "preview_w": 226, + "preview_h": 128, + "fps": 30, + "zoom": 1.0, + "ev": 0.0, + "transform": "0", + } + ) + self.assertTrue(rep["ok"]) + + rep = send_cmd( + { + "id": 5, + "cmd": "start_video", + "tmp_path": video_tmp, + "width": 1280, + "height": 720, + "fps": 30, + "bitrate": 4000000, + "audio": True, + } + ) + self.assertTrue(rep["ok"]) + self.assertIn("audio_recorded", rep) + + # Drain until we see a 16:9 frame while recording + saw_16_9 = False + for _ in range(30): + magic, w, h, pixfmt, flags, _, _ = _read_czfr_frame(r_fd, timeout=3.0) + if (w, h) == (226, 128) and (flags & FLAG_ASPECT_16_9): + saw_16_9 = True + break + self.assertTrue(saw_16_9, "Expected 16:9 CZFR preview frame during video recording") + + time.sleep(0.05) + rep = send_cmd({"id": 6, "cmd": "stop_video"}) + self.assertTrue(rep["ok"]) + self.assertGreater(rep["duration_sec"], 0.0) + self.assertGreater(rep["bytes"], 0) + self.assertIn("audio_recorded", rep) + self.assertTrue(os.path.isfile(video_tmp)) + + # Pause & resume + rep = send_cmd({"id": 7, "cmd": "pause"}) + self.assertTrue(rep["ok"]) + rep = send_cmd({"id": 8, "cmd": "resume"}) + self.assertTrue(rep["ok"]) + + # Shutdown + rep = send_cmd({"id": 9, "cmd": "shutdown"}) + self.assertTrue(rep["ok"]) + + rc = proc.wait(timeout=5.0) + self.assertEqual(rc, 0, f"stderr={proc.stderr.read() if proc.stderr else ''}") + finally: + os.close(r_fd) + if proc.poll() is None: + proc.kill() + proc.wait(timeout=5.0) + if proc.stdin: + proc.stdin.close() + if proc.stdout: + proc.stdout.close() + if proc.stderr: + proc.stderr.close() + + def test_invalid_json_and_unknown_command_do_not_crash(self): + repo_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + bin_path = os.path.join(repo_root, "cam-helper", "bin", "czcamera-cam") + r_fd, w_fd = os.pipe() + os.set_inheritable(w_fd, True) + + proc = subprocess.Popen( + [bin_path, "--frame-fd", str(w_fd), "--mock-driver"], + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + pass_fds=(w_fd,), + text=True, + bufsize=1, + ) + os.close(w_fd) + try: + assert proc.stdin is not None and proc.stdout is not None + ready = json.loads(proc.stdout.readline()) + self.assertEqual(ready["event"], "ready") + + # Malformed JSON triggers warn without exiting + proc.stdin.write("{not-valid-json\n") + proc.stdin.flush() + warn_msg = json.loads(proc.stdout.readline()) + self.assertEqual(warn_msg["event"], "warn") + self.assertEqual(warn_msg["code"], "bad_command") + + # Unknown command returns ok=False + proc.stdin.write(json.dumps({"id": 42, "cmd": "bogus"}) + "\n") + proc.stdin.flush() + err_msg = json.loads(proc.stdout.readline()) + self.assertEqual(err_msg["id"], 42) + self.assertFalse(err_msg["ok"]) + self.assertIn("unknown_cmd", err_msg["error"]) + + # Clean shutdown still works + proc.stdin.write(json.dumps({"id": 43, "cmd": "shutdown"}) + "\n") + proc.stdin.flush() + bye = json.loads(proc.stdout.readline()) + self.assertEqual(bye, {"id": 43, "ok": True}) + self.assertEqual(proc.wait(timeout=5.0), 0) + finally: + os.close(r_fd) + if proc.poll() is None: + proc.kill() + proc.wait(timeout=5.0) + if proc.stdin: + proc.stdin.close() + if proc.stdout: + proc.stdout.close() + if proc.stderr: + proc.stderr.close() + + +if __name__ == "__main__": + unittest.main()