2026-11-19 13:40:11 -05:00
|
|
|
"""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,
|
2026-11-19 13:47:24 -05:00
|
|
|
wakeup_fd: Optional[int] = None,
|
2026-11-19 13:40:11 -05:00
|
|
|
) -> None:
|
|
|
|
|
self._stdin = stdin
|
|
|
|
|
self._stdout = stdout
|
2026-11-19 13:47:24 -05:00
|
|
|
self._wakeup_fd = wakeup_fd
|
2026-11-19 13:40:11 -05:00
|
|
|
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))
|
|
|
|
|
|
2026-11-19 13:47:24 -05:00
|
|
|
def _get_stdin_fd(self) -> Optional[int]:
|
|
|
|
|
try:
|
|
|
|
|
fd = self._stdin.fileno()
|
|
|
|
|
except (AttributeError, OSError, ValueError):
|
|
|
|
|
return None
|
|
|
|
|
return fd if isinstance(fd, int) and fd >= 0 else None
|
|
|
|
|
|
|
|
|
|
def _read_line_fd(self, stdin_fd: int, wakeup_fd: int, buf: bytearray) -> str:
|
|
|
|
|
while True:
|
|
|
|
|
nl = buf.find(b"\n")
|
|
|
|
|
if nl != -1:
|
|
|
|
|
line_bytes = bytes(buf[: nl + 1])
|
|
|
|
|
del buf[: nl + 1]
|
|
|
|
|
return line_bytes.decode("utf-8", errors="replace")
|
|
|
|
|
|
|
|
|
|
if self._shutdown_requested:
|
|
|
|
|
return ""
|
|
|
|
|
|
|
|
|
|
try:
|
|
|
|
|
rlist, _, _ = select.select([stdin_fd, wakeup_fd], [], [], 0.25)
|
|
|
|
|
except (InterruptedError, OSError, ValueError):
|
|
|
|
|
if self._shutdown_requested:
|
|
|
|
|
return ""
|
|
|
|
|
continue
|
|
|
|
|
|
|
|
|
|
if wakeup_fd in rlist:
|
|
|
|
|
while True:
|
|
|
|
|
try:
|
|
|
|
|
drained = os.read(wakeup_fd, 256)
|
|
|
|
|
if not drained:
|
|
|
|
|
break
|
|
|
|
|
except BlockingIOError:
|
|
|
|
|
break
|
|
|
|
|
except OSError:
|
|
|
|
|
break
|
|
|
|
|
if self._shutdown_requested:
|
|
|
|
|
return ""
|
|
|
|
|
|
|
|
|
|
if stdin_fd in rlist:
|
|
|
|
|
try:
|
|
|
|
|
chunk = os.read(stdin_fd, 4096)
|
|
|
|
|
except BlockingIOError:
|
|
|
|
|
continue
|
|
|
|
|
except OSError:
|
|
|
|
|
return ""
|
|
|
|
|
if not chunk:
|
|
|
|
|
if buf:
|
|
|
|
|
tail = bytes(buf).decode("utf-8", errors="replace")
|
|
|
|
|
buf.clear()
|
|
|
|
|
return tail
|
|
|
|
|
return ""
|
|
|
|
|
buf.extend(chunk)
|
|
|
|
|
|
2026-11-19 13:40:11 -05:00
|
|
|
def run(self) -> int:
|
|
|
|
|
self._worker.start()
|
2026-11-19 13:47:24 -05:00
|
|
|
stdin_fd = self._get_stdin_fd() if self._wakeup_fd is not None else None
|
|
|
|
|
fd_buf = bytearray()
|
2026-11-19 13:40:11 -05:00
|
|
|
try:
|
|
|
|
|
while not self._shutdown_requested:
|
2026-11-19 13:47:24 -05:00
|
|
|
if stdin_fd is not None and self._wakeup_fd is not None:
|
|
|
|
|
raw_line = self._read_line_fd(stdin_fd, self._wakeup_fd, fd_buf)
|
|
|
|
|
else:
|
|
|
|
|
try:
|
|
|
|
|
raw_line = self._stdin.readline()
|
|
|
|
|
except (OSError, ValueError):
|
|
|
|
|
break
|
2026-11-19 13:40:11 -05:00
|
|
|
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
|