gnome-jarvis/docs/settings.md

Settings and voice customization

Open Settings in the Jarvis tray or conversation header. The window banner shows the Jarvis mark, Jarvis QVAC, and Local voice for your desktop · HoneyPeer, LLC. The standalone Control Center (python3 apps/control-center/main.py, gjs -m apps/control-center/main.js, or the installed Jarvis launcher) 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. 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

Identity

• Assistant name — assistantName, default "Jarvis". What to call the assistant in the tray HUD, spoken prompt, and workspace IDENTITY.md. Up to 32 characters. Apply writes the name without restarting jarvisd; the current conversation is reset so the new name takes effect.
• How they should act — assistantPrompt, default "". Optional character instructions (tone, habits, always/never). Shown as a multiline field under the name. Apply writes PERSONA.md for the workspace copy and puts the notes in the system prompt only, where they override SOUL.md / IDENTITY.md for name and character. Speakable-text rules still apply so replies can be read aloud. Up to 4000 characters.

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-4gb-mm (Qwen3.5 0.8B, vision), laptop-8gb, laptop-8gb-mm (Qwen3.5 2B, vision), 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. Gold #F4B942 is the brand default. Signal, Copper, Jade, and Rose are circular swatches; a custom hex field is also accepted. The hex field uses the GTK 4 entry buffer (set_max_length), not a maxLength constructor property. See brand for tokens and HUD rules.

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.