architecture.md is now a concise overview (~155 lines) with a
Documentation section linking to all sub-docs.
New sub-docs in docs/:
transport.md — wire modes, frame header, serialization, web peer
relay.md — delivery modes, memory model, congestion, scheduler
codec.md — stream metadata, format negotiation, codec backends
xorg.md — screen grab, viewer sink, render loop, overlays
discovery.md — multicast announcements, multi-site, site gateways
node-state.md — wanted/current state, reconciler, stats, queries
device-resilience.md — device loss handling, stream events, audio (future)
All cross-references updated to file links. Every sub-doc links back
to architecture.md. docs/transport.md links to docs/protocol.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Graph representation is plain ESM objects in the web interface.
No special format needed. Graph reconstruction, topology diffing,
and layout logic belong in ESM rather than C. Future TUI/CLI tools
reuse the same ESM libraries via Node.js.
No open questions remain.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Drop policy (per-output configurable), stream ID passthrough at relay,
TCP-only transport for now, soft byte budget limits with hysteresis,
and relay scheduler (strict priority first, pluggable interface) were
all already decided — move them out of Open Questions.
Only genuinely open question remaining: graph representation format.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add 'Declarative, Not Imperative' section near top explaining why the
control model is wanted-state-based rather than imperative commands
- Update Control Plane section: remove 'connection instructions' language,
replace with wanted state; note CLI controller comes before web UI
- Fix node naming example: xorg:preview instead of mpv:preview
- Update ingestion diagram: 'wanted state' instead of 'connection config'
- Add Per-Stream Stats note (stream_stats.h) to Node State Model
- Mark GET_CONFIG_STATE / GET_RUNTIME_STATE as planned, not yet implemented
- Split Open Questions: add Decided section for resolved questions
(connection direction, stream ID assignment, single port, first delivery mode)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Document the wanted/current state separation, generic resource state
machine reconciler (BFS pathfinding, event + periodic tick), node state
queries (GET_CONFIG_STATE / GET_RUNTIME_STATE), stream ID assignment
by controller, and connection direction model.
Add reconciler module to module order and reconciler_cli experiment
to CLI tools table in planning.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- tools/gen_font_atlas: Python/Pillow build tool — skyline packs DejaVu
Sans glyphs 32-255 into a grayscale atlas, emits build/gen/font_atlas.h
with pixel data and Font_Glyph[256] metrics table
- xorg: bitmap font atlas text overlay rendering (GL_R8 atlas texture,
alpha-blended glyph quads, dark background rect per overlay)
- xorg: add xorg_viewer_set_overlay_text / clear_overlays API
- xorg: add xorg_viewer_handle_events for streaming use (events only,
no redundant render)
- xorg_cli: show today's date as white text overlay
- v4l2_view_cli: new tool — V4L2 capture with format auto-selection
(highest FPS then largest resolution), MJPEG/YUYV, measured FPS overlay
- docs: update README, planning, architecture to reflect current status
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
libjpeg-turbo can decompress directly to planar YUV, bypassing CPU-side
color conversion entirely. Document the precise pipeline: separate Y/Cb/Cr
GL_RED textures, BT.601 matrix in fragment shader, SIMD Huffman+DCT on CPU only.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace XShmPutImage approach with GLFW+OpenGL as the initial renderer.
Documents the two-renderer plan: GLFW handles window/input for both;
only the rendering backend differs. Notes that both renderers should
conform to the same internal interface for swappability.
Adds input event forwarding (keyboard/mouse → INPUT_EVENT upstream)
as a first-class capability of the viewer sink.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Documents multi-input scheduling as a distinct concern from delivery
mode. Covers strict priority, round-robin, weighted round-robin, deficit
round-robin, and source suppression policies. Notes that the relay module
should expose a pluggable scheduler interface. Adds scheduler policy
selection to Open Questions.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Both sites default to site_id=0; gateway must rewrite site_id in
announcements and protocol messages crossing the boundary. site_id=0
on a cross-site link is a gateway protocol error.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Covers all layers: TCP → transport frame → message type dispatcher →
payload schemas. Documents frame format (6-byte header), all message
types, STREAM_OPEN/CLOSE lifecycle, codec/pixel_format/origin tables,
stream events, and discovery announcement wire format.
Also fixes stale channel_id reference in audio section of architecture.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Removes channel_id from the header. All message-specific identifiers
(stream_id, request_id, etc.) now live at the start of the payload,
interpreted by each message type handler. A relay seeing an unknown
type can skip or forward it using only payload_length, with no
knowledge of the payload structure.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
No central message hub or broker. Controller is a function_flags bit — any
node with a user interface (e.g. web UI) holds it. Multiple nodes can hold
the role simultaneously. Controller communicates directly with peers over
the binary protocol; no intermediary.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ingest module: dequeue V4L2 buffers, emit one encapsulated frame per buffer.
Driver guarantees per-buffer framing for V4L2_PIX_FMT_MJPEG; no scanning needed.
mjpeg_scan: future optional module for non-compliant hardware only.
Explicitly a workaround, not part of the primary pipeline.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
V4L2 with proper node: driver guarantees per-buffer framing, no scan needed.
Opaque pipe (dd|nc): buffer boundaries lost, EOI scanner is the correct tool.
Weird containers (RIFF-wrapped USB cams, IP cameras, RTSP): route via ffmpeg,
not a custom parser. Scanner is an option only for constrained raw-stream cases.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
format (u16): what the bytes are — drives decode, stable across encoder changes
pixel_format (u16): layout for raw formats, ignored otherwise
origin (u16): how it was produced — informational only, no effect on decode
Eliminates numerical range assumptions (0x01xx ffmpeg range). A camera
outputting MJPEG natively and libjpeg-turbo encoding MJPEG are the same
format with different origins; receiver handles both identically.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
0x01xx range reserved for ffmpeg-backed formats (H.265, AV1, FFV1,
ProRes). Documents libavcodec vs subprocess trade-offs: subprocess suits
archival completeness paths, libavcodec suits low-latency encode. Receiver
only cares about wire format, not which encoder produced it.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
xorg module: XRandR geometry queries, screen grab source (XShmGetImage),
frame viewer sink (XShmPutImage, fullscreen per monitor). All exposed as
standard source/sink node roles on the existing transport.
Audio: deferred but transport is already compatible — channel_id mux,
audio_frame message type slot reserved, relay/allocator are payload-agnostic.
Also marks serial as done in planning.md.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
site_id (u16) is reserved in the announcement payload from day one,
always 0 in single-site deployments. Documents the site gateway node
concept and fully-qualified addressing (site_id:namespace:instance) so
multi-site can be added later without wire format changes.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
A node can declare multiple roles simultaneously (e.g. relay + sink).
Replaces the function string with a fixed-size flags field; keeps the
payload layout simple and fixed-width up to the name.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Reuse UDP multicast transport (224.0.0.251:5353) with our own binary
wire format — no Avahi, no Bonjour, no daemon dependency.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
architecture.md:
- Web interface connects as a first-class binary protocol peer; no JSON
bridge in C; DataView in JS maps directly to get_u32 etc.
- Future preprocessor section: protocol schema defined once, emits both
C (put/get, write_*/read_*) and ESM JS (DataView encode/decode);
same tool as planned for error location codes
planning.md:
- Add web node (entry #11) to module order
- Add Future: Protocol Preprocessor section above Deferred Decisions
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
architecture.md: replace JSON control payloads with binary serialization;
add Protocol Serialization section describing little-endian wire format,
put/get buffer layer, and write_*/read_* protocol layer.
planning.md: mark common/media_ctrl/v4l2_ctrl done; insert serial (#4)
and protocol (#6) modules with descriptions.
conventions.md: document -flto and its implication (no manual static for
inlining — compiler handles it at link time).
Makefiles: add -flto to CFLAGS in all four Makefiles.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Initial documentation for the multi-peer video routing system:
- architecture.md covers graph model, transport protocol, relay design,
and the Pi get-it-on-the-wire-first rationale
- planning.md defines module build order and directory structure
- conventions.md captures C11 code style, naming, error handling approach,
and directory layout rules
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
