startLiveStreaming()

startLiveStreaming({instanceId, rtmpUrl, endpoints, ...options })

Compatibility:
Prebuilt
Custom

Receive a $15 credit for free

Try Daily pay-as-you-go features for free! New accounts have a $15 credit automatically applied when you add a credit card to the account. Learn more about pay-as-you-go features on our pricing page.

Starts a live stream at the rtmpUrl specified. Note that the participant who initiates this must be an owner and there is a domain level constraint on the number of concurrent streams (max_live_streams).

Multiple RTMP URLs can be passed in as an array to the endpoints property. (See addLiveStreamingEndpoints() for a code example using this property.) When multiple RTMP URLs are provided, each receives the same layout.

Multiple streaming sessions (up to max_streaming_instances_per_room on your Daily domain) can be started by specifying a unique instanceId, which should be a valid UUID string. Each instance can have a different layout, participants, lifetime, and update rules.

Contact us to configure max_streaming_instances_per_room for your domain. Note: recording and streaming instances that share the same instanceId also share the same underlying composition process, so any layout change made to streaming will also affect recording, and vice-versa.

startLivestreaming() cannot accept both rtmpURL and endpoints at the same time. Use endpoints when you want to start both RTMP and HLS.

If you would like to use both RTMP and HLS, we recommend that you define streaming_endpoints for both types of endpoints.

Note: The outgoing rtmp stream has the following properties:

  • Resolution: 1920 x 1080
  • Frame rate: 30fps
  • Keyframe: every 2 seconds (60 frames)
  • Target bitrate: 5Mbps

The following additional options are currently available:

  • height, width: Can be specified to control the resolution of the live stream. The value must be even, i.e., a multiple of 2.

  • backgroundColor: Specifies the background color of the stream, formatted as #rrggbb or #aarrggbb string.

  • fps: Specifies the video frame rate per second.

  • videoBitrate: Specifies the video bitrate in kilobits per second (kbps) to use for video output. Value can range between 10 and 10000. If not specified, the following bitrate values will be used for each given resolution:

    • 1080p: 5000
    • 720p: 3000
    • 480p: 2000
    • 360p: 1000
  • audioBitrate: Specifies the audio bitrate in kilobits per second (kbps) to use for audio output. Value can range between 10 and 320.

  • minIdleTimeOut: Amount of time in seconds to wait before ending a recording or live stream when the room is idle (e.g. when all users have muted video and audio). Default: 300 (seconds). Note: Once the timeout has been reached, it typically takes an additional 1-3 minutes for the recording or live stream to be shut down.

  • maxDuration: maximum duration in seconds after which recording/streaming is forcefully stopped. Defaults: 10800 seconds (3 hours) for recordings, 86400 seconds (24 hours) for streaming. This is a preventive circuit breaker to prevent billing surprises in case a user starts recording/streaming and leaves the room.

  • instanceId: UUID for a streaming or recording session. Used when multiple streaming or recording sessions are running for single room. Default: "c3df927c-f738-4471-a2b7-066fa7e95a6b". Note: "c3df927c-f738-4471-a2b7-066fa7e95a6b" is reserved internally; do not use this UUID.

  • layout: an object specifying the way participants’ videos are laid out in the live stream. A preset key with one of the following values must be provided:

    • 'default': This is the default grid layout, which renders participants in a grid, or in a vertical grid to the right, if a screen share is enabled. Optionally, a max_cam_streams integer key can be provided to specify how many cameras to include in the grid. The default value is 20, which is also the maximum number of cameras in a grid. The maximum may be increased at a later date.
    • 'single-participant': Use this layout to limit the audio and video to be streamed to a specific participant. The selected participant’s session ID must be specified via a session_id key.
    • 'active-participant': This layout focuses on the current speaker, and places up to 9 other cameras to the right in a vertical grid in the order in which they last spoke.
    • 'portrait': Allows for mobile-friendly layouts. The video will be forced into portrait mode, where up to 2 participants will be shown. An additional variant key may be specified. Valid values are:
      • 'vertical' for a vertical grid layout (the default)
      • 'inset'for having one participant's video take up the entire screen, and the other inset in a smaller rectangle. Participants' videos are scaled and cropped to fit the entire available space. Participants with the is_owner flag are shown lower in the grid (vertical variant), or full screen (inset variant).
    • 'custom': Allows for custom layouts. (See below.)

We're working on improving the set of available presets. Please contact us if you have specific requirements or feedback.


Daily offers a "baseline" composition option via the "custom" layout preset for customizing your video layouts while live streaming. This option allows for even more flexibility while using Daily's live streaming API.

Review our Video Component System (VCS) guide or VCS Simulator for additional information and code examples.

Many VCS properties use a "grid unit". The grid unit is a designer-friendly, device-independent unit. The default grid size is 1/36 of the output's minimum dimension. In other words, 1gu = 20px on a 720p stream and 30px on a 1080p stream. Learn more about grid units in our [VCS SDK docs](/reference/vcs/layout-api#the-grid-unit).

Baseline composition properties

string

Sets the layout mode. Valid options:

  • single: Show a single full-screen video.
  • split: Show the first two participants side-by-side.
  • grid: Show up to 20 videos in a grid layout.
  • dominant: Show the active speaker in a large pane on the left, with additional video thumbnails on the right.
  • pip: Show the active speaker in a full-screen view, with the first participant inlaid in a corner.
Default: grid

Sets whether a text overlay is displayed. You can configure the contents of the overlay with the text.* properties.

Default: false

Sets whether an image overlay is displayed. You can configure the display of the overlay with the image.* properties. The image used must be passed in the session_id layout option when the stream or recording is started.

Default: false

Sets whether a title screen (a "slate") is displayed. You can configure the display of the slate with the titleSlate.* properties.

Default: false

Sets whether a title screen (a "slate") is automatically shown at the start of the stream. You can configure the display of this automatic slate with the openingSlate. properties.

Default: false

Group: videoSettings

Limits the number of non-screenshare streams that are included in the output.

Default: 25

Lets you do render-time reordering of video inputs according to participant IDs within a Daily room. To enable this sorting, pass a comma-separated list of participant IDs as the value for this param; video inputs matching these IDs will be moved to the top of the list. If you pass an ID that is not present in the room, it's ignored. All other video inputs will remain in their original order. The default value is an empty string indicating no reordering. Also note that videoSettings.preferScreenshare takes precedence over the ordering passed here. For more information about how participants and videos are sorted, see the section on selecting participants.

Default:

When enabled, screen share inputs will be sorted before camera inputs. This is useful when prioritizing screen shares in your layout, especially when all inputs are not included in the final stream. For more information about how participants and videos are sorted, see the section on selecting participants.

Default: false

When enabled, paused video inputs will not be included. By default this is off, and paused inputs are displayed with a placeholder graphic. ("Paused video" means that the video track for a participant is not available, either due to user action or network conditions.)

Default: false

When enabled, audio-only inputs will not be included in rendering. By default this is off, and audio participants are displayed with a placeholder graphic.

Default: false

When enabled, any screenshare video inputs beyond the first one will not be included in rendering. You can control the ordering of the inputs using the layout.participants property to explicitly select which participant should be first in the list of inputs.

Default: false

Sets whether call participants' names are displayed on their video tiles.

Default: false

Sets whether to display video tiles with squared or rounded corners. Note that some modes (dominant and pip) have additional params to control whether the main video has rounded corners or not.

Default: false

Sets the corner radius applied to video layers when videoSettings.roundedCorners is enabled, in grid units.

Default: 1.2

Controls how source video is displayed inside a tile if they have different aspect ratios. Use 'fill' to crop the video to fill the entire tile. Use 'fit' to make sure the entire video fits inside the tile, adding letterboxes or pillarboxes as necessary.

Default: fill

Controls how a screenshare video is displayed inside a tile if they have different aspect ratios. Use 'fill' to crop the video to fill the entire tile. Use 'fit' to make sure the entire video fits inside the tile, adding letterboxes or pillarboxes as necessary.

Default: fit

Sets the background color for video placeholder tile. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgb(0, 50, 80)

Sets the highlight color. It's used as the border color to indicate the 'dominant' video input (typically the active speaker). Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgb(255, 255, 255)

Sets the stroke width used to render a highlight border. See also 'videoSettings.highlight.color'. Specified in grid units.

Default: 0.2

Sets the visual margin between the two video layers shown in split mode, in grid units.

Default: 0

Selects whether the 'split' layout mode is rendered in a horizontal or vertical configuration. The default value 'auto-by-viewport' means that the split direction will be automatically selected to be most appropriate for the current viewport size: if the viewport is landscape or square, the split axis is vertical; if portrait, the split axis is horizontal. Valid options: 'auto-by-viewport', 'vertical', 'horizontal'

Default: auto-by-viewport

When enabled, the layout will automatically switch to dominant mode from grid if a screenshare video input is available. By using this automatic behavior, you avoid having to manually switch the mode via an API call.

Default: false

Overrides the visual margin between items in grid mode, in grid units. The default value of -1 means that the layout algorithm selects a reasonable margin automatically depending on the number of videos.

Default: -1

Overrides the outer padding around items in grid mode, in grid units. The default value of -1 means that the layout algorithm selects a reasonable padding automatically depending on the number of videos.

Default: -1

By default, the grid mode will highlight the dominant video (typically the "active speaker") with a light outline. You can disable the highlight using this setting.

Default: true

By default, the layout for the grid mode will try to preserve the aspect ratio of the input videos, i.e. avoid cropping the videos and instead add margins around the grid if needed. Setting this parameter to false will make the grid layout fill all available area, potentially cropping the videos.

Default: true

Control where the dominant (or "active speaker") video is displayed in the dominant layout mode. Values are left, right, top or bottom.

Default: left

Sets the position of the imaginary line separating the dominant video from the smaller tiles when using the dominant layout. Values are from 0 to 1. The default is 0.8, so if videoSettings.dominant.position is set to left, the dominant video will take 80% of the width of the screen on the left.

Default: 0.8

Controls how many "chiclets", or smaller video tiles, appear alongside the dominant video when using the dominant layout.

Default: 5

When in dominant mode, the large tile displays the active speaker by default. Turn off this followDomFlag to display the first participant instead of the active speaker.

Default: true

Margin between the “chiclet” items, in grid units.

Default: 0.7

Padding around the row/column of “chiclet” items, in grid units.

Default: 0.5

Margin between the "dominant" video and the row/column of "chiclet" items, in grid units.

Default: 0

Sets whether the "dominant" video will be rendered with rounded corners when videoSettings.roundedCorners is enabled. Defaults to false because sharp corners are a more natural choice for the default configuration where the dominant video is tightly aligned to viewport edges.

Default: true

Sets the position of the smaller video in the pip (picture-in-picture) layout. Valid options: top-left, top-right, bottom-left, bottom-right.

Default: top-right

Sets the aspect ratio of the smaller video in the pip layout. The default is 1.0, which produces a square video.

Default: 1

Sets the height of the smaller video in the pip layout, measured in grid units.

Default: 12

Sets the margin between the smaller video and the edge of the frame in the pip layout, in grid units.

Default: 1.5

When in "pip" (or picture-in-picture) mode, the overlay tile displays the first participant in the participant array by default. Turn on this followDomFlag to display the active speaker instead.

Default: false

Sets whether the main video in pip mode will be rendered with rounded corners when videoSettings.roundedCorners is enabled. Defaults to false because sharp corners are a more natural choice for the default configuration where the main video is full-screen (no margin to viewport edges).

Default: true

Sets the participant label style option: font family. Valid options: Roboto, RobotoCondensed, Bitter, Exo, Magra, SuezOne, Teko

Default: Roboto

Sets the participant label text font weight. Valid options: 100, 200, 300, 400, 500, 600, 700, 800, 900.

Note: Not all font weights are valid for every font family.

Default: 600

Sets the participant label text font size.

Default: 100

Sets the offset value for participant labels on the x-axis, measured in grid units.

Default: 0

Sets the offset value for participant labels on the y-axis, measured in grid units.

Default: 0

Sets the participant label font color. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: white

Sets the label font stroke color (the line outlining the text letters). Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(0, 0, 0, 0.9)

Sets the left margin value applied to videos (in any layout mode), in grid units. You can use these videoSettings.margin.* params to shrink the video area, for example to make room for overlays.

Default: 0

Sets the right margin value applied to videos (in any layout mode), in grid units. You can use these videoSettings.margin.* params to shrink the video area, for example to make room for overlays.

Default: 0

Sets the top margin value applied to videos (in any layout mode), in grid units. You can use these videoSettings.margin.* params to shrink the video area, for example to make room for overlays.

Default: 0

Sets the bottom margin value applied to videos (in any layout mode), in grid units. You can use these videoSettings.margin.* params to shrink the video area, for example to make room for overlays.

Default: 0

Group: text

Sets the string to be displayed if showTextOverlay is true.

Default:

Sets the horizontal alignment of the text overlay within the video frame. Values are left, right, or center.

Default: center

Sets the vertical alignment of the text overlay within the video frame. Values are top, bottom, or center.

Default: center

Sets an x-offset (horizontal) to be applied to the text overlay's position based on the values of text.align_horizontal and text.align_vertical.

Default: 0

Sets a y-offset (vertical) to be applied to the text overlay's position based on the values of text.align_horizontal and text.align_vertical.

Default: 0

Applies a rotation to the text overlay. Units are degrees, and positive is a clockwise rotation.

Default: 0

Sets the font of the text overlay. Valid options: Roboto, RobotoCondensed, Anton, Bangers, Bitter, Exo, Magra, PermanentMarker, SuezOne, Teko

Default: Roboto

Selects a weight variant from the selected font family. Valid options: 100, 200, 300, 400, 500, 600, 700, 800, 900.

Note: Not all font weights are valid for every font family.

Default: 500

Sets the font style for text. Valid options: 'normal','italic'.

Default:

Sets the text overlay font size using grid units (gu). By default, one grid unit is 1/36 of the smaller dimension of the viewport (e.g. 20px in a 1280*720 stream).

Default: 2.5

Sets the color and transparency of the text overlay. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(255, 250, 200, 0.95)

Sets the color of the stroke drawn around the characters in the text overlay. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(0, 0, 0, 0.8)

Group: image

Sets the overlay image. Icon asset must be included in session_assets object. showImageOverlay must be true.

Default: overlay.png

Sets position of overlay image. Valid options: top-left, top-right, bottom-left, bottom-right

Default: top-right

Sets overlay image to full screen.

Default: false

Sets aspect ratio of overlay image.

Default: 1.778

Sets height of overlay image, in grid units.

Default: 12

Sets margin between the overlay image and the viewport edge, in grid units.

Default: 1.5

Sets opacity of overlay image, in range 0-1. Default value of 1 is full opacity.

Default: 1

Sets the overlay image to fade in or out when the showImageOverlay property is updated.

Default: true

Group: toast

number

Triggers display of toast component. To send a toast, increment the value of key

Default: 0

Sets text displayed in toast component.

Default: Hello world

Sets duration of time toast component is displayed (in seconds).

Default: 4

Sets number of lines text in toast component is displayed on.

Default: 2

Sets whether icon is displayed in toast component (true or false).

Default: true

Sets asset value for toast icon. Icon asset must be included in session_assets object.

Default:

Sets the toast component's background color. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(15, 50, 110, 0.6)

Sets the color of the stroke drawn around the text characters in the toast component. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(0, 0, 30, 0.44)

Sets the toast component's text color. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: white

Sets the toast component's font family. Valid options: Roboto, RobotoCondensed, Bitter, Exo, Magra, SuezOne, Teko

Default: Roboto

Sets the font weight for the toast component's text. Valid options: 100, 200, 300, 400, 500, 600, 700, 800, 900.

Note: Not all font weights are valid for every font family.

Default: 500

Sets the font size for the toast component's text.

Default: 100

Group: openingSlate

Sets the number of seconds that the opening slate will be displayed when the stream starts. After this time, the slate goes away with a fade-out effect.

Default: 4

Sets text displayed in the main title of the opening slate.

Default: Welcome

Sets text displayed in the subtitle (second line) of the opening slate.

Default:

Sets an image to be used as the background for the slate. This image asset must be included in session_assets object when starting the stream/recording.

Default:

Sets the slate's background color. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(0, 0, 0, 1)

Sets the text color of the titles in the slate. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(255, 255, 255, 1)

Sets the font of the titles in the slate. Valid options: Roboto, RobotoCondensed, Anton, Bangers, Bitter, Exo, Magra, PermanentMarker, SuezOne, Teko

Default: Bitter

Selects a weight variant from the selected font family. Valid options: 100, 200, 300, 400, 500, 600, 700, 800, 900.

Note: Not all font weights are valid for every font family.

Default: 500

Sets the font style for the titles in the slate. Valid options: 'normal','italic'.

Default:

Sets the main title font size using grid units (gu). By default, one grid unit is 1/36 of the smaller dimension of the viewport (e.g. 20px in a 1280*720 stream).

Default: 2.5

Sets the subtitle font size as a percentage of the main title.

Default: 75

Selects a weight variant from the selected font family specifically for the subtitle. Valid options: 100, 200, 300, 400, 500, 600, 700, 800, 900.

Note: Not all font weights are valid for every font family.

Default: 400

Group: titleSlate

Sets text displayed in the main title of the slate.

Default: Title slate

Sets text displayed in the subtitle (second line) of the slate.

Default: Subtitle

Sets an image to be used as the background for the slate. This image asset must be included in session_assets object when starting the stream/recording.

Default:

Sets the slate's background color. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(0, 0, 0, 1)

Sets the text color of the titles in the slate. Valid options:

  • Hex color codes

  • RGB or RGBA syntax

  • Standard CSS color names (e.g. 'blue')

Default: rgba(255, 255, 255, 1)

Sets the font of the titles in the slate. Valid options: Roboto, RobotoCondensed, Anton, Bangers, Bitter, Exo, Magra, PermanentMarker, SuezOne, Teko

Default: Bitter

Selects a weight variant from the selected font family. Valid options: 100, 200, 300, 400, 500, 600, 700, 800, 900.

Note: Not all font weights are valid for every font family.

Default: 500

Sets the font style for the titles in the slate. Valid options: 'normal','italic'.

Default:

Sets the main title font size using grid units (gu). By default, one grid unit is 1/36 of the smaller dimension of the viewport (e.g. 20px in a 1280*720 stream).

Default: 2.5

Sets the subtitle font size as a percentage of the main title.

Default: 75

Selects a weight variant from the selected font family specifically for the subtitle. Valid options: 100, 200, 300, 400, 500, 600, 700, 800, 900.

Note: Not all font weights are valid for every font family.

Default: 400

Selecting participants

The baseline composition has several modes that display multiple participant videos. You may be wondering how to control which participants appear in specific places within those layouts.

Internally, VCS uses an ordered array of video inputs that it calls "video input slots". By default, that array will contain all participants in the order in which they joined the call. But there are two ways you can override this default behavior and choose which participants appear in your layout:

  1. Participant selection on the room level using the participants property.
  2. Input reordering on the composition level (a.k.a. switching) using the preferredParticipantIds and preferScreenshare params available in the baseline composition.

These two are not mutually exclusive. What's the difference, and when should you use one or the other?

Room-level participant selection is a powerful generic tool. It lets you choose any participants within the room, and will trigger any necessary backend connections so that a participant's audio and video streams become available to the VCS rendering server. This means there may be a slight delay as connections are made.

In contrast, composition-level input reordering (a.k.a. switching) happens at the very last moment in the VCS engine just before a video frame is rendered. (The name "switching" refers to a video switcher, a hardware device used in traditional video production for this kind of input control.) It's applied together with any other composition param updates you're sending, so there is a guarantee of synchronization. You should use this method when you want to ensure that the reordering of inputs happens precisely at the same time as your update to some other composition param value(s). For example, if you're switching a layout mode and want the inputs to be sorted in a different way simultaneously.

You can use the two methods together. Room-level selection using the participants property lets you establish the participants whose streams will be available to the rendering. You can then do rapid switching within that selection using the preferredParticipantIds and preferScreenshare params in the baseline composition.

Here's an example of selecting three specific participant video tracks, everyone's audio tracks, and sorting the video by most recent active speaker:

Here's another example where we're further sorting the same video tracks using the baseline composition params. The params update is switching to a different layout mode ('split'). This mode can only show two participants, so we use videoSettings.preferredParticipantIds to select the two participants in a clean frame-synchronized way, without having to modify the underlying connections made via the participants property:

If you include the participants object in a startLiveStreaming()/startRecording() or updateLiveStreaming()/updateRecording() call, you need to include it in any subsequent updateLiveStreaming()/updateRecording() calls as well, even if you aren't changing it.

If you set the participants property for your recording or live stream and then make an updateLiveStreaming()/updateRecording() call to update the composition_params, you'll need to resend the same values you used before in the participants property. This is true even if you are not updating the participants property. If you don't, the participant configuration will reset to default, as if you hadn't set it in the first place —meaning VCS will receive all audio and video tracks from all participants, sorted by the order in which the participants joined the call.

participants properties

array

Required. An array of strings indicating which participant videos to make available to VCS. Possible values are:

  • ["participant-guid-1", "participant-guid-2", "participant-guid-3"]: A list of specific participant IDs

  • ["*"]: everyone

  • ["owners"]: All call owners

array

An optional array of strings indicating which participant audio tracks to make available to VCS. Possible values are the same as the video property.

string

The only currently valid value for this property is "active". This property controls the order in which VCS sees the participant video tracks. When set to "active", each time the call's active speaker changes to a different participant, that participant will bubble up to the first position in the array. In other words, setting sort to "active" will cause an n-tile layout to always show the n most recent speakers in the call. If you leave the property unset, the list of participants will stay in a fixed order: either the order you specified in the video property, or in the order they joined the call if you use "*" or "owners".

Session assets

Session assets — images or custom VCS components — that can be passed as assets and used during a live stream or cloud recording. To learn more, visit our Session assets page in the VCS SDK reference docs.

Note: Session assets must be made available at the beginning of the recording or live stream even if they are not used until later in the call.

Default values

Composition parameter defaults