Troubleshooting¶
Start by identifying which workflow failed: hotkey dictation, Meeting Recording, Transcribe File(s), Notes, LLM post-processing, trigger routing, or the HTTP service. These workflows can share libraries, but they do not all share the same preferences.
Hotkey Does Not Trigger¶
- Confirm Accessibility/Input Monitoring permissions.
- Reopen
Preflight Checks.... - Verify hotkey is enabled and has a key assigned.
- Check for a conflicting assignment in
Manage Hotkeys....
Dictation Uses Unexpected Settings¶
- Open
Manage Hotkeys...and check the hotkey's mapped profile. - Remember that selecting a profile in the profile editor does not remap hotkeys.
- A quick-switch key can change profile during an active session.
- Meeting Recording and Transcribe File(s) use their own workflow preferences rather than a dictation hotkey profile.
Nothing Was Pasted¶
- Confirm
Auto paste into active windowis enabled on the profile mapped to the hotkey. - Keep the destination text field focused until processing finishes.
- Check whether a matching trigger route suppressed auto paste.
- Set both paste input and output formats to plain text when diagnosing destination-app formatting.
Temporary History Recall¶
- Enable
Add transcriptions to temporary historyon the mapped profile. - Start an active dictation before pressing
Left Arrow. - Arrow keys select a result but do not paste it. Finish with the hotkey's normal push-and-hold or toggle action.
- Press
Right Arrowbeyond the newest result to return to live listening. - Temporary history holds up to ten results in memory and is cleared when OpenScreech exits.
Microphone Issues¶
- Check the selected microphone under
App Settings→Audio Input. - If device is unavailable, OpenScreech falls back to system default input.
- Use
Refreshin microphone picker.
No ASR Output¶
- Confirm Parakeet model is downloaded in Preflight.
- Ensure speech duration is long enough (very short snippets can be ignored).
Preparing speech model…means microphone capture is already active and retaining audio while the dictation model loads. Wait forListening; if it never appears, reopen Preflight and confirm Parakeet v3 is installed.
LLM Issues¶
- Confirm the intended processor is selected in the profile stage,
Recording Settings, or the Transcribe File(s) window. - Use
Edit Processor...to verify its provider, endpoint, model, API key, prompt, and timeout. - Use
Test LLM Post-Processing...from the corresponding workflow; its request preview updates when the processor or selection changes. - If an endpoint should receive only the user message, disable
Send system promptand confirm the request preview contains nosystemmessage. - For an OpenAI-compatible gateway, confirm required Custom Headers are enabled and named correctly. Custom values override generated headers with the same name.
- If changing one processor affects another workflow, both intentionally reference the same library entry. Duplicate the processor and select the copy where independent behavior is required.
- Increase the selected processor's timeout if requests are timing out.
- In a profile graph, a failed stage blocks only its descendants. It prevents primary delivery only when the selected final output depends on it; successful sibling branches continue normally.
- Confirm the intended stage or Original text is selected under
Final Output.
Screechback Issues¶
- Confirm Screechback is enabled on the profile mapped to the active hotkey.
- Confirm the selected model reports
Ready to use; download it from the profile orApp Settings→Local Speech Models & Voicesif needed. - Selecting a model checks that model's installed state. In-app downloads and deletions update immediately; after changing model files manually in Finder, select the model again or relaunch OpenScreech.
- To reinstall a model cleanly, use its confirmed
Delete Model & Voices…action and then download it again. This removes only the selected model and its voices, preserving sibling models and shared resources. - The first test or playback after launch can take longer while the local model loads. Retry with a short sentence after it completes.
- An
Update availablestatus means a FluidAudio upgrade renamed a model component. ChooseUpdateto fetch only that component; downloaded voices are kept, and the superseded component is removed once its replacement is in place. - Confirm the selected text source exists. Removing an LLM stage changes a Screechback reference to
Final profile output. - Use
Test Screechback…with the same model, voice, language, and representative text. - Confirm the Mac's output device is available and its volume is audible.
- If PocketTTS 24-layer generation is too slow, compare its 6-layer variant where one is available.
- Generated speech is temporary; it does not currently appear in Saved Outputs or Notes.
- If temporary WAVs remain after a crash, forced termination, or an earlier OpenScreech release, open
App Settings→Local Speech Models & Voices→Temporary Screechback Audio. UseShow in Finderto inspect them or the confirmedDelete Temporary Audio…action to remove only Screechback playback and test WAVs. - OpenScreech keeps these WAVs in a dedicated
OpenScreech/Screechbacktemporary subfolder rather than the shared macOS temporary root. It does not automatically delete temporary audio at launch. Normal playback removes its WAV when it ends or stops, and the tester removes its replay file when replaced or when its window closes. - To reclaim disk without removing a working model, open
App Settings→Local Speech Models & Voices→Unused Model Components. This lists uncompiled model sources and components replaced by a FluidAudio upgrade; deleting them leaves installed models and voices working and causes no re-download. - See Screechback for model and voice guidance.
Missing Recording or File Outputs¶
- Confirm the required output toggle was enabled before starting the workflow.
- Use
TXTfor the basic readable transcript. Other formats are separate representations and do not improve recognition quality. - Meeting Recording uses
Recording Settings; Transcribe File(s) keeps its configuration in its own window. Each workflow has its own output directory. - See Output Formats Explained for artifact meanings.
Multitrack Interface or Mapping Issues¶
- Use one physical interface with multiple input channels. Aggregate and virtual devices do not appear in the multitrack picker.
- If the picker shows Configured interface unavailable, reconnect the interface and click Refresh. A missing device does not by itself clear the saved mapping.
- Track names, order, enabled choices, and input overrides persist across interfaces. Tracks with unavailable inputs stay in the list and are skipped when recording.
- Automatic input mappings follow list order, including disabled tracks. Check explicit overrides after switching interfaces; duplicate enabled input assignments must be corrected or disabled before recording.
- If capture stops after disconnection, inspect Session Status in Recording Settings and
session.jsonin the recording folder. Reconnection does not automatically resume that session. - If transcripts contain repeated speech from different microphones, check microphone placement and try the optional quiet-bleed reduction. The merger deliberately retains matching speech from separate tracks.
- If recognition returns no usable timing, the affected chunk is reported as an error and retained for investigation. Check
session.json; a combined transcript can be incomplete when errors occurred. - Final multitrack exports appear after Stop, even when recognition ran during capture. Keep the app running until processing completes.
Notes Issues¶
- Confirm
Save to Notesis enabled on the profile mapped to the hotkey. - Meeting Recording and Transcribe File(s) do not currently create Notes bundles.
- If Notes became empty after changing the root, switch back to the previous root. Changing roots does not move bundles.
- If the Notes root is in iCloud Drive and rows pause on loading, Control-click the root folder in Finder and choose
Keep Downloaded. Without this setting, macOS may download older metadata or transcript files only when they are opened. - One cloud-delayed note should not block other rows or a different selected note. If the complete window stops responding after updating to the latest version, record which grouping and search were active.
- Use the Notes folder menu's
Rebuild Tag Library…action after changing note metadata outside OpenScreech. Ordinary browsing does not rescan every note or rewritetags.json. - Temporary history and Notes are separate. History does not persist after the app exits.
- See Notes for bundle and search behavior.
HTTP Service Issues¶
- Confirm service status is
RunninginHTTP Transcription Service. - Check bind address/port conflicts.
- Confirm any client token and configured endpoint path match the current settings.
- Use health script:
./OpenScreech-macOS/Packaging/Scripts/test-http-health.sh
Permissions Reset (if prompts are stuck)¶
tccutil reset All com.openscreech.app
Resetting permissions makes macOS ask for access again. Reopen Preflight afterward and complete each required check.
Quick Tips¶
- When dictation starts but behaves unexpectedly, check the hotkey's mapped profile before changing processing settings. The editor's selected profile is not necessarily the runtime profile.
- Diagnose the earliest incorrect state shown by the overlay.
Checking microphone,Listening,Transcribing,Processing, andPastingpoint to different parts of the workflow.
See Also¶
Visual Notes¶
- TODO: add screenshot of common error states (permission denied, helper not running).