> This project was developed entirely with AI coding assistance (Google Neon) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.
`czcamera` separates user-space UI, image processing, media assembly, and storage management in C++17 from Raspberry Pi hardware capture in Python 3 (`python3-picamera2`) through an explicit backend abstraction (`cz::ICameraBackend`).
Sony IMX219 (3280x2464) + ES8389 MEMS Mic (ALSA default)
```
### Replacing `picamera2` with Native `libcamera` Later
`czcamera` C++ sources have **zero**`#include <libcamera/...>` or CMake linkage to `libcamera.so`. To swap `python3-picamera2` for a native C++ `libcamera` backend (or `rpicam-apps`), implement [`app/src/camera_backend.hpp`](../app/src/camera_backend.hpp) (`cz::ICameraBackend`) and return it from `create_camera_backend()` in [`app/src/sim_backend.cpp`](../app/src/sim_backend.cpp) without touching `UiController`, `AppView`, filters, timelapse, or gallery code.
---
## 2. Camera Helper Wire Protocol v1
`SubprocessCameraBackend` launches `/usr/bin/czcamera-cam --frame-fd <N>` (overridable via `CZCAMERA_CAM_BIN`, passing `--mock-driver` in protocol tests) with an inherited read/write pipe (`frame_fd`).
### Control Channel (`stdin` / `stdout` Newline-Delimited JSON)
Requests from C++ → Python carry `"id"` (uint64) and `"cmd"`:
| `capture_still` | `tmp_path`, `width`, `height` | `bytes` (temporarily stops video / switches to still format if needed and restores stream config) |
Every preview frame packet starts with a fixed **16-byte little-endian** header (`struct.Struct("<4sHHBBHI")`) followed immediately by `payload_len` bytes:
-`FramePipeWriter` uses a single-slot bounded queue (`_pending`). When the UI consumer slows down, `push_frame()` drops any unconsumed queued packet and replaces it with the newest frame, keeping camera/H.264 encoder threads non-blocking.
-`Picam2Worker._extract_lores_yuv420()` inspects the negotiated `lores``stride` (handling 64-byte DMA padding such as `256` for `226px`) and strips row padding before packing tight `YUV420` payloads.
---
## 3. Target Hardware Constraints & Media Pipelines
- **Timelapse Compilation:** [`TimelapseEngine`](../app/src/timelapse_engine.hpp) invokes `ffmpeg` with `-threads 1 -filter_threads 1` and scales `4:3` (`2mp`/`8mp`) to `1024:768` or `16:9` (`1080p`) to `1280:720` (`bilinear,setsar=1`) to stay safely within CardputerZero's 512 MB RAM / 64 MB CMA budget and VideoCore IV `/dev/video11` constraints, encoding with `h264_v4l2m2m` (`-num_output_buffers 4`, `5M`, `yuv420p`) and falling back to low-memory `libx264` (`-threads 2 -preset ultrafast -crf 23 -x264-params rc-lookahead=0:ref=1:bframes=0:threads=2:lookahead-threads=1:sync-lookahead=0`) on failure.
- **Gallery Playback:** [`VideoPlayer`](../app/src/video_player.hpp) probes duration & audio presence via `ffprobe`, spawns `ffmpeg` raw `rgb24` frames timed cleanly to PTS, and drives audio through ALSA `aplay` on Linux or `set_pcm_sink` (SDL2 audio queue) on desktop—allowing silent `.mp4` files (compiled timelapses or muted clips) to play smoothly without audio failure.
---
## 4. `320×170` UI Renderer & Zinc Color Tokens
[`AppView`](../app/src/app_ui.hpp) renders into an offscreen `320×170` ARGB8888 canvas with SDF antialiased rounded primitives and FreeType2 + `5×7` bitmap fallback, then blits via [`fb_blit.hpp`](../app/src/fb_blit.hpp) (`RGB565` / `RGB24` / `XRGB8888`) or SDL2 texture.
Exact palette tokens defined in [`app/src/theme.cpp`](../app/src/theme.cpp):