Real-time SDK migration from v1 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.

This section outlines changes applicable to all real-time SDKs.

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');

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);

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"]});

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();

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)

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

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.*

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.

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.

• 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

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).

• 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 SDK v2 has migrated to Swift Concurrency(async/await) from Google Promises.

• 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.

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