Skip to content

Setup Guide English

Jump to bottom
zkwi edited this page Apr 27, 2026 · 5 revisions

VoxType User Configuration Guide

This page helps new users configure VoxType with the minimum required setup first, then enable optional quality, shortcut, caption, update, and troubleshooting features as needed.

简体中文版本：用户配置指南

1. Installation and Requirements

VoxType targets Windows 10/11.

Download the Windows installer from GitHub Releases:

https://github.com/zkwi/VoxType/releases

The installer includes the Microsoft Edge WebView2 Bootstrapper. If WebView2 Runtime is missing, the installer will install it automatically.

Before recording, allow desktop apps to access the microphone:

Windows Settings → Privacy & security → Microphone → Let desktop apps access your microphone

2. Main Pages

Page Purpose
Home Current input state, start/stop recording, triggers, and input performance
Hotwords & prompts Custom hotwords, scene notes, polishing prompt, and automatic hotword candidates
API Config Required Doubao ASR credentials and optional LLM API
Options Shortcut, paste mode, microphone, captions, startup, and close behavior
Statistics Recent 24-hour, 7-day, and daily usage statistics

Settings are split into three levels:

  • Default: required or frequent settings.
  • Advanced: troubleshooting or low-frequency settings.
  • config.toml only: low-level implementation parameters that remain supported but are not shown in the UI.

3. Required: Doubao ASR

VoxType requires Doubao streaming ASR for the main voice input flow. Without ASR credentials, recording, recognition, and paste actions remain locked.

Open API Config → Doubao authentication and fill in:

Field Required Notes
App Key Yes From Volcengine console
Access Key Yes From Volcengine console
Resource ID Yes Default is usually volc.seedasr.sauc.duration

Then click Test.

Official Doubao documentation:

https://www.volcengine.com/docs/6561/1354869?lang=en

Never commit real API keys to GitHub or share your local config.toml.

4. Optional: LLM Polishing API

The optional LLM API is used for:

  • Light text polishing.
  • Structuring longer dictated text.
  • Generating automatic hotword candidates.

Open API Config → LLM API:

Field Notes
Enable polishing Off means ASR only
Base URL OpenAI-compatible endpoint, for example https://dashscope.aliyuncs.com/compatible-mode/v1
API Key Key from your provider
Model For example qwen3.5-plus

Performance recommendations:

  • Keep thinking disabled for voice polishing unless your provider requires it.
  • Text shorter than min_chars = 40 is not polished by default.
  • Increase timeout only when the network or model is slow; timeout does not make polishing faster.

5. Hotwords and Prompts

Open Hotwords & prompts.

Custom Hotwords

Use one word or phrase per line:

  • Names
  • Product names
  • Project names
  • Technical terms
  • English abbreviations

Do not put passwords, ID numbers, phone numbers, or customer-sensitive information in hotwords.

Polishing Prompt

The prompt entry is visible by default. You can edit and save it even when LLM polishing is disabled; it only takes effect after LLM polishing is enabled.

You can:

  • Restore the default prompt.
  • Preview the final prompt.
  • Edit the User Prompt template.

System Prompt and minimum polishing length are advanced settings.

Recent Context

Recent context is disabled by default. When enabled, VoxType stores recent recognition snippets in local context/recent_context.jsonl for continuous dictation context.

It only stores VoxType recognition snippets, does not record keyboard input, does not write text back into config.toml, and can be cleared from advanced settings.

Automatic Hotword Candidates

Automatic hotword candidates are disabled by default. When enabled, VoxType stores final voice input text locally. Only when you manually click generate will it call the configured LLM service.

Candidates are not automatically added. You must select and confirm them.

6. Options

Default Options page:

Group Visible by default
Usage Main shortcut, startup, close behavior
Output Auto paste / clipboard only, remove trailing period
Microphone Input device
Caption appearance Preview, color presets, opacity presets

Advanced settings:

  • Backup triggers: main shortcut switch, middle mouse, right Alt.
  • Paste compatibility: full paste mode, clipboard restore, restore delay.
  • Caption fine-tuning: colors, width, height, bottom margin.
  • Recording and troubleshooting: max recording time, local silence auto-stop, mute system volume while recording.
  • Updates and diagnostics: check updates, update now, open logs, copy diagnostic report.

7. Recommended Defaults

Setting Recommended Why
Main shortcut Ctrl + Q Low conflict and easy to remember
Middle mouse Off May conflict with browsers or editors
Right Alt Off May conflict with IME or system shortcuts
Paste mode Auto paste Works for most fields
Clipboard restore On Restores previous clipboard when possible
Silence auto-stop 10 seconds Prevents server endpointing misses from recording until the max duration
Recent context Off More conservative by default
Automatic hotwords Off Does not store transcript history by default
Mute system volume while recording Off Avoids affecting meetings, videos, and notifications
Thinking Off Faster for voice polishing

8. Key config.toml Fields

Minimal ASR:

[auth]
app_key = ""
access_key = ""
resource_id = "volc.seedasr.sauc.duration"

Optional LLM:

[llm_post_edit]
enabled = false
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key = ""
model = "qwen3.5-plus"
min_chars = 40
enable_thinking = false

Recording:

[audio]
max_record_seconds = 300
silence_auto_stop_seconds = 10
mute_system_volume_while_recording = false

Triggers:

[triggers]
hotkey_enabled = true
middle_mouse_enabled = false
right_alt_enabled = false

Output:

[typing]
paste_method = "ctrl_v"
remove_trailing_period = true
restore_clipboard_after_paste = true
clipboard_restore_delay_ms = 1800

Updates:

[update]
auto_check_on_startup = true
github_repo = "zkwi/VoxType"

9. First Use Checklist

  1. Install and start VoxType.
  2. Open API Config and fill in Doubao ASR App Key, Access Key, and Resource ID.
  3. Click Test for ASR.
  4. Return to Home and put your cursor in a target input field.
  5. Press Ctrl + Q to start recording, then press it again to stop. If input remains silent, VoxType stops automatically after 10 seconds by default.
  6. Wait for final recognition and optional polishing.
  7. If text does not appear in the target field, press Ctrl + V manually.

10. Next Steps

简体中文

English

Clone this wiki locally