# voice-commander
An application for defining macros and triggers using voice commands and hotkeys. Inspired by the popular commercial
software [VoiceAttack](https://www.voiceattack.com/).
**Requires Python 3.12+**
This is a major rewrite of a pre-existing project. If you're looking for the older version of this software, see the [pre-rewrite tag](https://github.com/spyoungtech/voice-commander/releases/tag/pre-rewrite) (or the now-yanked `0.0.1a` version on PyPI).
## Installation
### Via pip
To install, ideally in a virtualenv, use `pip`:
```bash
pip install voice-commander
```
This software also requires that you have AutoHotkey installed. You can either install AutoHotkey to a default location or, alternatively, install the `ahk-binary` package in your virtualenv:
```bash
pip install ahk-binary
```
### Windows executable
Coming soon.
## Usage
The basic primitives include **profiles**, **triggers**, **actions**, and **conditions**.
- An **action** defines the underlying action is to be performed upon triggering, such as pressing a keyboard key, playing a sound, opening a program, etc.
- A **trigger** is used to trigger an associated set of _actions_. For example, speaking a voice activation phrase, pressing a hotkey combination (like win+n), or similar. A trigger may trigger any number of _actions_.
- A **condition** is used to conditionally control execution of a trigger or any specific action within a trigger. For example, you may only want an action to perform a key press to actually activate when a specific window (like a game) is open/focused. A trigger may be attached to a _trigger_ or an _action_.
- A **profile** is a collection of triggers (and their associated actions/conditions) which can be activated/deactivated together for convenience.
### Basic example
You can define and run profiles in Python code.
```python
from voice_commander.profile import Profile
from voice_commander.triggers import *
from voice_commander.actions import *
profile = Profile("myprofile")
# triggers when any of these phrases are spoken
# You can add as many phrases as you want
trigger = VoiceTrigger('lower landing gear', 'retract landing gear')
# When the above trigger activates from a voice command, presses the "l" button (bound in-game to landing gear toggle)
action = AHKPressAction("l")
trigger.add_action(action) # you can add multiple actions if you want. Here, we're just adding one action.
profile.add_trigger(trigger)
profile.run()
```
You can also serialize/deserialize profiles to/from JSON.
```python
# save the profile to the present working directory
profile.save_json(dirname='.', filename='myprofile.vcp.json') # "vcp" means "Voice Commander Profile"
```
```python
from voice_commander.profile import load_profile
# easily load profiles from JSON
profile = load_profile('./myprofile.vcp.json')
profile.run()
```
You may also edit and run JSON files which represent the complete profile directly. The above example produces a JSON file substantially as follows:
```json
{
"configuration": {
"profile_name": "myprofile",
"schema_version": "0",
"triggers": [
{
"trigger_type": "voice_commander.triggers.VoiceTrigger",
"trigger_config": {
"*trigger_phrases": [
"lower landing gear",
"retract landing gear"
]
},
"actions": [
{
"action_type": "voice_commander.actions.AHKPressAction",
"action_config": {
"key": "l"
}
}
]
}
]
}
}
```
JSON5 is also supported. More formats may be supported in the future.
You can run profiles from these files directly from the command line:
```bash
python -m voice_commander run-profile --profile-file ./myprofile.vcp.json
```
Full documentation coming soon.
## Extending voice commander
voice-commander is being built with extension in mind. We don't have much to share here just yet, but you can check out
the [voice-commander-elite](https://github.com/spyoungtech/voice-commander-elite) project, which is an extension intended
to provide special functionality for players of the game _Elite Dangerous_. It is currently being used as a guinea pig
for future extensions. `voice-commander-elite` may also give you ideas of the kinds of other extensions that may be possible.
## Status
This project is in early stages of development, but is ready for use. Efforts will be made to keep existing
profile schemas compatible with (or convertable to) any future schema versions, though the Python API is likely to have
some breaking changes, at least while we're getting off the ground.
### Current Limitations
Some of the notable limitations of this software are as follows:
- Can only read `X`, `Y`, `Z`, `R`, `U`, and `V` axes of Joystick controllers. Some special axes (such as the `Dial` of certain throttle controllers) cannot be used as a trigger
- While controller/joystick inputs can be used for _triggering_ macros, we do not yet support _sending_ joystick or controller inputs in macros. You will, therefore, probably want to make sure you have keyboard bindings available for in-game actions.
- Only wave audio files (`.wav`) are currently supported for playing sounds (and only supported on Windows)
- Does not yet support XInput devices (e.g., Xbox One controllers) for triggers or sending
- Requires `ahk` (and therefore also AutoHotkey, and Windows) for most meaningful functionality. Future versions will support Linux-friendly alternatives
- Input interception (preventing the active program from receiving the input) is not supported for joystick/controller inputs.
Raw data
{
"_id": null,
"home_page": "https://github.com/spyoungtech/voice-commander",
"name": "voice-commander",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12.0",
"maintainer_email": null,
"keywords": "ahk, autohotkey, windows, mouse, keyboard, automation, pyautogui, voice-attack, voice, macro",
"author": "Spencer Young",
"author_email": "spencer.young@spyoung.com",
"download_url": "https://files.pythonhosted.org/packages/7e/eb/a256d319eff4ce1d66cca8ade270a727dc09a798ae439615057906022187/voice_commander-0.0.3.tar.gz",
"platform": null,
"description": "# voice-commander\n\nAn application for defining macros and triggers using voice commands and hotkeys. Inspired by the popular commercial\nsoftware [VoiceAttack](https://www.voiceattack.com/).\n\n**Requires Python 3.12+**\n\nThis is a major rewrite of a pre-existing project. If you're looking for the older version of this software, see the [pre-rewrite tag](https://github.com/spyoungtech/voice-commander/releases/tag/pre-rewrite) (or the now-yanked `0.0.1a` version on PyPI).\n\n## Installation\n\n### Via pip\n\nTo install, ideally in a virtualenv, use `pip`:\n\n```bash\npip install voice-commander\n```\n\nThis software also requires that you have AutoHotkey installed. You can either install AutoHotkey to a default location or, alternatively, install the `ahk-binary` package in your virtualenv:\n\n```bash\npip install ahk-binary\n```\n\n### Windows executable\n\nComing soon.\n\n\n## Usage\n\nThe basic primitives include **profiles**, **triggers**, **actions**, and **conditions**.\n\n- An **action** defines the underlying action is to be performed upon triggering, such as pressing a keyboard key, playing a sound, opening a program, etc.\n- A **trigger** is used to trigger an associated set of _actions_. For example, speaking a voice activation phrase, pressing a hotkey combination (like win+n), or similar. A trigger may trigger any number of _actions_.\n- A **condition** is used to conditionally control execution of a trigger or any specific action within a trigger. For example, you may only want an action to perform a key press to actually activate when a specific window (like a game) is open/focused. A trigger may be attached to a _trigger_ or an _action_.\n- A **profile** is a collection of triggers (and their associated actions/conditions) which can be activated/deactivated together for convenience.\n\n### Basic example\n\nYou can define and run profiles in Python code.\n\n\n```python\nfrom voice_commander.profile import Profile\nfrom voice_commander.triggers import *\nfrom voice_commander.actions import *\n\nprofile = Profile(\"myprofile\")\n\n# triggers when any of these phrases are spoken\n# You can add as many phrases as you want\ntrigger = VoiceTrigger('lower landing gear', 'retract landing gear')\n# When the above trigger activates from a voice command, presses the \"l\" button (bound in-game to landing gear toggle)\naction = AHKPressAction(\"l\")\ntrigger.add_action(action) # you can add multiple actions if you want. Here, we're just adding one action.\nprofile.add_trigger(trigger)\n\nprofile.run()\n```\n\nYou can also serialize/deserialize profiles to/from JSON.\n\n```python\n# save the profile to the present working directory\nprofile.save_json(dirname='.', filename='myprofile.vcp.json') # \"vcp\" means \"Voice Commander Profile\"\n```\n\n```python\nfrom voice_commander.profile import load_profile\n# easily load profiles from JSON\nprofile = load_profile('./myprofile.vcp.json')\nprofile.run()\n```\n\nYou may also edit and run JSON files which represent the complete profile directly. The above example produces a JSON file substantially as follows:\n\n```json\n{\n \"configuration\": {\n \"profile_name\": \"myprofile\",\n \"schema_version\": \"0\",\n \"triggers\": [\n {\n \"trigger_type\": \"voice_commander.triggers.VoiceTrigger\",\n \"trigger_config\": {\n \"*trigger_phrases\": [\n \"lower landing gear\",\n \"retract landing gear\"\n ]\n },\n \"actions\": [\n {\n \"action_type\": \"voice_commander.actions.AHKPressAction\",\n \"action_config\": {\n \"key\": \"l\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\nJSON5 is also supported. More formats may be supported in the future.\n\nYou can run profiles from these files directly from the command line:\n\n```bash\npython -m voice_commander run-profile --profile-file ./myprofile.vcp.json\n```\n\n\nFull documentation coming soon.\n\n## Extending voice commander\n\nvoice-commander is being built with extension in mind. We don't have much to share here just yet, but you can check out\nthe [voice-commander-elite](https://github.com/spyoungtech/voice-commander-elite) project, which is an extension intended\nto provide special functionality for players of the game _Elite Dangerous_. It is currently being used as a guinea pig\nfor future extensions. `voice-commander-elite` may also give you ideas of the kinds of other extensions that may be possible.\n\n## Status\n\nThis project is in early stages of development, but is ready for use. Efforts will be made to keep existing\nprofile schemas compatible with (or convertable to) any future schema versions, though the Python API is likely to have\nsome breaking changes, at least while we're getting off the ground.\n\n\n### Current Limitations\n\nSome of the notable limitations of this software are as follows:\n\n- Can only read `X`, `Y`, `Z`, `R`, `U`, and `V` axes of Joystick controllers. Some special axes (such as the `Dial` of certain throttle controllers) cannot be used as a trigger\n- While controller/joystick inputs can be used for _triggering_ macros, we do not yet support _sending_ joystick or controller inputs in macros. You will, therefore, probably want to make sure you have keyboard bindings available for in-game actions.\n- Only wave audio files (`.wav`) are currently supported for playing sounds (and only supported on Windows)\n- Does not yet support XInput devices (e.g., Xbox One controllers) for triggers or sending\n- Requires `ahk` (and therefore also AutoHotkey, and Windows) for most meaningful functionality. Future versions will support Linux-friendly alternatives\n- Input interception (preventing the active program from receiving the input) is not supported for joystick/controller inputs.\n",
"bugtrack_url": null,
"license": null,
"summary": "Voice-controlled macros and hotkeys.",
"version": "0.0.3",
"project_urls": {
"Documentation": "https://voice-commander.readthedocs.io/en/latest/",
"Funding": "https://github.com/sponsors/spyoungtech/",
"Homepage": "https://github.com/spyoungtech/voice-commander",
"Source": "https://github.com/spyoungtech/voice-commander",
"Tracker": "https://github.com/spyoungtech/voice-commander/issues"
},
"split_keywords": [
"ahk",
" autohotkey",
" windows",
" mouse",
" keyboard",
" automation",
" pyautogui",
" voice-attack",
" voice",
" macro"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ff8f1e0af9e77d2f14e35ec7f355cf054e5fe8fee9de1fd29dd00a11bc52bb2c",
"md5": "87e96ee5f212a26b20a419b649dca577",
"sha256": "d3e65890c81864dbed692c20012aa52900355e3bd43056bbd3dbbc9bf0d8f3c8"
},
"downloads": -1,
"filename": "voice_commander-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87e96ee5f212a26b20a419b649dca577",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12.0",
"size": 24400,
"upload_time": "2024-06-07T22:02:45",
"upload_time_iso_8601": "2024-06-07T22:02:45.927225Z",
"url": "https://files.pythonhosted.org/packages/ff/8f/1e0af9e77d2f14e35ec7f355cf054e5fe8fee9de1fd29dd00a11bc52bb2c/voice_commander-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7eeba256d319eff4ce1d66cca8ade270a727dc09a798ae439615057906022187",
"md5": "d3c9b0955e2c26d7ce05f5ada034d68c",
"sha256": "2414f32cfdcfd145920d3aa39436310038f46460e06092f8ca7d992d4bc8463b"
},
"downloads": -1,
"filename": "voice_commander-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "d3c9b0955e2c26d7ce05f5ada034d68c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12.0",
"size": 22329,
"upload_time": "2024-06-07T22:02:47",
"upload_time_iso_8601": "2024-06-07T22:02:47.180458Z",
"url": "https://files.pythonhosted.org/packages/7e/eb/a256d319eff4ce1d66cca8ade270a727dc09a798ae439615057906022187/voice_commander-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-07 22:02:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "spyoungtech",
"github_project": "voice-commander",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "voice-commander"
}
JSON
