Troubleshooting

Solutions to common issues with Trueears

Quick reference

Issue	Solution
LLM responding instead of formatting	Reset App Profiles to defaults
Settings not saving	Clear store and restart
Microphone not working	Check OS permissions
Hotkey not responding	Check for conflicts with other apps
No transcription after recording	Verify Groq API key and network
”Default” profile always used	Check exe name match in App Profiles
WebView2 not found	Run installer or download manually
High memory usage	Restart app; expected <50MB idle

---

LLM issues

LLM responding instead of formatting

If the LLM generates conversational responses like “I’m doing great!” instead of formatting your dictated text:

1. Open Settings

   Press Ctrl+Shift+S to open Settings.

2. Navigate to App Profiles

   Go to the App Profiles tab.

3. Reset to defaults

   Click Reset to Defaults. This reloads the base system prompt which includes “DO NOT respond” instructions.

This issue typically occurs when a custom system prompt has been modified and the formatting instruction was accidentally removed.

Formatting is inconsistent

If transcribed text is formatted differently across recordings:

• Confirm LLM Post-Processing is enabled in Settings.
• Verify the active app profile matches your current application.
• If using a custom profile, review the system prompt — it may need adjustment to clarify the expected output format.

---

Recording issues

Microphone not detected

1. Check OS permissions

   On Windows, go to Settings > Privacy > Microphone and ensure Trueears has access. On macOS, check System Preferences > Security & Privacy > Microphone.

2. Verify microphone in other apps

   Confirm the microphone works in another application (e.g., a browser or voice recorder) to rule out a hardware issue.

3. Select a different input device

   Open Trueears Settings and try selecting a different microphone from the input device list.

Recording starts but no transcription appears

1. Check your Groq API key

   Open Settings and verify your Groq API key is entered correctly. You can validate the key at console.groq.com.

2. Check network connectivity

   Ensure you have an active internet connection. Transcription requires a live connection to the Groq API.

3. Check console for API errors

   Press F12 to open the developer console and look for any API error messages.

Hotkey not responding

1. Check for hotkey conflicts

   Ensure no other application is bound to Ctrl+Shift+K. Common conflicts include screen capture tools, password managers, and gaming overlays.

2. Confirm Trueears is running

   Check that the Trueears icon is visible in the system tray. If not, relaunch the application.

3. Restart Trueears

   Close and reopen Trueears to re-register the global hotkey.

Some elevated processes (games running as administrator, UAC-elevated apps) can block global hotkeys. If the focused window is running with elevated privileges, Trueears may not be able to intercept the shortcut.

---

Settings issues

Settings not persisting

Settings are stored via Tauri’s Store plugin. If your settings are not saved between sessions:

1. Check the console for errors

   Press F12 to open the developer console and look for storage-related errors.

2. Clear the store and restart

   Run the following in the browser console, then reload:

   localStorage.clear();
   location.reload();
   
3. Verify plugin configuration

   Ensure @tauri-apps/plugin-store is properly configured in the project if you are running a development build.

API key not working

1. Validate the key

   Go to console.groq.com and confirm the key is active and has the required permissions.

2. Check for trailing spaces

   When pasting an API key, trailing whitespace is sometimes included. Delete and re-enter the key manually if in doubt.

---

Window detection

Default profile is always used

Active window detection uses the Windows Win32 API. Common causes:

• The active application does not have a matching entry in the App Profiles list.
• The executable name in your profile does not match the actual .exe name. Check the exact name in Settings > App Profiles.
• Running Trueears as administrator may interfere with detection of non-elevated windows.

To add a custom profile:

1. Open App Profiles

   Go to Settings > App Profiles and click Add Profile.

2. Enter the executable name

   Enter the exact executable name, for example notepad.exe or slack.exe.

3. Configure formatting instructions

   Set context-specific system prompt instructions for that application and click Save.

Window detection not working on macOS or Linux

Window detection is currently Windows-only. It relies on Windows Win32 APIs (GetForegroundWindow, GetWindowText). macOS and Linux implementations are planned for a future release.

---

Build issues

WebView2 not found on Windows

The Trueears installer includes an embedded WebView2 bootstrapper that should install it automatically.

If the error persists after running the installer, manually install WebView2:

1. Download WebView2

   Go to the Microsoft WebView2 download page and download the Evergreen Standalone Installer.

2. Install and restart

   Run the installer, then restart your machine and launch Trueears again.

Build fails with Rust errors

# Update the Rust toolchain
rustup update stable

# Clean the build cache and rebuild
cd backend
cargo clean
cd ..
npm run build

Missing Visual Studio Build Tools

Rust on Windows requires the MSVC build tools. Install them from Visual Studio Downloads:

• Select the Desktop development with C++ workload.
• Ensure the Windows SDK component is included.

Restart your terminal after installation.

---

Performance

High memory usage

Expected memory usage:

• Idle: less than 50 MB
• During recording: less than 150 MB

If usage is significantly higher:

1. Open the developer console (F12) and check for memory leak warnings.
2. Restart the application.
3. Confirm that audio buffers are being released after each recording session.

Slow transcription

Transcription latency is usually caused by one of the following:

• Network latency to the Groq API — check your connection speed.
• Large audio files — try shorter recordings to reduce processing time.
• Groq API degradation — check Groq’s status page for any ongoing incidents.

Overlay flickering

Flickering of the Trueears overlay window may be caused by display scaling or graphics driver issues:

• Set display scaling to 100% in your OS display settings and test again.
• Update your graphics drivers to the latest version.

---

Reporting an issue

When opening a bug report on GitHub, include the following debug information to help diagnose the problem:

1. Trueears version — found in Settings > About
2. Operating system and version — e.g., Windows 11 23H2
3. Steps to reproduce — a minimal sequence of actions that triggers the issue
4. Console errors — open the developer console with F12 and copy any error output

Screenshots or screen recordings are also helpful for UI-related issues.

Open an issue at github.com/anomalyco/Trueears/issues.