Skip to main content

FAQ

Recording​

The recording has no sound, or the transcription is empty​

  1. Check that the system recognises the microphone.
  2. Confirm that the recording tool is installed (parecord).
  3. Check the log output: RUST_LOG=altgo=debug altgo.

Recording starts slowly​

The first recording may take a few seconds to initialise the device. Later ones are faster.

Trigger key​

Pressing right Alt does nothing​

First click Check trigger key in the empty state on the home page. It waits for one press, then compares the captured key name and code with the configured trigger key. The press records normally, so the same press also verifies transcription. The result falls into one of these cases:

  • The trigger key works: the key reaches altgo, so the problem is in recording or transcription. Follow the Recording and Transcription sections.
  • It shows a different key: the captured key and the configuration do not match. Note the two key codes shown, then use Press to set in Settings to change the trigger key to the key you actually press.
  • It shows the captured key was injected by another program (Windows only): the key reaches altgo with a marker that another program synthesised it. altgo ignores these events, so no recording starts. Remapping tools, keyboard vendor drivers and some input methods inject keys this way. Stop them or change their mapping.
  • It reports that no key was received: the key never reaches altgo. Work through the list below.

Linux:

  1. Is the user in the input group, and did you log out and back in? Key listening fails when /dev/input/event* cannot be read: run sudo usermod -aG input "$USER", then log out or restart and try again.
  2. Confirm that xinput is available: which xinput (the X11 path).
  3. Check the Alt binding: xmodmap -pke | grep Alt. The configuration defaults to key_name = "Alt_R", which should match Press to set in Settings.
  4. Wayland: key listening still needs evdev access. With only XWayland and no permission, the symptom is the same as a missing input group. For the clipboard on Wayland, install wl-copy (or use xclip/xsel through XWayland).
  5. If you use an IME, increase min_press_duration to reduce accidental triggers.

Windows:

altgo uses a global low-level keyboard hook on Windows. Another program registering the same hotkey does not stop the hook from receiving keys, so "another application owns it" is usually not the cause. Hook failures fall into three cases: SetWindowsHookExW fails, a callback times out and the system removes the hook, or a key remapping tool replaces the key at a lower level. Start with RUST_LOG=altgo=debug altgo; the log should contain Windows keyboard hook installed with key and vk fields. When reporting a problem, include this log section and the raw key code from the probe card. The key code appears on the diagnostic line only when it differs from the configured trigger key.

Press to set in Settings reads keys from the listener while the listener is running, and it captures keys even when the altgo window has focus. If the pipeline is not running (for example the key name cannot be resolved and the listener failed to start), capture falls back to a temporary hook. On Windows this temporary hook is installed late and may miss keys while the window has focus. In that case, focus another window and press again. The failure message in the interface says this as well. On Linux the fallback starts its own evtest process, which is not affected by focus, and the failure message mentions device read permission.

Accidental triggers or IME conflicts​

Increase min_press_duration (default 100 ms) to filter short press chatter:

[key_listener]
min_press_duration = 200

Transcription​

Recording works but there is no transcription​

  1. Check whether the overlay enters the processing phase after recording stops.
  2. For the local engine, confirm that a model has been downloaded in Settings. For the online engine, confirm that the API key, base URL and model name are correct.
  3. Check the log: RUST_LOG=altgo=debug altgo. Look for transcription failed, model paths and polishing service request failures.

Chinese recognition is poor​

  1. Confirm that language = "zh" is set correctly.
  2. For the local engine, confirm that the model files downloaded completely (both model.int8.onnx and tokens.txt exist).
  3. For the online engine, confirm that the selected model supports Chinese, and check in the provider console whether requests are truncated or rate limited.

What should I do when online transcription fails​

Online transcription does not fall back to local and reports the failure directly. Check in order whether [transcriber] backend is "online", whether [transcriber.online] protocol is mimo_chat, chat_input_audio or transcriptions, whether the API key, base URL and model name are valid, and whether the network can reach the provider. Search the log for transcription failed.

Does online transcription need a network connection​

Yes. Local transcription works offline after the model is downloaded, and online transcription must reach the provider on every request.

Where do I download local models​

Download them from the transcription section in Settings. The choices are SenseVoice (about 230 MB, automatic detection of Chinese, English, Japanese, Korean and Cantonese), SenseVoice Cantonese-enhanced (about 237 MB) and FireRedASR2 CTC (about 740 MB, stronger on mixed Chinese and English speech). You can also download model.int8.onnx and tokens.txt manually from the Hugging Face repository listed in the model catalog and place them in the model directory.

Polishing​

Polishing is too slow​

  1. Lower the polishing level (heavy, then medium, then light).
  2. Use a faster model, or switch to local polishing (change the polishing engine to local in Settings). The first local call waits for the runtime to start and the model to load, and later sentences take about 0.15 to 0.3 seconds.
  3. Set level = "none" to turn polishing off.

Polishing changed the meaning​

Use the light level, which only fixes punctuation and typos and does not change the content. Alternatively, use a custom system prompt:

[polisher]
level = "light"
system_prompt = "Fix punctuation and typos only, without changing the meaning or tone of the original text"

The local engine also has a fidelity check. When numbers, URLs or paths change, or the result is reduced to a summary, gains content, or contains formatting markers, altgo falls back to the raw transcript and never sends out a damaged result.

Does local polishing need a network connection​

No. After the runtime and model are downloaded, local polishing runs entirely on this machine and the transcript never leaves it. Only the optional remote polishing engine needs the network.

How much disk and memory does local polishing use​

The runtime takes about 47 MiB (unpacked on Windows x64). The Qwen3-0.6B model is about 397 MB and Qwen3-1.7B about 1.1 GB. The runtime commits about 1 GB (0.6B) or 1.5 GB (1.7B) of memory, with measured peak working sets of about 1.3 GB and 2.5 GB. It exits after ten idle minutes to release memory.

Clipboard and overlay​

It reports success but pasting gives old content, or the clipboard fails​

  1. Install xclip, xsel or wl-copy, and make sure altgo runs inside the graphical session.
  2. If another program holds the clipboard, try again later.
  3. Use the copy button in the history list on the home page (WebView gesture copying is sometimes more reliable than the backend clipboard). The overlay only displays the result, which is already on the clipboard.
  4. For debugging, run RUST_LOG=altgo=debug altgo and look for clipboard errors.

General​

How do I run altgo in the background​

# Linux
nohup altgo &
# or use a systemd user service

How do I view the log​

# Linux
RUST_LOG=altgo=debug altgo

Available log levels: debug, info, warn, error