Skip to content

docs: add hotkey troubleshooting guide #689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alexdcesm wants to merge 1 commit into
base: main
Choose a base branch
from
+25 −0
Open

docs: add hotkey troubleshooting guide #689

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/HOTKEY_TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Hotkey Troubleshooting

## FluidVoice does not detect a mouse side button

Mouse utilities can intercept or replace a button press before FluidVoice receives it. Common examples include Logitech G HUB, Logi Options+, SteerMouse, BetterMouse, and vendor-specific profile software.

1. Open the mouse utility and select the active mouse and application profile.
2. Check the button diagram or assignment list for the side button you want to use.
3. Remove any app launch, keyboard shortcut, macro, or gesture assigned to that button.
4. Reset the button to its default/native action, such as **Forward**, **Back**, or **Use Default**.
5. Return to FluidVoice, start shortcut capture again, and press the button.

Also check whether the mouse utility changes profiles automatically when FluidVoice is active. If the button still does not register, temporarily quit the utility and try shortcut capture again. If it works while the utility is closed, the interception is happening in that utility or one of its profiles.

## FluidVoice does not accept F13–F19

FluidVoice's hotkey field records an actual keyboard event. Typing or pasting the text `F18`, or clicking a virtual key that does not emit an F18 key event, will not assign that shortcut.

F13–F19 work only when your keyboard, Stream Deck setup, or remapping tool can emit those function-key events. If your physical keyboard has no F18 key, use one of these options:

- Choose a low-conflict shortcut your keyboard can produce directly.
- Use Karabiner-Elements to map an unused key or key combination to `F18`, then trigger that mapping while FluidVoice is recording the shortcut.
- To use `F18` with Stream Deck, use the remapped key to enter `F18` in Stream Deck's Hotkey action field, then press that Stream Deck button while FluidVoice is recording its shortcut.

@greptile-apps greptile-apps Bot Jul 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 The third bullet references "the remapped key" without anchoring it to the Karabiner-Elements setup described in the preceding bullet. A user who skips straight to the Stream Deck option (or who uses a different remapping tool) will not know what "the remapped key" refers to. Making the phrase self-contained removes that ambiguity.

Suggested change
- To use `F18` with Stream Deck, use the remapped key to enter `F18` in Stream Deck's Hotkey action field, then press that Stream Deck button while FluidVoice is recording its shortcut.
- To use `F18` with Stream Deck, first follow the Karabiner-Elements step above to create a key that emits `F18`, then use that key to enter `F18` in Stream Deck's Hotkey action field, and finally press that Stream Deck button while FluidVoice is recording its shortcut.
Prompt To Fix With AI 
This is a comment left during a code review.
Path: docs/HOTKEY_TROUBLESHOOTING.md
Line: 23

Comment:
The third bullet references "the remapped key" without anchoring it to the Karabiner-Elements setup described in the preceding bullet. A user who skips straight to the Stream Deck option (or who uses a different remapping tool) will not know what "the remapped key" refers to. Making the phrase self-contained removes that ambiguity.

```suggestion
- To use `F18` with Stream Deck, first follow the Karabiner-Elements step above to create a key that emits `F18`, then use that key to enter `F18` in Stream Deck's Hotkey action field, and finally press that Stream Deck button while FluidVoice is recording its shortcut.
```

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Codex


After FluidVoice records F18, any device configured to emit the same F18 event can trigger dictation.
Loading