Real-time SDK migration from v1 to v2

Overview of how to migrate your applications from real-time 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 real-time 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 real-time 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.

//v1
room.sid
//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
remotePublication.setQuality(VideoQuality.HIGH)
// v2 VideoQuality.OFF is no longer available
remotePublication.setQuality(VideoQuality.HIGH)

Platform specific changes

Android

Removal of previously deprecated APIs

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

Renaming of org.webrtc package to livekit.org.webrtc

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

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

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.

Flutter

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

Javascript/Typescript

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

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.

Go

CreateRoom -> NewRoom

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

Removal of APIs

  • LocalParticipant.PublishDataPacket - Use LocalParticipant.PublishData instead.