# Voice Assisted Macros

Voice Assisted Macros adds a powerful additional input mechanism to your gaming sessions. Instead of just using your keyboard and mouse, you will have a new powerful tool along these, your voice 🗣️🫳⌨️.

Try a new way of gaming with fast ( and configurable ) response times and highly customizable voice-to-keyboard commands that you define from scratch.

## 💉Installing

The app comes in a portable form, compatible with Windows 10/11 64-bit (x64) or 32-bit (x86). Once downloaded, it should be working out of the box.

The app uses a lightweight voice recognition model that works offline. By default, the app comes packed with a lightweight English model. Should you want to use voice commands in different languages, see Voice Model Language section for details on how to easily replace the defaul model.

## ⚙️Configuring

### 👤 Profiles

When you open the app, you will be able to edit the Profiles file (`profiles.ini`). This is where you cook. You define and store all your commands here.

You can create as many profiles as you want (e.g., one per game or character), then select which profile is currently active from the UI. The commands the app listens for while in listening mode come from the selected profile.

Profiles are defined and placed between brackets [Your profile name]. Each command for a profile will be entered on a new line under the profile name, like so:

    [Your profile name]
    Voice Command = action
    Voice Command = action
    ...
    [Other profile name]
    Voice Command = action
    Voice Command = action
    # Inactive voice command ( commented out by prefixing with # )
    ...

> The General Profile: There is a special profile named [General] which should not be renamed or deleted because it serves a unique function. All commands written under this profile will be shared with, and active in, all other profiles that you create. Use this to store commands you want available everywhere.

> See more about profiles in the Profiles fine-tuning section.

### 🎤 Voice commands

A voice command is written in a single line, under the desired profile.

The command is composed of two parts, separated by an equal sign (=) :

1. The Voice Trigger: The word or phrase you pronounce.
2. The Macro Action: The keyboard commands that will be executed.

##### Some basic examples

`jump = space`

> Pronouncing “jump” presses the Space bar once.

`i'm dying = shift + 1`

> Pronouncing “i’m dying” presses the Shift + 1 key combination (e.g., to use a health potion).

`run forrest = hold:3:shift`

> Pronouncing “run forrest” will hold the SHIFT key pressed for 3 seconds.***

#### 🧬 Speak once, run multiple keyboard commands.

One voice command can execute multiple keyboard commands in different ways:

1. Sequential Commands (Separator: `,`) To run commands in sequence (one after the other), use a comma to separate them.

`walk around = hold:3:w , hold:3:s`

> Holds “W” for 3 seconds (to move forward), and after it finishes, holds “S” for 3 seconds (to move back).

`i'm sapped = enter,type:I'm sapped!,enter`

> Presses Enter (opens chat), then types the message, then presses Enter again (sends message).

2. Concurrent Commands (Separator: `<||>`) To run commands simultaneously (at the same time), use the concurrency operator `<||>`.

`hop run = hold:4:w <||> repeat:4:0:1:(space)`

> Holds “W” for 4 seconds while, at the exact same time, it repeatedly presses Space 4 times (with 1 second between each press).

An example of a really basic Profiles file:

    [My Awesome Profile]

    run forrest = hold:3:shift
    i'm dying = shift + 1
    walk around = hold:3:w , hold:3:

    hop run = hold:4:w <||> repeat:4:0:1:(space)

    [General]

    jump = space

#### Check out all the available keyboard commands in the Command index section or check out some Examples.

#### All the available keyboard keys that can be used are found in the Keyboard index

## 🚀Usage

Once everything is configured and set-up, press “Start listening” for the app to start listening for your defined commands.

Make sure your game is focused ( window in foreground ) before speaking voice commands.

You can at any time <pause>, <resume> or <stop> the app from listening to commands. You can do this by using your voice. Please refer to “Controlling the app voice listening state” for more information about this.

## 🔩Finetuning

### Script word detection problems

#### 🎚️If your script detects different words than those you speak, or multiple commands run too fast, try adjusting one of the following settings:

> Latency (Audio buffer Size)

The app has a buffer size setting that determines how much audio data the audio AI model processes at a time. While lower latency is faster, it can also hurt accuracy.

Low Buffer (e.g., 1024): Faster responses, but gives the model less context to work with, increasing the chance of errors.

High Buffer (e.g., 4096 or 8192): Slower response, but gives the model more data for better confidence, potentially reducing misdetections.

Suggestion: If you’re experiencing random errors, try moving your Latency (Buffer Size) slider up to 4096 or 8192. See if the increased processing window helps the model stabilize its predictions.

> Debounce Time

The Debounce Time slider controls the minimum delay between voice command executions.

This doesn’t improve the recognition quality, but it prevents the same command from running multiple times if the audio model keeps detecting it for a fraction of a second, which is a common source of frustration. If your macros are executing too frequently, try increasing this delay to 1.5 or 2.0 seconds.

#### 😵‍💫 Improving Voice Recognition and Accuracy.

> Check Your Microphone / Wording Quality

If the model confuses some of the words from your configuration, instead of going for short, similar words, try using longer and more distinct phrases, depending on how fast the command needs to be ran.

For example, instead of “go” you could use “go now”, which is composed of two words and is less prone to being misdetected for other similar words. Instead of “kick”, “kick target”, and so on…

This forces the model to wait for a specific trigger. Commands like “reload” become “weapon reload” The word “weapon” acts as a sonic key.

#### 🖉 Punctuation & Typos

Ensure your keywords in the Profiles file ( profiles.ini ) are lower-case, exist in the English vocabulary ( or the vocabulary of whatever language model you use ) , are spelled correctly, and don’t contain punctuation (Vosk models are trained on simple, phonetic transcriptions).

### ⏯️ Controlling the app voice listening state ( pause, resume )

If the noise around you is too loud or you need to use your voice for different purposes other than the app, you can use the <pause> and <resume> function by speaking the voice commands you have set for these. This helps so that commands are not triggered accidentally by the noise around you by you speaking for other purposes.

Consider the following scenario:

1. You set these commands in your [General] profile:

    [General]
    ...
    pause commands = <pause>
    resume commands = <resume>

2. You suddenly need to use your voice for other purpose ( your phone rings / your mom barges into the room, etc ) .You can simply speak “pause commands” and the app will now ignore any further voice command.
3. When you want to use the voice commands again, simply speak “resume commands” and the app will start listening again.

> If you use the <stop> command, making the app listen again will require you to click the “Start listening” button, so if it’s just a quick pause, use <pause> and <resume> instead.

> You can also use pause listening when you alt-tab out of your game, as the app does not currently focus specific windows when receiving a command, and in pausing the app when not using it, you risk less accidental keypresses.

### 👤Profiles fine-tuning

💡A profile can represent a game, a character with different keybinds or anything you can think of.
💡The app will only listen to the vocabulary from a single selected profile at a time. The vocabulary from the “General” profile will always be included with your chosen profile.

Considering the points above:

❗Do not clutter all the commands that you use for different games in a single profile, this will make it harder ( and slower) for the model to process your voice commands. The model only listens for the words you have defined, so if these are less, it will pick up faster what you want to say.
❗You should add frequent voice commands that you use in multiple profiles in the [General] profile, that way you don’t have to type the command for each profile. Only add commands that are unique to your profile.

💡 Saving the profiles file while the app is opened will automatically refresh the commands it listens to, you don’t have to restart the app.

💡You can disable commands without deleting them from a profile by prefixing them with a hashtag. Example of a disabled voice command ( #voice command = space ). Should you ever want to use it again, simply remove the (#) hashtag in front.

## 🌐 Voice model language

The app uses a lightweight voice recognition model which works offline. By default, this is a lightweight English model from Vosk, but this can be changed.

Should you need it in a different language, there are different models which are available here.
I recommend only using the lightweight versions of the models as these will only use the vocabulary that you have defined in your profiles file, and are much faster because they only have to listen to a limited vocabulary that you defined.

### Changing the model:

First you need to download one of the lightweight small models, then store it in the models folder. For this example let’s download a Polish model:

We will mainly work with two folders:

This is the folder inside the app where the model data is stored:
`VoiceAssistedMacros\_internal\model\` ( the ai models are stored here )
`VoiceAssistedMacros\_internal\config\model.ini` ( tells app which model to use )

1. Then from the website download vosk-model-small-pl-0.22.zip, I will unarchive it and save it to my models folder. My model folder should now have 2 models:

   `VoiceAssistedMacros\_internal\model\vosk-model-small-pl-0.22` ( the new model that we just downloaded )
   +
   `VoiceAssistedMacros\_internal\model\vosk-model-small-en-us-0.15` ( the original model that the app came with )

2. Edit `VoiceAssistedMacros\_internal\config\model.ini` and change from:
   `model = vosk-model-small-en-us-0.15`
   to
   `model = vosk-model-small-pl-0.22`

   > model.ini can only contain one line which is the model name. Do not use comments or add multiple lines here.

3. Save the file and restart the app, don’t forget to update the profiles file with the appropriate voice commands for the new language of your model.

## 🪢Addons

Addons are stored in the folder `VoiceAssistedMacros\_internal\addons`
A typical addon would be stored like this:
`VoiceAssistedMacros\_internal\addons\example_addon`

Then the addon is assigned to a voice command like so:

`call my example addon = addon:example_addon:(test,123,data)`

In the line above, “addon:” is the predefined command, while “example_addon” is the used addon name, and everything surrounded by paranthesis () will be passed to the addon as command line arguments.

An addon folder most contain “`init.ini`” which provides a way for the app to communicate with the addon.
The init.ini contains

> run_cmd = which command should be ran for the executable
> run_target = the executable target for the command

The init.ini should contain something like:

    [DEFAULT]
    run_cmd = python
    run_target = init.py

or if you want to directly run an executable, we use “exe” as the run_cmd parameter.

    [DEFAULT]
    run_cmd = exe
    run_target = myaddon.exe

> For personalized, custom addon creation, please reach out via the contact section for more details.

## 📑Command index

> All existing commands can be combined in all sorts of ways by using one of the two separators. Commands may also exist within other commands that support nesting.

<||>
concurrent commands separator

> Can be used run commands simultaneously.

Example:

`my command = hold:5:w <||> hold:5:shift`

Holds down at the same time both “w” and “shift” keys for 5 seconds.

,
sequential commands separator

> Run commands in sequence by using a comma as the separator.

Example:

`my command = shift + e , space`

Presses “shift + e” key combination, then after that it presses “space” one time.

> Usable commands list 👇

### basic key press

> You can register a simple keypress on a voice command like so

`my command = space` - Presses space when “my command” is spoken
`my command = r` - Presses “r” key when “my command” is spoken
`my command = enter` - Presses enter when “my command” is spoken

### key combination press

> You can register a key combination on a voice command like so

`my command = shift + i` - Presses shift + i when “my command” is spoken
`my command = ctrl + shift + w` - Presses ctrl + shift + w when “my command” is spoken

### hold

hold:[seconds]:[key | key combination]
holds down a key/key-combination for a number of seconds

    Arguments:
       [seconds] - number of seconds to hold down the key or key-combination
       [key | key combination ] -  the key or key combination that will be held for the number of seconds you specified.

Example:

`my command = hold:5:w`
Holds “w” for 5 seconds.

`my command = hold:3.3:alt + s`
Holds "alt + s " for 3.3 seconds.

Example:

> You can combine hold with other commands using <||> to execute other actions while the hold is active.

Example:

`my command = hold:5:w <||> repeat:4:0:1(space)`

Holds down “w” key and at the same time presses “space” for 4 times every second.

### type

type:[text to type]
writes text on keyboard

> Has a small delay between each keypress.

Example:

`type:Hello people`

or a command sequence that types, then presses enter
`type: Hello people,enter`

### wait:

wait:[number of seconds]
pause command between commands

> Can be used in a comma separated command sequence to pause execution.

Example:

`my command = ctrl + 5 , wait:4.23 , shift + 5`
Presses ctrl + 5 , pauses for 4.23 seconds then presses shift + 5

`my command = 9 , wait:2 , ctrl + r`
Presses 9 key, waits for 2 seconds then presses ctrl + r

### repeat

repeat:[repeat number]:[sequence delay]:[repeat delay]:([commands to repeat])
commands sequence repeater

> Allows repetition of a series of commands

    Arguments:
       [repeat number]
          a number, the times the whole sequence will be repeated

       [sequence delay]
          the pause ( in seconds ) between each command in the sequence

       [repeat delay]
          the pause ( in seconds ) after a command sequence has been completed

       [commands to repeat]
          -  the commands that will be repeated, separated either by , or <||>
          -  separating the commands by a comma(,) will run these in order ( sequence )
          -  separating the commands by <||> will run them at the same time ( concurrent )

Example 1 ( sequence ):

`my command = repeat:3:0.2:4:(space, hold:1:a, hold:1:d)`

    Repeats 3 times the following sequence:
       presses "space"
       pauses 0.2 seconds
       holds "a" down for 1 second
       pauses 0.2 seconds
       holds "d" down for 1 second
    pauses 4 seconds before running the sequence again

Example 2 ( concurrent ):

`my command = repeat:2:0:3:(hold:1:w <||> space)`

    Repeats 2 times the following, at the same time:
       holds "w" down for 1 second
       presses "space"
    pauses 3 seconds before running the commands again

### <cancel>

cancels all the current running commands that have not finished running

Example:
`scratch that = <cancel>`

Cancels all ongoing commands once you speak “scratch that”.

💡This is useful if you defined commands that take more time to run, such as ***wait: , repeat: , hold:***. Using this command will attempt to stop all ongoing commands.

### <stop>

stops the app from listening to further commands

Example:
`stop listening = <stop>`

App stops listening once you speak “stop listening”. ( if you stopped listening like this, you will need to press the “Start listening” button once you want the app to listen again )

### <pause> and <resume>

pauses or resumes the app listening state

Example:

    pause commands = <pause>
    resume commands = <resume>

Pauses or resumes the app from listening to voice commands when speaking “pause commands” or “resume commands”.

Please refer to “Controlling the app voice listening state” for more information about how this works.

### addon

addon:[addon-name]:([addon arguments])
triggers an addon using a voice command

    Arguments:
       [addon-name] - the addon folder name
       [addon arguments] - a comma separated list of arguments to pass to the addon

> This is for advanced usage, see the addon section for mode details.

💡To unset a command defined in the General profile, simply write that command with nothing following the equal sign.

## #️⃣Keyboard index

The available keys that you can use are listed here, they can be used either as a single keypress or in a combination.

    '\t', '\n', '\r', ' ', '!', '"', '#', '$', '%', '&', "'", '(',
    ')', '*', '+', ',', '-', '.', '/', '0', '1', '2', '3', '4', '5', '6', '7',
    '8', '9', ':', ';', '<', '=', '>', '?', '@', '[', '\\', ']', '^', '_', '`',
    'a', 'b', 'c', 'd', 'e','f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o',
    'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '{', '|', '}', '~',
    'accept', 'add', 'alt', 'altleft', 'altright', 'apps', 'backspace',
    'browserback', 'browserfavorites', 'browserforward', 'browserhome',
    'browserrefresh', 'browsersearch', 'browserstop', 'capslock', 'clear',
    'convert', 'ctrl', 'ctrlleft', 'ctrlright', 'decimal', 'del', 'delete',
    'divide', 'down', 'end', 'enter', 'esc', 'escape', 'execute', 'f1', 'f10',
    'f11', 'f12', 'f13', 'f14', 'f15', 'f16', 'f17', 'f18', 'f19', 'f2', 'f20',
    'f21', 'f22', 'f23', 'f24', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9',
    'final', 'fn', 'hanguel', 'hangul', 'hanja', 'help', 'home', 'insert', 'junja',
    'kana', 'kanji', 'launchapp1', 'launchapp2', 'launchmail',
    'launchmediaselect', 'left', 'modechange', 'multiply', 'nexttrack',
    'nonconvert', 'num0', 'num1', 'num2', 'num3', 'num4', 'num5', 'num6',
    'num7', 'num8', 'num9', 'numlock', 'pagedown', 'pageup', 'pause', 'pgdn',
    'pgup', 'playpause', 'prevtrack', 'print', 'printscreen', 'prntscrn',
    'prtsc', 'prtscr', 'return', 'right', 'scrolllock', 'select', 'separator',
    'shift', 'shiftleft', 'shiftright', 'sleep', 'space', 'stop', 'subtract', 'tab',
    'up', 'volumedown', 'volumemute', 'volumeup', 'win', 'winleft', 'winright', 'yen',
    'command', 'option', 'optionleft', 'optionright'

## `🍿Examples`

Here are some example profiles for World of Warcraft, but you can use the app for whatever you need:

    [Druid]

    form bear = ctrl + f1
    form water = ctrl + f2
    form cat = ctrl + f3
    form travel = ctrl + f4
    form fly = ctrl + f5

    fly you fool = ctrl + f5 <||> hold:5:w <||> hold:5:space

    # We are disabling the "fly" command from the general profile as we do not need it on this profile.
    fly =

    bear charge = ctrl + f1 , wait:0.1 ,  1

    dash = alt + d

    [Mage]

    # Using some english words to create portals.

    portal dale = shift + 1
    portal shell = shift + 2
    portal terra = shift + 3
    portal exodus = shift + 4
    portal darn = shift + 5
    portal iron = shift + 6
    portal storm = shift + 7

    # Some interaction utilities for making portals

    accept party = enter,type:/run AcceptGroup(),enter,esc
    exit party = enter,type:/script LeaveParty(),enter

    take the tip = enter,type:/click TradeFrameTradeButton,enter,enter,type:/p Ty!,enter

    you're welcome = enter,type:/p yw,enter

    reply invite = enter , type:/r Invite me for potal , enter
    say invite = enter , type:/s Invite me for portal , enter

    [Rogue]

    stealth = ctrl + f1

    ambush = num7
    kidney shot = num8
    garrote = num9
    sap = num0

    stab him = alt + t , wait:0.2 , num7

    [General]

    # General category, commands here will be applied to all other categories.

    escape = esc
    jump = space
    dance = enter,type:/dance,enter

    # Keybinds for ground or flying mount
    run = pgdn
    fly = pgup

    # Just a movement complex command to showcase what's possible

    movement test = repeat:3:1:3:(hold:2:w<||>space,wait:2)

    # The <app commands> should always be in the General profile in order to appear in all your other profiles.

    cancel actions = <cancel>

    stop listening = <stop>
    pause commands = <pause>
    resume commands = <resume>

## 💬 Contact / Support

⛑️ For support, bug reports or any kind of requests, feel free to contact me at clerk@gnomish.tech or submit a new post on this app’s reddit community page or discord.

⚘ This version of the app is and will always be free, because of this, any support is greatly appreciated.

⚡ Please stick to the game rules: please use this app only in concordance to what the game allows, you are solely responsible for not violating the games terms and conditions.

You can find a copy of this documentation your app’s root folder ( README.html )

Enjoy,
Gnomish Tech!