Skip to content

The CLI and AutoHotkey

Jump to bottom
Craig McLure edited this page Jul 8, 2024 · 3 revisions

The GoXLR Utility comes with a fully featured Command Line Interface (cli) which allows you to configure all aspects of the GoXLR without needing to open the GUI. This is great for things like automation and basic scripting, or simply hooking behaviours up to things like buttons or key combinations (hotkeys).

Please Note: If you're able to use the full API directly, we recommend you use it as it provides more flexibility on checking the current 'state' of the GoXLR. This guide will include some suggestions on ways to programatically fetch specific data points for more advanced users.

The GoXLR CLI

In this section, we're going to walk through navigating the CLI and performing actions, specifically in this case loading a profile.

The goxlr-client binary is installed alongside the Utility, and accessing it is dependant on your operating system:

  • Windows: Open a Command Prompt, and cd "C:\Program Files\GoXLR Utility" (or your install path if changed)
  • Linux: Open a Terminal, the goxlr-client will be on $PATH if installed via a package

Now you can run goxlr-client and it will present you with the initial help text.

Navigating the help

The GoXLR Utility CLI is broken down into a series of 'commands' which each have their own commands, which eventually drill down to an action. Each 'section' will display a help message if a command is incomplete to help direct us to where we need to go.

In this example, we're going to navigate the CLI in an attempt to Load a profile called Frosty. Some arguments and text has been removed from the following snippets just to help keep things clean, and provide clearer direction on what needs to be looked at.

We'll start by just running goxlr-client and getting a list of available commands.

Commands:
  profiles      Profile Settings
  microphone    Adjust the microphone settings (Eq, Gate and Compressor)
  volume        Adjust Channel Volumes
  submix        Adjust Submix Settings
  bleep-volume  Configure the Bleep Button
  faders        Commands to manipulate the individual GoXLR Faders
  cough-button  Commands for configuring the cough button
  router        Commands to manipulate the GoXLR Router
  lighting      Commands to control the GoXLR lighting
  effects       Commands to Control the Effects Panel
  sampler
  settings

We know we want to load a profile, so we can drill into the profiles area by running goxlr-client profiles, which will present us with the following help:

Commands:
  device      General Device Profile
  microphone  Microphone Profile

The GoXLR has two types of profile but we're only interested loading the main device profile, not the microphone profile, so we can now run goxlr-client profiles device to be presented with the following:

Commands:
  new           Create a new profile
  load          Load a profile by name
  load-colours  Load a Profiles Colours Only
  save          Save the currently running profile
  save-as       Save the currently running profile with a new name

Again, a list of various things we can do with profiles, but we want to load. So execute goxlr-client profiles device load and you'll be presented with the following error message:

error: the following required arguments were not provided:
  <PROFILE_NAME>

Usage: goxlr-client profiles device load <PROFILE_NAME> [PERSIST]

For more information, try '--help'.

The error message indicates that a profile name is required for this command which means we've reached the command we want!

Before we step forward, if you're unsure about what the arguments mean, or what values are considered valid, you can (as recommended) run the same command with --help to get a breakdown. So in this case goxlr-client profiles device load --help, which will present you with the following:

Usage: goxlr-client profiles device load <PROFILE_NAME> [PERSIST]

Arguments:
  <PROFILE_NAME>  The profile name to load
  [PERSIST]       Persist the Load [possible values: true, false]

Arguments wrapped in <> are required arguments, and arguments in [] are optional.

We can now simply add the profile name to the command (in this example case Frosty), and execute goxlr-client profiles device load Frosty which will instruct the GoXLR Utility to load the Frosty profile to the device.

And you're done! The CLI provides options for everything that can be set via the GUI and is 'self documenting'. The method used above can be used to drill into various areas and features of the GoXLR and used to make changes. There are still a couple of places which aren't fully documented yet but they're generally pretty self-explainatory. If you find something you can't do via the CLI but need, open an issue or let us know on discord.

Windows Only: Command Prompt Popup

If you're using the CLI in a script (such as AutoHotkey) you may find that a Command Prompt will quickly open and close whenever your script runs the CLI which can result in focus being lost to your active window. When doing things like gaming, this is not a desirable effect! In order to avoid this the Utility provides a goxlr-client-quiet binary which is designed to silently execute a command without spawning a window or providing output.

Once you've worked out the command you want to run, so for example goxlr-client profiles device load Frosty, you can replace the goxlr-client with goxlr-client-quiet to silently run the command. All the parameters are the same for both, just one runs quietly! So the above example would be goxlr-client-quiet profiles device load Frosty

AutoHotkey

AutoHotkey is a tool that allows you to run code and programs when a certain key combination is hit. This makes it a popular tool when using the GoXLR Utility as you're able to create keyboard shortcuts that trigger the CLI to change settings. I'm going to avoid going into massive detail on AutoHotkey itself, and instead recommend you check out the AutoHotkey beginner tutorial to help familiarise yourself with how AHK works. The examples provided here are for AutoHotkey v2.

For these examples, I'll use what we learned above for loading a profile, and assign them to key combinations. I will be using two different profiles (Headphones and Speakers) as an example of switching.

Simple Example

In this example, we want to be able to load the Headphones profile when pressing Ctrl+Z, and the Speakers profile when pressing Alt+Z, we can do that simply by assigning the two combinations.

#Requires AutoHotkey v2.0

^z:: Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device load Headphones"
!z:: Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device load Speakers"

Now if you run the script you can Hold Ctrl or Alt then press Z and it will load the defined profile.

Adding and adjusting how things run is generally an excersize for the user, but multiple commands can be batched up. Say we want to save the active profile before loading the new one, that's easy enough to do. From the above we know there's a save command under the profiles section, so all we need to do is adjust our script to call that first.

#Requires AutoHotkey v2.0

^z::{
	Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device save"
	Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device load Headphones"
}
!z::{
	Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device save"
	Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device load Speakers"
}

And now when triggering a profile change from the keyboard, the old profile will be saved first. This method can be used to perform any number of commands either before or after loading a profile, so the skys the limit!

Advanced Example

Note: This guide requires some knowledge of JSON, and JSON Path, and some general programming practises.

The GoXLR Utility has multiple ways of fetching data from the API which AHK is able to ingest and process. There are multiple ways to fetch this data, for a basic overview of the entire state of the GoXLR in JSON format you can open http://localhost:14564/api/get-devices in a browser window.

The Utility's API also supports fetching individual values based on a JSON path of the above state. So as an example, you can use the API with a JSON Path to fetch the currently loaded profile: http://localhost:14564/api/path?path=$.mixers..profile_name

So what can we do with this? Well, quite a lot! In the above simple example we have two separate keys to switch between the profiles, but using this information we can have a single button simply toggle between profiles depending on which profile is currently active:

#Requires AutoHotkey v2.0

!z::
{
	; The URL to fetch just the currently active Profile Name
	url := "http://localhost:14564/api/path?path=$.mixers..profile_name"

	; Send the HTTP Request and Fetch the Profile
	whr := ComObject("WinHttp.WinHttpRequest.5.1")
	whr.Open("GET", url, true)
	whr.Send()
	whr.waitForResponse()
	profile := whr.ResponseText
	
	; Save the Active Profile
	Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device save"

	; We use InStr to save having to parse JSON
	If InStr(profile, "Headphones")
		Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device load Speakers"
	else
		Run "C:\Program Files\GoXLR Utility\goxlr-client-quiet.exe profiles device load Headphones"
}

Now if you hold Alt then press Z it'll toggle between the two profiles. This methodology can be used for a magnitude of different things where you can read a state from the Utility and make decisions based on it, and it's not limited to AHK!

Conclusion

This should give a good overview of how to use the CLI and leverage it in scripts to perform simple changes to the GoXLR. A shoutout goes to WheelyNerman on Discord who was the first to experiment with using the API alongside an AHK script to toggle a setting.

Clone this wiki locally