This documentation is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2026.
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.
This guide provides an introduction to the 3.x Programmable Video iOS SDK and a set of guidelines to migrate an application from 2.x to 3.x.
Programming Model
The programming model has not changed from 2.x to 3.x. Refer to our 2.x migration guide for a refresher on the Video iOS SDK models.
Xcode and iOS Version Support
Twilio Video 3.x is built with Xcode 11 and officially adds support for iOS 13 and iPadOS 13 APIs. The framework can be consumed with previous versions of Xcode. However, re-compiling Bitcode when exporting for Ad Hoc or Enterprise distribution requires the use of Xcode 11.x. 3.0 also removes support for iOS 9 and iOS 10, and raises the minimum supported iOS version to 11.0.
If your application's Deployment Target was previously set to iOS 10.3 or earlier, you will need to update it to 11.0 or greater to use the 3.x SDK.
Region Selection
The SDK uses a new WebSocket based signaling transport, and communicates with globally available signaling Servers over IPv4 and IPv6 networks. The TVIConnectOptions.region property has been added which allows you to specify the region of the signaling server. By default, the Client will connect to the nearest signaling Server determined by latency based routing. Setting a value other than "gll" bypasses routing and guarantees that signaling traffic will be terminated in the region that you prefer.
_10
let connectOptions = ConnectOptions(token: accessToken) { (builder) in
If you were previously allowing traffic to signaling servers by IP address you will now need to allow the FQDN for the region that you are connecting to instead. See the Signaling Communication section of the Video IP Addresses guide for more information.
Access Tokens
With this new WebSocket based signaling transport, some modifications may need to be made to the Access Tokens that you generate. Specifically:
Ensure that the AccessToken does not contain a configuration profile sid. Configuration profiles were previously deprecated and are no longer supported.
Set the Time-To-Live (TTL) of your AccessToken to the maximum allowed session duration, currently 14400 seconds (4 hours). This ensures that when a network loss occurs the client will be able to re-authenticate the reconnection. Note, a reconnection attempt with an expired AccessToken will result in an
AccessTokenExpiredError
.
TVICameraSource Orientation Tracking Changes
With support for iOS 13, we now have the ability to monitor UIWindowScene based notifications, for determining the orientation of the camera for capture and preview. The TVICameraSourceOrientationTracker protocol has been added and TVICameraSourceOptionsBuilder has a new property, orientationTracker which allows you to adopt this method of tracking.
To opt into tracking based on the rotation of a UIWindowScene you must provide the scene to track when creating the TVICameraSourceOptions.
_10
// Track the orientation of the key window's scene.
_10
let options = CameraSourceOptions { (builder) in
_10
if let keyScene = UIApplication.shared.keyWindow?.windowScene {
The TVIAudioSessionActivated() and TVIAudioSessionDeactivated() methods have been removed as the Video SDK no longer needs to terminate the signaling connection when an application is backgrounded.
The TVIVideoRenderer.optionalPixelFormats property has been removed. TVIVideoRenderer is expected to deal with video in any of the valid TVIPixelFormats. If the renderer cannot handle a frame it should drop that frame. There will be no more automatic conversion to I420 for renderers that do not support a particular format.
Improved Objective-C API
In 3.x we have refactored the TVILocalParticipantDelegate and TVIRemoteParticipantDelegate methods to be consistent with the did naming convention used in the Swift APIs. Listed below are the changes to the Objective-C APIs:
In 3.x we have revisited the way the Programmable Video iOS SDK is exposed in Swift to make developing Swift applications more idiomatic. Numerous changes were made across the entire surface area of the SDK which will require modifications in your current project. Among the high level changes:
The
TVI
prefix has been removed from all exposed types.
Many of the delegate and class function declarations have been renamed to provide better clarity of their intent.
The
TwilioVideo
class has been renamed to
TwilioVideoSDK
. This was necessary to allow type clashes to be resolved by qualifying the type name with the module name. For instance, if your application also declares a
Room
type, it will be necessary to distinguish the SDK's
Room
type by prefixing it with module name,
TwilioVideo.Room
. In previous versions of the iOS SDK, this would fail because Swift would recognize that there was a
TwilioVideo
class and it would attempt to find the
Room
type declared there. This is a
known issue
in Swift where type qualification will fail if a module contains a type of the same name.
For example, consider an application, MyApp, that contains its own implementation of a RemoteParticipant class. To differentiate between the RemoteParticipant class from the application and from the SDK, you would prefix the type definition with the module name:
_10
var remoteParticipantFromApp: MyApp.RemoteParticipant?
_10
var remoteParticipantFromSDK: TwilioVideo.RemoteParticipant?
Listed below are the major changes to the Swift APIs:
TwilioVideoSDK
New
TwilioVideoSDK.Error
Previous
TVIError
New
TwilioVideoSDK.ErrorDomain
Previous
kTVIErrorDomain
New
TwilioVideoSDK.LogLevel
Previous
TVILogLevel
New
TwilioVideoSDK.LogModule
Previous
TVILogModule
New
TwilioVideoSDK.sdkVersion
Previous
TwilioVideo.version
New
class func connect(options: ConnectOptions,delegate: RoomDelegate?) -> Room
Previous
class func connect(with options: TVIConnectOptions,delegate: TVIRoomDelegate?) -> TVIRoom
AudioDevice
New
public func AudioDeviceFormatChanged(context: AudioDeviceContext)
Previous
public func TVIAudioDeviceFormatChanged(_ context: TVIAudioDeviceContext)
New
public func AudioDeviceWriteCaptureData(context: AudioDeviceContext,data: UnsafeMutablePointer<Int8>,sizeInBytes: Int)
Previous
public func TVIAudioDeviceWriteCaptureData(_ context: TVIAudioDeviceContext,_ data: UnsafeMutablePointer<Int8>,_ sizeInBytes: Int)
New
public func AudioDeviceReadRenderData(context: AudioDeviceContext,data: UnsafeMutablePointer<Int8>,sizeInBytes: Int)
Previous
public func TVIAudioDeviceReadRenderData(_ context: TVIAudioDeviceContext,_ data: UnsafeMutablePointer<Int8>,_ sizeInBytes: Int)
New
public typealias AudioDeviceWorkerBlock = () -> Void
Previous
public typealias TVIAudioDeviceWorkerBlock = () -> Void
New
public func AudioDeviceExecuteWorkerBlock(context: AudioDeviceContext,block: @escaping AudioDeviceWorkerBlock)
Previous
public func TVIAudioDeviceExecuteWorkerBlock(_ context: TVIAudioDeviceContext,_ block: @escaping TVIAudioDeviceWorkerBlock)