Working with live streams
When working with live streams, you will want to retrieve details about them, update them or sometimes delete them. This guide walks you through how to manage your live streams.
API documentation
Choose an api.video client
The clients offered by api.video include:
Installation
To install your selected client, do the following:
go get github.com/apivideo/api.video-go-clientcomposer require api-video/php-api-clientnpm install @api.video/nodejs-client --save
...or with yarn:
yarn add @api.video/nodejs-clientpip install api.videoUsing Nuget
Install-Package ApiVideoCreate an account
Before you can start streaming, you need to create an api.video account.
Once you are logged in to the Dashboard, select the environment of your choice (sandbox or production) and copy your API key.
Show live stream (retrieve details for watching)
You can retrieve details about any live stream by sending a request containing the live stream ID. The response will show you the current state of the live stream and provide all the details you need if you want to broadcast using a particular live stream container.
curl --request GET \
--url https://ws.api.video/live-streams/li400mYKSgQ6xs7taUeSaEKr \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ'package main
import (
"context"
"fmt"
"os"
apivideosdk "github.com/apivideo/api.video-go-client"
)
func main() {
client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build()
// if you rather like to use the sandbox environment:
// client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build()
liveStreamId := "li400mYKSgQ6xs7taUeSaEKr" // string | The unique ID for the live stream you want to watch.
res, err := client.LiveStreams.Get(liveStreamId)
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `LiveStreams.Get``: %v\n", err)
}
// response from `Get`: LiveStream
fmt.Fprintf(os.Stdout, "Response from `LiveStreams.Get`: %v\n", res)
}<?php
require __DIR__ .'/vendor/autoload.php';
use Symfony\Component\HttpClient\Psr18Client;
use ApiVideo\Client\Client;
use ApiVideo\Client\Model\LiveStreamsApi;
$apiKey = 'API key here';
$apiVideoEndpoint = 'https://ws.api.video';
$httpClient = new \Symfony\Component\HttpClient\Psr18Client();
$client = new ApiVideo\Client\Client(
$apiVideoEndpoint,
$apiKey,
$httpClient
);
$livestream = $client->liveStreams()->get("live stream ID here");
print($livestream);const ApiVideoClient = require('@api.video/nodejs-client');
(async () => {
try {
const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });
const liveStreamId = 'li400mYKSgQ6xs7taUeSaEKr'; // The unique ID for the live stream you want to watch.
// LiveStream
const result = await client.liveStreams.get(liveStreamId);
console.log(result);
} catch (e) {
console.error(e);
}
})();## Get details about a live stream using its ID
import apivideo
from apivideo.apis import LiveStreamsApi
from apivideo.exceptions import ApiAuthException
api_key = "your api key here"
live_stream_id = "your live stream ID here"
client = apivideo.AuthenticatedApiClient(api_key)
## If you'd rather use the sandbox environment:
## client = apivideo.AuthenticatedApiClient(api_key, production=False)
client.connect()
live_stream_api = LiveStreamsApi(client)
## Retrieve live stream details
response = live_stream_api.get(live_stream_id)
print(response)Show live stream (retrieve details for watching) with your dashboard
If you don't want to retrieve details about a live stream programmatically, you can retrieve live stream details from your dashboard. Do the following:
Log in to your dashboard.
From the menu on the left, click Live streams. The Live streams page opens.
If you have a lot of live stream containers, you can filter them by title using the search bar at the top of the Live streams page. Otherwise, click on the live stream container you want information about.
When you click on a container title, you'll get a pop-up with some quick details about the live stream container. If you want full details, click Live Stream Details. This will bring up all information about the live stream container you wanted to review.
Update a live stream
If you want to update details for your live stream, you need the unique ID for your live stream and then the changes you want to make. You're able to update:
name- A string representing the name of your live stream.public- A boolean representing whether your video is public or not (true for public, false for private).playerId- You can associate an api.video player with your live stream by providing the player's ID.
The code sample to update is:
curl --request PATCH \
--url https://ws.api.video/live-streams/li400mYKSgQ6xs7taUeSaEKr \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ' \
--header 'Content-Type: application/json' \
--data '
{
"name": "My Live Stream Video",
"public": true,
"playerId": "pl45KFKdlddgk654dspkze"
}
'package main
import (
"context"
"fmt"
"os"
apivideosdk "github.com/apivideo/api.video-go-client"
)
func main() {
client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build()
// if you rather like to use the sandbox environment:
// client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build()
liveStreamId := "li400mYKSgQ6xs7taUeSaEKr" // string | The unique ID for the live stream that you want to update information for such as player details.
liveStreamUpdatePayload := *apivideosdk.NewLiveStreamUpdatePayload() // LiveStreamUpdatePayload |
res, err := client.LiveStreams.Update(liveStreamId, liveStreamUpdatePayload)
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `LiveStreams.Update``: %v\n", err)
}
// response from `Update`: LiveStream
fmt.Fprintf(os.Stdout, "Response from `LiveStreams.Update`: %v\n", res)
}const ApiVideoClient = require('@api.video/nodejs-client');
(async () => {
try {
const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });
const liveStreamId = 'li400mYKSgQ6xs7taUeSaEKr'; // The unique ID for the live stream that you want to update information for such as player details.
const liveStreamUpdatePayload = {
name: "My Live Stream Video", // The name you want to use for your live stream.
_public: true, // Whether your video can be viewed by everyone, or requires authentication to see it. A setting of false will require a unique token for each view.
playerId: "pl45KFKdlddgk654dspkze", // The unique ID for the player associated with a live stream that you want to update.
};
// LiveStream
const result = await client.liveStreams.update(liveStreamId, liveStreamUpdatePayload);
console.log(result);
} catch (e) {
console.error(e);
}
})();## Update information about your live stream. For example you can change whether you have it presented publicly.
import apivideo
from apivideo.apis import LiveStreamsApi
from apivideo.exceptions import ApiAuthException
api_key = "your api key here"
live_stream_id = "your live stream id here"
client = apivideo.AuthenticatedApiClient(api_key)
## If you'd rather use the sandbox environment:
## client = apivideo.AuthenticatedApiClient(api_key, production=False)
client.connect()
live_stream_api = LiveStreamsApi(client)
## Add the details you want to update to a dictionary
live_stream_update_payload = {
"public": True,
"name": "Bob III"
}
## Update the live stream
response = live_stream_api.update(live_stream_id, live_stream_update_payload)
print(response)Update a live stream using the dashboard
You can update live stream details from your dashboard if you don't want to retrieve details about a stream programmatically. Do the following:
Log in to your dashboard.
From the menu on the left, click Live streams. The Live streams screen opens.
Choose the live stream container you want to update by clicking on it. A pop-up appears displaying key details about your live stream.
Click Live Stream Details to open a display of complete information about your live stream.
You can change the title of your live stream, upload a thumbnail, and associate a player ID on this screen. When you're done, click Save.
Complete a live stream
You can request the API to complete a live stream that is currently running. This operation is asynchronous and the live stream will stop after a few seconds.
The API adds the EXT-X-ENDLIST tag to the live stream's HLS manifest. This stops the live stream on the player and also stops the recording of the live stream. The API keeps the incoming connection from the streamer open for at most 1 minute, which can be used to terminate the stream.
curl --request PUT \
--url https://ws.api.video/live-streams/li400mYKSgQ6xs7taUeSaEKr/complete \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ'api.video recommends that you use this endpoint to properly complete a live stream.
Delete a live stream
You can delete a live stream by sending in a DELETE request using the unique ID for the live stream. The code sample looks like this:
curl --request DELETE \
--url https://ws.api.video/live-streams/li400mYKSgQ6xs7taUeSaEKr \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ'package main
import (
"context"
"fmt"
"os"
apivideosdk "github.com/apivideo/api.video-go-client"
)
func main() {
client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build()
// if you rather like to use the sandbox environment:
// client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build()
liveStreamId := "li400mYKSgQ6xs7taUeSaEKr" // string | The unique ID for the live stream that you want to remove.
err := client.LiveStreams.Delete(liveStreamId)
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `LiveStreams.Delete``: %v\n", err)
}
}const ApiVideoClient = require('@api.video/nodejs-client');
(async () => {
try {
const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });
const liveStreamId = 'li400mYKSgQ6xs7taUeSaEKr'; // The unique ID for the live stream that you want to remove.
// void
const result = await client.liveStreams.delete(liveStreamId);
console.log(result);
} catch (e) {
console.error(e);
}
})();## Delete a live stream using its ID
import apivideo
from apivideo.apis import LiveStreamsApi
from apivideo.exceptions import ApiAuthException
api_key = "your api key here"
live_stream = "your live stream ID here"
client = apivideo.AuthenticatedApiClient(api_key)
## If you'd rather use the sandbox environment:
## client = apivideo.AuthenticatedApiClient(api_key, production=False)
client.connect()
live_stream_api = LiveStreamsApi(client)
## Delete the live stream
response = live_stream_api.delete(live_stream)
print(response)Delete a live stream from your dashboard
To delete a live stream from your dashboard, do the following:
Log in to your dashboard.
From the menu on the left, click Live streams.
Check the check box next to one or more live stream containers you want to delete. Please choose carefully. Once you delete them, they are not retrievable. After checking one or more boxes, a trash can icon appears at the bottom of the screen.
Click the trash can icon.
You'll see a pop-up asking if you're sure you want to delete because deletion is permanent. If you want to delete the live stream(s) you checked the box for, click Confirm.