HOW TO: Use Elgato's Stream Deck

A few of our applications can be controlled simply using a "Stream Deck" from Elgato. Here are a explanations on how it works.

Softron integration or Elgato software?

First you will need to choose how you are going to use the Stream Deck. You can indeed use either :

• use the integration that we have built in our software,
• or use the Bitfocus Companion and either:
  • some Companion "Modules" (currently only available for OnTheAir Video and MovieRecorder)
  • our RESTfull HTTP API (not available with OnTheAir Video Express)
  • the HyperDeck Emulation
• or use the software that Elgato is providing,

It will be one or the other.  Below are the differences between the three. 

Feature	Softron Integration	StreamDeck Application	Bitfocus Companion
Plug and Play - No Configuration	YES	No. You will have to configure it either using the "Website" or the "Hotkey" Action.	No. You will have to configure it using either a "connection", a "Generic HTTP Request"
Automatically change page with application	YES. If you start MovieRecorder, it will show a different page than if you start OnTheAir Video.	No, there is no "application context", so the Stream Deck does not change page automatically when the application changes.	No, there is no "application context", so the Stream Deck does not change page automatically when the application changes.
Status Feedback	YES	No	YES, with connections
Control Multiple Applications from one page	No, you have to be in the application for the control to happen.	YES	YES, and it can even be remotely. Control of various appliances and applications is the strength of the Bitfocus Companion.
Possible Actions	Only the actions that are listed in the Stream Deck window in your Softron application.	All actions that have either a keyboard shortcut, or a REST API request.	All actions that have a REST API request, or the applications that have a HyperDeck emulation
SDK Supported?	No, our integration is done via simple USB connection	No	No
Supported Applications	OnTheAir Video Express OnTheAir Video MovieRecorder Express MovieRecorder Multicam Logger M|Replay	OnTheAir Video MovieRecorder Express MovieRecorder Multicam Logger M|Replay	OnTheAir Video Express (only with the HyperDeck emulation) OnTheAir Video MovieRecorder Express MovieRecorder Multicam Logger M|Replay

 

What about Elgato's SDK?

In January 2019, Elgato has released a new way to interact with the Stream Deck, through its own SDK. We currently don't support that (we started working on this a while ago when there was no SDK available), but it may be added in future versions of our software. Contact us if you are interested.

What about Bitfocus' Companion integration?

Currently, there are 2 modules available:

• OnTheAir Video
• MovieRecorder

Softron integration

At the time of writing, the applications that support the Stream Deck are:

• OnTheAir Video 
• OnTheAir Video Express
• MovieRecorder
• Multicam Logger
• M|Replay

Elgato's Stream Deck software can not be running

In order to be able to use the Softron integration, you need to make sure that the "Stream Deck" software is not running. If it is running, it will prevent us to access the Stream Deck. So make sure that it is not set to automatically launch at startup.

Note that the application will not show in the Dock, look up for this icon in the menu bar:

If you see this icon, click on it, and then select "Quit Stream Deck".

 

But at next computer restart, the Stream Deck application will be started again. If you don't want to have any conflict, make sure to delete the application from there: /Applications/Stream Deck.app

Using the built-in controls

It should be as easy as plug the Stream Deck in your computer, start your Softron application. Depending on the application that you use, you will have different layouts. 

If you go to the menu "Window > Show Stream Deck window", you should see a window such as this one:

There are 2 sections in the window:

• To the left is the list of available pages, with their names and which kind of Stream Deck device they are for
• To the right is the list of Stream Deck devices that are connected to your computer. On the screenshot above, there is a "Classic" and a "Mini"

 

Setting up the Stream Decks

As we wanted to allow you to select which device you want to use for each application. Before you can start using your Stream Deck, you have to drag and drop at least one page from the list on the left on to one of the device on the right. 

You can also decide to enable the "Hold" option. This option is important for 2 things:

• if you want to be able to trigger your Softron application, even when using a different application
• if you are using multiple Stream Decks and you want each to use a different application

Customising the pages

You can create new pages by clicking on the + icon at the bottom of the pages list:

Each page can also be modified. For this, right-click on any of the page, and select "Edit":

Or you can click on the triangle.

When you are editing a page, you will see the device in big, with the list of possible actions on the left:

You can drag and drop actions from one button to another to move them, or from the list to a button.

Click on "OK" when you are done.

Customising the list of actions

In the edit window, you can create a new action by clicking on the + icon at the bottom of the list:

 You can also select an action, right click and select either "New" or "Duplicate" (note that you can not edit the default actions):

After a new action is created (or duplicated), click on the "wheel" icon to edit it (or right-click and select "Edit"). This should open a window:

You can set:

• Name: This is the name displayed in the list
• Selector: This is the "action" that will be made. We recommend that you duplicate an existing action and then edit the parameter, as all possible actions are listed in the list, there are no other.
• Parameter: Only certain actions support a parameter. This is true for example in OnTheAir Video to start playing a specific clip, or in Multicam Logger or M|Replay to add markers.
• Enabled Image: It's the image that is used when the action is not active.
• Active Image: It's the image that is used when the action is active. For example if a source is recording in MovieRecorder. 

Customising the Stream Deck using the plist

If you want to really customise the Stream Deck, currently, it requires some knowledge. This is something that we will also improve in the future. But here is how you should do for now:

Go to the following folder: 

/Library/Application Support/Softron/StreamDeck

In that folder, locate the folder that pertains to the application that you are using. For example, for OnTheAir Video, there should be a folder called "com.softronmedia.OnTheAirVideo". Inside that folder, you should see something like this:

The 2 "plist" files are the 2 pages of your StreamDeck. And the "Images" folder are where all the images are stored.

The best is that you start from one of the existing pages, so you can know the syntax. And if you have requests, don't hesitate to contact Softron support so we can better help you.

Restore to defaults

The "Restore to defaults" button can be used if you want to restore to the default configuration.

Note that this can be useful also if you want to use new features or buttons that were done in a new version of the application. It will also copy the new images to the folder.

Using multiple Stream Decks on one computer

If you want to use multiple Stream Decks on one computer, and have each Stream Deck control a specific application, you should:

• make sure that you are using an application that was released on or after January 2019. Previous versions only supported one Stream Deck.
• then start the first Softron application that you want to be controlled by a Stream Deck. It will 

Bitfocus Companion

Installing the Bitfocus Companion app

First you will need to download the application from Bitfocus's website. Once installed, start it, and click on the "Launch GUI" button:

Then a few questions will be asked to do the setup, we suggest that you check the documentation online to set it up the best way to match your needs.

Depending on the software you use, you will either use a module, our REST API or the HyperDeck Emulation:

• Use a module for OnTheAir Video and MovieRecorder
• Use the HyperDeck emulation for OnTheAir Video Express
• Use our REST API for all other applications that have a REST API (OnTheAir CG, M|Replay, Multicam Logger, ...)

 

Setting up your Softron application

To control your Softron application with bitfocus, you will need to find the IP address of the computer where it runs (check the network settings) as well as the port number. You can find the different port numbers either in the articles in our help center, or simply by checking the settings of your Softron application. For example, in OnTheAir Video, the port number is here:

Note that for the "multi" versions of the applications, they will all have a different port number. Make sure that port numbers are unique across multiple applications, or you will have conflicts.

Make sure also that the "Enable Remote Control" checkbox is enabled and that the "Require Authentication" option is disabled.

Using a Module

Once you have done the first steps of your setups, in the "Connections" tab of Companion, search for "Softron" to show all modules available:

Click on "Add" next to the module you want to use.

Then configure:

• The Label = how it will be shown in the Companion settings
• Target IP = the IP address of the computer where your Softron application is running
• Target Port = the port number used by your Softron Application. The port number should be the good "default" port number, but for OnTheAir Video, if you are using the "multi" version, you may want to change this  (see above).

Once this is setup, you should see that the Status is now "Connected" (provided your Softron application is running).

Now go to the "Buttons" pane, where you will now see the Presets for OnTheAir Video: 

Click on that red button, to show the different types of actions:

If you then click on "Transport" for example, you will see the different "Presets" available to control the playback of OnTheAir Video:

You can now drag and drop these on buttons to assign them:

That's it, the buttons should now show up on your Stream Deck. If you want to emulate on your computer, you can click on "Web buttons" in the left list.

Of course there is more to it, you can then also edit the preset buttons, as these are just preset, you can modify them to your liking...

Using the REST API

If you want to either do actions not available in the MovieRecorder or OnTheAir Video modules, or use it with an application that does not have a module, you can use our REST API. Most of our application have a REST API, one major applications that does not have it is OnTheAir Video Express. For OnTheAir Video Express to be controlled by the Bitfocus Companion app, you can use the HyperDeck Emulation.

You can find some information about our REST API on our support desk. If you need more info, don't hesitate to get in touch with us.

Once you have the documentation for the REST API, then in the "connections" pane, search for "http":

Then click on 3add" in front of "Generic: HTTP Requests". This should immediately show a "Edit connection" pane:

You can set a Label and add a "Base URL" as above (which is an example if you want to control a OnTheAir CG). Modify the IP and port number depending on the application that you want to control (see above on how to find the port number). Note that the base URL is not mandatory, you can leave it blank, but then when editing buttons, you will have to write the IP and port number every time. Then click on "Save".

Once this is set, you can start creating buttons. Select the "Buttons" pane and click on one button to edit it, and click on "Create button":

This will open the following page:

Then edit the "Button text string" (the text that will be displayed on the button), and click on the "Add press action" drop down menu, start typing "http" and select the type of request that you will need to do:

Check the REST API to know which kind you will need to do, but most of the time a simple "GET" will be enough.

Then in the press action setting, type the remaining of the URI. The example below is to start playing the first project in OnTheAir CG Server:

That's it for your first button. 

The nice thing is that you can do multiple REST requests when pushing on a button, and thus control multiple applications at once. Here there is much more to it than just these, but we wanted to show you the basics...

Using the HyperDeck emulation of OnTheAir Video or OnTheAir Video Express

As OnTheAir Video Express does not have a REST API, if you want to use it with the Bitfocus Companion app, you can use the HyperDeck emulation feature available in OnTheAir Video Express 4.1 and later.

Check the following video for more info on how to use that emulation: https://www.youtube.com/watch?v=zxZ0YdotX0M

Once enabled, OnTheAir Video Express will be available for control as a HypderDeck from Blackmagic-Design. In the Bitfocus Companion app, simply add the HyperDeck module, and add the controls that you need.

Warning: the HyperDeck protocol communicates on a specific port, so you can not use multiple channels of OnTheAir Video Express on the same computer, it will work if they are installed on different computers with different IP addresses.

StreamDeck application

We won't go into too much details, as you can find a lot of info on Elgato's website or on the web about this, but the idea is that you should first download and install the Elgato Stream Deck software.

Again if you use the Softron integration, you should NOT start the Stream Deck software as it will prevent us to access the Stream Deck. It can be present on the computer, but not running.

Once installed, you will be able to configure the buttons.

For an integration with the Softron software, you will have to either:

• send REST requests (you will have to know how our REST API works)
• emulate keyboard shortcuts (you will have to know the keyboard shortcuts that you can use in our application)

The advantage of the keyboard shortcuts, is that it's way easier to do, but the downside is that you will have to make sure that the application is the front application for the keyboard shortcut to work. If it's not the front application, the keyboard shortcut might do something different. The REST requests are a little harder to setup, but will work wether the application is front or not.

StreamDeck and REST Requests

To make your life easier, we have created a Stream Deck profile that you can download here. It's a good starting point. There are buttons to control OnTheAir Video, OnTheAir CG Server or MovieRecorder. Note that for OnTheAir CG Server, and MovieRecorder, it will control the first project or source.

So how does it work? Let's say you want to start recording your first source in MovieRecorder:

• search for the "Website" action in the right pane:
• then drag and drop it on a button of your Stream Deck, and enter:
  • a title: what will be shown on the button
  • a URL: a REST request that will be done to your Softron application. In the case below, it's a request to start recording on the first source (in the list)
  • an image: you can choose an image that will illustrate that action
  • enable the option "Access in background" so that it starts even if the Stream Deck application is not front
• 
•  

That's it! Then you can create a different button to control MovieRecorder, one to control OnTheAir CG, etc... or also other applications that are not from us. 

StreamDeck and Keyboard Shortcuts

To configure the StreamDeck application to trigger a keyboard shortcut, simply search for the action "System > Hotkey":

Then configure the Hotkey to emulate the keyboard shortcut that you want. For example cmd + R to do a gang record in MovieRecorder.

Note that you will have to grant Stream Deck some Accessibility Privacy settings: