screen_cast/docs/ARCHITECTURE.md

Architecture

screen_cast is a native Linux screencast application that sends and receives desktop video over the LAN. It is intentionally split into small, replaceable modules so that capture, codec, network, and rendering concerns can evolve independently.

Goals

• Works on modern Linux desktops (Wayland and X11).
• Low-latency peer-to-peer streaming.
• CLI-first; optional GUI later.
• Software and hardware-accelerated encoding paths.
• Minimal, auditable network protocol.

Module overview

┌─────────────┐     ┌────────────┐     ┌─────────────┐     ┌──────────┐
│   Capture   │────▶│  Encoder   │────▶│   Packetize │────▶│ RTP/UDP  │  Sender
│  (PipeWire) │     │  (FFmpeg)  │     │    (RTP)    │     │ Transport│
└─────────────┘     └────────────┘     └─────────────┘     └──────────┘

┌──────────┐     ┌─────────────┐     ┌────────────┐     ┌─────────────┐
│ RTP/UDP  │────▶│ Depacketize │────▶│   Decoder  │────▶│   Renderer  │ Receiver
│Transport │     │    (RTP)    │     │  (FFmpeg)  │     │  (SDL/GL)   │
└──────────┘     └─────────────┘     └────────────┘     └─────────────┘

┌──────────────────────────────────────────────────────────────────┐
│                    Control / Signaling / Discovery               │
│        WebSocket/JSON control  +  mDNS/Avahi discovery           │
└──────────────────────────────────────────────────────────────────┘

Module responsibilities

Module	Directory	Responsibility
Capture	include/screencast/capture/	Acquire raw frames from PipeWire/portal.
Codec	include/screencast/codec/	Encode to / decode from H.264 with FFmpeg.
Network	include/screencast/network/	RTP framing, UDP transport, signaling, discovery.
Render	include/screencast/render/	Display decoded frames.
App	include/screencast/app/	CLI parsing, sender/receiver pipelines.

Pipeline rules

• Each pipeline owns its modules and threads.
• Frames are transferred as owned buffers (std::vector<std::byte>).
• Timestamps start in the capture clock domain and are converted to RTP clock domain once at packetization.
• On sender error the transport is drained and stopped.
• On receiver loss a PLI is sent over signaling; the sender inserts a keyframe.

Namespace

All project code lives in namespace sc.

Dependencies (planned)

Library	pkg-config	Phase
FFmpeg	libavcodec, libavutil, libswscale	2
PipeWire	libpipewire-0.3	3
SDL2/3	sdl2 / sdl3	5
ASIO	bundled or standalone asio	6
Avahi	avahi-client	7
WebSocket	websocketpp or uWebSockets	7

See docs/PHASES.md for the phased build plan.