video-setup/planning.md

Planning

Approach

Build the system module by module in C11. Each module is a translation unit (.h + .c) with a clearly defined API. Modules are exercised by small driver programs in dev/ before anything depends on them. This keeps each unit independently testable and prevents architectural decisions from being made prematurely in code.

The final binary is a single configurable node program. That integration work comes after the modules are solid.

---

Directory Structure

video-setup/
  src/
    modules/
      common/        - shared definitions (error types, base types)
      media_ctrl/    - Linux Media Controller API (topology, pad formats, links)
      v4l2_ctrl/     - V4L2 camera controls (enumerate, get, set)
      serial/        - little-endian binary serialization primitives
      transport/     - framed TCP stream, single-write send
      protocol/      - typed write_*/read_* message functions
    node/            - video node entry point and top-level integration (later)
  include/           - public headers
  dev/
    cli/             - exploratory CLI drivers, one per module
    web/             - development web UI (Node.js/Express); browser-side equivalent
                       of the CLI tools; depends on protocol being finalised
    experiments/     - freeform experiments
  tests/             - automated tests (later)
  Makefile
  architecture.md
  planning.md
  conventions.md

---

Module Order

Modules are listed in intended build order. Each depends only on modules above it.

#	Module	Status	Notes
1	common	done	Error types, base definitions — no dependencies
2	media_ctrl	done	Media Controller API — device and topology enumeration, pad format config
3	v4l2_ctrl	done	V4L2 controls — enumerate, get, set camera parameters
4	serial	done	put/get primitives for little-endian binary serialization into byte buffers
5	transport	done	Encapsulated transport — frame header, TCP stream abstraction, single-write send
6	discovery	done	UDP multicast announcements, peer table, found/lost callbacks
8	protocol	not started	Typed write_*/read_* functions for all message types; builds on serial + transport
9	frame_alloc	not started	Per-frame allocation with bookkeeping (byte budget, ref counting)
10	relay	not started	Input dispatch to output queues (low-latency and completeness modes)
11	ingest	not started	V4L2 capture loop — dequeue buffers, emit one encapsulated frame per buffer
12	archive	not started	Write frames to disk, control messages to binary log
13	codec	not started	Per-frame encode/decode — MJPEG (libjpeg-turbo), QOI, ZSTD-raw, VA-API H.264 intra; used by screen grab source and archive
14	xorg	not started	X11 screen geometry queries (XRandR), screen grab source (calls codec), frame viewer sink — see architecture.md
15	web node	not started	Node.js/Express peer — speaks binary protocol on socket side, HTTP/WebSocket to browser; protocol.mjs mirrors C protocol module
—	mjpeg_scan	future	EOI marker scanner for misbehaving hardware that does not deliver clean per-buffer frames; not part of the primary pipeline
—	config	future	Unified config file reader; nodes currently configured via CLI args — needed before production deployment

---

Dev Tools

CLI (dev/cli/)

Each module gets a corresponding CLI driver that exercises its API and serves as both an integration check and a useful development tool.

Driver	Exercises	Notes
media_ctrl_cli	media_ctrl	List media devices, show topology, configure pad formats
v4l2_ctrl_cli	v4l2_ctrl	List controls, get/set values — lightweight v4l2-ctl equivalent
transport_cli	transport	Send/receive framed messages, inspect headers

Web UI (dev/web/)

A Node.js/Express development web UI — the browser-side equivalent of the CLI tools. Connects to a running video node as a binary protocol peer and exposes its capabilities through a browser interface: V4L2 control inspection and adjustment, media topology view, stream state.

Prerequisite: the transport and protocol modules must be finalised before dev/web/ can be implemented — the web UI depends on a stable wire format and a protocol.mjs that mirrors the C protocol module.

This is a development aid, not the production dashboard. The production dashboard (full stream configuration UI) is a later, separate project.

---

Future: Protocol Preprocessor

The C protocol module and JavaScript protocol.mjs will eventually be generated from a single schema by a future preprocessor. This eliminates drift between the two implementations. The preprocessor also handles error location codes (see common/error). Neither the schema format nor the preprocessor tool exists yet — the hand-written implementations are the interim state.

---

Deferred Decisions

These are open questions tracked in architecture.md that do not need to be resolved before module work begins:

• Graph representation format
• Connection establishment model (push vs pull)
• Completeness queue drop policy (oldest vs newest, per-output config)
• Stream ID remapping across relay hops
• Transport for relay edges (TCP / UDP / shared memory)
• Node discovery mechanism
• Hard vs soft byte budget limits