Backstage
Introduction
By default, livestreams are created in backstage mode, while in backstage mode, streams can only be accessed by admin-like users. This is necessary because it makes it possible to create the setup in advance and to notify and grant access to viewers when the event starts.
Configuration
You change the backstage mode settings on the call type or on the call level.
- JavaScript
- Python
- cURL
// call level
call.update({
settings_override: {
backstage: {
enabled: true,
},
},
});
// or call type level
client.video.updateCallType('<call type name>', {
settings: {
backstage: {
enabled: true,
},
},
});
# call level update
call.update(
settings_override=CallSettingsRequest(
backstage=BackstageSettingsRequest(
enabled=True,
),
),
)
# call type level update
call_type_name = '<call type name>'
client.video.update_call_type(
settings=CallSettingsRequest(
backstage=BackstageSettingsRequest(
enabled=True,
),
),
)
# call level update
curl -X PATCH "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE_NAME}/${CALL_ID}?api_key=${API_KEY}" \
-H "Authorization: ${TOKEN}" \
-H "stream-auth-type: jwt" \
-H "Content-Type: application/json" \
-d '{
"settings_override": {
"backstage": {
"enabled": true
}
}
}'
# call type level update
curl -X PUT "https://video.stream-io-api.com/api/v2/video/calltypes/${CALL_TYPE_NAME}?api_key=${API_KEY}" \
-H "Authorization: ${TOKEN}" \
-H "stream-auth-type: jwt" \
-H "Content-Type: application/json" \
-d '{
"settings": {
"backstage": {
"enabled": true
}
}
}'
Setting the backstage mode to false
means that calls won't be created in backstage mode, and anyone can join the call.
Backstage Permissions
When a call is in backstage mode, only users with the join-backstage
capability are allowed to join.
- JavaScript
- Python
- cURL
client.video.updateCallType('<call type name>', {
grants: {
host: [VideoOwnCapability.JOIN_BACKSTAGE],
},
});
callTypeName = '<call type name>'
client.video.update_call_type(
grants={"host": [OwnCapability.JOIN_BACKSTAGE.to_str()]},
)
curl -X PUT "https://video.stream-io-api.com/api/v2/video/calltypes/${CALL_TYPE_NAME}?api_key=${API_KEY}" \
-H "Authorization: ${TOKEN}" \
-H "stream-auth-type: jwt" \
-H "Content-Type: application/json" \
-d '{
"grants": {
"host": ["join-backstage"]
}
}'
With this approach you can add multiple members that have the join-backstage
capability, which allows you to have multiple hosts.
Go Live
When the hosts are ready to start the stream and allow viewers to join, you can call the GoLive
method.
Optionally, you can start the HLS broadcast and/or recording at the same time as going live.
- JavaScript
- Python
- cURL
call.goLive();
// optionally start HLS broadcast and/or recording
call.goLive({ start_hls: true, start_recording: true });
call.go_live(start_hls=True, start_recording=True)
curl -X POST "https://video.stream-io-api.com/api/v2/video/call/livestream/${CALL_ID}/go_live?api_key=${API_KEY}" \
-H "Authorization: ${TOKEN}" \
-H "stream-auth-type: jwt"
# optionally start HLS broadcast and/or recording
curl -X POST "https://video.stream-io-api.com/api/v2/video/call/livestream/${CALL_ID}/go_live?api_key=${API_KEY}" \
-H "Authorization: ${TOKEN}" \
-H "stream-auth-type: jwt" \
-H "Content-Type: application/json" \
-d '{ "start_hls": true, "start_recording": true }'
It's also possible to send push notifications to call members on this event, for more information see the Call Types page.
Stop Live
When the stream ends the StopLive
endpoint will remove the viewers that are still in the call, and prevent from new viewers to join.
A call can enter and leave backstage mode multiple times.
- JavaScript
- Python
- cURL
call.stopLive();
call.stop_live()
curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE_NAME}/${CALL_ID}/stop_live?api_key=${API_KEY}" \
-H "Authorization: ${TOKEN}" \
-H "stream-auth-type: jwt"