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 software that Elgato is providing,
• or use the Bitfocus Companion and our REST API/

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 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	No
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

 

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, we don't have a module for the Companion ready, but don't hesitate to let us know if you are interested as well.

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 

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:

Bitfocus Companion

Using the REST API

If you want to use Bitfocus Companion, you will need to use Bitfocus's application, and 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.

First, get in touch with us to get the documentation about the REST API for your Softron application.

Then once you have the documentation, download the application from Bitfocus's website. Once installed, start it, and click on the "Launch GUI" button:

Then in the "Instances" pane, click on "Add by Category", then choose the menu "Generic > Generic HTTP Requests":

Then configure the HTTP request. You can add a "Base URL" as below (which is an example if you want to control a MovieRecorder, modify it according to the documentation you have received for your Softron application):

 

Then click on "Apply changes", select the "Buttons" pane and click on one button to edit it.

Add a Button text, and in the "Key down/on actions" section, click on the "+Add key down/on Action" menu and select "http: GET":

Then in the Options section, type the remaining of the URI. So for example if you used the same setting as above to control MovieRecorder, you could add "/0/record" to start recording on the first source:

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.

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.