vcam

High-Performance, Low-Latency Phone-as-Webcam System for Linux

vcam transforms your Android phone into a high-definition, ultra-low-latency webcam for Linux desktop environments. Designed for zero-lag streaming, it seamlessly bridges hardware-accelerated H.264 video encoding on Android with native in-process decoding and virtual camera integration on Linux.

---

Features

• Ultra-Low Latency (~50–150ms) — Real-time glass-to-screen performance powered by Android MediaCodec hardware encoding and in-process OpenH264 decoding on Linux.
• Plug & Play USB Connection — Automatic ADB port forwarding over USB with zero configuration required.
• Wi-Fi LAN Streaming — Connect wirelessly over local Wi-Fi with low latency.
• Dual Virtual Camera Sinks:
  • PipeWire Native Node — First-class integration for Wayland & modern desktop portals.
  • v4l2loopback Device — Universal compatibility for Chrome, Google Meet, Zoom, OBS, and Electron applications.
• Dynamic Streaming Profiles:
  • Low (720p @ ~2 Mbps) — Optimized for minimum latency and smooth video calls.
  • Balanced (1080p @ ~5 Mbps) — Crisp Full HD video for presentations and streams.
  • Ultra-low (480p @ ~800 kbps) — Ultra-lightweight stream for resource-constrained connections.
• Live Controls — On-the-fly camera flipping (front/rear), profile switching, and live HUD metrics (FPS, bitrate, network RTT).

---

Architecture Overview

 ┌──────────────────────────────────┐        TCP (USB / Wi-Fi)       ┌──────────────────────────────────────────────┐
 │          Android Phone           │ ──────────────────────────────> │                 Linux Desktop                │
 │  CameraX ──> MediaCodec (H.264)  │   Port 9077 (Media Stream)     │ OpenH264 Decode ──> PipeWire (Native Node)  │
 │              Framed Server       │   Port 9078 (Control Channel)  │                  ──> v4l2loopback (/dev/video)│
 └──────────────────────────────────┘                                └──────────────────────────────────────────────┘

1. Android App (apps/android): Uses CameraX and Android MediaCodec to encode video to H.264 NAL units in real-time. Emits framed packets over a lightweight TCP server.
2. Desktop Client (apps/desktop): A native Linux application powered by Zig and Native SDK. Receives the H.264 stream, decodes frames in-process via OpenH264, and presents a zero-copy preview.
3. Virtual Camera Sinks: Simultaneously publishes video buffers to PipeWire (vcam node) and /dev/video* via v4l2loopback.

---

Quick Start

1. Requirements

• Linux Desktop: System with PipeWire and/or v4l2loopback installed.
• Android Phone: Android 8.0+ (API 26+) with USB Debugging enabled (for USB mode).

2. User Setup

For step-by-step connection instructions and system configuration, read the User Guide.

# Recommended: Load v4l2loopback module for browser compatibility (Chrome/Zoom/Meet)
sudo modprobe v4l2loopback exclusive_caps=1 card_label=vcam video_nr=10

3. Developer Building

# Clone the repository
git clone https://github.com/gitadityakumar/vcam.git
cd vcam

# Install workspace dependencies
pnpm install

# Run Desktop app in development mode
pnpm desktop

# Build Android APK
pnpm android

---

Workspace Layout

This project is organized as a Turborepo monorepo:

Directory	Package	Description
apps/desktop	@vcam/desktop	Native Linux desktop application (Zig + OpenH264 + PipeWire/v4l2)
apps/android	@vcam/android	Android Kotlin application (CameraX + H.264 MediaCodec streamer)
packages/protocol	@vcam/protocol	Shared binary framed stream protocol definition
packages/mock-stream	@vcam/mock-stream	Development mock streamer utility
docs/	—	Documentation (User Guide, Contributing, Latency)

---

Documentation

• User Guide — Installation, permission setup, and usage instructions.
• Contributing Guide — Monorepo setup, build toolchain, and development workflow.
• Latency Deep Dive — Technical breakdown of latency budgets and frame-pacing design.

---

License

Distributed under the MIT License.