# VuvoDesk Client

For normal users, run the unified VuvoDesk application:

```powershell
npx -y --prefer-online livedesk@latest
```

The direct Client form remains available for compatibility and diagnostics.

```powershell
npx -y --prefer-online livedesk@latest client
npx -y --prefer-online livedesk@latest client 3
```

`@livedesk/client` is the internal direct package and remains available for
advanced diagnostics. The public command above keeps Hub and client versions
aligned.

The default flow lets the local Client runtime own Google authorization,
callback exchange, and saved authentication as one path. The browser only
shows progress; it does not maintain a second session that must be transferred
back to the Client. VuvoDesk then waits for the active Hub published by the
same account and connects locally. If the Hub is not
ready yet, the client waits for a Hub-online event and polls the registry at
most every six seconds as a fallback. Missing a wake event can never leave a
Client asleep for minutes. If a
connected Hub is replaced, the launcher also leaves the stale endpoint and
discovers the newly published Hub without another Google login. Omit the number
for first-available placement, or pass `1` to `999` to pin this machine to a
screen wall slot.

On Windows, check **Start with Windows** on the connection page to reconnect this
client automatically after reboot. The startup entry reuses the saved Google
session and only opens the connection page again if sign-in is needed.

On the Hub computer, open the VuvoDesk dashboard, sign in, and run **Sync
Server** once. The dashboard transfers the signed-in session to the local Hub;
the Hub process then keeps its own local address and private pair token
refreshed in the VuvoDesk Supabase registry. The dashboard can be closed after
that while the Hub remains running.

Supabase Auth must allow the CLI callback URL:

```text
http://127.0.0.1:5179/callback
```

If you use a custom port, run `npx -y --prefer-online livedesk@latest client --auth-port 5200` and add
the matching callback URL to Supabase Auth redirect URLs.

The client registers the device, sends status heartbeats, can return
Hub-requested thumbnails, can stream a focused view-only live screen, and
can receive safe task-only instructions. The C# RemoteFast engine also supports
keyboard/mouse control on Windows, macOS, and Linux/X11, file transfer, and
system-audio playback from Windows, macOS, and Linux. Linux captures the default
output through PipeWire `pw-record` or PulseAudio `parec`. macOS control requires Accessibility
permission for the terminal app that started VuvoDesk; screen streaming and
system-audio capture require Screen Recording permission. VuvoDesk checks these
permissions without opening repeated system dialogs and prints the matching
System Settings path when access is missing; after granting access, restart the
client. When file transfer is enabled by the Hub, received files are saved
to `Desktop/VuvoDeskFiles` unless the Hub sets another destination folder.

By default, the launcher uses the packaged C# RemoteFast engine when supported.
It falls back to the Node engine only when a compatible RemoteFast runtime is
unavailable. Windows, macOS, and Linux all try RemoteFast first so
the Hub can request the Mode 3 hardware video path when it is available.
RemoteFast is shipped as a platform-specific self-contained .NET executable,
so client computers do not need a separate .NET installation.
The launcher also includes a prebuilt ffmpeg executable through
`@ffmpeg-installer/ffmpeg` and passes it to RemoteFast automatically. Set
`LIVEDESK_FFMPEG` to override that path. If you need LGPL-only distribution,
point `LIVEDESK_FFMPEG` at a verified LGPL ffmpeg build before shipping.

Useful flags:

```powershell
npx -y --prefer-online livedesk@latest client 3
npx -y --prefer-online livedesk@latest client --no-thumbnail
npx -y --prefer-online livedesk@latest client --no-live
npx -y --prefer-online livedesk@latest client --no-audio
npx -y --prefer-online livedesk@latest client --files-dir "D:\VuvoDeskFiles"
npx -y --prefer-online livedesk@latest client --engine node
npx -y --prefer-online livedesk@latest client --engine fast --trace-frames
npx -y --prefer-online livedesk@latest client --auth-port 5200
npx -y --prefer-online livedesk@latest client --logout
```

Frame pipeline roadmap:

- Mode 1: `mode1-jpeg` - current test path using screen capture, resize, and JPEG binary frames.
- Mode 2: `mode2-lzo` - cross-platform wall path using independent RGB565LE frames capped at 320x180 and compressed as LZO1X blocks. The wall defaults to 8 fps. macOS and Linux keep one persistent local capture helper per client process. Legacy `mode2-lz4` settings migrate to this mode.
- Mode 3: `mode3-h264-hw` - OS-specific H.264 path. Windows tries Media Foundation/NVENC/QSV/AMF, macOS prefers ScreenCaptureKit plus VideoToolbox, and Linux tries NVENC/VAAPI/QSV before falling back to the bundled ffmpeg `libx264` encoder. Linux users do not need to install ffmpeg separately when starting VuvoDesk through the published npm package. macOS emits one startup key frame and then an approximately half-second recovery GOP. The launcher uses bundled ffmpeg for fallback paths unless `LIVEDESK_FFMPEG` points to a custom binary. On macOS, set `LIVEDESK_FFMPEG_AVFOUNDATION_INPUT` only when the ScreenCaptureKit helper is unavailable and the AVFoundation fallback input is not `1:none`.

Legacy mode names such as `remote-fast` and `remote-quality` are treated as
Mode 1 aliases.