nbphone

nbphone adds Android phone mirroring and a phone-powered webcam to a Linux desktop through a small, scriptable CLI. It manages ADB connections and starts scrcpy without duplicating file transfer, notifications, or messaging. KDE Connect, LocalSend, and Syncthing remain the right tools for those jobs.

The project targets Arch Linux, niri, and nbshell, while its JSON status output is intentionally desktop-shell independent.

Install

sudo pacman -S android-tools scrcpy
git clone https://github.com/nerdislb/nbphone.git ~/projects/nbphone
~/projects/nbphone/install.sh

On the phone, enable Settings > System > Developer options > USB debugging, connect USB, approve the computer, and run:

nbphone doctor
nbphone start

Phone webcam

The webcam mode sends an Android 12+ camera directly to a V4L2 loopback device. OBS, browsers, and conferencing apps see it as Phone Camera. No Android app is required.

Run the one-time Arch Linux setup. It installs v4l2loopback-dkms, v4l-utils, and the header package matching the running kernel, then creates /dev/video10:

nbphone camera setup

Start either camera and select Phone Camera as a Video Capture Device in OBS:

nbphone camera back
nbphone camera front
nbphone camera status
nbphone camera off

The phone may be connected through USB or an existing wireless ADB connection. Mirroring and webcam capture are managed as independent scrcpy processes. The managed webcam includes a watchdog: if Android or scrcpy disconnects the camera after a stable run, nbphone restarts the same camera automatically while keeping the /dev/video10 source path unchanged. Five consecutive rapid failures stop the watchdog instead of creating an endless restart loop. The loopback also repeats the last frame and switches to a null frame after three seconds without input, so OBS does not enter a high-volume V4L2 timeout/log loop while the phone camera reconnects.

Wireless ADB

For a simple USB-assisted setup, run nbphone wireless. It reads the phone's Wi-Fi address, switches ADB to TCP port 5555, connects, and remembers the endpoint. Android disables this mode after a phone reboot, so USB is required once again afterward.

Android's encrypted Wireless debugging flow also remains available:

nbphone pair HOST:PAIRING_PORT
nbphone connect HOST:CONNECTION_PORT

Commands

nbphone status [--json]       Show ADB, mirror, and webcam status
nbphone doctor [--json]       Check core dependencies and connection
nbphone pair HOST:PORT        Pair wireless ADB
nbphone connect [HOST:PORT]   Connect or reuse the remembered endpoint
nbphone disconnect            Disconnect the remembered Wi-Fi endpoint
nbphone wireless              Enable or reconnect USB-assisted Wi-Fi ADB
nbphone start [--private]     Start phone mirroring
nbphone stop                  Stop the managed mirror
nbphone camera setup          Install and configure the loopback device
nbphone camera list           List cameras reported by the phone
nbphone camera back|front     Start a phone camera on /dev/video10
nbphone camera off            Stop the managed camera stream

--private turns off the physical display while mirroring. The phone remains unlocked, so this is a convenience option rather than a security lock.

Desktop shells should consume nbphone status --json and invoke these public commands instead of managing scrcpy processes directly.

Credits

The phone-webcam workflow was inspired by omarchy-dori. See THIRD_PARTY.md for attribution.

License

MIT