Installation guide

Installation and Setup

Installing Wheelhouse, updating it, removing it, and the checks to perform after the first start.

Running the installer

The installer is a standard Windows setup wizard. Download it and run it -- nothing needs to be installed ahead of time:

https://github.com/wheelhouse-project/Wheelhouse/releases/latest/download/Wheelhouse-Setup.exe

If Windows shows a "Windows protected your PC" screen, see Security warnings below. The whole process takes about 10 to 20 minutes, most of it downloading (roughly 3 GB in total). The wizard:

1. Asks its questions up front: which speech engine to use (the pre-selected answer suits most installations -- see Speech Engines), whether to set up the optional AI helper (the wizard offers one AI choice, a cloud model from Google, and skipping; the model that runs on your own machine is set up from the command line instead, described below), and whether Wheelhouse starts when you log in and right after setup finishes (both pre-selected). It also asks you to turn on microphone access for desktop apps, but only when that Windows setting is currently off; when it is already on, setup says nothing about it.
2. Checks the requirements listed under What you need. Four of them stop setup when they are not met: 64-bit Windows, the Windows version, free disk space, and enough memory for the chosen speech engine. In each case setup states on screen what is missing and what to do about it. The rest -- the processor core count, a connected microphone, and memory below the recommended 16 GB -- produce a notice and setup continues.
3. Installs the Microsoft Visual C++ runtime that the speech engine needs, but only when the computer does not have it or has a copy that is too old. Windows asks for permission first, and then Microsoft's own progress window appears. If you decline, or the runtime install fails, setup continues and its final page says so and what to do.
4. Installs uv, the environment manager Wheelhouse uses, into the user profile.
5. Downloads the Wheelhouse application, verifies the download against its published fingerprint, and creates Wheelhouse's own Python environments. Those environments are self-contained and separate from any other Python installation on the computer.
6. Downloads the offline speech model if the default engine was kept (2.5 GB; this is the longest step).
7. Creates Start-menu and desktop shortcuts.
8. Reports anything worth knowing on its final page. Setup can complete and still have had to change something -- installing Parakeet in place of a speech engine that Wheelhouse no longer includes, for example -- and those notices appear there rather than only in the setup log.

Wheelhouse installs for one user account. Administrator rights are not required. The one change outside your user account is the Microsoft Visual C++ runtime in step 3, which Windows installs for the whole computer after its permission prompt. If that prompt cannot be approved, setup still finishes, and its final page says that the runtime was not installed.

Running the wizard again to update. When Wheelhouse is already installed, the AI helper page shows "Leave my AI helper setting unchanged." in place of "Skip for now (recommended). You can set this up later." The wizard pre-selects it. It keeps the current AI helper setting and any saved access key as they are, including a local AI model set up from the command line. The other choice, the Google cloud model, replaces the current setting.

Command-line installation. The same install runs as one PowerShell line, asking only the speech-engine, start-at-login, and start-now questions as text prompts; both start questions default to no. On a computer with less than 8 GB of memory, a question that offers the Google Cloud engine replaces the speech-engine question. An update of an install that already uses the Google Cloud engine asks neither question on such a computer and keeps that engine. It asks nothing about the AI helper: the AI choice is given as an argument instead, or left out, which installs without AI on a first install and keeps the current AI setting on an update. The one-line command cannot carry arguments; to pass one, download install-wheelhouse.ps1 from the release page and run it as a file, for example powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -AiMode local.

irm https://github.com/wheelhouse-project/Wheelhouse/releases/latest/download/install-wheelhouse.ps1 | iex

Setting up the AI helper on this machine. Adding -AiMode local to the command-line installer sets up an AI model that runs on your own computer, with no account, no key, and no text leaving the machine. Setup downloads the AI files only after it has measured the hardware, and only when this computer can run the model. The result of that check does not change the rest of the install: setup installs Wheelhouse itself and the speech model in every case. Setup then says where the model runs. When the model runs on the processor, it works but is slow -- about 3 seconds for a short correction and about 12 seconds for a long one. A machine that cannot run the model is told why and left with the AI features switched off rather than having several gigabytes downloaded that could not run. -AiMode cloud selects the Google cloud model the wizard offers, -AiMode off installs without AI, and -AiMode keep leaves an existing AI configuration alone on a re-run.

Command-line switches. The first three switches below answer the three text prompts in advance, so the installer does not ask them. The three AI switches give the details of the cloud AI helper and work only with -AiMode cloud. Pass them by running the script as a file, as described above.

• -SttProvider chooses the speech engine: parakeet_tdt (Parakeet) or google_stt (Google Cloud). Left out, the installer asks. Pressing Enter keeps Parakeet on a new install, or the current engine on an update when that engine is Parakeet or Google Cloud. Example: powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -SttProvider google_stt
• -AutoStart sets whether Wheelhouse starts when you log in: yes or no. Left out, the installer asks, and the default answer is no. Example: powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -AutoStart yes
• -StartNow sets whether Wheelhouse starts when the install finishes: yes or no. Left out, the installer asks, and the default answer is no. Example: powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -StartNow yes
• -AiApiKey gives the access key for the cloud AI helper. Setup reads it only together with -AiMode cloud and ignores it otherwise. Setup saves the key in the user environment variable WHEELHOUSE_AI_API_KEY, never in the settings file. It has no default: with -AiMode cloud and no key, setup leaves AI off, clears any saved key, and says so. Other programs on the computer can read a command line while the install runs. To keep the key off the command line, set the environment variable WHEELHOUSE_AI_API_KEY_INPUT to the key in the same PowerShell window and leave -AiApiKey out. The command is $env:WHEELHOUSE_AI_API_KEY_INPUT = '<your key>'. Example: powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -AiMode cloud -AiApiKey <your key>
• -AiBaseUrl sets the address of the cloud AI service. Setup reads it only with -AiMode cloud and a key. The default is Google's address, https://generativelanguage.googleapis.com/v1beta/openai/. Another address must belong to an AI service that accepts requests in the same format as the OpenAI API. Example: powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -AiMode cloud -AiApiKey <your key> -AiBaseUrl https://example.com/v1/
• -AiModel sets the name of the cloud AI model. Setup reads it only with -AiMode cloud and a key. The default is gemini-2.5-flash-lite. Example: powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -AiMode cloud -AiApiKey <your key> -AiModel gemini-2.5-flash

Two further switches, -Force and -KeepData, apply only to uninstalling; see Uninstalling Wheelhouse.

What you need

• Windows 10 or Windows 11, 64-bit. Any Windows 11 edition; most Windows 10 editions.
• 10 GB of free disk space.
• Memory (RAM): 8 GB for the offline speech engine, Parakeet; 6 GB for the Google Cloud speech engine, which is the minimum for any engine; 16 GB recommended. Below 8 GB, the installer stops for the offline engine but still installs the Google Cloud engine. In the setup wizard, choose Google Cloud at the speech-engine question. The one-line command-line installer, when no engine was chosen, asks one question in place of the speech-engine question: yes installs the Google Cloud engine, and no stops the install. An update of an install that already uses the Google Cloud engine does not ask this question and keeps that engine. Below 6 GB, the installer stops for every speech engine, including the cloud one, and adding memory is the only fix.
• 4 or more CPU cores recommended. With fewer, Wheelhouse installs and runs, but speech recognition may respond slowly.
• A microphone. One can be connected after installing.
• A keyboard and a mouse, or a person who can use them for you. You cannot install Wheelhouse by voice. Wheelhouse is not running yet during the install, so answering the installer's questions needs clicks and typing. Voice control starts after the first run.
• An internet connection during installation. The default speech engine operates offline afterward.

Successful installation

The wizard reports its progress step by step, and the PowerShell installer reports the same steps as text. Installation is complete when it reaches the end without stopping on an error. Wheelhouse then appears in the Start menu under W and as a desktop shortcut.

Installation failure messages

The PowerShell installer's failure messages contain no personal data and can be included in a help request. The wizard's failure window is the exception: it shows the full path of the setup log, which is in the Windows temporary folder under your account name, and the Windows error text it quotes can still contain your account name. Remove your account name from anything you copy out of that window before you include it in a help request. When the wizard stops, a window states what went wrong and what to try. When setup knows the path of its log, the same window names the file, and when that file exists it in most cases also offers to open it; when setup cannot work out the path, the window omits any reference to a log. Either way it gives an address to write to, help@wheelhouse-project.org. The PowerShell installer prints the same two lines as text. The common messages:

• "Wheelhouse appears to be running" (during an update): the installer refuses to replace an application that is running. Exit Wheelhouse first (right-click the floating button or the tray icon -- both open the same menu -- and choose Exit), then run the installer again. If it reports that it could not check, restart the computer and try again.
• "Another program is using the Wheelhouse folder, so the update cannot replace it. Nothing was deleted." (during an update): a program has a file or folder inside the Wheelhouse application folder open, for example a command prompt or an editor that Wheelhouse opened. The installer changed nothing. Close those programs, or restart Windows, then run the update again.
• "This computer has N GB of memory": your machine has less memory than the chosen speech engine needs. When the message says the offline speech engine needs about 8 GB, install with the Google Cloud engine instead: choose Google Cloud in the setup wizard, or run install-wheelhouse.ps1 as a file with -SttProvider google_stt. For the offline engine, adding memory is the only fix. When the message says Wheelhouse needs about 6 GB for any speech engine, no choice of engine helps, and adding memory is the only fix.
• "Not enough free disk space": the message names the drive that holds your user data folder. Make sure that drive has at least 10 GB free, then run the installer again.
• "Putting the speech model in place failed": the step that assembles the model stopped, and the message includes its exit code and the last lines it printed. Run the installer again -- the downloads themselves are kept and do not repeat. If it fails the same way twice, include the message in a help request.
• "Could not install uv": usually a blocked network -- corporate proxies can block the download. Install uv manually from https://docs.astral.sh/uv/getting-started/installation/ and run the installer again.
• "... failed its integrity check": the downloaded file does not match its published fingerprint. An antivirus or proxy rewriting downloads is the most common cause; a changed release asset is the other. Add an exception or try a different network, and if it keeps failing, file an issue on the GitHub page.
• "Downloading ... failed twice": network trouble. Run the installer again -- downloads resume where they left off.
• "Setting up services\wheelhouse failed" (or another folder under services): a Python environment could not be built. If the message shows a "uv sync exit code", it is usually a network or proxy problem -- check the connection and run the installer again. If it says a path "is missing or is not a folder", the unpacked files are incomplete or were quarantined -- run the installer again and check whether antivirus is removing files.
• "An incomplete speech model was found": informational, not an error. The speech model an earlier run installed is now incomplete or damaged, for example because one of its files was deleted. The installer removes it and installs the model again, which repeats the 2.5 GB download. An interrupted run does not cause this message: the installer only puts a model in place after checking it is complete.
• "The spoken-hint vocabulary ...": informational, not an error; the install finishes. The word list Parakeet reads before it can favour a boosted word is absent, failed its checksum, or could not be copied. Parakeet biasing is off by default, so nothing else changes. If biasing is switched on, Parakeet then applies no hints, and "boost" is typed as a word. Google still applies hints. Re-running the installer replaces the file.
• "The Microsoft Visual C++ runtime is installed. Restart the computer before you use speech.": informational, not an error; the install finishes. Microsoft's installer needs a restart before Windows uses the new runtime. Restart the computer, then start Wheelhouse.
• "You declined the Windows permission prompt, so the Microsoft Visual C++ runtime the speech engine needs was not installed ...": the install finishes, but speech may not start. Run the installer again and select Yes when Windows asks.
• "Wheelhouse could not download a Microsoft-signed copy of the Visual C++ runtime ...": the install finishes, but speech may not start. Either the download failed or the downloaded file did not carry a valid Microsoft signature, and setup discarded it. Run the installer again, or install the Microsoft Visual C++ Redistributable (x64) from Microsoft, then start Wheelhouse again.
• "Installing the Microsoft Visual C++ runtime the speech engine needs failed (code N) ...": the install finishes, but speech may not start. Run the installer again, or install the Microsoft Visual C++ Redistributable (x64) from Microsoft, then start Wheelhouse again. The code is Microsoft's exit code, or the word "unknown" when setup could not read one; include it in a help request.
• No Wheelhouse entry in the Start menu: check Start > All apps under W first -- new entries are not pinned to the front page. If it is truly absent, the desktop shortcut works the same; the installer log records a "Shortcut created" or "Could not create" line for a help request.

Re-running the installer is safe at any time. It repairs a broken install, resumes interrupted downloads, and updates an existing install while preserving your user data; the list of what is preserved is under Updating Wheelhouse.

If none of these apply, the Wheelhouse Assistant can read an installer message and identify the cause; see Getting Help. Reports can also be filed at https://github.com/wheelhouse-project/Wheelhouse or sent to help@wheelhouse-project.org -- include the installer's output or the setup log.

Updating Wheelhouse

There is no separate update procedure: updating is re-running the installer. Download and run the newest Wheelhouse-Setup.exe, or run the same PowerShell line, from Running the installer. Each Wheelhouse-Setup.exe installs the release it belongs to, so a Wheelhouse-Setup.exe downloaded earlier installs that earlier release again. The newest Wheelhouse-Setup.exe and the PowerShell line, which downloads the newest installer script, install the newest release. When the installer finds Wheelhouse already present, it updates it in place. Exit Wheelhouse first -- right-click the floating button or the tray icon, both of which open the same menu, and choose Exit. The installer refuses to replace an application that is running.

Wheelhouse also checks once a day whether a newer release exists. When one exists, a notice offers to update. "Update now" downloads the installer, checks it, closes Wheelhouse, and runs it. "Later" hides that version's notice. Wheelhouse can show it again 7 days after the notice last appeared. A newer version shows its notice at once. The setting CHECK_FOR_UPDATES in config.toml turns the automatic check off. A manual check does not depend on that setting. To start one, choose Check for updates in the About Wheelhouse window, or say "check for updates"; the spoken command opens the window if it is closed. A manual check runs also when CHECK_FOR_UPDATES is false and during the 7-day "Later" wait. It sends the same one request as the automatic check. It does not change the time of the last check or the record of the last notice, so the automatic schedule and the "Later" wait stay as they were. The result shows in the window: Wheelhouse <version> is available with an Update now button that works as the button in the notice, You have the newest version (<installed version>)., or Wheelhouse could not reach GitHub. Check your internet connection and try again. A copy of Wheelhouse that has no version number cannot compare versions; the window then names the newest release and says so.

An update replaces the application and preserves user data:

• The settings file (config.toml)
• Personal voice patterns
• Approved and declined dictation targets, and the retry counts kept for targets not yet decided
• Three marker files that record a one-time message as already shown: the Assistant explanation window (help_explainer_notebook_shown.toml), the first-click hint (click_first_use_hint_shown.toml), and the notice shown on the first start after an install (first_run_notice_shown.toml)
• Saved speech hints
• The record of the last update check, and of the version and the time of the last notice Wheelhouse showed (update_check_state.toml)
• The downloaded speech model -- it is stored outside the part an update replaces, so the 2.5 GB download does not repeat.

In the kept settings file, the update changes the assistant setting under [ai.help]. Release 1.2.1 and earlier named the assistant address setting gem_url; the update renames it to assistant_url. An assistant_url that holds an address release 1.2.0 or earlier shipped as the default is replaced with the current Wheelhouse Assistant address; an address you entered yourself stays. If the installer cannot make the change, it writes a warning, keeps the old address, and finishes the update.

The update also copies one value from the old settings file of the Parakeet engine (services/stt_providers/sherpa_offline_parakeet_stt_server/config.toml) into the new one: lead_word_path, which turns the training word on. The rest of that file comes from the new release. An empty or missing value leaves the new file as shipped. The recordings themselves are stored outside the part an update replaces. The Speech Engines section describes the training word under "Your training word".

If an update is interrupted -- a power cut, a closed window, a crash -- user files are preserved. Before replacing anything, the installer copies them into a holding folder next to the application, and the next run restores whatever it finds there. Recovery is running the same command again; no manual step is required. An update first moves the old application folder aside, to a folder beside it whose name is app.old- followed by the date and time. If the update stops with an error before your files are restored, the installer puts the previous install back, and Wheelhouse starts as it did before the update. If the installer cannot put it back, its message names the folder that holds the previous install. Do not delete that folder; run the update again, and it restores your settings and voice patterns. After a successful update, the installer deletes the old folder. If it cannot, the setup wizard names the folder on its final page. Wheelhouse does not use that folder, you can delete it, and the installer tries again each time it runs.

Security warnings

The Wheelhouse installer is digitally signed by the project's author, David Chesley Hite III, which allows Windows to verify that the download came from the project unaltered. Windows may still warn about each new release until it has seen that file often enough. The source code is public at https://github.com/wheelhouse-project/Wheelhouse.

• SmartScreen ("Windows protected your PC"): appears when running a recently released Wheelhouse-Setup.exe. Click "More info", check that the publisher reads David Chesley Hite III, then click "Run anyway". If the setup wizard fails, its failure window names the setup log when it can find the file, and in most cases offers to open it; the file is at %TEMP%\Setup Log <date> #<number>.txt. Attach it to a help request.
• Antivirus flags or rewrites the download: some antivirus products quarantine downloads or alter them as they arrive. The installer verifies its own downloads -- the application, the speech model, and the AI files -- against published fingerprints and refuses anything altered (the "failed its integrity check" message); two downloads are not checked this way. uv arrives through winget or uv's own installer. The Microsoft Visual C++ runtime is downloaded from Microsoft only when the computer needs it, and setup keeps the file only when it carries a valid Microsoft signature. Add an exception for Wheelhouse, or install on a different network, then run the installer again.
• A downloaded script will not run: Windows marks a saved install-wheelhouse.ps1 as coming from the internet, and PowerShell may refuse to run it. Remove the mark once with Unblock-File .\install-wheelhouse.ps1, or start it with powershell -ExecutionPolicy Bypass -File .\install-wheelhouse.ps1.

Installing from source avoids these warnings. CONTRIBUTING.md in the GitHub repository has the development setup steps.

Uninstalling Wheelhouse

If you installed with Wheelhouse-Setup.exe, uninstall it like any Windows program: Settings > Apps > Installed apps > Wheelhouse > Uninstall. If you installed with the PowerShell one-liner instead, you need the script as an actual file: download install-wheelhouse.ps1 from the releases page, open PowerShell in that folder, and run:

powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -Uninstall

The uninstaller will not run while Wheelhouse is running -- exit it first by right-clicking the floating button or the tray icon and choosing Exit. Run from the command line as above, it asks two questions before removing anything:

1. "Remove Wheelhouse from this computer?" -- nothing is removed until this is answered yes.
2. "Keep your personal data?" -- the settings file, voice patterns, and the downloaded speech model. Keeping also holds the other eight files an update preserves: the three dictation-target files, the three marker files, the saved speech hints, and the record of the last update check.

Removed through Windows instead, after a Setup.exe install, only the second question is asked: Windows has already asked whether to uninstall, so the wizard puts the keep-or-remove choice to you and then runs the same uninstaller without repeating the first question.

Two switches answer those questions in advance. Both work only together with -Uninstall, and neither takes a value; left out, the uninstaller asks. Neither one skips the check that Wheelhouse is not running.

• -Force skips both questions and removes everything, personal data included, unless -KeepData is also given. Example: powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -Uninstall -Force
• -KeepData answers the second question with keep. Without -Force, the first question is still asked. Example: powershell -ExecutionPolicy Bypass -File install-wheelhouse.ps1 -Uninstall -Force -KeepData removes Wheelhouse without asking and keeps your personal data.

What each answer does:

• Keeping personal data: the application, all its shortcuts, and its bookkeeping folder are removed. The engine-audio folder is removed too. It holds the sound files that the SAVE_ENGINE_AUDIO setting saves, which contain everything you said, and only a running speech engine would otherwise delete them. The speech model remains in %LOCALAPPDATA%\Wheelhouse. Two more items remain there when they exist: the lead-word folder, which holds the Parakeet engine's training-word recordings, and the file stt_model_overrides.toml. After a reinstall the training word is off even so, because the setting that turns it on is in the Parakeet engine's settings file, inside the removed application; select Turn on in the Your training word window to turn it on again with the kept recording. The ten files an update preserves (the settings file, personal voice patterns, the three dictation-target files, the three marker files, the saved speech hints, and the record of the last update check) are gathered into a subfolder there named preserved-user-data. On a machine where the local AI helper was set up, the AI model and the program that runs it -- several gigabytes -- also remain there. A folder whose name is app.old- followed by a date and time, which an update could not delete, also remains there; Wheelhouse does not use it, and you can delete it. A later reinstall starts from defaults; copy files back from that folder to restore the previous settings and patterns.
• Keeping nothing: the entire %LOCALAPPDATA%\Wheelhouse folder, the %APPDATA%\Wheelhouse folder, and all shortcuts (Start menu, desktop, and the start-at-login entry) are removed. A configured cloud AI access key is also cleared from the user environment.

Those two folders, plus a small WheelhouseSetup folder used by the graphical installer's uninstaller, hold everything Wheelhouse itself stores. Setup writes in up to five further places. It removes the shortcuts it created and the start-at-login entry. When you choose to remove your personal data too, it also removes the saved cloud AI key, the WHEELHOUSE_AI_API_KEY variable in your user environment, which setup writes only when you choose cloud AI; a removal that keeps your personal data keeps that key too, because the kept settings file can still turn cloud AI on. It leaves the others, deliberately: uv, the environment manager, installed in the user profile, together with the entry for uv's folder that setup adds to your user PATH when uv's own installer has not added it, and, where setup installed it, the Microsoft Visual C++ runtime. Other programs may also be using either one. The graphical installer additionally leaves its own log in the Windows temporary folder. %APPDATA%\Wheelhouse holds no personal data -- only bookkeeping such as helper-process ID files -- and is removed under either answer. Run from the command line, the uninstaller prints both folder paths when it finishes; removed through Windows, it runs hidden, so those paths never reach the screen. A removal through Windows shows a message only when something went wrong, and several different ones are possible. Three of them concern the saved AI key. Two say that the key could not be cleared, or that setup could not read the removal step's output at all; both of those ask you to check WHEELHOUSE_AI_API_KEY yourself in Windows Environment Variables. The third says the key changed but running programs could not be told, and its remedy is different: sign out of Windows and back in once. Two further messages report a removal that could not run as intended. Setup stops with "Wheelhouse could not be fully removed" when the removal step fails, most often because Wheelhouse is still running; close it and run the uninstall again. Setup finishes but asks you to delete the %LOCALAPPDATA%\Wheelhouse folder by hand when the removal helper itself is missing.

Administrator windows and UAC prompts

Wheelhouse installs for a single user account and runs without administrator rights. A program without administrator rights cannot change system files or settings, and anything it types or clicks is confined to what that user account is permitted to do.

One Windows rule follows from this. Windows does not allow a program to send keystrokes or clicks into a program running as administrator, and applies that rule to all non-administrator software. Two consequences:

• Programs running as administrator. A program started with "Run as administrator", or one that elevated itself as some system tools do, cannot receive typed text, key presses, or clicks from Wheelhouse.
• UAC prompts. The dimmed "Do you want to allow this app to make changes to your device?" screen is more restricted still: Windows displays it on a separate secure desktop that no ordinary program can reach or observe.

Observed behavior: dictation into an administrator window is detected before any keystroke is sent, and a notice titled "Wheelhouse can't type into administrator apps" appears in the corner of the screen. Repeating the same attempt within a minute shows no second notice. Nothing is typed either way. The same notice appears for a terminal running as administrator. Click commands spoken with the safety word produce their own notice: the contents of a protected window are not visible to Wheelhouse, so "x-ray click cancel" reports no match. Spoken key presses such as "press enter" produce no notice -- Windows discards them silently.

Available options:

• To dictate into administrator programs, start Wheelhouse as administrator: exit it, right-click its Start menu entry, and choose "Run as administrator".
• Use the physical keyboard and mouse for the administrator window or the UAC prompt, and voice for everything else.
• If the program does not require administrator rights, start it normally. Wheelhouse can then type into it as it does any other program. Some tools require administrator rights and will not run without them; for those, use the two options above.

No Wheelhouse setting removes this limit. Windows enforces it, and the UAC screen remains protected in all cases.

First run

Starting Wheelhouse starts five programs: the launcher (started from the shortcut; it watches the logic, input, and GUI processes, and when one of them exits it shuts all three down; it starts Wheelhouse again only when you choose Restart Wheelhouse from the menu), the logic process (interprets recognized speech and routes it to an action), the input process (types text, presses keys, performs clicks), the GUI process (the tray icon and the floating status button), and the speech engine (a separate helper that converts audio to text; if it stops, Wheelhouse restarts it once automatically, and a second stop needs the Restart Wheelhouse menu item). Within a few seconds the Wheelhouse icon appears in the system tray, near the clock; if it does not, see Troubleshooting.

When the speech engine is ready, a window titled "Welcome to Wheelhouse" opens. It says that the round red button shows that Wheelhouse hears you, and that the word "help" said on its own opens the help page. Its buttons are Open help and Close. Wheelhouse shows this window one time: on the first start after an install, or on the first start after an update from a release that did not have this window.

Microphone verification

Confirm Windows itself receives audio before diagnosing recognition problems. Three checks, in order:

1. The privacy setting. Open Settings > Privacy and security > Microphone: "Let desktop apps access your microphone" must be on. With it off, Windows refuses the microphone to Wheelhouse, and Wheelhouse reports it with this message:

WheelHouse cannot use your microphone. Windows is blocking it. Open Settings > Privacy and security > Microphone, turn on "Let desktop apps access your microphone", then start WheelHouse again.

The message appears in two places. A Windows notification appears near the clock and closes itself after about three seconds. A Wheelhouse notice titled "Windows is blocking your microphone" appears in the corner of the screen and stays there until you close it.

1. The input meter. Right-click the taskbar speaker icon, choose Sound settings, scroll to Input. The intended microphone should be selected and the level meter should move while you speak; if it stays flat, select a different input device.
2. A dictation test. Open Notepad, confirm Wheelhouse is listening, and say "hello world". On current hardware the words appear within about two seconds.

The safety word ("x-ray")

The safety word protects commands that would be disruptive or hard to undo if they fired while you were dictating. These commands run only when the utterance begins with "x-ray": "close window" is transcribed as ordinary dictation, "x-ray close window" closes the active window. Common commands such as "undo", "copy", and "select all" need no safety word. Throughout this document a command that requires it is written with the "x-ray" prefix; the Voice Commands section of the help guide (the User guide page on the website) marks every command that requires it.

The wake word ("computer")

Whenever listening is off, saying "computer" turns it back on, no keyboard or mouse needed. That holds whatever switched it off: the floating button, the "stop listening" command, a start with listening off, sound playing on this computer, Sonos playback, or an idle pause. The one exception is a program that has taken sole control of the speaker: that pause ends only when the program releases the speaker (see ENABLE_AUDIO_SUPPRESSION under Plugins). In push-to-talk mode the wake word ends only the idle pause, and listening then waits for the next hold of the floating button. After a period with no keyboard or mouse activity, Wheelhouse pauses listening -- the measure is input, not silence, so a film watched without touching either triggers the pause. The wake word and the safety word differ: "computer" turns listening back on, "x-ray" runs a protected command. While sound plays, a recording that says "computer" can also turn listening back on. Wake-word behavior is configurable in the wake_word section of the settings file, enabled by default. The idle pause comes from the Idle Monitor plugin (Plugins), also enabled by default; with that plugin disabled, listening does not pause when idle.

Speech Engines

Account requirements

No account is required for the default configuration. Wheelhouse ships with the Parakeet engine as its default: it runs on the local processor, works offline, costs nothing, and transmits no audio. The installer downloads its model, and it is preselected in the settings.

An account is required in one case: the Google Cloud speech engine, selected at the installer's speech-engine question. That engine processes speech on Google's servers and requires a Google Cloud account and a one-time credentials setup. The account is free and most personal use stays within Google's free tier; Google charges for use beyond it. The Google Cloud engine needs less memory than the offline engine. On a computer with less than 8 GB of memory, the installer stops for the offline engine but still installs the Google Cloud engine: in the setup wizard, choose Google Cloud; the one-line command-line installer, when no engine was chosen, asks one question and installs the Google Cloud engine when the answer is yes; an update of an install that already uses the Google Cloud engine keeps it without the question. On a computer with less than 6 GB of memory, the installer stops before installing anything, for every engine, and adding memory is the only fix.

Local and cloud engines compared

Setting up Google Cloud credentials (only if you chose that engine)

This section applies only if you selected the Google Cloud speech engine at the installer's speech-engine question. With the default Parakeet engine, skip it: that engine requires no account and no credentials.

If you selected Google Cloud, the installer ended with a warning that the engine requires credentials before it can transcribe, and referred you to "the Google Cloud section". This is that section.

1. Create a Google Cloud account and a project at https://console.cloud.google.com/.
2. In the project, enable the Cloud Speech-to-Text API.
3. Create a service account (under IAM & Admin > Service Accounts) and give it the Cloud Speech Client role.
4. Create a JSON key for that service account; a small file downloads.
5. Move the file somewhere permanent on your computer.
6. Open the settings file, %LOCALAPPDATA%\Wheelhouse\app\services\wheelhouse\config.toml, in Notepad. Find the [stt.google] section and put the full path to your key file in credentials_file, between the quotation marks. Write each backslash twice, because TOML reads a single backslash as an escape character:

[stt.google]
credentials_file = "C:\\Users\\yourname\\keys\\wheelhouse-speech.json"

1. Save the file and restart Wheelhouse. The engine reads the key when it starts.

There is a second method, and it needs no file editing: set an environment variable named GOOGLE_APPLICATION_CREDENTIALS to the full path of the key file (press the Windows key, type "environment variables", open "Edit environment variables for your account"), then close Wheelhouse and start it again from the Start menu. The menu item "Restart Wheelhouse" is not enough for this method: part of the program keeps running across it, and that part still holds the environment from before you set the variable. Google's own software reads that variable automatically. Wheelhouse uses the variable whenever credentials_file is empty, so set one or the other, not both.

Adding or switching engines later

To switch between engines already set up on this computer, right-click either the floating button or the tray icon -- both open the same menu -- open Speech-to-Text Provider, and select the engine: Google Cloud or Parakeet V3 (Local). The change takes effect at once: Wheelhouse stops the running engine, starts the one you chose, and then records it as last_provider in the stt section of the settings file so the next start comes back on it. The choice is recorded as soon as the new engine's process starts. If that process cannot be started at all, the choice is not recorded and the next start returns to the previous engine. If the process starts and the engine then fails its own startup, the choice stays recorded and the next start tries that engine again; select a working engine from the menu to change it. Switching to Google Cloud this way does not set up its credentials; see the Google Cloud section above.

To add an engine that was never set up on this machine, re-run the installer and select that engine at its speech-engine question. The installer downloads and sets up what that engine requires.

Parakeet can also be requested from the menu. When the installer turned Parakeet off because its speech model is missing, Speech-to-Text Provider lists it as Parakeet V3 (Local) - model not installed. Selecting that item, or selecting Parakeet while its model is missing or incomplete, keeps the current engine and shows the notice "Parakeet speech model not installed", which gives the download size, about 2.5 GB. Not now, or closing the notice, changes nothing.

If Wheelhouse was installed or last updated with the setup wizard, the notice offers Download now: Wheelhouse closes and the installer runs again with Parakeet chosen. It repeats its whole setup for several minutes, downloads the model, and starts Wheelhouse with Parakeet. If Wheelhouse has not closed within two minutes, the installer does not start. On a computer that uses the Google Cloud engine and has less than 8 GB of memory, Wheelhouse still closes, and the installer stops at its memory check, before any download, with a message that the built-in offline engine needs about 8 GB of memory. It downloads nothing and does not start Wheelhouse; start Wheelhouse again from the Start menu. When Download now is not possible, the notice offers Copy command instead, which copies the install command: exit Wheelhouse, run the command in PowerShell, and choose Parakeet at the speech-engine question. That command installs the latest release, which can be newer than the installed version.

The same re-run repairs a missing or incomplete speech model, for example after an interrupted download. The installer detects an incomplete model and reinstalls it. Re-running the installer is safe at any time, and the speech-engine question defaults to the engine already installed, so pressing Enter keeps it. When the installed engine is one that Wheelhouse no longer includes, the question defaults to Parakeet. Installing Parakeet in its place produces a message that the old engine was removed, which the setup wizard shows on its final page, and on the first start after the update Wheelhouse shows the notice "Wheelhouse: Speech engine changed" one time. Choosing Google Cloud at the question instead installs Google Cloud with no such message.

Installer troubleshooting

Installer failures

Each installer failure message and its action is listed under Installation failure messages; re-running the installer is safe and interrupted downloads resume.