NearbyCast

Logo

Open-source screen casting for Linux

View the Project on GitHub kenan-karimli/nearby-cast

Nearby Cast — Project Wiki

Cast anything. Nearby. — Open-source Linux desktop screen casting app.

Table of Contents

  1. Overview
  2. Architecture
  3. Tech Stack
  4. Core Components
  5. Streaming Pipeline
  6. Video Encoding Strategy
  7. Transport Modes
  8. Security Model
  9. Installation
  10. Development
  11. Test Infrastructure
  12. Supported Devices
  13. System Requirements
  14. Environment Variables
  15. License

Overview

Nearby Cast is a lightweight, open-source Linux desktop application that streams your screen to compatible devices on your local network — Google Cast / Chromecast and Android TV. Device discovery is handled via mDNS, requiring zero manual configuration.

Feature Summary:

Feature | Support -- | -- Automatic device discovery | ✅ mDNS Google Cast / Chromecast | ✅ Android TV | ✅ Local network casting | ✅ Wayland | ✅ X11 | ✅ Open source | ✅ MIT

License

Nearby Cast is released under the MIT License. See LICENSE for details.

Last updated: August 2026 | Author: kenan-karimli

Nearby Cast — Project Wiki

Cast anything. Nearby. — Open-source Linux desktop screen casting app.

Table of Contents

  1. [Overview](https://github.com/kenan-karimli/nearby-cast/wiki/_new#overview)
  2. [Architecture](https://github.com/kenan-karimli/nearby-cast/wiki/_new#architecture)
  3. [Tech Stack](https://github.com/kenan-karimli/nearby-cast/wiki/_new#tech-stack)
  4. [Core Components](https://github.com/kenan-karimli/nearby-cast/wiki/_new#core-components)
  5. [Streaming Pipeline](https://github.com/kenan-karimli/nearby-cast/wiki/_new#streaming-pipeline)
  6. [Video Encoding Strategy](https://github.com/kenan-karimli/nearby-cast/wiki/_new#video-encoding-strategy)
  7. [Transport Modes](https://github.com/kenan-karimli/nearby-cast/wiki/_new#transport-modes)
  8. [Security Model](https://github.com/kenan-karimli/nearby-cast/wiki/_new#security-model)
  9. [Installation](https://github.com/kenan-karimli/nearby-cast/wiki/_new#installation)
  10. [Development](https://github.com/kenan-karimli/nearby-cast/wiki/_new#development)
  11. [Test Infrastructure](https://github.com/kenan-karimli/nearby-cast/wiki/_new#test-infrastructure)
  12. [Supported Devices](https://github.com/kenan-karimli/nearby-cast/wiki/_new#supported-devices)
  13. [System Requirements](https://github.com/kenan-karimli/nearby-cast/wiki/_new#system-requirements)
  14. [Environment Variables](https://github.com/kenan-karimli/nearby-cast/wiki/_new#environment-variables)
  15. [License](https://github.com/kenan-karimli/nearby-cast/wiki/_new#license)

Overview

Nearby Cast is a lightweight, open-source Linux desktop application that streams your screen to compatible devices on your local network — Google Cast / Chromecast and Android TV. Device discovery is handled via mDNS, requiring zero manual configuration.

Feature Summary:

Feature Support
Automatic device discovery ✅ mDNS
Google Cast / Chromecast ✅
Android TV ✅
Local network casting ✅
Wayland ✅
X11 ✅
Open source ✅ MIT

Architecture

The project is split into two main layers:

┌─────────────────────────────────────────────┐
│              Tauri Desktop App               │
│         (React + TypeScript frontend)        │
│                                              │
│  - mDNS device discovery                     │
│  - User interface                            │
│  - Manages cast_launcher.py subprocess       │
└──────────────────┬──────────────────────────┘
                   │ subprocess
                   ▼
┌─────────────────────────────────────────────┐
│          cast_launcher.py (Python)           │
│                                             │
│  wf-recorder → FIFO pipe → ffmpeg           │
│       │                       │             │
│  (Wayland capture)     (H.264 encode)       │
│                               │             │
│                    HTTP Media Server        │
│                  (fMP4 / HLS stream)        │
│                               │             │
│                    Chromecast / ATV         │
└─────────────────────────────────────────────┘

Inter-component communication:

Tech Stack

Frontend

| Technology | Version | Purpose | |—|—|—| | Tauri | v2.x | Lightweight Rust-based desktop framework | | React | ^19.0.0 | UI components | | TypeScript | ^5.7.3 | Type safety | | Vite | ^6.1.0 | Build tool | | Lucide React | ^0.475.0 | Icon library |

Backend / Capture Pipeline

| Technology | Version | Purpose | |—|—|—| | Python 3 | 3.x | Streaming orchestration | | wf-recorder | System | Wayland screen capture | | ffmpeg | System | Video encoding | | pychromecast | pip | Google Cast protocol |

Packaging

| Format | Target | |—|—| | .deb | Debian / Ubuntu | | .rpm | Fedora / RHEL | | .bin | Universal binary | | Flatpak | Sandboxed install | | Snap | Ubuntu Snap Store |

Core Components

1. cast_launcher.py — Streaming Orchestrator

This ~974-line Python script manages the entire capture → encode → serve → cast lifecycle.

Key functions:

2. Tauri App (src-tauri/)

The Rust-based desktop shell:

3. React Frontend (src/)

4. Embedded HTML Player

The HTML_PLAYER template inside cast_launcher.py:

Streaming Pipeline

Monitor / Window
      │
      ▼
wf-recorder (Wayland)
  --muxer=rawvideo -c rawvideo -x bgr0 -r 30
      │
   FIFO pipe (capture.raw.pipe)
      │
      ▼
ffmpeg
  -f rawvideo -pix_fmt bgr0 -framerate 30
  + audio (PulseAudio monitor / silence)
  → H.264 encode (VA-API / NVENC / QSV / libx264)
  → fMP4 (live.mp4)  or  HLS (live.m3u8 + .ts segments)
      │
      ▼
HTTP Media Server (0.0.0.0 : random port)
  Session-token-protected URL
      │
      ▼
pychromecast → Cast receiver
  play_media(URL, content_type, stream_type="LIVE")

Latency tuning:

Video Encoding Strategy

Encoder selection uses an automatic probe mechanism — a real one-frame encode is attempted for each candidate before it is accepted:

Priority order:
1. h264_vaapi   (VA-API — Intel / AMD GPU, per /dev/dri/renderD*)
2. h264_nvenc   (NVIDIA GPU)
3. h264_qsv     (Intel Quick Sync)
4. libx264      (Software fallback — always available)

Cast-optimized encoding parameters:

Transport Modes

Selected via the NEARBY_CAST_TRANSPORT environment variable:

fMP4 (Fragmented MP4) — Default

NEARBY_CAST_TRANSPORT=fmp4  (default)

HLS (HTTP Live Streaming)

NEARBY_CAST_TRANSPORT=hls

Security Model

The project uses multiple layers of isolation:

Session isolation:

Media server authorization:

Process management:

Installation

Quick Install (one command)

curl -fsSL https://raw.githubusercontent.com/kenan-karimli/nearby-cast/main/install.sh | sh

The installer auto-detects your Linux distribution and installs the appropriate package.

Manual Install

Download the latest release from [GitHub Releases](https://github.com/kenan-karimli/nearby-cast/releases/latest):

Package System
.deb Debian, Ubuntu, Linux Mint
.rpm Fedora, openSUSE, RHEL
.bin Any Linux

System Dependencies

The cast launcher requires the following to be installed:

Development

git clone https://github.com/kenan-karimli/nearby-cast.git
cd nearby-cast
npm install
npm run dev      # Vite dev server
npm run tauri    # Tauri development build

Build

npm run build    # TypeScript + Vite production build

NPM Scripts Reference

Script Description
npm run dev Start Vite dev server
npm run build Production build
npm run typecheck TypeScript type check (no emit)
npm run tauri Tauri CLI
npm run virtual-receivers Start virtual Cast receiver server
npm run test:virtual E2E test against virtual receivers
npm run test:protocols E2E + production path tests
npm run test:latency Measure stream latency
npm run test:stress Stability under load
npm run test:all Run every test suite

Test Infrastructure

The tools/virtual-receivers/ directory contains a comprehensive test suite that allows testing the full pipeline without real Cast hardware:

Script Purpose
e2e_test.py Full end-to-end cast flow
production_path_test.py Production pipeline validation
failure_test.py Error and failure scenario handling
latency_test.py Stream latency measurement
stress_test.py Stability under sustained load
run_all_tests.py Sequential runner for all suites

Lab mode (NEARBY_CAST_LAB_MEDIA=1):

Supported Devices

Device Protocol Status
Google Chromecast Google Cast ✅ Supported
Chromecast with Google TV Google Cast ✅ Supported
Android TV Google Cast / fMP4 LIVE ✅ Verified
Google Nest Hub Google Cast ✅ Supported
Cast-enabled smart TVs Google Cast ✅ Supported

System Requirements

Requirement Details
OS Linux
Display server Wayland recommended (wlroots-compatible: Sway, Hyprland, GNOME Wayland); X11 also supported
Network Same local network as the Cast device
GPU / CPU Any; hardware encoder strongly recommended for performance

Wayland compositor detection (in get_monitor_resolution):

Environment Variables

Variable Default Description
NEARBY_CAST_SESSION_DIR — Required. Path to the session directory
NEARBY_CAST_SESSION_TOKEN — Required. HTTP URL authorization token
NEARBY_CAST_TRANSPORT fmp4 Transport mode: fmp4 or hls
NEARBY_CAST_ENCODER auto Force encoder: auto, h264_vaapi, h264_nvenc, h264_qsv, libx264
NEARBY_CAST_LAB_MEDIA — Set to 1 to enable Wayland-free lab mode
NEARBY_CAST_LAB_CAST_LOAD — Virtual receiver HTTP endpoint for lab casts
NEARBY_CAST_ALLOW_LOOPBACK — Set to 1 to permit casting over loopback
XDG_RUNTIME_DIR /run/user/<uid> Wayland runtime directory
WAYLAND_DISPLAY wayland-1 Wayland display socket

License

Nearby Cast is released under the MIT License. See [LICENSE](https://github.com/kenan-karimli/nearby-cast/blob/main/LICENSE) for details.

*Last updated: August 2026 Author: [kenan-karimli](https://github.com/kenan-karimli)*