USB display streaming from Linux to Android over ADB.
Captures a virtual display on the host, encodes H.264/H.265, and pushes frames to an Android device connected via USB. No Wi-Fi, no network config.
┌─────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────┘ └───────────────┘
Prerequisites: Linux host, Android device (API 17+), USB cable, ADB.
Fresh machine wizard:
git clone <repo> && cd WBeam
# Probe the machine, choose Wayland/X11 or EVDI, install deps, build host,
# install the user service, then onboard the Android phone.
./install-wbeam
# Preview first if needed
./install-wbeam --dry-runDeveloper rebuild/deploy flow:
git clone <repo> && cd WBeam
# Build host daemon, build+install APK, launch desktop UI.
# On Fedora this also bootstraps missing build, Android SDK, GStreamer,
# and EVDI/DisplayLink dependencies when possible.
./redeploy-local
# Verify everything matches
./wbeam version doctorOn Fedora 43, both ./install-wbeam and ./redeploy-local call
scripts/fedora-setup.sh --yes when native packages, Android SDK components,
or EVDI/DisplayLink pieces are missing. Some system states still require manual
confirmation outside the repo:
- Secure Boot MOK enrollment for DKMS EVDI modules requires a reboot and the firmware MOK screen.
- Android install may require accepting USB debugging and allowing APK installs on the device.
- If EVDI is intentionally skipped, run with
WBEAM_REDEPLOY_WITH_EVDI=0 ./redeploy-localto use Wayland/X11 fallback.
Fedora details are in docs/FEDORA_43_SETUP.md. General EVDI diagnostics are
in EVDI_SETUP_INDEX.md and docs/EVDI_SETUP_GUIDE.md. The installer wizard
design is tracked in docs/INSTALLER_WIZARD.md.
EVDI (recommended) -- Kernel-level virtual display. 1920x1080 fixed EDID,
low latency, bypasses compositor. On Fedora, ./redeploy-local attempts this
automatically through scripts/fedora-setup.sh --yes --with-evdi.
Wayland portal -- Fallback for Wayland sessions. Compositor-dependent performance (~30-60 FPS). Automatic if EVDI is unavailable.
X11 -- Fallback for X11 sessions. Variable performance.
host build | run | debug | status | down/stop | probe | tuner
android build | install | launch | deploy | deploy-all
build-release | install-release | deploy-release
version new | current | doctor
watch tui | devices | connections | streaming | service
logs | status | health | doctor
debug up/start | watch/logs
logs live | host | adb (start|stop|status|tail)
deps virtual (check | install)
ip up | down | status
The daemon runs via ./wbeam host run (foreground) or ./wbeam host debug
(debug mode). For persistent operation, manage the systemd user service
(~/.config/systemd/user/wbeam-daemon.service) directly with systemctl --user.
./wbeam host tuner launches the interactive Rust TUI autotuner for
benchmarking encoding profiles against your hardware.
| Script | What it does |
|---|---|
./wbeam |
Main CLI |
./install-wbeam |
Fresh-machine installer wizard |
./wbgui |
Interactive TUI menu |
./devtool |
Dev convenience (gui, deps install) |
./desktop.sh |
Desktop app launcher |
./redeploy-local |
Full rebuild + deploy + launch |
./start-remote |
Remote session bootstrap |
./runas-remote |
Run command as another desktop user |
The trainer GUI is the desktop trainer-tauri app (desktop/apps/trainer-tauri).
WBeam/
android/ Android client (APK)
host/ Linux daemon, streamer, training
desktop/ Tauri desktop apps (control + trainer)
shared/ Shared protocol definitions
config/ Configuration templates and profiles
scripts/ Setup and utility scripts
docs/ Documentation
logs/ Runtime logs (gitignored)
Key docs: docs/repo-structure.md, docs/agents.workflow.md,
docs/FEDORA_43_SETUP.md, docs/EVDI_SETUP_GUIDE.md.
No stream -- Check adb devices shows your device. Check daemon is
running (./wbeam host status). Check version parity (./wbeam version doctor).
Inspect logs/ and desktop-connect.log.
EVDI not loading -- Run bash scripts/evdi-diagnose.sh --verbose --fix.
On Fedora, rerun ./redeploy-local; it will retry EVDI setup unless
WBEAM_REDEPLOY_WITH_EVDI=0 is set.
No supported encoder -- Fedora may lack H.265 encoders. WBeam falls back to
H.264 when openh264enc, x264enc, or nvh264enc is available. Run
scripts/fedora-setup.sh --yes --no-android-sdk to repair GStreamer packages.
Low FPS -- Switch to EVDI backend. Run ./wbeam host tuner to find
optimal encoding settings for your hardware.
Desktop UI issues on Wayland -- Launch via ./desktop.sh. If that fails,
try XDG_SESSION_TYPE=x11 ./desktop.sh.
- Linux: Arch, Debian, Ubuntu, Fedora, RHEL (kernel 5.10+ for EVDI)
- Android: API 17+ (Android 4.2+), USB 2.0+
./redeploy-local # build everything, deploy, launch
./wbgui # interactive menu for common tasks
./devtool # dev shortcutsSee docs/agents.workflow.md for branch/PR conventions and commit format.
See LICENSE file in repository root.