Playout delay hints | LiveKit Documentation

Overview

Playout delay is a room-level setting that controls how subscribers buffer video before playback. It applies to all subscribers in the room and sets the trade-off between low latency and smooth playback.

Value selection

Each subscriber buffers incoming video for a short time before playback. A large buffer absorbs network jitter and packet loss. Playback is smooth, but the delay is higher and the first frame appears later. A small buffer shows video sooner, but playback can become choppy on a bad network.

You set a minimum and a maximum delay in milliseconds for the room. Every subscriber in the room then buffers video within this range. A value of 0 means "not set." When both values are 0, playout delay is off. Each subscriber then uses the default buffer behavior of its platform. This default gives smooth, synchronized playback. When you set only the minimum, a maximum of 10,000 ms applies.

For most robotics apps, use the recommended low-latency values below.

Get the lowest latency

Consider zero jitter buffer mode

For the lowest possible latency, subscribers using supported SDKs can use zero jitter buffer mode instead of setting playout delay hints. Zero jitter buffer mode is equivalent to setting both the minimum and maximum playout delay to 0 ms, which isn't supported when using playout delay hints.

For teleoperation and remote vision inference, late video is worse than choppy video. An operator must see what the robot sees now, and a model must run inference on current frames. A low playout delay shows each frame as soon as it arrives. Video also appears quickly after a subscription starts.

Values: minimum 0 ms, maximum 10 ms.

Get smooth playback

In a video conference or a one-way broadcast, viewers accept a small delay but notice each stutter. Set a higher minimum. The extra buffer gives lost packets time to arrive again before their frame is due. Playback stays smooth on a bad network.

Values: minimum 400 ms, maximum 2,000 ms.

Let the network decide

A wide range gives the choice to each subscriber. Playback stays near the minimum on a good network. When the network becomes worse, the buffer grows.

Values: minimum 0 ms, maximum 2,000 ms.

Apply to room

With a minimum and maximum selected, apply the values to the room when it is created.

Explicit room creation

If your app explicitly creates rooms using the LiveKit CLI or server SDKs, specify playout delay hints in options:

lk room create \
   --name my-robot \
   --min-playout-delay 0 \
   --max-playout-delay 10

use livekit_api::services::room::CreateRoomOptions;

let room = api.room().create_room_with_playout_delay(
    "my-robot",
    CreateRoomOptions::default(),
    0,   // min
    10, // max
).await?;

room, err := api.Room().CreateRoom(context.Background(), &livekit.CreateRoomRequest{
  Name:            "my-robot",
  MinPlayoutDelay: 0,
  MaxPlayoutDelay: 10,
})

from livekit.api import CreateRoomRequest

room = await lkapi.room.create_room(CreateRoomRequest(
  name="my-robot",
  min_playout_delay=0,
  max_playout_delay=10,
))

const room = await api.room.createRoom({
  name: 'my-robot',
  minPlayoutDelay: 0,
  maxPlayoutDelay: 10,
});

Rooms created on join

If your app doesn't create rooms explicitly, LiveKit creates the room when the first participant joins. To set playout delay hints for these rooms, include a room configuration in the participant's access token. The RoomConfiguration object accepts the same minimum and maximum playout delay fields as explicit room creation.

The configuration in a token applies only when the room is first created. If the room already exists, LiveKit ignores it. Playout delay hints from participants who join later have no effect.

Trade-offs and limitations

Playout delay lets you trade playback smoothness and synchronization for lower latency. Keep the following trade-offs and limitations in mind when configuring it.

Applies to the full room

The values apply to all subscribers in the room. You can't set different values for one subscriber.

Audio and video synchronization

A subscriber can't deliver fast video and synchronized audio at the same time. When you set a low playout delay, a subscriber shows video as soon as it arrives. The subscriber doesn't hold the video to match the audio. Lip-sync can drift. If exact synchronization is more important than speed, don't set playout delay.

A low maximum limits recovery

A subscriber doesn't buffer more than the maximum, even on a bad network. If your users often have a bad network, set a low minimum and a high maximum.

Video only

These values apply only to video. Audio buffering is automatic and doesn't change.

Hints, not guarantees

Each platform applies the values within its own limits. The values apply in steps of 10 ms, rounded down: a value of 15 ms becomes 10 ms. Playback adapts within your range as network conditions change.