LiveSunday

API reference

Bitfocus Companion

Stream Deck buttons for start, stop and captions with Bitfocus Companion, and a button that shows whether a start would work.

Bitfocus Companion turns a Stream Deck into buttons that call the LiveSunday API. This guide sets up five buttons and a status color, using Companion's Generic HTTP connection.

What you need

  • Companion 4.1 or later
  • A LiveSunday API key. See the quick start.
  • The dashboard's Stream page open on the computer connected to your sound. The API starts the stream there. See Which computer sends the audio.

Add the connection

  1. In Companion, open Connections and add Generic HTTP.
  2. Set Base URL to https://api.livesunday.ai.
  3. Leave Authentication on None. Each action sends the key in a header instead.

Add the buttons

For each button, add a Press action from the Generic HTTP connection, with these options:

  • URI: the path from the table below
  • header input(JSON): {"Authorization": "Bearer ls_live_your_key_here"}
  • Body: leave it empty
  • Content Type: application/json
ButtonActionURIWhat it does
StartPOST/v1/stream/startStarts the stream with the languages saved in your dashboard
StopPOST/v1/stream/stopEnds the stream
ClearPOST/v1/captions/clearClears the captions on every listener's screen
HidePOST/v1/captions/hideHides captions. Listeners stay connected.
ShowPOST/v1/captions/showShows captions again

If a request fails, Companion marks the connection with an error. Its log shows the response, and the code in it says why. For example, Stop, Clear, Hide and Show answer SESSION_NOT_ACTIVE when nothing is live.

Show whether a start would work

GET /v1/status returns canStart.ok, which is true when a start would work right now. Companion can poll it and color the Start button.

1. Create a variable

Open Variables → Custom Variables and add one named livesunday_status.

2. Poll the status

  1. Open Triggers and add a trigger.
  2. Add the event Time interval and set it to 5 seconds.
  3. Add the Generic HTTP action GET with:
    • URI: /v1/status
    • header input(JSON): {"Authorization": "Bearer ls_live_your_key_here"}
    • JSON Response Data Variable: livesunday_status
    • Store result as text: off, so the variable holds an object

3. Color the buttons

On the Start button, add the feedback internal: Variable: Check boolean expression:

jsonpath($(custom:livesunday_status), '$.canStart.ok') == true

Give it a green background. The button turns green when a start would work.

To show that a stream is live, add a second feedback with a red background to the Stop button:

jsonpath($(custom:livesunday_status), '$.session') != null

Stay under the rate limit

Each key may make 60 requests a minute. Polling every 5 seconds uses 12 of them and leaves plenty for button presses. Don't poll faster than every 2 seconds.

When Start doesn't work

While canStart.ok is false, the status variable holds the reason in canStart.code. To show it on the Start button, turn on expression mode for the button text and enter:

jsonpath($(custom:livesunday_status), '$.canStart.ok') ? 'Start' : jsonpath($(custom:livesunday_status), '$.canStart.code')

OPERATOR_NOT_CONNECTED and OPERATOR_NOT_READY mean the Stream page isn't open or can't start audio on its own. Which computer sends the audio explains how to fix each code.