Table of Contents

Install VoiceMacro

Update VoiceMacro

Run VoiceMacro

Configure VoiceMacro

Using VoiceMacro

Add Profiles
Add Macros & Actions
All Actions
Group affixes
Tray Icon & Tray Menu

Successful Speech Recognition

Command line arguments

Data Directory

Plugins SDK (vmAPI.dll) (beta)




Install VoiceMacro

Using Setup file: Start the Setup file and follow the instructions on the screen

Using the ZIP file: Simply extract the ZIP archive anywhere you want, you can install VoiceMacro "standalone" on any portable drive
Just make sure the directory you are installing it is writable so VoiceMacro can save it's configuration data and your profile data



How to update VoiceMacro

If you have installed from setup file (.msi):
Close VoiceMacro, then use the new setup file to update your current version, your settings, profiles and variables will be preserved.

If you need the latest features from the test build, you can overwrite VoiceMacro.exe with the new version from the latest test build ZIP file by overwriting VoiceMacro.exe in "C:\Program Files (x86)\VoiceMacro" (if you used the default installation directory).

If you used the ZIP file:
Close VoiceMacro, then extract VoiceMacro.exe and overwrite your old version where you have put it. Your settings, profiles and variables will be preserved.

Note: "GlobalHook.dll" is usually not updated but to be sure, check the dates. Optionally you can also check the "Externals", "Sample-Profiles" and "Sounds" directory for new files or just overwrite the old files by default.

For more information about the directory structure VoiceMacro is using see "Data Directory".



Run VoiceMacro

Doubleclick on VoiceMacro.exe to run VoiceMacro, you can make VoiceMacro
start with Windows by clicking on -> Startup settings -> Start with Windows

If you run VoiceMacro for the first time, you are asked if you want to import the VoiceMacro
demo profile
that contains a collection of documented sample macros:

Note: Edit the macros in the Demo Profile and click the "Test" button to see how each sample macro works.

Check it out and learn a lot about what VoiceMacro can do in no time! (Highly recommended)

IMPORTANT: Before you start using Voice Commands, it is highly recommended to train the Speech Recognition Engine with your Voice! Please read this on how to to achieve a Succsessfull Speech Recognition



Configure VoiceMacro

Click on the button to open the configuration menu:

In Startup settings submenu you can toggle VoiceMacro to start with Windows, and start minimized
Windows 10 Users, please check this forum thread on how to start VoiceMacro as Administrator with Windows

If Show hints is activated, VoiceMacro is randomly displaying available voice commands for the current profile in the Main window's status bar (bottom of window)

If Always show Tray Icon is activated, the Tray Icon remains visible if the main window is open, otherwise the Tray Icon is only visible if the main window is hidden

Show data directory opens the location of the current data directory used by VoiceMacro in Windows Explorer

Click "Recognizer settings..." to open the Recognizer settings window:

Note: VoiceMacro is using the Microphone that is set as "Default Device" in Window's Audio Recording Settings, if you have attached more than one Microphone you might have to define which one to use as default Microphone.



Using VoiceMacro

This is only a short introduction to VoiceMacro's vast functionality

If you run VoiceMacro for the first time, you are asked if you want to import the VoiceMacro
demo profile
that contains a collection of documented sample macros

In the folder "Sample-Profiles" you will find even more profiles to import

Check it out and learn a lot about what VoiceMacro can do in no time!

Note: VoiceMacro is using a lot of Tooltips to explain to you what is what,
just hover with your mouse on any button or object to see the hints!

If you have any questions, please use the VoiceMacro Forum



Add Profiles:

In VoiceMacro, data is structured like this:

Profiles > Macros > Actions

Note: with profiles you can do more than only organize your macros! By assigning a target window you do not have to worry about selecting the correct profile.
Assuming you have "start with windows" activated,- you start your PC, start a Game or Application and VoiceMacro automatically switches to the profile you have defined depending on the currently active window

This means before you can add macros you have to create a profile, to do this, open the Main window:

Hint: you can make the log show only recognized commands (use Context Menu in the log)
Double click to edit a command directly from log

In the main window click on "Edit..." to open the Profiles and macros window:

Hint: Use the Context Menu (right Mouse button) in the Macros gridview to access more functions, hit CTRL+F to open search bar.
Note: Macros with activated scheduler are marked with "@", followed by the (first) macro name/voice command, followed by "..." if the macro has more than 1 voice command, followed by the hotkey. E.g. @Reboot System... / (2x) lWin + F12

Click on "Add" to open the Add New Profile window:

Hint: Use Semicolon ";" to separate multiple target windows
You can make a "Desktop" profile by using "[Program Manager (Desktop)]" as target window!

Enter a name for the Profile (usually the name of the Game or Application you want to create macros for)

Target window: in order for VoiceMacro to know which profile to activate automatically depending on the Game or Application you currently have active (Auto has to be checked in Main window), you have to set a "Target window" name



Add Macros/Actions:

Now you can add a macro by clicking on "Add new" which will open the Edit macro window:

First you enter the Macro's Name
(first Voice command = Macro Name, separate multiple commands with Semicolon ";")

Set the checkboxes to how you want the macro to be activated.
You have three options here: by voice command, by keyboard / mouse button and scheduler

Activate by keyboard / mouse:

Hint: you can have any keyboard or mouse button hotkey to trigger a macro not only on single click, but also on double- and tripleclick! This way you can assign 2 functions to the same key or button, one if clicked once, and another on double or triple click

Activate by scheduler:

Note: additionally VoiceMacro can trigger macros by command line, from other macros or by the "Auto" feature when a profile is switched.

You can now start adding basic actions by clicking on the buttons "Keyboard", "Mouse" and "Pause" or click on the "Other..." menu to access more of VoiceMacro's 40+ actions

Congratulations! When you are done and saved your macro you can start using or testing it

Important: use SHIFT+ESC to abort all running macros at all times!

VoiceMacro has a built-in "recursion" detection, this means if you by mistake created a macro that is started extremely frequent in a very short time VoiceMacro will terminate all macros by itself to prevent overloading your System

General hints:

To rearrange actions you can press SHIFT to move a action to top or bottom while clicking on the "Up" or "Down" buttons

Most of the buttons and menus have Shortcuts! Press the ALT key to reveal the Shortcuts from the menu's and buttons!

You can deactivate and reactivate ("comment out") one or more actions, press the "Active" button to toggle or press the space bar key, this will make VoiceMacro to skip those actions

Use the Context Menu (right Mouse button) in the Actions gridview to access more functions!

Also check out the "Pro tips" section is in the VoiceMacro Forum



All Actions:

Note: Items ending with "..." will open another window to configure the action.
Use the "Active" button to activate/deactivate a action (if you want to disable a action without deleting it)

Main actions

Note: You can use the "Recorder" feature to record these basic actions in realtime

Add Keyboard action

Add Mouse action

Insert Pause

> Other

Insert comment
Insert a comment

Write to Log
Write something to log (of Main window)

Execute/open a file...
Open or execute a file

Play sound...
Play various audio file formats

Stop sound
Stopps all sound from playing

Speak text...
Speak a text via TTS

Window to front and activate...

Wait for window...
Wait for a window then continue with actions
(Use "OnTimeOut" and "End OnTimeOut" with this action)

Wait for pixel...
Wait for a pixel color to appear or disappear on a specified coordinate
(Use "OnTimeOut" and "End OnTimeOut" with this action)

Close window...
Close a window

Kill process...
Terminate a program

Insert text...
Insert text by typing or by using clipboard and ctrl-v

> Copy to/paste from clipboard...

Copy to clipboard

Paste from clipboard

> Abort...

Abort all running macros
Aborts all running macros except the macro that is starting this action

Abort all running macros from this profile
Aborts all running macros from the profile of the macro that is executing this action except the macro that is starting this action

Abort this macro
Aborts all instances of this macro inclusive the one that started the abort action


Other > Statements & Conditions

Set Variable...
Set or change a variable (see Variables)

Loop Start...
Run the same actions in a macro for x ammounts between "Loop start" and "Loop end", then continue with macro after "Loop End"

Loop End
Use this to mark the end of a loop

> Toggle/rotate...

Toggle On
Toggle between 2 different actions each time the macro is started (ON)

Toggle Off
Toggle between 2 different actions each time the macro is started (OFF)

Continue skips to the end of the current loop body (also works with repeat)

Exit loop
Exit a loop

Exit macro
Exit a macro

> If/Else/EndIf...
(see Conditions and Variables)

If / ElseIf...
Conditional If/ElseIf

Conditional Else

Conditional EndIf

Use with "Wait for window" and "Wait for pixel" to continue macro after timeout instead of terminating the macro
Actions between OnTimeOut and EndOnTimeOut are executed if a timeout occured, otherwise they are skipped

End OnTimeOut
Use with "Wait for window" and "Wait for pixel" to continue macro after timeout instead of terminating the macro
Actions between OnTimeOut and EndOnTimeOut are executed if a timeout occured, otherwise they are skipped

Insert label
A simple label that indicates a target for "Goto"

Goto (label)...
Goto a predefined label (use "Insert label" to create labels)

Other > Control VoiceMacro...

Enable/Disable keyboard shortcuts...

Start/stop listening...

Start/stop ignore voice commands...
Use this command to ignore voice commands while you push a button to talk in a voice communtication app
Set "IgnoreExceptions" variable with commands (semicolon delimited) you want to except from being ignored!

Change Recognizer Engine...

Start/stop scheduler...

Start/stop executing macros...

Start/stop auto profile switching...

Minimize/restore VoiceMacro window...

Other > Advanced...

Show Dialog...
Show dialog with custom title, text and buttons

Show OSD...
Show On Screen Display

Hide OSD...
Hide On Screen Display

Switch to profile...
Switch to another profile

Change target window...
Set new target window for the current profile (permanent)

Speech to text...
Listen to you and send words or phrases (in a text box or chat window)

Get key state...
Get (and wait for) the state of a keyboard or mouse button

Send Virtual Keys...
Send keystokes with Virtual Key codes (use this table to get codes or Virtual Key numbers)

Use "VK_" then add the Virtual Key code and the key action:
_C = Click / Duration default (20ms)
_D = Down
_U = Up

Default is _C (can be ommited)

Add :n.nnn to override default click duration in seconds (only for Click)

VK_DELAY:n = Delay in seconds.

VK_#1 to VK_#256 use Virtual Key numbers instead of keywords (see table)

Press CTRL+S

Press A for 1 second

Press A for 0.05 seconds

CTRL+C, Wait 0.03 seconds, TAB, Wait 0.03 seconds, CTRL-V

Run macro from other profile...

> Window manipulation...

Change DisplayStyle...
Set window style (Normal / Minimized / Maximized), Transparency, Set/Unset TopMost

Resize/move window...

Change window title...

> Block Input...

Block Keyboard and Mouse input (used to prevent user from interfering with a running macro)



Group affixes:

Group affixes (prefixes and suffixes) are used to set prefixes and suffixes to commands

For example if you want to have the prefix "please" to each of the commands in a group:

- Right click on group and select "Edit group affixes", in the group's prefix enter please in the suffix

For example if you want to have a single command like "Set ViewDistance x", where x has to be a range from 200 to 4000, in steps of 100's:

- Set a group name for the macro, right click on group and select "Edit group affixes"

- In the group's suffix you enter (200-4000,100)

- "CommandSuffix" variable contains only the number that was recognized




There are 5 types of variables in VoiceMacro:

1. Internal variables: this are fixed name variables like "Time", "RepeatCounter" etc. that contain various useful values, most of them are read-only but some of them can be changed by using their variable name in SetVariable action
Hint: to get access to all internal variables use context menu where variables are possible (green colored input boxes), tooltips provide "live" preview and description of the various variables!

2. Local variables: user defined local variable, name ending with "_l" or none- only the current macro can set and read those
3. Profile variables: user defined profile variable, name ending with "_p" - the current profile can set and read those
4. Global variables: user defined global variable, name ending with "_g" - all profiles can set and read those
5. Global saved variables: user defined global variable, name ending with "_s" - all profiles can set and read those variables which are saved to disk

Use the SetVariable action to set, change or delete a variable, you can use calculations, combine text and variables, create random numbers etc. to generate the value of the variable

To set a variable with the content of a file or a URL (Website, etc.), use:
SetVariable testFILE = {File://c:\test.txt}
SetVariable testURL = {}

Note: use two curly brackets if you need to output curly brackets, for example to output "Hello {World}" with a InsertText Action you put in "Hello {{World}}"

Note: every input field with a green background has variables support. Press right mouse button to open the context menu to insert a variable (internal or user defined). Notice some of them have "Live" tooltips, showing the possible content of the variable.


SetVariable test_1 = Chair
SetVariable test_2 = Stairs
SetVariable test_3 = Bed
SetVariable test_4 = Floor
SetVariable index = RANDOM 1-4
SpeakText "Please sit on {test_{index}}"

The Variable Name (or part of it) can be a variable. Example:

SetVariable myvariable{myOtherVariable}_p = TestValue






VoiceMacro has several statements and actions to check conditions

You can make a macro wait for a window (WaitForWindow), or wait until a certain colored pixel on the screen appears/disappears (WaitForPixel), use OnTimeOut and EndOnTimeOut to continue macro at another point when a timeout occurred

You can have labels anywhere in your macro and use the Goto action to jump to any label

Variables can be evaluated in many different ways with various Expressions and Math functions in If / ElseIf / Else / EndIf conditional branchings:

Notice that all Expressions and and Math functions are presented where you need them (even with samples)!



Tray Icon & Tray Menu:

VoiceMacro's Tray Icon has several status icons:

Switched Profile
Executing macro(s)
Executing macros is disabled
Recording in progress

Left click on the Tray Icon to hide/open the Main Window

Right click to open VoiceMacro's Tray Menu and get quickly access to some functions, edit profile or add a macro to current profile without having to open the Main Window:

Hint: it is intended that you customize the notification area and set VoiceMacro's Icon behavior to "Show icon and notifications". This way you can always see VoiceMacro's activity and have quick access to the Tray Menu



Successful Speech Recognition

VoiceMacro is using Microsoft's (built in Windows) Speech Recognition Engine SAPI5 (Microsoft Speech Application Interface Version 5.1) or any other SAPI5-Compatible Speech Recognition Engine that you may have installed

Although the Engine has "Self-Learning" capabilities, it is highly recommended to train the Speech Recognition Engine with your Voice before you start using Voice Commands!
Read here how to set up and train Speech Recognition in Windows

Important Note: VoiceMacro is using the Microphone that is set as "Default Device" in Window's Audio Recording Settings, if you have attached more than one Microphone you might have to define which one to use as default Microphone - you also have to make sure the Microphone Input Volume Level is not too low or the Microphone is muted.
Check VoiceMacro's Main Window left bottom corner for the green Input Volume Meter to make sure the Microphone Input is not too low when you speak.

There are many factors for a good working Speech Recognition:

- Quality of Microphone
- Position of your Microphone
- Training of the Speech Engine
- How clear you are speaking (try to talk like a News Reporter)
- Background Noise*

Very important: do not use very short "one word" voice commands like "Ok", "Go", "Boost", "Pick" etc. or you will have lots of unwanted macro executions, and furthermore the engine is not as good recognizing short commands as it is when commands are longer or more than one word

One long word or better two and more words works best! Use "Confirm" instead of "Ok", "Boost the Engine" instead of "Boost", "Pickup stuff" instead of "Pick"

After talking, make a short pause (about 1 sec) before you speak any command, the Engine does not pick up any possible commands out of a sentence

If you misspoke a command (like "Boost the Engine"), don't correct yourself by saing "err, boost the eeeeengine"... unless you have a command "err, boost the eeeeengine"

If the recognition engine does not understand a command at first try, don't change your voice, just wait a second and repead and speak clear

*From my own experience, Speech Recognition is working way better over time (I play with speakers without a problem, once I was sick and only could whisper commands which worked impressively well)



Command line arguments

Note: if VoiceMacro is already running, (new) command line arguments are sent to the already running instance! You can use this feature to communicate from external programs or scripts to VoiceMacro

Use /ExecuteMacro=ProfileGUID/MacroGUID to execute a macro from a profile

To get ProfileGUID/MacroGUID right click in the actions list of Edit Macros window and choose "Copy profile/macro GUID's to clipboard"

Use /SetVariable:MyVariable_g="this is a test" to set a variable (only for Profile, Global and Global saved variables!)

Use /ShowWindow to show VoiceMacro's main window (if minimized)

Hint: you can have any arguments several times in the same command line! They are processed in order of input



VoiceMacro.exe /executemacro=414bb82f-12e0-427d-bf7c-712288d03142/28fdfdf2-1502-4bf0-9ace-d6649d921f32 /showwindow

VoiceMacro.exe /SetVariable:Feedback1_p="This variable has been changed externally!"

VoiceMacro.exe /SetVariable:Feedback1_p="This variable has been changed externally!" /executemacro=414bb82f-12e0-427d-bf7c-712288d03142/28fdfdf2-1502-4bf0-9ace-d6649d921f32 /SetVariable:Feedback2_p="This variable has also been changed externally!" /showwindow



Data Directory

The Data Directory contains the "Externals", "Sample-Profiles" and "Sounds" folders

It is recommended to use the "Sounds" and "Externals" folder for any sounds, scripts etc. your macro is using for easy sharing macros without requiring to adjust paths


There are up to 3 additional files in the main folder:

VoiceMacroConfig.xml - this is where the configuration of VoiceMacro is stored (window positions etc.)

VoiceMacroData.xml - this is where all the profiles are stored

Variables_s.xml - this is where the global saved variables are stored


To open the data directory, simply click on the button to open the configuration menu:

Then select "Show data directory" to open the current data directory in Windows Explorer

Note: Only if you have installed VoiceMacro under "Program files" (via Setup), the data Directory will be something like "C:\Users\YourUserName\AppData\Roaming\VoiceMacro\"
Otherwise VoiceMacro will use the path where the executable is located as data Directory



Plugins SDK (vmAPI.dll) (beta)

VoiceMacro version 1.3 and above comes with official plugin support and SDK for C#/

Download the SDK here:


How to install:

1. Unzip the files in your Visual Studio (2015 or higher) Projects folder and load the Solution file (VoiceMacroPluginSamples.sln)

2. Go to both project properties and change the output path to your VoiceMacro's Plugin folder:

3. Re-set the Reference of vmAPI.dll to the correct location of vmAPI.dll (in the Plugins folder of VoiceMacro):
Note: Set "Copy Local" to "False"

4. Terminate VoiceMacro and compile one of the projects of your preferred language

5. Start VoiceMacro and see the Plugin working!

Add a Macro (doing whatever you want) with the name "My sample plugin CS command" for C# or "My sample plugin command" for VB to test starting a macro from the sample plugin. Copy the Profile/Macro GUID (right click in the macros action list) and replace it in the code where starts a macro with vmCommand.ExecuteMacro.

Uncomment the SendKey sample code to test sending a key through VoiceMacro.

Join VoiceMacro's discord server at discord dot gg slash 9UTJqXJ to get in contact with other plugin developers.

Plugin API documentation (work in progress)

Plugin Name, Description and ID:

vmAPI.vmInterface.DisplayName (string)
The Display name of your plugin.

vmAPI.vmInterface.Description (string)
The Description of your plugin.

vmAPI.vmInterface.ID (string)
The ID (GUID) of your plugin.


Initializing and Disposing:

This is invoked when your plugin is loaded.

This is invoked when VoiceMacro is terminated.



vmAPI.vmInterface.ReceiveParams(string Param1, string Param2, string Param3, bool Synchron)
This is invoked when a macro is sending parameters (using SendToPlugin action).

vmAPI.vmInterface.ProfileSwitched(string ProfileGUID, string ProfileName)
This is invoked when a profile is switched.


API calls:

Returns the name of a profile.

Returns Unique ID of the profile.

Returns a list of commands.

The name and recognitiontext of a command.

Unique ID of the command.

vmAPI.vmCommand.GetVariable(string name)
Returns the value of a variable by name. Returns "ERR!" if variable is not existing.
Note: Only works for profile (_p), global (_g) and saved (_s) variables.

vmAPI.vmCommand.SetVariable(string name, string value)
Sets the value of a variable by name. Creates the variable if not existing.
Note: Only works for profile (_p), global (_g) and saved (_s) variables.

vmAPI.vmCommand.AddLogEntry(string text, Color color, string ID, [string sign = "P"], [string statusText = ""])
Writes a text to the log file with a specific color.
text is the message, color is the color of the log sign, ID is your plugin ID, optional sign is your sign (only 1 character allowed), optional statusText is showed in the status bar of the main window.

Returns all the profiles and commands as List(Of vmProfile).

vmAPI.vmCommand.ExecuteMacro(string ProfileMacroGUID)
Starts a macro by Profile/Macro GUID.

Gets active Profile GUID. "No Profile" is returned if there is none.

vmAPI.vmCommand.CommandExists(string CommandName)
Checks if a command exists. Returns Profile GUID/Macro GUID of the command.

Returns VoiceMacro's Data Directory.

Sends a key.



This is the structure for a command.

This is the structure for a profile.

This is the structure for a Keyboard action.

(0 = Click, 1 = Down, 2 = Up).

Click duration in milliseconds.



Last change: Feb 4, 2019