Realtime SDK migration from v1 to v2

Overview of how to migrate your applications from realtime SDK v1.x to v2

In version 2 of our SDKs, we've minimized breaking changes. This major release focuses on:

  • Streamlining APIs to reduce confusion and improve naming consistency.
  • Updated APIs to accept a participant's identity instead of their SID, offering a more intuitive experience as identities are application-provided.
  • Enabling the coexistence of multiple libraries dependent on libwebrtc with LiveKit native SDKs.

Breaking changes across SDKs

This section outlines changes applicable to all realtime SDKs.

room.participants -> room.remoteParticipants

In v2, we've updated the participants map on the room object, with key changes to note:

  • Clarification: localParticipant has always been excluded from this map, so the term participants was previously misleading.
  • Map key change: Instead of using the participant's SID as the map key, we now use their identity.
// legacy v1: in v1 participants were stored in a map with keys representing their SID. This led to unnecessary complications e.g. when trying to filter for a list of identities
const alice = room.participants.get('PA_8sMkEu4vhz4v');
// new in v2: you can now use a participant's identity (encoded in the token) to directly access it from the remoteParticipants map
const alice = room.remoteParticipants.get('alice');

track -> trackPublication

In version 1, our realtime SDKs used the term track ambiguously, referring to both TrackPublication and Track. In version 2, we've simplified this terminology: now, all API references to publications explicitly use trackPublications. For instance,

  • participant.tracks -> participant.trackPublications
  • participant.getTrack -> participant.getTrackPublication
  • participant.videoTracks -> participant.videoTrackPublications
// v1
const cameraPublication = room.localParticipant.getTrack(Track.Source.Camera);
// v2
const cameraPublication = room.localParticipant.getTrackPublication(Track.Source.Camera);

Updated publishData API

We've streamlined the publishData API in v2, reducing its arguments to:

  1. The payload (data being sent)
  2. A DataPublishOptions object for advanced features

DataPublishOptions now allows you to:

  • specify a list of recipient participants using their identities
  • set a topic
  • choose if the data should be delivered reliably (slower, with retries) or not (faster)

In our effort to remove server identities from user facing APIs, we've removed the need to specify participant SIDs for recipients. In v2, simply use participant identities, which are stable across reconnects.

// v1
localParticipant.publishData(data, DataPacketKind.Reliable, ["participant-sid"]);
// v2
localParticipant.publishData(data, { reliable: true, destinationIdentities: ["participant-identity"]});

Async room SID

In order to speed up the initial connection, the room SID may not be immediately available upon connection. It's instead received later (typically within 300ms). To handle this, getting the room SID is done asynchronously in v2.

await room.getSid();

Removed VideoQuality.OFF from VideoQuality enum

In v2 we've removed the OFF option on the VideoQuality enum. Previously, setting OFF via the setQuality APIs had no effect and was confusing to users.

// v1
// v2 VideoQuality.OFF is no longer available

Platform specific changes


Removal of previously deprecated APIs

  • LiveKit.connect - Please use LiveKit.create and Room.connect instead.
  • Room.listener - Please use instead.
  • Participant.listener - Please use instead.

Renaming of org.webrtc package to

We've renamed our internal org.webrtc package to to prevent conflicts with other WebRTC implementations. If your code references this package, update your import as follows:

// v1
import org.webrtc.*
// v2

Moved composables into a separate package

Composables, including VideoRenderer have been moved into a separate package, components-android. Previously the SDK depended on Jetpack Compose, causing View-based apps to depend on an unnecessary package. By moving these components to a separate package, only Compose-based apps will need to depend on it.

To migrate, add in your build.gradle:

dependencies {
implementation "io.livekit:livekit-android-compose-components:1.0.0"

The VideoRenderer composable has also been renamed to VideoTrackView to maintain parity with other platforms.

Participant.Sid and Identity inline value classes

To avoid confusion between participant sid and identity which shared the String type, we've added the Participant.Sid and Participant.Identity inline value classes. This will prevent inadvertantly using one in place of the other.


Removal of previously deprecated APIs

  • LiveKitClient.connect - Please use var room = Room(...) and room.connect instead.
  • track in TrackMutedEvent/TrackUnmutedEvent - Use publication instead
  • TrackStreamStateUpdatedEvent.trackPublication - Use TrackStreamStateUpdatedEvent.publication instead
  • RemotePublication.videoQuality - Use RemotePublication.setVideoQuality(quality) instead
  • RemotePublication.subscribed - Use RemotePublication.subscribe() or unsubscribe() instead
  • RemotePublication.enabled - Use RemotePublication.enable() or disable() instead
  • Participant.unpublishTrack - Use Participant.removePublishedTrack instead
  • Removed AudioPublishOptions.stopMicTrackOnMute


webAudioMix is enabled by default and no longer experimental

For this release, we're removing the experimental notion of the expWebAudioMix room option, and because it has significant end-user benefits, we're making webAudioMix: true the default.

If you've previously relied on setting the volumes of HTMLAudioElements directly, rather than using one of the SDK's setVolume methods, you'll need to either set webAudioMix: false explicitly or start using the setVolume methods that exist on both RemoteParticipant and RemoteAudioTrack (recommended).

Removal of previously deprecated APIs

  • RoomConnectOptions.publishOnly - The publishOnly mode has been deprecated even before v1.0, finally removing those bits in the code
  • RoomState - Use ConnectionState instead
  • RoomEvent.StateChanged - Use RoomEvent.ConnectionStateChanged instead
  • TrackPublishOptions.audioBitrate - Use TrackPublishOptions.audioPreset instead
  • room.getActiveAudioOutputDevice() - Use room.getActiveDevice('audiooutput') instead


Swift concurrency support

Swift SDK v2 has migrated to Swift Concurrency(async/await) from Google Promises.

Renamed APIs

  • WebRTC types such as RTCVideoFrame are now not exported by the SDK, use new types defined by the SDK(VideoFrame etc) instead.
  • LocalParticipant.publish(track:publishOptions:) has been renamed to LocalParticipant.publish(track:options:).
  • RoomDelegate and ParticipantDelegate signatures have been renamed. Xcode compiler will fail and suggest a rename if any of the previous delegates are used.
  • Legacy statistics (TrackStats) has been repalced with TrackStatistics.


CreateRoom -> NewRoom

The CreateRoom function has been renamed to NewRoom to disambiguate it from the RoomService.CreateRoom API in the server SDK.