HLS

HLS streaming provides better buffering than WebRTC, at the cost having a slight delay in your livestreams.

Start and stop HLS broadcast

There are two ways to start/stop HLS broadcast:

call.startHLSBroadcasting();

// to end broadcasting
call.stopHLSBroadcasting();

call.start_hls_broadcasting()

# to end broadcasting
call.stop_hls_broadcasting()

call.StartHLSBroadcasting(ctx, &getstream.StartHLSBroadcastingRequest{})
// to end broadcasting
call.StopHLSBroadcasting(ctx, &getstream.StopHLSBroadcastingRequest{})

curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}/start_broadcasting?api_key=${API_KEY}" \
    -H "Authorization: ${TOKEN}" \
    -H "stream-auth-type: jwt"

Or, if you’re using backstage mode, you can do that when going live:

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, &getstream.GoLiveRequest{
	StartHls:       getstream.PtrTo(true),
	StartRecording: getstream.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 }'

Once the live ended, the HLS broadcast will be stopped as well.

User permissions

To perform these operations, users need the following capabilities:

start-broadcast-call
stop-broadcast-call

Broadcast state

You can check if the call is being broadcast like this:

const resp = await call.getOrCreate();
const isBroadcasting = resp.call.egress.broadcasting;

response = call.get()
print(f"broadcasting: {response.data.call.egress.broadcasting}")

response, err := call.Get(ctx, &getstream.GetCallRequest{})
fmt.Printf("broadcasting: %v", response.Data.Call.Egress.Broadcasting)

# Broadcasting state: resp.call.egress.broadcasting
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"

Events

These events are sent to users connected to the call and your webhook/SQS:

call.broadcasting_started
call.broadcasting_stopped
call.broadcasting_failed

Consuming HLS broadcast

Users don’t need to join the call to consume the HLS broadcast, but they need to have the URL of the broadcast:

const resp = await call.getOrCreate();
const URL = resp.call.egress.hls?.playlist_url;

response = call.get()

# the URL of the HLS stream
response.data.call.egress.hls.playlist_url

response, err := call.Get(ctx, &getstream.GetCallRequest{})
fmt.Printf("HLS URL: %v", response.Data.Call.Egress.Hls.PlaylistUrl)

# Broadcasting URL: resp.call.egress.hls.playlist_url
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"

Multitracking allows you to provide multiple quality streams to your users, so they can choose the one that fits their network conditions. Lower quality streams will be downsampled from the highest quality stream. Using portrait and landscape orientations in the same stream is not supported. To enable multitracking, you need to override the quality_tracks field in the HLS settings or update call type settings on the dashboard.

const callType = "default";
const callId = "my-call";
const call = client.video.call(callType, callId);

// optionally provide additional data
call.getOrCreate({
  data: {
    created_by_id: "john",
    settings_override: {
      broadcasting: {
        enabled: true,
        hls: {
          quality_tracks: ["720p", "480p", "360p"],
        },
      },
    },
  },
});

call = client.video.call("default", uuid.uuid4())

call.get_or_create(
    data=CallRequest(
        created_by_id="john",
        settings_override=CallSettingsRequest(
            broadcasting=BroadcastSettingsRequest(
                enabled=True,
                hls=HLSSettingsRequest(
                    quality_tracks=["720p", "480p", "360p"],
                ),
            ),
        ),
    ),
)

call := client.Video().Call("default", uuid.NewString())

response, err := call.GetOrCreate(context.Background(), &getstream.GetOrCreateCallRequest{
    Data: &getstream.CallRequest{
        CreatedByID: getstream.PtrTo("john"),
        SettingsOverride: &getstream.CallSettingsRequest{
            Broadcasting: &getstream.BroadcastSettingsRequest{
                Enabled: getstream.PtrTo(true),
                HLS: &getstream.HLSSettingsRequest{
                    QualityTracks: []string{"720p", "480p", "360p"},
                },
            },
        },
    },
})

curl -X POST "<https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${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",
        "settings_override": {
            "broadcasting": {
                "enabled": true,
                "hls": {
                    "quality_tracks": ["720p", "480p", "360p"]
                }
            }
        }
    }
  }'

Overview

RTMP broadcasts