Use overlays.uno with the Bitfocus Companion Stream Deck app

Want to take your news live stream, sports broadcast or live podcast to the next level? The Bitfocus Companion Stream Deck plugin allows pro streamers to access more control over uno overlays, while managing the equipment you need for complex live streams. 

You can integrate any uno overlay into Companion by setting up the REST API and adding the payload from the Singular App. 

However, if you aren’t using the Singular App, you can also add the payload from any uno overlay using a generic HTTP connection. Each uno overlay has a unique API tailored to its specific functionalities (what we call the Uno App API). 

Here’s how you can set up controls on Bitfocus Companion using Uno App API.

Download and set up Companion for Stream Deck

1. Download the latest version of Bitfocus Companion and install it on your PC. 

Note: if you are working on MacOS, you may have to bypass some additional security warnings. We suggest you right-click on the Companion DMG file and click Open. 

2. A small control window should open. Click the “Launch GUI” button.

Now you can set up the REST API by adding the Generic HTTP Requests Connection.

3. Make sure you are in the Connections tab in Bitfocus Companion. Under the +Add Connection tab, type Generic HTTP into the search bar. Then, click the “Add” button. 

4. Configure the connection and make sure the Label is something you’ll recognize later.

Note: You can leave the Base URL field empty for now. You can define REST endpoints later when you define buttons. 

4. The Singular-API connection should appear under your Connections tab. Enable the HTTPS connector by clicking on the toggle next to the Singular-API connection.

Set up Companion with Uno App API 

Some important notes before you begin

All Uno App APIs use the PUT HTTP method without authentication. 

In this guide, we’re using the Pyrite-themed Stream Pack. However, if you’re just starting out and want to test this tutorial out first, you can also use these URLs for testing:

• App URL: https://app.overlays.uno/control/1bccBWBDKFWNSHEo8CdhSQ 
• API URL: https://app.overlays.uno/apiv2/controlapps/1bccBWBDKFWNSHEo8CdhSQ/api 
• Output URL: https://app.overlays.uno/output/1mPK06W9o5htQ8tGYf6xRj

1. Find the API endpoint

If you’re signed into your account on overlays.uno, this is how you can find the Uno App API URL:

1. Go to My Overlays and double-click the overlay that you want to use to open up its interface.

2. Click on the “?” icon, then click on “API Description” on the dropdown menu that appears. This allows you access a comprehensive overview of the overlay’s API capabilities. 

3. Locate the API endpoint.

2. Find the request you want to send to the Uno App API

Basic requests 

Here’s some examples of how you can send some basic requests to the Uno App API using Postman REST Client.

To show all overlays: 

1. Request method: PUT

2. Request URL: https://app.overlays.uno/apiv2/controlapps/1bccBWBDKFWNSHEo8CdhSQ/api

3. Request body: 

    {
            "command": "ShowAllOverlays"
     }
4. Response  body: 
 {
            "status": 200,
            "result": "ok",
            "payload": true
     }

To hide all overlays:

1. Request method: PUT:

2. Request URL: https://app.overlays.uno/apiv2/controlapps/1bccBWBDKFWNSHEo8CdhSQ/api

3. Request body:

    {
            "command": "ShowAllOverlays"
     }

4. Response body:

 {
            "status": 200,
            "result": "ok",
            "payload": false
     }

Find the ID for the overlay you want

With stream packs like the Pyrite-themed Stream Pack, you can control multiple overlays in one place. You need to find a particular overlay’s ID to control it. 

To find an overlays’ ID, first locate its name. For example, if you want to control different functions in the talking points, you need to identify the subcomposition with＂name＂: ＂Talking Points＂ and find the value next to ＂id＂.

You can then display the talking points by taking the following steps:

1. Set the following command and paste in the overlay ID :

    {
            "command": "ShowOverlay"
            "id" :  "paste the overlay id here"
     }

2. Add the following body:

 {
            "status": 200,
            "result": "ok",
            "payload": true
     }

Tip: To hide the talking points, change the payload to false. 

Get Overlay Models

Use the command ＂GetOverlayModels＂ to find an overlay, its ID, and the field you want to modify.

Set content for talking points

You can send a request that launches preset text in the stream pack’s talking points by using the Set Overlay Content command:

  { 
            "command": "SetOverlayContent"
             "id" :  "paste the overlay id here" 
             "content" :  {COPY AND PASTE THE PAYLOAD HERE
        }
     }

Set one field in the talking points

You can set just one field in the talking point (for example, the title, or talking point 1) by using the Set Overlay Content Field command. Remember to:

• Paste the overlay id
• Add the field ID (that’s the field that corresponds to the part of the talking points you want to control)

For example, if you wanted to set the title, you would use the following command:

  { 
            "command": "SetOverlayContentField"
             "id" :  "paste the overlay id here" 
             "fieldId" :   "Title",
             "value" :   "YOUR TEXT HERE"
     }

Highlight the next row of talking points

Use the following command to add +1 increment to the active row in the talking points, which highlights the next talking point:

  { 
            "command": "SetOverlayContentField"
             "id" :  "paste the overlay id here" 
             "fieldId" :   "rowActive",
             "value" :   "1"
     }

Tip: If you change the value to "-1" you can highlight the previous row of talking points. 

3. Add a button in Bitfocus Companion

1. Click on Buttons in the top menu tab to navigate to your buttons, then click on a square in the panel to select and edit a button. 

2.  Open the Action Browser by clicking on the file icon under “Press Actions”.

3. Select PUT method from the dropdown menu.

4. Define the PUT request.

• In the “URL” field, paste the Uno App API URL that you found by identifying the API Endpoint.
• In the “Body” field, paste the request body you want to use. 

For example, if you want to animate in the stream pack’s lower third overlay, paste the following request body:

{"command":"ShowOverlay","id":"f62741ea-7de0-468d-ad98-6a778bb5eeae"}

You can start by using any of the commands we listed out in the examples above, or writing your own text.

Test your Companion setup

You can check if your setup works properly by clicking on the Web buttons view the menu on the left of your screen.

If you need help using an Uno App API with Bitfocus Companion Stream Deck software, reach out to the uno team on our official Discord channel. You can also check out our other guides on using Bitfocus Companion, including how to use Companion to swap between uno slots.