Library evolution support (xcframework) (#816)

pblazej · web-flow · commit 92e223173128 · 2025-10-16T08:07:17.000+02:00
Resolves #731 Resolves #790 Fixes the library evolution build failure by replacing protocols with `Self` requirements (which cannot form a stable ABI) with protocol composition typealiases that provide a concrete existential type the compiler can support. Protocols with `Self` or associated type requirements cannot form a stable ABI because the compiler cannot create a generic, fixed-size storage container (an "existential") for them, as the concrete size and layout of the conforming type are unknown at the API boundary, making forward-compatible memory management and function dispatch impossible. This is a breaking change ⚠️ for anyone e.g. extending the current hierarchy: ```swift extension VideoTrack // vs extension VideoTrackProtocol where Self: Track ``` This should NOT be a breaking change for just consuming concrete types returned e.g. from factory methods in the SDK.
diff --git a/.changes/xcframework b/.changes/xcframework
@@ -0,0 +1 @@
+minor type="fixed" "Breaking change: Library evolution support (xcframework). May break existing `*Track` extensions."
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -151,6 +151,7 @@ jobs:
             -scheme LiveKit \
             -configuration Release \
             -destination 'platform=${{ matrix.platform }}'  \
+            BUILD_LIBRARY_FOR_DISTRIBUTION=YES \
             OTHER_SWIFT_FLAGS="-Xfrontend -emit-symbol-graph\
                                -Xfrontend -emit-symbol-graph-dir\
                                -Xfrontend \"${PWD}/symbol-graph\"" \
diff --git a/Sources/LiveKit/Broadcast/BroadcastScreenCapturer.swift b/Sources/LiveKit/Broadcast/BroadcastScreenCapturer.swift
@@ -97,7 +97,7 @@ class BroadcastScreenCapturer: BufferCapturer, @unchecked Sendable {
 public extension LocalVideoTrack {
     /// Creates a track that captures screen capture from a broadcast upload extension
     static func createBroadcastScreenCapturerTrack(name: String = Track.screenShareVideoName,
-                                                   source: VideoTrack.Source = .screenShareVideo,
+                                                   source: Track.Source = .screenShareVideo,
                                                    options: ScreenShareCaptureOptions = ScreenShareCaptureOptions(),
                                                    reportStatistics: Bool = false) -> LocalVideoTrack
     {
diff --git a/Sources/LiveKit/Core/Room.swift b/Sources/LiveKit/Core/Room.swift
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import Combine
 import Foundation
 
 #if canImport(Network)
diff --git a/Sources/LiveKit/E2EE/E2EEManager.swift b/Sources/LiveKit/E2EE/E2EEManager.swift
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import Combine
 import Foundation
 
 internal import LiveKitWebRTC
diff --git a/Sources/LiveKit/Extensions/Sendable.swift b/Sources/LiveKit/Extensions/Sendable.swift
@@ -53,3 +53,9 @@ extension NSMapTable: @unchecked Swift.Sendable {} // cannot specify Obj-C gener
 #if swift(<6.2)
 extension Dictionary: Swift.Sendable where Key: Sendable, Value: Sendable {}
 #endif
+
+// MARK: AV
+
+extension AVCaptureDevice: @unchecked Swift.Sendable {}
+extension AVCaptureDevice.Format: @unchecked Swift.Sendable {}
+extension CVPixelBuffer: @unchecked Swift.Sendable {}
diff --git a/Sources/LiveKit/Participant/Participant.swift b/Sources/LiveKit/Participant/Participant.swift
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import Combine
 import Foundation
 
 internal import LiveKitWebRTC
diff --git a/Sources/LiveKit/SwiftUI/TrackDelegateObserver.swift b/Sources/LiveKit/SwiftUI/TrackDelegateObserver.swift
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import Combine
 import Foundation
 
 /// Helper class to observer ``TrackDelegate`` from Swift UI.
diff --git a/Sources/LiveKit/Track/AudioTrack.swift b/Sources/LiveKit/Track/AudioTrack.swift
@@ -17,10 +17,12 @@
 import Foundation
 
 @objc
-public protocol AudioTrack where Self: Track {
+public protocol AudioTrackProtocol: AnyObject, Sendable {
     @objc(addAudioRenderer:)
     func add(audioRenderer: AudioRenderer)
 
     @objc(removeAudioRenderer:)
     func remove(audioRenderer: AudioRenderer)
 }
+
+public typealias AudioTrack = AudioTrackProtocol & Track
diff --git a/Sources/LiveKit/Track/Capturers/ARCameraCapturer.swift b/Sources/LiveKit/Track/Capturers/ARCameraCapturer.swift
@@ -94,7 +94,7 @@ public class ARCameraCapturer: VideoCapturer {
 public extension LocalVideoTrack {
     /// Creates a track that can directly capture `CVPixelBuffer` or `CMSampleBuffer` for convenience
     static func createARCameraTrack(name: String = Track.cameraName,
-                                    source: VideoTrack.Source = .camera,
+                                    source: Track.Source = .camera,
                                     options: ARCameraCaptureOptions = ARCameraCaptureOptions(),
                                     reportStatistics: Bool = false) -> LocalVideoTrack
     {
diff --git a/Sources/LiveKit/Track/Capturers/BufferCapturer.swift b/Sources/LiveKit/Track/Capturers/BufferCapturer.swift
@@ -59,7 +59,7 @@ public class BufferCapturer: VideoCapturer, @unchecked Sendable {
 public extension LocalVideoTrack {
     /// Creates a track that can directly capture `CVPixelBuffer` or `CMSampleBuffer` for convienience
     static func createBufferTrack(name: String = Track.screenShareVideoName,
-                                  source: VideoTrack.Source = .screenShareVideo,
+                                  source: Track.Source = .screenShareVideo,
                                   options: BufferCaptureOptions = BufferCaptureOptions(),
                                   reportStatistics: Bool = false) -> LocalVideoTrack
     {
diff --git a/Sources/LiveKit/Track/Local/LocalAudioTrack.swift b/Sources/LiveKit/Track/Local/LocalAudioTrack.swift
@@ -21,7 +21,7 @@ import Foundation
 internal import LiveKitWebRTC
 
 @objc
-public class LocalAudioTrack: Track, LocalTrack, AudioTrack, @unchecked Sendable {
+public class LocalAudioTrack: Track, LocalTrackProtocol, AudioTrackProtocol, @unchecked Sendable {
     /// ``AudioCaptureOptions`` used to create this track.
     public let captureOptions: AudioCaptureOptions
 
diff --git a/Sources/LiveKit/Track/Local/LocalTrack.swift b/Sources/LiveKit/Track/Local/LocalTrack.swift
@@ -17,16 +17,18 @@
 import Foundation
 
 @objc
-public protocol LocalTrack where Self: Track {
+public protocol LocalTrackProtocol: AnyObject, Sendable {
     @objc
     var publishOptions: TrackPublishOptions? { get }
 
     @objc
-    var publishState: PublishState { get }
+    var publishState: Track.PublishState { get }
 
     @objc
     func mute() async throws
 
     @objc
     func unmute() async throws
 }
+
+public typealias LocalTrack = LocalTrackProtocol & Track
diff --git a/Sources/LiveKit/Track/Local/LocalVideoTrack.swift b/Sources/LiveKit/Track/Local/LocalVideoTrack.swift
@@ -19,7 +19,7 @@ import Foundation
 internal import LiveKitWebRTC
 
 @objc
-public class LocalVideoTrack: Track, LocalTrack, @unchecked Sendable {
+public class LocalVideoTrack: Track, LocalTrackProtocol, @unchecked Sendable {
     @objc
     public internal(set) var capturer: VideoCapturer
 
@@ -65,7 +65,7 @@ public class LocalVideoTrack: Track, LocalTrack, @unchecked Sendable {
 
 // MARK: - VideoTrack Protocol
 
-extension LocalVideoTrack: VideoTrack {
+extension LocalVideoTrack: VideoTrackProtocol {
     public func add(videoRenderer: VideoRenderer) {
         capturer.rendererDelegates.add(delegate: videoRenderer)
     }
diff --git a/Sources/LiveKit/Track/Remote/RemoteAudioTrack.swift b/Sources/LiveKit/Track/Remote/RemoteAudioTrack.swift
@@ -20,7 +20,7 @@ import CoreMedia
 internal import LiveKitWebRTC
 
 @objc
-public class RemoteAudioTrack: Track, RemoteTrack, AudioTrack, @unchecked Sendable {
+public class RemoteAudioTrack: Track, RemoteTrackProtocol, AudioTrackProtocol, @unchecked Sendable {
     /// Volume with range 0.0 - 1.0
     public var volume: Double {
         get {
diff --git a/Sources/LiveKit/Track/Remote/RemoteTrack.swift b/Sources/LiveKit/Track/Remote/RemoteTrack.swift
@@ -17,4 +17,6 @@
 import Foundation
 
 @objc
-public protocol RemoteTrack where Self: Track {}
+public protocol RemoteTrackProtocol: AnyObject, Sendable {}
+
+public typealias RemoteTrack = RemoteTrackProtocol & Track
diff --git a/Sources/LiveKit/Track/Remote/RemoteVideoTrack.swift b/Sources/LiveKit/Track/Remote/RemoteVideoTrack.swift
@@ -17,7 +17,7 @@
 internal import LiveKitWebRTC
 
 @objc
-public class RemoteVideoTrack: Track, RemoteTrack, @unchecked Sendable {
+public class RemoteVideoTrack: Track, RemoteTrackProtocol, @unchecked Sendable {
     init(name: String,
          source: Track.Source,
          track: LKRTCMediaStreamTrack,
@@ -33,7 +33,7 @@ public class RemoteVideoTrack: Track, RemoteTrack, @unchecked Sendable {
 
 // MARK: - VideoTrack Protocol
 
-extension RemoteVideoTrack: VideoTrack {
+extension RemoteVideoTrack: VideoTrackProtocol {
     public func add(videoRenderer: VideoRenderer) {
         guard let rtcVideoTrack = mediaTrack as? LKRTCVideoTrack else {
             log("mediaTrack is not a RTCVideoTrack", .error)
diff --git a/Sources/LiveKit/Track/VideoTrack.swift b/Sources/LiveKit/Track/VideoTrack.swift
@@ -19,22 +19,24 @@ import Foundation
 internal import LiveKitWebRTC
 
 @objc
-public protocol VideoTrack where Self: Track {
+public protocol VideoTrackProtocol: AnyObject, Sendable {
     @objc(addVideoRenderer:)
     func add(videoRenderer: VideoRenderer)
 
     @objc(removeVideoRenderer:)
     func remove(videoRenderer: VideoRenderer)
 }
 
+public typealias VideoTrack = Track & VideoTrackProtocol
+
 // Directly add/remove renderers for better performance
 protocol VideoTrack_Internal where Self: Track {
     func add(rtcVideoRenderer: LKRTCVideoRenderer)
 
     func remove(rtcVideoRenderer: LKRTCVideoRenderer)
 }
 
-extension VideoTrack {
+extension VideoTrackProtocol where Self: Track {
     // Update a single SubscribedCodec
     func _set(subscribedCodec: Livekit_SubscribedCodec) throws -> Bool {
         guard let videoCodec = VideoCodec.from(name: subscribedCodec.codec) else { return false }
diff --git a/Sources/LiveKit/TrackPublications/TrackPublication.swift b/Sources/LiveKit/TrackPublications/TrackPublication.swift
@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import Combine
 import Foundation
 
 @objc
diff --git a/Sources/LiveKit/VideoProcessors/BackgroundBlurVideoProcessor.swift b/Sources/LiveKit/VideoProcessors/BackgroundBlurVideoProcessor.swift
@@ -171,5 +171,3 @@ public final class BackgroundBlurVideoProcessor: NSObject, @unchecked Sendable,
         return cachedPixelBuffer
     }
 }
-
-extension CVPixelBuffer: @unchecked Swift.Sendable {}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+minor type="fixed" "Breaking change: Library evolution support (xcframework). May break existing `*Track` extensions."
Original file line number	Diff line number	Diff line change
`@@ -97,7 +97,7 @@ class BroadcastScreenCapturer: BufferCapturer, @unchecked Sendable {`
`97`	`97`	`public extension LocalVideoTrack {`
`98`	`98`	`/// Creates a track that captures screen capture from a broadcast upload extension`
`99`	`99`	`static func createBroadcastScreenCapturerTrack(name: String = Track.screenShareVideoName,`
`100`		`- source: VideoTrack.Source = .screenShareVideo,`
	`100`	`+ source: Track.Source = .screenShareVideo,`
`101`	`101`	`options: ScreenShareCaptureOptions = ScreenShareCaptureOptions(),`
`102`	`102`	`reportStatistics: Bool = false) -> LocalVideoTrack`
`103`	`103`	`{`
Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,7 @@ public class ARCameraCapturer: VideoCapturer {`
`94`	`94`	`public extension LocalVideoTrack {`
`95`	`95`	/// Creates a track that can directly capture `CVPixelBuffer` or `CMSampleBuffer` for convenience
`96`	`96`	`static func createARCameraTrack(name: String = Track.cameraName,`
`97`		`- source: VideoTrack.Source = .camera,`
	`97`	`+ source: Track.Source = .camera,`
`98`	`98`	`options: ARCameraCaptureOptions = ARCameraCaptureOptions(),`
`99`	`99`	`reportStatistics: Bool = false) -> LocalVideoTrack`
`100`	`100`	`{`