gnome-jarvis/docs/settings.md

# Settings and voice customization

Open **Settings** in the Jarvis tray or conversation header. The standalone
Control Center (`python3 apps/control-center/main.py`) uses the same pages.
Search is available in the window header.

## Choosing a voice

1. On **Voice**, enable **Spoken replies** and choose a speech model.
2. For Supertonic, choose a voice (F1–F5 or M1–M5), then adjust speed,
   quality steps, and volume. Start at speed 1.0–1.05 and 5 steps.
3. Edit **Preview text** and press **Apply & Preview**. **Stop** interrupts
   playback. The preview does not add a chat message or replace the last reply.
4. Use **Reset this page** to restore defaults in the form, then Apply.

Models offered by the installed QVAC SDK:

- **Supertonic English:** the existing lightweight default. Uses English.
- **Supertonic 3:** multilingual speech with a language picker. Its registry
  model supports the 31 languages listed in the window.
- **Chatterbox Turbo:** English speech with an optional local reference voice
  recording. Choose a clear mono WAV of at least five seconds. Leave it empty
  for the model's default voice. Supertonic voice IDs and speed do not apply.
- **Parler Mini:** English speech controlled by a written voice description.
  Describe pitch, tone, pace, and recording style. Variation, seed, CPU threads,
  and GPU acceleration are available. It does not use Supertonic voice IDs.

The preset voice IDs follow the [official Supertonic voice list](https://github.com/supertone-inc/supertonic/blob/main/web/README.md).
Older GGUF bundles may contain fewer voices. Unsupported voices or unavailable
models produce an error in Settings rather than silently falling back.

The presets and configuration fields were checked against the installed
`@qvac/inference` 0.19.1 schemas, model registry, and `@qvac/tts-ggml` 0.8.1
implementation. Each engine's native audio rate is used for playback (24 kHz
for Chatterbox, 44.1 kHz for Supertonic and Parler).

## Saving and applying

**Apply** saves the form and reloads voice, listening, audio routing, and desktop
settings. A running chat request must finish first. Loading a new model may
require a download and take time; the status row reports progress or errors.
Already downloaded assets use the QVAC cache. The preview requires spoken
replies to be enabled.

Chat model and agent-limit changes require **Models → Save & Restart**.
This saves pending changes and restarts `jarvisd.service`, ending current work.
If the service is not installed or D-Bus is unavailable, settings remain saved;
the status explains what still needs applying. The daemon also reads them on
its next launch. Appearance and hotkey changes apply immediately through GNOME.

Settings live in `$XDG_CONFIG_HOME/jarvis/config.json`, defaulting to
`~/.config/jarvis/config.json`. Opening a window does not write to this file.
Saving re-reads it and merges only changed fields, preserving unrelated keys
and changes from another window. Invalid JSON is reported and not overwritten.
Legacy snake_case keys and explicitly customized voice GSettings are migrated;
the JSON file takes precedence over GSettings. New writes use the keys below.

`JARVIS_TTS_MODEL`, `JARVIS_ASR_MODEL`, `JARVIS_WAKE_COMMAND`, and
`JARVIS_QVAC_MODEL` environment variables take precedence over the form. Apply
reports active overrides. The custom speech model must match the selected
engine; an arbitrary model does not change the engine automatically.

## Listening and desktop behavior

**Microphone input** disables capture entirely when off. **Hold Talk only**
keeps automatic wake and follow-up listening off; **One request per wake**
returns to the armed state after a reply. A wake phrase needs a configured
local detector trained to recognize it. Changing the text alone does not train
or install a detector.

Microphone and speaker pickers list PipeWire devices by name. An empty value
means the system default. Refresh after plugging in a device. Speech detection
controls adjust quiet-speech sensitivity, pause timing, minimum speech, maximum
recording duration, and post-playback echo protection.

Desktop mode is enforced: Disabled refuses grants, Observe only refuses input,
and Observe and control permits input within an explicit temporary grant.
Changing mode, duration, or budget revokes existing access. Screenshot dimensions
and WebP quality tune observation detail and processing cost.

## Complete daemon setting reference

### Speech

- **Spoken replies** — `ttsEnabled`, default `true`. Read replies aloud using local speech synthesis.
- **Speech model** — `ttsPreset`, default `"supertonic-en"`. Models download on first use. Larger models need more memory. Choices: `supertonic-en`, `supertonic3`, `chatterbox`, `parler`.
- **Voice** — `voiceId`, default `"F1"`. Try the same preview with different voices. Available voices depend on the model bundle. Choices: `F1`, `F2`, `F3`, `F4`, `F5`, `M1`, `M2`, `M3`, `M4`, `M5`.
- **Speech language** — `ttsLanguage`, default `"en"`. The English models always use English. Choose Supertonic 3 for other languages. Choices: `en`, `ko`, `ja`, `ar`, `bg`, `cs`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`, `hi`, `hr`, `hu`, `id`, `it`, `lt`, `lv`, `nl`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sv`, `tr`, `uk`, `vi`.
- **Speaking speed** — `ttsSpeed`, default `1.05`. 1 is normal speed; lower is slower. Range: 0.25–4.
- **Voice quality steps** — `ttsSteps`, default `5`. More steps can improve quality but take longer. Range: 1–30.
- **Reply volume (%)** — `ttsVolume`, default `100`. Relative to the system speaker volume. Does not change other apps. Range: 0–100.
- **Preview text** — `previewText`, default `"Hello. I am Jarvis. This is how I will sound with your settings."`. Use the same sentence to compare voices.

### Voice design

- **Reference voice recording** — `ttsReferenceAudio`, default `""`. Choose a clear mono WAV recording of at least 5 seconds. Leave empty for the model’s default voice.
- **Synthesis quality steps** — `ttsCfmSteps`, default `2`. Chatterbox: fewer steps respond faster. Range: 1–10.
- **Describe the voice** — `ttsDescription`, default `"A clear, warm voice speaks at a natural pace in a quiet room."`. Parler: describe tone, pace, pitch, and recording style in English.
- **Voice variation** — `ttsTemperature`, default `1`. Parler: higher values produce more variation. Range: 0–2.
- **Voice seed** — `ttsSeed`, default `42`. Use a fixed seed for repeatable speech generation. Range: 0–2147483647.
- **Speech CPU threads** — `ttsThreads`, default `4`. Limit CPU work for Chatterbox and Parler. Range: 1–32.
- **Accelerate speech with GPU** — `ttsUseGpu`, default `false`. Use a supported GPU backend for speech synthesis. May increase GPU memory use.
- **Custom speech model** — `ttsModel`, default `""`. Advanced: registry name or local GGUF matching the selected speech model. Empty uses the bundled preset.

### Listening

- **Microphone input** — `microphoneEnabled`, default `true`. Turn off for typed chat and speech output only.
- **Recognition model** — `asrModel`, default `"WHISPER_TINY"`. Larger models need more memory and download on first use. Choices: `WHISPER_TINY`, `WHISPER_BASE_Q8_0`, `WHISPER_SMALL_Q8_0`.
- **Recognition language** — `asrLanguage`, default `"en"`. Whisper language code such as en, es, fr, or auto.

### Wake and privacy

- **Wake phrase** — `wakePhrase`, default `"hey jarvis"`. Must match a phrase supported by your local wake detector.
- **Wake aliases** — `aliases`, default `["jarvis", "okay jarvis"]`. Additional detector phrases, separated by commas.
- **Wake detector command** — `wakeCommand`, default `"jarvis-wake-bridge"`. Built-in CPU detector for Hey Jarvis. Replace it only if you have openWakeWord or sherpa. Empty disables the detector and uses Hold Talk.
- **Listening behavior** — `listeningMode`, default `"conversation"`. Hold Talk only disables the wake detector and automatic follow-up listening. Choices: `conversation`, `single`, `ptt`.
- **Idle sleep delay (minutes)** — `idleMinutes`, default `30`. Sleep after this much listening inactivity. Range: 1–240.
- **Free GPU memory when idle** — `freeVramOnIdle`, default `true`. Unload speech and chat models after the idle delay. The microphone and Hey Jarvis detector stay ready on the CPU. The first reply after a long idle reloads models.

### Detection tuning

- **Speech detection threshold** — `vadThreshold`, default `0.6`. Lower picks up quieter speech; higher rejects more background noise. Range: 0.05–1.
- **Minimum speech (ms)** — `vadMinSpeechMs`, default `300`. Ignore very short sounds during automatic listening. Range: 100–2000.
- **Pause before sending (ms)** — `vadSilenceMs`, default `700`. Wait this long after speech before sending your request. Range: 200–3000.
- **Maximum recording (seconds)** — `vadMaxSpeechSeconds`, default `15`. Limit each recorded utterance, including pauses. Range: 3–120.
- **Echo protection after replies (ms)** — `playbackCooldownMs`, default `400`. Delay microphone processing after speech output ends. Range: 0–2000.

### Audio routing

- **Microphone device** — `inputTarget`, default `""`. System default follows your desktop sound settings. Refresh the list after connecting a device.
- **Speaker device** — `outputTarget`, default `""`. System default follows your desktop sound settings. Refresh the list after connecting a device.

### Desktop access

- **Desktop access mode** — `computerMode`, default `"act"`. A temporary Allow now grant is always required. Changing this revokes existing access. Choices: `off`, `observe`, `act`.
- **Actions per grant** — `computerSteps`, default `20`. Maximum input actions before another grant is needed. Range: 1–100.
- **Grant duration (minutes)** — `computerGrantMinutes`, default `3`. Desktop access expires automatically. Range: 1–15.

### Desktop images

- **Screenshot maximum edge (pixels)** — `screenshotMaxEdge`, default `1280`. Larger screenshots preserve detail but take more memory. Range: 640–2560.
- **Screenshot quality (%)** — `screenshotQuality`, default `70`. Higher WebP quality preserves more text detail. Range: 30–95.

### Chat model

- **Chat model profile** — `modelProfile`, default `"laptop-16gb"`. Requires a daemon restart. GPU inference remains required. Choices: `laptop-8gb`, `laptop-16gb`, `desktop-gpu`.
- **Custom chat model** — `chatModel`, default `""`. Advanced: overrides the profile. Empty uses the profile model. Requires restart.

### Agent limits

- **Maximum reasoning turns** — `maxTurns`, default `6`. Requires restart. Limits how long the assistant works on one request. Range: 1–30.
- **Shell commands per request** — `maxShellCalls`, default `1`. Requires restart. Commands still require normal permissions. Range: 1–10.
- **Tool rounds per request** — `maxToolRounds`, default `4`. Requires restart. Limits repeated tool use. Range: 1–20.
- **File access** — `fsAccess`, default `"workspace"`. Requires restart. Limits `read_file`, `list_dir`, `grep`, and the `fs_*` tools. The agent still runs as your user account, not root, and asks before writing. Shell commands can already reach other paths. Choices: `workspace`, `home`, `filesystem`.

## GNOME appearance and boundaries

The Desktop page also exposes the GNOME hotkey, accent color, and tray versus
expanded layout. These retain their GSettings keys: `hotkey`, `accent-color`,
and `overlay-style`.

Previously displayed controls for chimes, legacy input fallback, enrollment,
startup, memory ingestion, Lab toggles, transcript retention, and disabling
confirmations did not consistently have working consumers. They are not
presented as working controls in the shared window. Their stored values are
preserved. Confirmations remain enforced; desktop mode is not a permission
bypass. CosyVoice3 and Audio8 need additional component and reference-text
configuration and are not offered as presets in this change.

## Verification

- `npm test`: migration, merging, validation, installed SDK schemas and registry,
  adapter forwarding, volume, device routing, listening modes, VAD limits,
  grant enforcement, preview behavior, and settings reload.
- `bash packaging/bare-launch.sh packaging/bare-run.js scripts/smoke-settings-runtime.js`:
  validates the settings-to-adapter path under Bare without loading models.
- `XDG_CONFIG_HOME=/tmp/jarvis-settings-smoke GSETTINGS_BACKEND=memory gjs -m scripts/smoke-settings-ui.js`:
  opens all four pages, saves page images under `/tmp`, checks engine-specific
  control visibility, and closes. It does not save or apply settings.

Live audio quality, model downloads, and GPU support depend on the host and
selected model; the automated schema checks do not establish those results.