Overview
In this section, we are going to explain how you can use Stream to power different livestream use cases.
Stream supports HLS and WebRTC-based livestreams.
Using WebRTC yields the best user experience:
- Stream video allows you to power ultra-low-latency streaming (hundreds of milliseconds). This is made possible by our worldwide edge infrastructure, which supports WebRTC for consuming and sending video.
- WebRTC livestreams can be interactive (users can send reactions, messages, etc.). This is not possible with other protocols (such as HLS).
Let us know if you wish to use other streaming protocols.
Other important features related to livestream that are discussed in this section:
- Multiple streams & co-hosts
- RTMP in and WebRTC input
- Exporting to HLS
Quickstart
Before diving into the detail, let's get a livestream up and running.
Create a new livestream call using the API
- JavaScript
- Python
- Golang
- cURL
call = client.video.call('livestream', callId);
const response = await call.getOrCreate({
data: {
created_by_id: 'john',
// You can add multiple hosts if you want to
members: [{ user_id: 'john', role: 'host' }],
},
});
from getstream.models import CallRequest, MemberRequest
call = client.video.call('livestream', callId)
response = call.create(
data=CallRequest(
created_by_id="john",
# You can add multiple hosts if you want to
members=[MemberRequest(user_id="john", role="host")],
),
)
call := client.Video().Call("livestream", callID)
response, err := call.GetOrCreate(ctx, &GetOrCreateCallRequest{
Data: &CallRequest{
CreatedByID: PtrTo("john"),
// You can add multiple hosts if you want to
Members: &[]MemberRequest{
{UserID: "john", Role: PtrTo("host")},
},
},
})
curl -X POST "https://video.stream-io-api.com/api/v2/video/call/livestream/${CALL_ID}?api_key=${API_KEY}" \
-H "Authorization: ${TOKEN}" \
-H "Content-Type: application/json" \
-H "stream-auth-type: jwt" \
-d '{
"data": {
"created_by_id": "john",
"members": [
{ "role": "host", "user_id": "john" }
]
}
}'
The built-in livestream
call type has sensible defaults for livestreaming. However, you can customize that call type or create your own to better match your requirements. More information on this topic can be found in the Call Types section.
Set the call live
By default, livestreams are created in backstage mode. When 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.
All we need to do in this case is call the GoLive
method on the call object, and that will make it accessible to viewers.
- JavaScript
- Python
- Golang
- 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)
call.GoLive(ctx, &GoLiveRequest{
StartHls: PtrTo(true),
StartRecording: PtrTo(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 }'
For more information, see the Backstage page.
Sending video from browser or mobile with WebRTC
For testing purposes, you can use this simple example host application. You can open the application multiple times which allows you to have multiple hosts, who can send multiple audio/video streams. Don't forget to provide the necessary credentials before testing.
Watching the stream
For testing purposes, you can use this simple example application that can play WebRTC and HLS streams as well. Don't forget to provide the necessary credentials before testing.
Test sending video via RTMP using OBS
Almost all livestream software and hardware supports RTMP. Our API supports using third-party software for streaming using RTMP.
Let's keep the demo app open and try to send video to the same call using RTMP.
Log the URL & Stream Key
- JavaScript
- Python
- Golang
- cURL
- JavaScript@0.3 (deprecated)
const resp = await call.get();
// userId of existing user
const userId = 'jane';
await client.upsertUsers([{ id: userId }]);
const token = client.generateUserToken({ user_id: userId });
const rtmpURL = resp.call.ingress.rtmp.address;
const streamKey = token;
console.log(rtmpURL, streamKey);
from getstream.models import UserRequest
call = client.video.call("default", uuid.uuid4())
# create the call where the RTMP will be sent to
response = call.get_or_create()
# ensure we have a user for the host to send video via RTMP
client.upsert_users(
UserRequest(id="tommaso-the-host")
)
# create a token for the user sending video, this can be used as the stream key
stream_key = client.create_token(user_id, expiration=3600)
rtmp_url = response.data.call.ingress.rtmp.address
print(rtmp_url, stream_key)
call := client.Video().Call("default", uuid.New().String())
// create the call where the RTMP will be sent to
response, err := call.GetOrCreate(ctx, nil)
// ensure we have a user for the host to send video via RTMP
client.UpdateUsers(ctx, &UpdateUsersRequest{
Users: map[string]UserRequest{
"tommaso-the-host": {
ID: "tommaso-the-host",
},
},
})
// create a token for the user sending video, this can be used as the stream key
expiration := time.Now().Add(1 * time.Hour)
streamKey, err := client.CreateToken("tommaso-the-host", &StreamJWTClaims{Expire: &expiration})
rtmpURL := response.Data.Call.Ingress.Rtmp.Address
fmt.Println("RTMP URL:", rtmpURL, "Stream Key:", streamKey)
# RTMP URL is: response.call.rtmp.address
curl -X GET "https://video.stream-io-api.com/api/v2/video/call/livestream/${CALL_ID}?api_key=${API_KEY}" \
-H "Authorization: ${TOKEN}" \
-H "stream-auth-type: jwt"
# Stream key: create a user token
const resp = await call.get();
// userId of existing user
const userId = 'jane';
await client.upsertUsers({
users: {
[userId]: {
id: userId,
},
},
});
const token = client.createToken(userId);
const rtmpURL = resp.call.ingress.rtmp.address;
const streamKey = token;
console.log(rtmpURL, streamKey);
Open OBS and go to settings -> stream
Select "custom" service Server: equal to the rtmpURL from the log Stream key: equal to the streamKey from the log
Press start streaming in OBS. The RTMP stream will now show up in your call just like a regular video participant.
You can test the livestream with the test application linked above.
For more information on this topic, see the RTMP page.