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 recommendations and best practices for building an iOS video app using the Twilio Programmable Video iOS SDK.
Please take a look at this Developing High Quality Video Applications guide to choose the right ConnectOptions when initializing the video call for your use case.
When the local participant mutes the microphone, it is recommended to unpublish the microphone track instead of disabling it. When the microphone track is only disabled, the orange indicator in the status bar is still displayed and this could be confusing for users.
_26var room: Room? // Set when connected to a video room_26var micTrack: LocalAudioTrack?_26_26var isLocalMicOn = false {_26 didSet {_26 guard oldValue != isLocalMicOn else {_26 return_26 }_26_26 if isLocalMicOn {_26 guard let micTrack = LocalAudioTrack(options: nil, enabled: true, name: "mic") else {_26 return_26 }_26_26 self.micTrack = micTrack_26 room?.localParticipant?.publishAudioTrack(micTrack)_26 } else {_26 guard let micTrack = micTrack else {_26 return_26 }_26_26 room?.localParticipant?.unpublishAudioTrack(micTrack)_26 self.micTrack = nil_26 }_26 }_26}
See the reference iOS video collaboration app for a similar implementation working in an app.
When the local participant turns off the camera, it is recommended to unpublish the camera track instead of disabling it. Unpublishing the camera track will minimize resources consumed and there is no impact to the user experience.
_35var room: Room? // Set when connected to a video room_35var cameraSource: CameraSource?_35var cameraTrack: CameraTrack?_35_35var isLocalCameraOn = false {_35 didSet {_35 guard oldValue != isLocalCameraOn else {_35 return_35 }_35_35 if isLocalCameraOn {_35 guard_35 let cameraSource = CameraSource(delegate: self),_35 let cameraTrack = LocalVideoTrack(source: cameraSource, enabled: true, name: "camera")_35 let captureDevice = CameraSource.captureDevice(position: .front),_35 else {_35 return_35 }_35_35 cameraSource.startCapture(device: captureDevice, completion: nil)_35_35 room?.localParticipant?.publishVideoTrack(cameraTrack)_35 self.cameraSource = cameraSource_35 self.cameraTrack = cameraTrack_35 } else {_35 if let cameraTrack = cameraTrack {_35 participant?.unpublishVideoTrack(cameraTrack)_35 }_35_35 cameraSource?.stopCapture()_35 cameraSource = nil_35 cameraTrack = nil_35 }_35 }_35}
See the reference iOS video collaboration app for a similar implementation working in an app.
When displaying track status in the user interface, check if the track is enabled. Tracks may be disabled instead of unpublished for some edge cases or to optimize the experience for users on a platform that isn't using the iOS Video SDK.
_19extension RemoteParticipant {_19 var isMicOn: Bool {_19 // Make sure to use the same track name that your app is using to create the microphone track_19 guard let track = participant.remoteAudioTracks.first(where: { $0.trackName == "mic" }) else {_19 return false_19 }_19_19 return track.isTrackSubscribed && track.isTrackEnabled_19 }_19_19 var isCameraOn: Bool {_19 // Make sure to use the same track name that your app is using to create the camera track_19 guard let track = participant.remoteVideoTracks.first(where: { $0.trackName == "camera" }) else {_19 return false_19 }_19_19 return track.isTrackSubscribed && track.isTrackEnabled_19 }_19}
See the reference iOS video collaboration app for a similar implementation working in an app.
When the app moves to the background, the system will interrupt camera capture. We recommend that you disable the camera track instead of unpublish it, since interruptions can be frequent due to things like notifications. When the camera interruption ends, enable the track again.
_10var cameraTrack: CameraTrack? // Set when camera is turned on_10_10// CameraSourceDelegate_10func cameraSourceWasInterrupted(source: CameraSource, reason: AVCaptureSession.InterruptionReason) {_10 cameraTrack?.isEnabled = false_10}_10_10func cameraSourceInterruptionEnded(source: CameraSource) {_10 cameraTrack?.isEnabled = true_10}
See the reference iOS video collaboration app for a similar implementation working in an app.
When another app interrupts audio (e.g. receiving a phone call in the Phone app), audio recording and playback in the video app will be interrupted. This could cause your app to be suspended because it is not playing or recording audio. When the app is suspended the app will be disconnected from the video room.
This section lists some of the important errors raised by the iOS Video SDK and provides recommendations on how best to handle them in order to provide the optimal user experience.
These errors are raised when the app is not able to connect to a Room. The app can use the RoomDelegate to receive connection errors.
Your app should handle errors that may happen when trying to connect to a Room.
_10// RoomDelegate function_10func roomDidFailToConnect(room: Room, error: Error) {_10 // Handle error_10}
The following table describes the most common connection errors and proposes ways for the application to handle them:
| Error | Code | Cause | Solution |
|---|---|---|---|
| SignalingConnectionError | 53000 | The client could not establish a connection to Twilio's signaling server | User should make sure to have a stable internet connection |
| SignalingServerBusyError | 53006 | Twilio's signaling server is too busy to accept new clients | User should try joining the Room again after some time |
| RoomMaxParticipantsExceededError | 53105 | The Room cannot allow in any more Participants to join | Your app should notify the user that the Room is full |
| RoomNotFoundError | 53106 | The client attempted to connect to a Room that does not exist | If ad-hoc Room creation is disabled, then your app should make sure that the Room is created using the REST API before clients attempt to join |
| MediaConnectionError | 53405 | The client failed to establish a media connection with the Room | 1. User should make sure to have a stable internet connection 2. If the user is behind a firewall, then it should allow media traffic to and from Twilio to go through |
These errors are raised when the app is inadvertently disconnected from the Room. The app can use the RoomDelegate to receive disconnect errors.
_10// RoomDelegate function_10func roomDidDisconnect(room: Room, error: Error?) {_10 if let error = error {_10 // Handle error_10 }_10}
The following table describes the most common disconnection errors and proposes ways for the application to handle them:
| Error | Code | Cause | Solution |
|---|---|---|---|
| SignalingConnectionDisconnectedError | 53001 | The client failed to reconnect to Twilio's signaling server after a network disruption or handoff | User should make sure to have a stable internet connection |
| SignalingConnectionTimeoutError | 53002 | The liveliness checks for the connection to Twilio's signaling server failed, or the current session expired | User should rejoin the Room |
| ParticipantDuplicateIdentityError | 53205 | Another client joined the Room with the same identity | Your app should make sure each client creates an AccessToken with a unique identity string |
| MediaConnectionError | 53405 | The client failed to re-establish its media connection with the Room after a network disruption or handoff | 1. User should make sure to have a stable internet connection 2. If the user is behind a firewall, then the firewall should allow media traffic to and from Twilio to go through |
| RoomNotFoundError | 53106 | The client tried to reconnect to Twilio's signaling server after a network disruption or handoff, but room they had joined ended while they were disconnected | Your app should notify user that Room has ended |