Native Chromecast display mirroring. Low latency. No Chrome.

Linux is the primary supported platform. You need a modern C++20 compiler (GCC 11+ or Clang 14+), CMake 3.20+, Ninja, and developer libraries for GTK 4, Libadwaita, FFmpeg, and PulseAudio.

Prerequisites (Debian / Ubuntu / Kali)

Copysudo apt update
sudo apt install -y build-essential cmake ninja-build pkg-config protobuf-compiler libprotobuf-dev     libssl-dev libopus-dev libpulse-dev libx11-dev libxext-dev libxrandr-dev libxfixes-dev     libxcomposite-dev libxdamage-dev     libva-dev libavcodec-dev libswscale-dev libavutil-dev nlohmann-json3-dev libgtest-dev     libgtk-4-dev libadwaita-1-dev

Configure and Build

Copycmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"12"

Build Artifacts

Running the GUI & CLI

Copy# Launch the GTK 4 desktop app
./build/app/castmirror-gui

# Cast a full monitor via CLI
./build/app/castmirror --device 192.168.0.164 --display 0 --preset High

# List available application windows, then mirror one
./build/app/castmirror --list-windows
./build/app/castmirror --device 192.168.0.164 --window 0x2400004

# Cast display without mirroring system audio
./build/app/castmirror --device 192.168.0.164 --no-audio

Environment Variables

• CASTMIRROR_FORCE_SOFTWARE_ENCODE=1: Force FFmpeg libx264 software encoding even when VAAPI GPU acceleration is available.
• CASTMIRROR_FORCE_X11=1: Force X11 display capture instead of the PipeWire portal when running under a Wayland compositor via XWayland.

Network & Firewall Configuration

Control traffic uses TCP 8009 (TLS) to the receiver. Media streams use UDP to the ephemeral port returned in the ANSWER. Both devices must be on the same local subnet. Helper script: scripts/setup_firewall.sh.

CastMirror is structured as a modular C++20 engine (castcore) with a decoupled GTK 4 + Libadwaita GUI (app/gui) and CLI (app/cli).

Performance & Latency Contract

• Connect to First Frame: ≤ 8 seconds typical (including TLS, app launch, and OFFER/ANSWER negotiation).
• Glass-to-Glass Latency: ≤ 200–250 ms on a clean 5 GHz LAN with targetDelay: 200.
• Teardown Budget: Clean Stop within ≤ 500 ms (guaranteed halt of capture, encoders, and UDP sockets).
• Idle Safety: Capture and encoders never run in the background when disconnected.

Media Pipeline

• Video Path: X11 XRandR / PipeWire portal → BGRA frame → GpuProcessor (letterbox scaling, direct YUV420P/NV12 plane write) → Hardware VAAPI / libx264 encoder (0 B-frames, zerolatency) → Annex-B NALUs → FrameCrypto (AES-128-CTR) → RtpPacketizer (Cast RTP) → Paced UDP socket.
• Audio Path: PulseAudio / PipeWire default sink monitor → PCM 48 kHz stereo (10 ms chunks) → Opus encoder (192 kbps) → FrameCrypto → RtpPacketizer → UDP. Host audio sink is muted during streaming and restored on Stop.

State Machine

All subsystems coordinate strictly through an explicit thread-safe state machine:

Idle → Discovering → Ready → Connecting → Negotiating → Streaming ↔ Reconnecting → Stopping → Idle
(Failed state transitions gracefully back to Idle or Reconnecting)

Module Boundaries

CastMirror classifies receivers using mDNS capability bitmasks (ca) and model identifiers (md), verified against the receiver's negotiation ANSWER.

Receiver Compatibility Matrix

8-Rung Dynamic Adaptation Ladder

Google Cast screen mirroring uses a specialized real-time media protocol (not WebRTC ICE/DTLS and not HLS media playback).

1. Control Plane (Cast V2 TLS :8009)

• Connection: OpenSSL TLS connection to device port 8009.
• Protobuf Frame: 4-byte big-endian length prefix followed by serialized CastMessage.
• Namespaces:
  • urn:x-cast:com.google.cast.tp.connection — Virtual sender/receiver session bindings.
  • urn:x-cast:com.google.cast.tp.heartbeat — PING / PONG keepalive packets (5-second cadence).
  • urn:x-cast:com.google.cast.receiver — LAUNCH, STOP, and GET_STATUS requests.
  • urn:x-cast:com.google.cast.webrtc — JSON OFFER / ANSWER session negotiation.
• Firmware Mirroring App ID: 0F5096E8 (audio + video display mirroring) or 85CDB22F (audio-only).

2. Media Plane (Cast RTP / RTCP over UDP)

• RTP Profile: rtpProfile: "cast" with a custom 7-byte Cast RTP header extension:

  Byte 0:    Flags (Keyframe marker, Reference frame present)
  Bytes 1-2: Frame ID (monotonically increasing 16-bit integer)
  Bytes 3-4: Packet ID (packet index within frame)
  Bytes 5-6: Max Packet ID (total packet count - 1)

• AES-128-CTR Crypto: Fresh random 16-byte key and 16-byte IV mask per session. Per-frame IV mixes frame_id with the IV mask.
• Compound RTCP: Sender Reports (SR) paired with receiver CAST feedback packets containing:
  • Checkpoint Frame IDs acknowledging complete display rendering.
  • Loss bitmasks (NACK / CST2) detailing dropped UDP packets for immediate retransmit.
  • Picture Loss Indicators (PLI) signaling decoder desync and requesting an immediate IDR keyframe.

CastMirror undergoes rigorous automated verification including unit tests, integration suites, synthetic network impairments, and simulated receiver loopback.

Test Suite Status (87 / 87 Passed — 100%)

Latency Budget & Performance Verification