Moanitor & HotMic - First-Time Setup
Voice-controlled triggers for VaM, fully offline. Talk to your scene, the plugin recognizes the phrases you defined, and fires the triggers you wired up. No cloud, no API key, no data leaves your PC.
This walkthrough is for someone brand new to all of it. If something looks obvious to you, skip ahead.
________________


What you're installing
* HotMic — a VaM plugin that captures your microphone and measures how loud you are (silence → whisper → talk → loud → max).
* Moanitor — a VaM plugin that listens for specific words and fires triggers when it hears them.
* Vosk server — a tiny offline speech recognizer that runs in its own little window on your PC. Moanitor talks to it.
You only set this up once. After that you just double-click one file when you want to use it.
________________


Step 1 — Get the package from the Hub
* Open the VaM Hub (the in-game Hub button, or hub.virtamate.com in your browser).
* Search for this package.
* Click Download.
* If you used the in-game Hub, the package is already in your VAM/AddonPackages/ folder. If you downloaded the .var file manually, drop it into that folder yourself.
* Restart VaM (or hit the refresh button in the scene browser).
That's the VaM side done. The plugin files are inside the .var. You don't need to extract them — VaM reads them straight out of the package.
________________


Step 2 — Find the "External" folder
Inside the package there's a small set of helper files you do need to get to from outside VaM in a folder called "External":
* Launchmaker.bat — runs once to install what's needed.
* vosk_server_grammar.py — the actual speech recognizer.
These live inside the .var. Easiest way to get at them:
* A .var file is just a renamed .zip. You can open it with 7-Zip or Windows Explorer.
* Inside, look for a folder called "External".
* Copy the whole folder out to somewhere convenient — your Desktop is fine, or Documents\VaM-Vosk\. Just somewhere stable that you can find again.
Don't run them from inside the .var. Copy them out first. The launcher will create new files in the same folder, and writing into a .var doesn't work.
________________


Step 3 — Run the installer (once)
* Open the folder where you copied the files.
* Double-click Launchmaker.bat.
* A black command window will open and walk through three steps:
   1. Checks that Python is installed.
   2. Installs the four packages Vosk needs (flask, waitress, vosk, numpy).
   3. Creates START_VOSK.bat next to the other files.
If Python isn't installed
Launchmaker will stop and tell you so. To install Python:
* Go to python.org/downloads.
* Download the latest stable version (anything 3.8 through 3.12 works).
* Important: tick "Add Python to PATH" on the first screen of the installer. This is the most common trip-up.
* Run Launchmaker.bat again.
If pip install fails
* Re-run Launchmaker.bat — sometimes the network blips.

If it still fails, open the same command window and run:

pip install flask waitress vosk numpy
   *  and read the error. Most often it's a firewall or proxy.

When you see "Installation Complete!", you're done with the installer forever. Don't run it again unless you reinstall Python or move folders.
________________


Step 4 — Start the Vosk server
      * Double-click START_VOSK.bat.
      * A new black window opens with the title "Vosk Server for VaM Moanitor".
      * The first time only, it downloads the speech model (~40 MB). You'll see download progress in the window. Wait for it to finish.
      * When you see something like Listening on http://localhost:5000, the server is ready.
      * Leave this window open. Closing it stops recognition. Treat it like a background app you forget about.
If your firewall pops up asking about Python, allow it. The server is talking to localhost (your own machine), nothing leaves your PC.
You'll start this window every time you want to use voice control. If you forget, the plugin will tell you it can't connect.
________________


Step 5 — Using Moanitor in VaM
      1. Load a scene (or start an empty one).
      2. Pick a Person atom (or any atom you want — Empty works fine).
      3. Open its Plugins tab and add ArachnutMoanitor.cslist from the package you downloaded.
      4. In HotMic:
      * Go to the Streaming page.
      * Turn on Streaming Mode (real-time).
      * On the Mic page, pick your microphone if it's not already right.
      5. In Moanitor:
      * Go to the Streaming page.
      * Turn on Enable Streaming. It'll try to connect to the Vosk server.
      * The plugin-panel header at the top should show ● HotMic and ● stream both in green.
      * If the header shows a yellow warning, read it — it'll usually say either HotMic's Streaming Mode is off, or the Vosk window isn't running.
That's it. Default phrases (yes, harder, fuck, good girl, please) are already in there. Try saying one and watch the HUD.
________________


How to actually wire up triggers
      * In Moanitor, go to the Phrases page. Add a phrase (give it a name), type the keyword(s) you want it to recognize.
      * Go to the Matrix page and turn on Show Matrix Grid. You'll see a table: rows are phrases, columns are loudness levels.
      * Click a cell to jump to that phrase's settings, click it again to open its trigger editor.
      * Wire up whatever VaM trigger you want — animation, morph, audio, whatever. Standard VaM trigger UI.
      * Say the phrase at that loudness, the trigger fires.
The whole point of the loudness columns: a whispered "harder" can do something different from a shouted "harder". Keep cells empty for any combination you don't care about.
________________


Tuning recognition (optional)
After things basically work, three knobs let you sharpen what gets matched. You can ignore all of this and the defaults will do fine; come back when something is misfiring.
Confidence Threshold (on the Streaming page). A slider between 0 and 1. Anything below that confidence gets dropped silently. Default is 0 (accept anything that matches the grammar). Raise it if you get false-fires; lower it if real phrases get missed.
Word Boosts (bottom of the Synonyms page). If Vosk keeps mis-hearing a specific word, you can boost it. Add a row in the format word:weight (weight 1–10), e.g. harder:5. The word gets duplicated into the grammar weight times, which biases the recognizer toward it. Save Boost List to File / Load Boost List from File export and import this list as a portable JSON, so you can carry your tuning between scenes.
Heads-up: boosts are a heuristic — they may or may not help on your machine. If a word still misfires after a boost of 5–10, the surer fix is to add the actually heard spelling as another comma-separated keyword on the phrase (e.g. harder, arder, hardor).
Per-phrase options (on the Phrases page).
      * Match Any Word Order — when on, "please turn yellow" matches the keyword "turn yellow please". Looser; enable only where word order varies.
      * Local Synonyms — word-equivalences just for this phrase. Same format as the global Synonym Groups (comma-separated, ; between groups).
________________


Daily routine (after setup is done)
      1. Double-click START_VOSK.bat — wait for "Listening on..."
      2. Open VaM, load your scene.
      3. Play. Talk.
      4. When you're done, close the Vosk window.
If the Vosk window crashes somehow mid-session, just restart it. Moanitor checks for the server every few seconds and reconnects automatically.
________________


Troubleshooting
The plugin says it can't connect.
      * Is START_VOSK.bat running? You should see a window labeled "Vosk Server for VaM Moanitor".
      * Did it finish loading the model on first run?
      * Once the server window is back up, Moanitor auto-reconnects within a few seconds — you don't need to toggle Streaming off/on.
It hears me but doesn't fire anything.
      * Look at the in-world HUD or the plugin panel — does it show your phrase being recognized?
      * If yes: the trigger probably isn't wired. Open the matrix, click the cell, click again, set up the trigger.
      * If no: the phrase you said isn't in your keyword list. Use the Test Match field on the Debug page to type what you said and see what it matches against.
HotMic's level meter doesn't move.
      * Wrong microphone selected. Mic page in HotMic, pick the right one.
      * Mic is muted in Windows.
	  * Mic is muted in Hotmic.
Recognition is slow / late.
      * The Vosk server's first response per session can be slow as it warms up. After that it should be near-instant.
It hears words it shouldn't. (or: keeps hearing the wrong thing for a specific word)
      * Add the actually-heard spelling as an extra keyword variant on the phrase, comma-separated (e.g. harder, arder).
      * Or try Word Boosts at the bottom of the Synonyms page — that_word:5 biases the recognizer toward it. See Tuning recognition above.
      * For phrases where word order varies, turn on Match Any Word Order on the phrase.
________________


What lives where
      * Plugin code (HotMic, Moanitor) — inside the .var, used by VaM.
      * Vosk server + launchers — the folder you copied out in Step 2.
      * Vosk speech model — downloaded into the same folder on first run. Don't delete the model subfolder unless you want to download it again.
      * Your phrases, triggers, settings — saved with your VaM scene, just like any other plugin storable. Save the scene, you save the setup.
      * Exported boost lists (optional, only if you use Word Boosts and export them) — saved as JSON in your VaM Saves/PluginData/Arachnut/ Moanitor/ folder. Portable; you can share them or move them between scenes.