Ending Live Streams with Automation and APIs

There are many scenarios where it is crucial to have fine control over your live streams to maintain a standard of quality and content being produced, as well as controlling cost by preventing unused streams from eating up bandwidth. Additionally, if there are technical difficulties on one end, or a need for automation, being able to control the status of your live stream is important to prevent live streams from hanging longer than intended.

For example, if someone’s internet drops while presenting on a live stream, we would want to find a way to stop that stream instead of letting it run until they return. Or if there is a set schedule to when streams start and stop, we can program the streams to end automatically without manual intervention.

With Dolby.io Real-time Streaming APIs, we have the ability to control your stream without the need to be on the dashboard at all. Instead, we can make API calls remotely to streamline this process without clicks. To run the Stop an active stream API, we first need to provide the information required to identify the stream we want to stop, as well as disable the publish token related to it to prevent any collisions. In all, the process to stop the stream will look like the following:

1. Find the publish token associated with the stream we wish to stop
2. Disable the above token
3. Stop the stream

Find the Publish Token

To find the stream name and the publish token, you can either look on the dashboard to find this information on the API tab of the token:

If the stream is live, you can find the tokenID using the Get all active Publish Token IDs API.

curl --request GET 
     --url https://api.millicast.com/api/publish_token/active/all 
     --header 'accept: application/json' 
     --header 'authorization: Bearer <token>'

Find the Stream Name

Using that tokenId in Read Token to also get the stream name:

curl --request GET 
     --url https://api.millicast.com/api/publish_token/<tokenId> 
     --header 'accept: application/json' 
     --header 'authorization: Bearer <token>'

Note that publish tokens for long running streams published before 1st October 2022 will not be returned. If you need to stop a long running stream, use the Dashboard or try republishing the stream.

Disable the Publish Token

Now that we have the parameters we need, lets perform the second step of disabling the token. For that, we can run the Disable Publish Token(s) API:

curl --request GET 
     --url https://api.millicast.com/api/publish_token/<tokenId> 
     --header 'accept: application/json' 
     --header 'authorization: Bearer <token>'

Stop the Stream

This will then open up the option to run the Stop an active stream API on the proper stream:

curl --request POST 
     --url https://api.millicast.com/api/stream/stop 
     --header 'accept: application/json' 
     --header 'authorization: Bearer <token>' 
     --header 'content-type: application/json' 
     --data '
{
     "streamId": "<streamId>"
}
'

And voilà! The stream has now been stopped remotely without touching the dashboard!

Re-enabling the Publishing Token

A common question one might have after performing the above steps is how to reuse the disabled publishing token, as not all streams are meant to be stopped forever. To fix this, we can just run another API call, Update Token. All we need to do is take the tokenId we had before, and change the isActive parameter to true:

curl --request PUT 
     --url https://api.millicast.com/api/publish_token/<tokenId> 
     --header 'accept: application/json' 
     --header 'authorization: Bearer <token>' 
     --header 'content-type: application/json' 
     --data '{"isActive":true}'

And now the token can be used to stream from once again.

Ending the Blog Post

All of these API calls are REST based, meaning that we do not need to use CURL commands as the only supported language. Any programming language that can support HTTP requests is viable, such as JavaScript, Python, Ruby, PHP, and more. Additionally, we have a .NET SDK you can use. Our documentation website provides examples.

If you’d like to reach more, read this post on generating new broadcasting tokens via the REST API and Postman for more automation tools! Good luck!