Linux Voice Activated Macros

• Status

  • Planned additions

• Install

  • Available packages
    • AUR
  • Install manually
    • Requirements
    • Installation steps

• Configuring uinput access

  • TL/DR
  • Manual configuration
    • Udev rule for input

• Usage

  • Usage with Steam

  • Display LinVAM profile and language in MangoHud

  • Profiles

  • Input mode

  • Key combinations

  • Complex commands

  • Output audio

  • Improve voice recognition accuracy

• Debugging if something isn't working

This project is in a work in progress state, meaning both UI and functionality will be improved in the future.

Currently supported languages (just for voice input, UI is in English):

• English
• Russian
• Chinese
• French
• German

Utilising VOSK-API, a lightweight voice to text engine you can specify voice commands for the tool to recognise and actions to perform.

• Add location selection for output sounds instead of a hardcoded location
• Support for joysticks and gaming devices

If a package is available for your distribution, that's the recommended way for installing. If not, install by following the manual installation steps

After installing from AUR, run sudo usermod -aG tty,input $USER to allow uinput access without sudo and restart your PC.

• python packages:
  • PyQt6
  • sounddevice
  • srt
  • requests
  • tqdm
  • vosk
• ffmpeg
• ydotool (optional)

To simulate typing and recording key events, the program needs access to your /dev/uinput device. By default, this requires root privileges.

To avoid that, you can give the program permanent access to the input device by adding your username to input and tty user groups on your system and giving the group write access to the uinput device.

To do that, we use an udev rule. Udev is the Linux system that detects and reacts to devices getting plugged or unplugged on your computer. It also works with virtual devices like ydotool.

You also need to define new udev rules that will give needed groups permanent write access to the uinput device (this will give LinVAM and ydotoold write and read access).

For easy setup, execute the configure-uinput-access.sh script from the scripts folder.

You will need to restart your computer for the change to take effect.

Start LinVAM from your list of applications or by typing linvam in the terminal. This works on both X11 and Wayland, but prior uinput access setup is required, read Configuring uinput access

If you are using MangoHud, you can set it up for displaying selected LinVAM profile and language.

Run the following command in the terminal after installing LinVAM:

linvam --setup-mangohud

This expects a MangoHud.conf file located at ~/.config/MangoHud/. If your config file is located in some other place, execute the previous command like this where /path/to/dir/ is a path to a dir containing MangoHud.conf file:

linvam --setup-mangohud --path='/path/to/dir/'

For this to work, you will need sed and grep which are probably already installed, if not install them with your package managers.

Multiple profiles are supported. To create a new profile for a specific task/game click Add and the main profile editor window will be displayed. Profiles are saved to and loaded from profiles.json file located at /home/$USER/.local/share/LinVAM/.

Backup options:

• Use Export to export profiles.json file to selected location for backing up.
• Use Import to import profiles from profiles.json file when restoring backup. CAUTION! This overrides any existing profiles.
• Use Merge to add profiles from profiles.json file you selected. This doesn't delete existing profiles, it adds new ones alongside existing ones.

You can choose between two input modes for LinVAM to listen to your commands (linvamrun will use the option selected in the GUI before starting linvamrun):

• Always on - LinVAM is always listening to what you are saying
• Push to listen - LinVAM is only listening when you hold the set keybind. If this mode is selected and no keybind is set, listening will be always active as if Always on was selected

For inputting combinations, press the Start recording button and then enter the desired combination by pressing keys on the keyboard in the desired order. Once finished, press Stop recording.

It is possible to add multiple actions to a voice command for complex macros with the ability to add a pause between each action. You can also assign mouse movements and system commands if you require (e.g. opening applications such as calculator, browser etc.)

In the Command Edit Dialog, choose 'Play sound'. Pick the sound you would like to play.

For this to work you need to create a folder voicepacks inside your home directory (e.g. by executing mkdir ~/voicepacks in the terminal) and copy any audio file you would like to use to that folder. Within voicepacks folder you can create as many folders as you like to group your audio files (category folders). Place the audio file into these category folders or in any subfolder within a category folder. In theory any audio file should work, but tested only with MP3 files.

Example:

• ~/voicepacks/my voicepack/custom commands/hello.mp3
• ~/voicepacks/my voicepack/other/thank you.mp3

Default recognition accuracy should be good enough for most usages. If you want to improve voice recognition accuracy, please see this resource on how to train the acoustic model: https://alphacephei.com/vosk/adaptation

You can use the following arguments with linvam or linvamrun for debugging when something isn't working:

• --debug - prints additional info while running
• --use-ydotool - LinVAM will try and input keyboard and mouse events through ydotool instead of directly to input