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 Portal 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 Portal.
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 -- ScreenCast/PipeWire capture for supported Wayland sessions. Consent and source types depend on the compositor. Automatic backend selection uses only available EVDI and Wayland Portal.
Legacy X11 modules remain in the source tree but are not supported capture paths and are not available in the release UI.
Control API: WBeam listens on 127.0.0.1:5001 by default for the
Android USB/ADB reverse workflow. To expose the unauthenticated API
to an isolated trusted LAN, both
WBEAM_CONTROL_BIND_ADDR=<LAN-IP> and
WBEAM_ALLOW_UNAUTHENTICATED_LAN_CONTROL=1 are required. Do not
enable this on an internet-facing interface; see docs/SECURITY_RELEASE.md.
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.
Inspect Tauri/WebKit dependencies and logs; switching to X11 is not supported.
- Release acceptance targets: Fedora 43 and Ubuntu 24.04 with GNOME Wayland, EVDI and Wayland Portal. Hardware QA evidence is required.
- Other distributions/kernels: may work, but not certified by this matrix.
- Android: API 17+ is the configured minimum; verify real device/codec
support using
docs/release-checklist.md.
./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.
The candidate tracked in epic #101 is not a certified stable release until quality and physical acceptance gates pass.
- Source development:
./install-wbeamand./redeploy-local. - Prebuilt RPM/DEB (once published): install with your package manager, launch
wbeam-desktop, and usewbeam android deployto install the bundled signed APK without Android SDK or Gradle. The DEB files are not interchangeable: usewbeam_*+bookworm_*.debon Debian 12 orwbeam_*+noble_*.debon Ubuntu 24.04. They are compiled against their respective EVDI ABI (libevdi0vslibevdi1). - Release signing:
docs/ANDROID_RELEASE_SIGNING.md. - Physical Android acceptance:
docs/release-checklist.md.
Rust/Cargo and RPM metadata currently declare MIT. Publication remains blocked
until the repository owner confirms legal terms and adds the root LICENSE
file. Do not infer a license grant solely from packaging metadata.