Onboarding Wizard

Five steps to nail down microphone, hotkey, models, APIs, and how to actually use it.

• Auto-pops on first install
• Re-opens on version bump
• All values written to ~/.zimablueai_config/config.json
• Re-open any time via the "Setup Wizard" button

Overview

The wizard is a full-window overlay. On open, the Tauri window resizes to roughly 85% × 88% of the current monitor's work area (capped at 1240 × 840 logical pixels) and centers itself. A 5-step pill rail lives on the left; the active step's card occupies the right pane; every non-interactive surface is a Tauri drag region — you can drag the window from anywhere.

Trigger logic

Whether the wizard auto-opens depends on two fields in config.json: onboarding.completed and onboarding.appVersion.

Scenario	Condition	Result
First install / cleared config	config.json does not exist	Wizard opens automatically
Upgrade (version bump)	onboarding.appVersion ≠ current version	Auto-opens (migration / new fields)
Completed & version matches	completed: true and versions equal	Silent launch
Manual re-configure	Click "Setup Wizard" in main panel	Pre-fills from current config, opens
User skipped	Click "Skip"	Writes skipped: true, no re-pop this version

Step 1 · System microphone

Get "does my mic work?" out of the way first.

• System input device: dropdown populated from list_audio_input_devices; the default device is annotated.
• Detected / Selected / Permission: three status cards. Permission can be "Not checked / Granted / Denied".
• Rescan devices: re-queries the backend; hot-plugged headphones show up immediately.
• Request mic permission: calls getUserMedia; success unlocks the live waveform; failure flips permission to "Denied".
• Live waveform test: 64-band canvas meter — if the bars dance, your mic is good.

Step 2 · Hotkey

One stable physical key to start/stop recording. The wizard only accepts 6 recommended keys — arbitrary letter combos are intentionally rejected to avoid global-shortcut collisions.

Key	Mac equivalent	Note
Right Alt ★ recommended	⌥ Right Option	One-handed, no conflicts (default)
Left Alt	⌥ Left Option	For left-hand use
Right Ctrl	⌃ Right Control	Low conflict on the right side
Left Ctrl	⌃ Left Control	May collide with editor shortcuts
Right Shift	⇧ Right Shift	May collide with IME
Left Shift	⇧ Left Shift	May collide with IME

Live key preview: focus the dark panel and press any key. The wizard uses KeyboardEvent.code (AltLeft/AltRight/ControlLeft/...) to disambiguate left vs right reliably. Unsupported keys (e.g. Win/⌘ or letters) just echo back with "(unsupported)" — no state change.

Step 3 · Models & parameters

Three base modules in one go. Fine-grained tuning lives in the main panel.

Step 4 · API providers

Eleven providers ship out-of-the-box. Each card opens to Base URL, API Key, and one input per supported capability (LLM / ASR / TTS / Realtime). Filling an API Key is treated as "enabled".

How models map to features

• LLM values are written to translateApiBaseUrl / translateApiKey / translateModel — translation panel works immediately.
• TTS values land in cfg.tts.cloudTtsModel as a cloud fallback (does not overwrite the local TTS you picked in Step 3).
• ASR / Realtime values are stored in cfg.onboarding.providers for the corresponding panels to consume.
• Comma-separated values are allowed for multiple model names; empty fields fall back to provider defaults.

Step 5 · Usage guide

Three SVG-animated cards explain the headline scenarios in 30 seconds:

1. One-key record → transcribe: press Right Alt to start, press again to stop; transcript follows the cursor.
2. TTS: type text or pick a history clip; one-click read-aloud with voice cloning.
3. STS (translation): workbench mode — source voice → live ASR → target language → TTS, with timbre preserved.

Config file reference

On save, the wizard writes to ~/.zimablueai_config/config.json. Key fields:

{
  "stt": {
    "inputDeviceName": "Headset Microphone (MCP01)",
    "backend": "sensevoice",
    "modelDir": "D:/models/SenseVoiceSmall",
    "hotkey": "RightAlt"
  },
  "tts": {
    "ttsModel": "qwen3_tts",
    "modelDir": "D:/models/qwen3-tts",
    "cloudTtsModel": "speech-01-v2"
  },
  "sts": {
    "sourceLanguage": "zh",
    "targetLanguage": "en"
  },
  "translateApiBaseUrl": "https://api.openai.com/v1",
  "translateApiKey": "sk-***",
  "translateModel": "gpt-4o-mini",
  "translateEnabled": true,
  "onboarding": {
    "completed": true,
    "skipped": false,
    "version": 1,
    "appVersion": "0.4.0",
    "completedAt": "2026-05-11T08:42:13.000Z",
    "providers": {
      "openai": {
        "enabled": true,
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-***",
        "models": { "llm": "gpt-4o-mini", "tts": "tts-1" }
      }
    }
  }
}