This guide walks through every control in the Electron desktop companion. Prefer the Windows installer when you can. From source: npm run desktop. Browser / localhost (npm run dev) is for contributors; some desktop-only features (overlay, device loopback, window scale, snap pad) are unavailable or limited there.
Related: Installation · User settings / config.yaml
- A transparent always-on-top window appears (overlay mode).
- The avatar loads (Avatar 1 by default).
- Motion starts on Default:
- Greeting plays once
- Then a loop forever: Model Pose → Show Full Body → Peace Sign → Squat → Shoot
- On desktop, audio defaults to Device output (auto) so lip sync can follow system sound when capture is active.
- Environment defaults to a soft lavender color fade (
#e9e1fa). - Preferences from a previous session load from
config.yamlif present (see User settings).
Glass bar at the bottom: drag handle (line), window scale, optional green live dot, gear menu.
- Drag the horizontal glass line.
- Or open Settings and use the 3×3 snap pad to jump to a screen position.
Tap the Scaling control (left of the live dot / gear). Choose:
| Preset | Effect |
|---|---|
| ×0.5 | Half size |
| ×1 | Default (~420×560 logical) |
| ×2 | Double size |
Scale is remembered in config.yaml.
A green pulsing dot appears when lip sync is actively capturing (Audio source not Off, status active). Hover title: Lip sync active.
| Item | Opens / does |
|---|---|
| Appearance | Avatars (built-ins or custom folder + VRoid Hub), environments |
| Voice | Audio source / lip sync |
| Camera & Lighting | Camera, lights, avatar transform |
| Animations | Submenu of clips (no drawer) |
| Pinned / Windowed | Toggle overlay vs opaque window (desktop) |
| Settings | Overlay mode, Snap to screen, Directories, VRoid Hub, System (reset / config path) |
| Close | Quit the companion window (desktop) |
Gear → Appearance.
Pick Avatar 1 / 2 / 3 when Directories → Avatars is Default.
On desktop you can point Settings → Directories → Avatars at a folder of .vrm files — Appearance then shows those instead of the bundled list. VRoid Hub stays under Avatars either way. Picker thumbnails are static images, so the drawer opens without rendering every model: bundled avatars ship with theirs, and a custom folder builds its own the first time you open it — cards fill in as each finishes, and are instant from then on. Details: Avatars.
On desktop, when VRoid Hub is connected, a VRoid Hub block appears under the built-in thumbnails so you can pick Hub characters here (setup still lives under Settings). Picking a hearted (someone else’s) character first shows its conditions of use, where View on VRoid Hub opens the model’s own page in your browser so you can check the author’s terms at the source. See VRoid Hub connection.
| Option | What you get |
|---|---|
| Stars | Dark starfield GIF |
| Code | Code-rain GIF |
| Bloom | Bright pastel GIF (bar often switches to “light” chrome) |
| None | No stage backdrop — desktop shows through (overlay) |
| Custom | Desktop: Settings → Directories → Environments (.gif / .png / .jpg / .jpeg). Dev with Directories Default: also src/assets/environments/custom/. Opening Custom hides built-ins until closed; Color fade stays pinned under the list |
| Color fade | Soft glow from a color you pick → Use color |
| Reset | Back to lavender #e9e1fa |
Full detail: Environments.
The bar and circular controls adapt to what sits behind the bar:
| Backdrop | Bar | Buttons |
|---|---|---|
| Dark | Whitish | Darker grey glass + white icons |
| Light | Grey | Lighter grey glass + dark icons |
In overlay mode the app samples the desktop near the window after you finish moving (and on focus), then crossfades bar/button colors. Environment GIFs themselves never change. In browser / windowed mode chrome follows the chosen environment.
Gear → Voice.
Go deeper: Audio sources (every input) · Lip sync (how the mouth moves).
| Source | When to use |
|---|---|
| Device output (auto) | (Default) Follow speakers / system audio via loopback |
| Pick app window | Lip sync to one app/window’s audio |
| Microphone | Your mic |
| Audio file | Play a local file into the analyser |
| Off | No lip sync |
Off (default), Microphone, Tab or window audio, Audio file.
- Status line shows
idle/starting/active/error/ … - Use Restart audio capture if OS permissions or devices change.
- Mouth shapes are amplitude-based (not phoneme ASR). See Lip sync and Audio sources.
Gear → Camera & Lighting. Three sections:
| Control | Default | Notes |
|---|---|---|
| X | -0.01 |
Horizontal framing |
| Y | 0.59 |
Height (heads stay in frame) |
| Z | 1.69 |
Distance |
| Look Y | 0.5 |
Look-at height |
| FOV | 26.8 |
Field of view |
- Reset Camera — restore all camera defaults.
- Double-click a slider — reset that control only.
| Control | Default |
|---|---|
| Intensity | 0.7 |
| X / Y / Z | 1, 2, 2 |
| Color | #ffffff |
- Reset Light — full lighting defaults.
- Double-click sliders for per-axis / intensity reset.
Position X / Y / Z (default 0, -1.03, -1.48).
Reset Avatar restores position and default facing.
See Camera & lighting.
Gear → Animations.
- Greeting once
- Loop: Model Pose → Show Full Body → Peace Sign → Squat → Shoot
Spin is available as a one-off clip but is not in the Default loop.
Pick any listed VRMA clip to play that motion only. Choosing Default again restarts the greeting + loop.
Catalog: VRMA.
Gear → Settings. Section titles share one style: Overlay mode, Snap to screen, Directories, VRoid Hub, System.
- On (Pinned): Transparent, always on top — companion over your apps.
- Off (Windowed): Opaque lavender window, normal stacking.
Also toggle from the gear Pinned / Windowed item.
Tap a cell in the 3×3 pad (divider separates this from Overlay mode):
Top left | Top center | Top right
Center left | Center | Center right
Bottom left | Bottom center | Bottom right
The active cell stays highlighted. If you drag the glass bar by hand, the highlight clears (no cell selected).
Three rows — Avatars, Animations, Environments:
| Row | Behavior |
|---|---|
| Avatars | Default (bundled) or Custom folder of .vrm files — replaces the Appearance avatar strip |
| Animations | Default (bundled pack) or Custom folder of .vrma files — replaces the Gear → Animations list |
| Environments | Default or Custom folder of images — adds the Appearance Custom expander; built-ins stay |
Every row scans the folder you pick top level only — subfolders are ignored. File names become menu labels.
A folder with no matching files is not applied (error notice; previous source kept). Reset a row (or System → Reset all settings) returns that source to Default. Choices persist in config.yaml under directories (mode + path).
With Animations → Custom active, the bundled Default greeting sequence and the VRMA Motion Pack are hidden — the folder is the whole menu. Your saved clip is matched by file path, so it survives a rescan; if that file is gone, the first clip in the folder is selected instead. Back on Default, the selection returns to the bundled Default sequence. Making your own .vrma: VRMA animations.
Register your own VRoid Hub OAuth app, paste Client ID / secret, then Connect VRoid Hub account. After connecting, pick characters under Appearance → Avatars. Hub models are not stored on disk — they last for the current session only.
Full steps (redirect URI, app form fields, hearted-model license gate, troubleshooting): VRoid Hub connection.
Reset all settings wipes saved preferences (including Directories paths) and restores factory defaults (avatar, animation, environment, camera, light, avatar transform, audio source, overlay, window scale, directories). It does not remove encrypted VRoid Hub credentials — use Remove app credentials / Disconnect in the VRoid Hub block for that.
| Where | Control |
|---|---|
| Appearance → Environments | Reset (color fade) |
| Camera & Lighting → Camera | Reset Camera / double-click slider |
| Camera & Lighting → Lighting | Reset Light / double-click slider |
| Camera & Lighting → Avatar | Reset Avatar / double-click slider |
| Voice | Restart audio capture (does not change which source is selected) |
Persistence details: User settings.
- Place the companion with drag or the snap pad.
- Set scale ×0.5 / ×1 / ×2.
- Appearance → pick avatar and environment. Optional: Settings → Directories for local folders, and/or Settings → connect VRoid Hub then Appearance → pick a Hub character.
- Voice → Device output (or window/mic) until the green dot appears when sound plays.
- Leave Default animation running, or pick a single clip.
- Nudge Camera if framing feels off; use section resets or Reset all if you want a clean slate.
- There is no global hotkey set yet — all actions are pointer-driven.
- Click outside a drawer/menu (or blur the window on desktop) to dismiss menus.
- The 3D canvas does not steal drag — move via the glass bar.