Troubleshooting English

Troubleshooting

简体中文版本：常见问题与排障

Quick Checklist

1. Check the health panel at the top of API Config.
2. Make sure Doubao ASR App Key, Access Key, and Resource ID are filled in.
3. Make sure Windows allows desktop apps to access the microphone.
4. Make sure at least one trigger is enabled.
5. Make sure the cursor is inside an editable field.
6. Check whether the target app blocks paste shortcuts.
7. Use advanced Options to open logs or copy the diagnostic report.

Ctrl + Q Does Nothing

Possible causes:

• ASR credentials are missing.
• Main shortcut is disabled.
• The shortcut is occupied by another app.
• VoxType is already starting, stopping, waiting for final result, or pasting.

Fix:

1. Open API Config and fill in required ASR fields.
2. Open Options and check the main shortcut.
3. Open advanced Options and confirm the main shortcut trigger is enabled.
4. Try another shortcut.

No Text Was Recognized

Possible causes:

• Microphone permission is disabled.
• Wrong input device.
• Microphone volume is too low.
• The recording contains no useful speech.
• Network or ASR service issue.

Fix:

1. Allow desktop microphone access in Windows Settings.
2. Select the correct input device in Options.
3. Test Doubao ASR from API Config.
4. Try again in a quieter environment.

Notes:

• Empty recognition becomes a failure. It does not run polishing, paste, or successful statistics.
• Continuous silence stops the current recording after 10 seconds by default, so a server endpointing miss does not record until the maximum duration.
• If you need long pauses, adjust "Silence auto-stop seconds" in advanced Options. Set it to 0 to disable the local silence fallback.

Recognition Finished But Text Was Not Pasted

Possible causes:

• Cursor is not in an editable field.
• Target app blocks Ctrl + V.
• Target app reads the clipboard slowly.
• Clipboard is temporarily occupied by another program.

Fix:

1. Test in Notepad first.
2. If text was copied, press Ctrl + V manually.
3. Try Shift + Insert in advanced paste compatibility settings.
4. Increase clipboard restore delay.
5. Use clipboard-only mode for apps that do not support auto paste.

Previous Clipboard Was Not Fully Restored

VoxType tries to restore common clipboard formats. Images, bitmap handles, file handles, large private formats, or very large clipboard content may not be fully backed up.

Suggestions:

• Plain text and common rich text are usually more stable.
• Large clipboard content may hit the snapshot size limit.
• If restore is partial, VoxType should keep the recognized text available and show a warning.

LLM Polishing Does Not Run

Possible causes:

• llm_post_edit.enabled = false.
• Base URL, API Key, or model is incomplete.
• Text length is below min_chars.
• LLM connection test fails.

Fix:

1. Enable LLM polishing in API Config.
2. Fill in Base URL, API Key, and model.
3. Run the LLM test.
4. Leave it off if you only need ASR.

LLM Polishing Is Slow

Try:

• Disable thinking.
• Increase min_chars so short text skips polishing.
• Use a faster model.
• Increase timeout only for slow networks or models; timeout does not speed up polishing.

Hotwords Do Not Help Much

Hotwords are context, not a forced replacement table.

Tips:

• Use one term per line.
• Use real spelling.
• Do not put long paragraphs into hotwords.
• Proper nouns, names, product names, and abbreviations work best.
• For style preferences, use scene notes instead.

Automatic Hotword Candidates Are Empty

Possible causes:

• Automatic hotwords are disabled.
• Local history is empty.
• LLM API is not configured.
• There are no high-quality candidate terms.

Fix:

1. Enable automatic hotwords in advanced Hotwords settings.
2. Use voice input a few times to accumulate local history.
3. Configure and test LLM API.
4. Generate candidates manually.

Auto Update Installed But Did Not Open the New Version

Recent versions use silent NSIS installation and try to reopen VoxType after installation.

When a new version is available, the Home/Options notice provides an "Update now" action to start download and installation.

If it still does not open:

1. Open VoxType manually from Start Menu or desktop shortcut.
2. Check whether security software blocked the installer.
3. Download the latest installer from GitHub Releases and reinstall.
4. Copy the diagnostic report for troubleshooting.

Logs and Diagnostic Report

Open Options → Advanced Settings → Updates and diagnostics:

• Open logs.
• Copy diagnostic report.

Diagnostic reports should be redacted. They should not include real API keys, recognized text, hotwords, prompts, recent context text, or Windows username paths.

When reporting an issue, include:

• VoxType version.
• Windows version.
• Steps to reproduce.
• Diagnostic report.
• Whether the issue reproduces in Notepad.