Stream Deck, X-keys and Companion

To control livematrix with a hardware panel like a Stream Deck or an X-keys panel, use the livematrix module for Bitfocus Companion.

Installation of Bitfocus Companion

Download Bitfocus Companion from bitfocus.io. You need a free Bitfocus account for that. Install it on the computer you plan to plug your USB panels into, then open Companion.

The launcher window shows the address Companion’s web interface runs on, by default http://127.0.0.1:8000. Launch GUI opens that address in your browser. Everything below happens there.

Connect

Next, connect your hardware panels to Companion.

Plug the panel into a USB port of the computer Companion runs on. Companion finds Stream Decks by itself. The Surfaces tab lists every panel Companion found. If a panel is missing, press Rescan USB.

For X-keys and other panels, turn on their support under Settings, in the Surfaces section, then rescan.

Close the Elgato Stream Deck app

The Elgato Stream Deck app claims the Stream Deck, and Companion cannot see it while the app runs. Quit the Stream Deck app, or don’t install it on the Companion computer.

If you want to keep using the Stream Deck app, for example to mix livematrix buttons with buttons of other software, install the Bitfocus Companion plugin from the Elgato Marketplace instead, and turn on the Elgato plugin under Settings in Companion. The Elgato app then keeps control of the Stream Deck, and the plugin’s buttons show and press Companion’s buttons.

Install the livematrix module

The livematrix module is available in the Companion module store.

1. In Companion, open the Connections tab and press Add connection.
2. Search for LiveMatrix.
3. Add it. Companion downloads the module from the store the first time.

The livematrix module needs Companion 5.0 or newer.

Connect Companion to livematrix

There are two ways to connect Companion to livematrix. The module can go through the livematrix app on the same computer, or it can log in to the server directly as a specific user. Logging in directly lets Companion run on a different computer from the app.

Through the local app, Companion acts for whoever is logged in to the app. When someone logs in to the app with another username, Companion follows.

Through the local livematrix client

Use this when Companion runs on the same computer as the livematrix app (Windows, macOS or Linux).

1. In the livematrix app, open Settings, then Control API.
2. Turn on Enable local control API and press Save Control API. The port is 9100 unless you change it.
3. In Companion, open the livematrix connection and set Connection mode to Via a client’s control API.
4. Leave Control API host at 127.0.0.1, and set Control API port to the port from step 2. Leave Use TLS off.
5. Save.

The module needs no username or password. It acts for whoever is logged in to the app. The app accepts these connections only from the same computer, so this does not work across machines.

Directly with a username

Use this when Companion runs on another computer than the livematrix app, or without the app at all.

1. In Companion, open the livematrix connection and set Connection mode to Direct to server.
2. Under Server host, enter the hostname of your livematrix server, for example studio-a.livematrix.app.
3. Under Server port, enter the server’s port. The module suggests 55678, which is not the livematrix default, so always change it:
   • For a hostname that shows Serving on the server’s Network & HTTPS page, enter the HTTPS port (9443 by default) and turn on Use TLS.
   • Otherwise, enter the HTTP port (9080 by default) and leave Use TLS off.
4. Enter the Username and Password of the livematrix user the panel acts for.
5. Save.

The module does not accept the server’s self-signed certificate. With Use TLS on and an IP address or a name without its own certificate, it does not connect. See HTTPS and the self-signed certificate.

The connection shows as connected in the Connections tab once the module has logged in. If the password is wrong, the module stops and shows the error until you save the connection again.

Configure buttons

Configure the panel’s buttons under Buttons. The quickest way is the Presets tab on the right of the screen. Drag a preset onto a button to give it that function. The module lists the keys of the user it acts for, so the presets show up once the connection is connected.

The presets come in four sections:

Section	Presets
Intercom Keys	A button that talks and listens, for each of your keys.
Talk Keys	A button that only talks, for each of your keys.
Listen Keys	A button that only listens, for each of your keys.
Microphone and Selection	Microphone mute, and the volume controls for the selected key.

The key sections have two groups, By key and By index:

• By key always drives the same key, whatever the administrator changes in the profile.
• By index drives the key at a position, counted from 0. When an administrator adds, moves or deletes keys in the profile, the button follows the position.

A key button stores its key in a variable called key. To move a button to another key, edit the button and change the value of key. Everything on the button follows.

Intercom keys

An intercom key is split down the middle. The left half is listen, the right half is talk, as on the keys in the app. The name of the key runs across both halves. The bar at the bottom shows the listen level.

• A short press latches talk on, or off again.
• A long press talks while you hold it.
• A double press turns listen on or off.

If your administrator turned latching off for the key, it talks only while you hold it.

On a Stream Deck +, put an intercom key on a dial. Turning the dial changes the listen level of that key by 1 dB per step.

Button	What you see
	Thin frames. The key is off. Green marks the listen half, red the talk half.
	Red right half. You are talking.
	Heavy red frame. Talk is latched and stays on.
	Green left half. You are listening. The heavy frame means it is latched.
	Both halves. You talk and listen.
	Amber stripe on the left. Audio is coming in on this key now, whether you listen or not. After it stops, the stripe stays dimmer for a minute.
	Amber stripe on the right. That person, or a member of the group, is listening to you.
	A faint name. That person is offline.
	Blue frame around the level bar. This is the selected key. See Change the listen level.

Talk keys and listen keys

A talk key or a listen key does one thing over the whole button. A talk key has a red frame, a listen key a green frame and a level bar. Use them for keys that only talk, such as a group, or only listen, such as a feed, or to put talk and listen of one key on two buttons.

• A short press latches the key on, or off again.
• A long press keeps it on while you hold it.

Button	What you see
	Filled red. You are talking.
	Heavy red frame. Talk is latched.
	Filled green with a heavy frame. Listen is latched.

The amber stripes and the faint name work as on intercom keys. A talk key shows the stripe on the right, a listen key on the left.

Change the listen level

The selected key is the key the volume controls act on. It is the key you hold down right now: press and hold an intercom key or a listen key, and change the level with the other hand. A blue frame around its level bar marks it. When you let go, nothing is selected any more. Holding a talk key does not select it.

The volume presets are in the Microphone and Selection section:

Button	Preset
	Selected key volume, for a dial on a Stream Deck +. Turning changes the level by 1 dB per step. Pressing sets it back to 0 dB.
	Selected key volume up and Selected key volume down, for buttons. Each press changes the level by 1 dB. Hold the button to keep changing. Place them as a pair: up shows the key’s name, down its level.
	Grey with “Hold a key”. No key is selected, and pressing does nothing.

The level goes from −100 dB (silent) to +10 dB. Every key starts at 0 dB.

To keep a key selected after you let go, use the Select key action on a button of your own, or tick Pressing selects this key and keeps it selected on a key’s Talk key down or Listen key down action. A key you hold still takes over while you hold it.

Mute your microphone

The Microphone mute preset (in the Microphone and Selection section) mutes and unmutes your microphone. It shows a grey mic while the mic is live, and a struck-through mic in amber while it is muted or while no device holds it, as the mic button in the app.

The button can also show the name of the device that holds your mic. Edit the button and turn on its Device element.

You have one microphone state, whichever device you use. Muting from Companion silences you everywhere: on talk keys, on party lines and for anyone listening to you. Muting in the app shows up on the Companion button, and the other way round. Unmuting from Companion turns the mic on in the app, with nothing to do there.

Companion never holds the mic itself. It mutes and unmutes the device that does. If that device is gone, unmuting gives the mic to the device of yours that held it most recently. If none of your devices can take it, nothing changes, and the $(livematrix:mic_error) variable says why until the mic state changes next.

The module offers these actions for your own buttons:

Action	Description
Mute microphone	Mutes the mic.
Unmute microphone	Unmutes the mic.
Toggle microphone mute	Mutes a live mic, or unmutes a muted one. The preset uses this.
Move microphone to device	Gives the mic to another of your devices and unmutes it there. Choose a device, or Next device to go through them in turn. Works only when the module logs in directly with a username.

For a cough button, put Mute microphone on the button’s press and Unmute microphone on its release.

The feedbacks Microphone muted and Microphone live, and the variables mic_muted, mic_open, mic_device, mic_holder_online and mic_error, show the same state on any button. Microphone live and mic_open are on while your voice goes out, also while you hold a talk key through a muted mic.

Different pages

Companion arranges buttons in pages. A page is one full grid of buttons, and each panel shows one page at a time. With more pages, one Stream Deck can carry more keys than it has buttons, for example one page per department.

You edit every page under Buttons. Choose the page with the arrows or the page number above the grid.

To move between pages on the panel itself, give some buttons the Page up, Page down or Page number type. Companion offers these types when you edit an empty button. Companion’s internal actions can also jump to a given page.

Each panel has a start page, set in the Surfaces tab. Two panels can show different pages of the same Companion, so two operators can share one Companion and each use their own keys.