Turn your Android phone or tablet into a wireless external display for Linux.
WBeam enables high-performance streaming from a Linux host to Android devices over USB/ADB, providing a second screen with minimal latency and maximum quality. Perfect for productivity, streaming, or extending your workspace.
WBeam has two main components working in concert:
| Component | Role | Details |
|---|---|---|
| Host (Linux) | Server & capture | Daemon + desktop control app, manages display capture and streaming |
| Android Client | Display sink | APK running on phone/tablet, receives and displays video stream |
Data flows over USB via ADB, requiring no network configuration or wireless setup.
Tip
Current best practice:
- EVDI capture backend is the recommended path, providing ~60 FPS with low latency
- Wayland portal fallback available, though less stable on some desktop configurations
- For optimal results, ensure EVDI module is loaded:
sudo modprobe evdi
- Linux host with USB port
- Android phone or tablet (API 17+)
- USB cable for ADB connection
- EVDI capture backend installed (see below)
-
Clone repository and enter directory:
git clone <repo> && cd WBeam
-
Connect Android device via USB:
- Ensure ADB shows device in
devicestate:adb devices - Enable USB debugging in Android settings if needed
- Ensure ADB shows device in
-
Build and deploy everything:
./redeploy-local
This automatically:
- Builds host daemon and desktop UI
- Compiles and installs Android APK
- Verifies version compatibility
- Launches desktop control application
-
Start the service (if not already running):
./wbeam service install ./wbeam service start
-
Connect in desktop UI:
- Click Connect button in the WBeam desktop application
- Observe video stream appearing on Android device
-
Verify EVDI capture:
sudo modprobe evdi initial_device_count=1
If EVDI isn't working, use the diagnostic tool:
bash scripts/evdi-diagnose.shFor automated setup across any major Linux distribution (Arch, Debian, Ubuntu, Fedora, RHEL):
sudo bash scripts/evdi-setup.shSee EVDI_SETUP_INDEX.md and docs/EVDI_SETUP_GUIDE.md for complete troubleshooting guidance.
To access debug options in the APK:
- Hold VOL+ and VOL- buttons simultaneously for ~2 seconds
- Debug menu appears with streaming diagnostics and settings
| Command | Purpose |
|---|---|
./wbeam --help |
Show all available commands |
./wbeam host build |
Build host daemon and streamer |
./wbeam android deploy-all |
Build and deploy APK to all connected devices |
./desktop.sh |
Launch desktop control application |
./redeploy-local |
Full rebuild + deploy + launch (recommended for development) |
./wbeam service install |
Install systemd service (user-level) |
./wbeam service start |
Start the daemon service |
./wbeam service status |
Check if daemon is running |
./wbgui |
Terminal UI wrapper around core workflows |
./devtool |
Developer convenience wrapper |
For a complete development workflow:
# One-command full setup (build, deploy, run)
./redeploy-local
# If desktop closes, restart it
./desktop.sh
# Manual service control
./wbeam service install && ./wbeam service start
# Check EVDI is loaded
sudo modprobe evdi initial_device_count=1WBeam includes an interactive tuner to benchmark different encoding profiles and automatically generate optimized configurations for your specific hardware and network conditions.
./wbeam host tunerThis launches an interactive GUI where you can:
| Setting | Purpose | Default |
|---|---|---|
| Objective | What to optimize for | FPS (frames per second) |
| Workload | Scene complexity to test | Mixed (varies) |
| Training Mode | Prerendered scenes vs. virtual desktop | Prerendered (deterministic) |
| Child Train Time | Seconds per test run | 5s |
-
Prerendered scenes (recommended)
- Uses deterministic synthetic test scenes
- Consistent, reproducible results
- No compositor overhead
- Useful for maximum frame rate tuning (>60 FPS)
-
Virtual desktop mode
- Captures from your live desktop
- Real-world testing
- Limited by Wayland/X11 compositor cap (~60 FPS on many systems)
After training completes, the tuner displays:
- Final score and performance metrics
- Winning bitrate/FPS/intra-frame settings
- Details about the run configuration
Profiles are automatically saved to:
~/.config/wbeam/trained_profiles.json
Example trained profiles are available in:
config/trainer-profiles/examples/
The repository is organized by domain boundaries:
WBeam/
├── android/ # Android client (APK source code)
├── host/ # Linux host daemon and streamer
├── desktop/ # Desktop UI applications
├── shared/ # Shared protocol and contracts
├── scripts/ # Utility and setup scripts
├── config/ # Configuration templates and profiles
├── docs/ # Documentation and guides
└── logs/ # Runtime logs and diagnostics
docs/repo-structure.md- Detailed repository layout and module organizationdocs/EVDI_SETUP_GUIDE.md- Complete EVDI installation and troubleshootingEVDI_SETUP_INDEX.md- EVDI quick reference and support matrixdocs/agents.workflow.md- Development workflow and best practices
| Tool | Purpose | Usage |
|---|---|---|
./wbeam |
Main CLI - all operations | ./wbeam --help |
./wbgui |
Terminal UI wrapper | Interactive menu-driven interface |
./devtool |
Developer convenience | Common dev tasks shortcut |
./desktop.sh |
Launch desktop app | Desktop control UI |
./trainer.sh |
Launch trainer GUI | Interactive performance tuner |
./start-remote |
Remote setup & bootstrap | Remote host initialization |
./runas-remote |
Remote command execution | Run commands in active session |
WBeam supports multiple capture methods to match your desktop environment:
- Platform: Linux with kernel module support
- Performance: ~60 FPS, low latency, high quality
- Setup:
sudo bash scripts/evdi-setup.sh - Use: Explicitly specify via
?capture_backend=evdiparameter - Advantages: Direct kernel capture, bypasses compositor, best quality
- Platform: Wayland sessions (GNOME, KDE, etc.)
- Performance: ~30-60 FPS (depends on compositor)
- Fallback: Automatic if EVDI unavailable
- Limitations: May be less stable on some configurations
- Platform: X11 sessions
- Performance: Variable based on system load
- Note: Slower than Wayland portal in most cases
| Requirement | Min Version | Notes |
|---|---|---|
| Android | API 17 (4.2) | Supports legacy devices |
| Linux | Kernel 5.10+ | For EVDI support |
| USB | USB 2.0+ | ADB over USB required |
- Use EVDI capture: Provides native resolution and 120 FPS capability
- Configure adaptive quality: Let WBeam adjust bitrate based on network
- Use prerendered scenes for tuning: More consistent profile generation
- Monitor bandwidth: Adjust target bitrate to match your USB link speed
- Reduce resolution on Android: Lower resolution = less network traffic
- Increase frame rate: WBeam adapts encode quality to maintain FPS
- Use EVDI backend: Eliminates compositor delay
- Check USB cable quality: Loose connections cause lag
- Reduce resolution: Better battery life and thermal performance
- Lower frame rate: Battery consumption scales with FPS
- Use adaptive profile: Automatically balances quality vs. power
- Verify ADB sees device:
adb devices - Check service is running:
./wbeam service status - Look at logs:
tail -f logs/*.log - Verify APK version matches host:
./wbeam version doctor
# Diagnose
bash scripts/evdi-diagnose.sh --verbose
# Automated setup
sudo bash scripts/evdi-setup.sh
# Manual load
sudo modprobe evdi initial_device_count=1- Try EVDI backend:
?capture_backend=evdi - Run adaptive tuning:
./wbeam host tuner - Monitor bandwidth: Check USB connection quality
- Verify CPU load: Both host and device should have headroom
# Use Wayland-aware launcher
./desktop.sh
# Or use xwayland wrapper if needed
XDG_SESSION_TYPE=x11 ./desktop.sh┌─────────────────────────────────────────────────────────────┐
│ Linux Host │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌──────────────────┐ │
│ │ Display Capture│ │ WBeam Daemon │ │
│ │ (EVDI/Wayland) │──────────▶│ • Stream Mgmt │ │
│ └─────────────────┘ │ • Encoding │ │
│ │ • Network Ctrl │ │
│ ┌─────────────────┐ └──────────────────┘ │
│ │ Desktop UI │ │ │
│ │ (Tauri App) │◀───────────────────┼───────┐ │
│ └─────────────────┘ │ │ │
│ │ │ │
│ ADB over USB │ │
│ │ │ │
│ ▼ ▼ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────▼────────────┐ ┌──────────▼────┐
│ Android Tablet│ │ Android Phone│
├─────────────────┤ ├───────────────┤
│ • H.264/H.265 │ │ • H.264/H.265 │
│ • Display Sink │ │ • Display Sink │
│ • Telemetry │ │ • Telemetry │
└─────────────────┘ └───────────────┘
For development workflow details, see:
docs/agents.workflow.md- Team workflow and PR processdocs/repo-structure.md- Detailed codebase organizationEVDI_SETUP_INDEX.md- Setup troubleshooting guide
Quick dev setup:
git clone <repo> && cd WBeam
./redeploy-local # One-command setup
./wbgui # Use terminal UI for common tasksWBeam is under active development. See workflow documentation for:
- Issue/branch naming conventions
- PR review process
- Commit message format
- Testing requirements
See LICENSE file in repository root.
Last Updated: March 2026
Status: Production Ready
Supported Platforms: Linux (Arch, Debian, Ubuntu, Fedora, RHEL), Android 4.2+