Skip to contentSkip to navigationSkip to topbar
On this page

iOS Video Application Recommendations and Best Practices


(warning)

Warning

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(link takes you to an external page).

We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) 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.


Contents

contents page anchor

Please take a look at this Developing High Quality Video Applications guide to choose the right ConnectOptions(link takes you to an external page) when initializing the video call for your use case.


Mute and Unmute the Microphone

mute-and-unmute-the-microphone page anchor

When the local participant mutes the microphone, it is recommended to unpublish the microphone track instead of disabling it(link takes you to an external page). When the microphone track is only disabled, the orange indicator in the status bar(link takes you to an external page) is still displayed and this could be confusing for users.

1
var room: Room? // Set when connected to a video room
2
var micTrack: LocalAudioTrack?
3
4
var isLocalMicOn = false {
5
didSet {
6
guard oldValue != isLocalMicOn else {
7
return
8
}
9
10
if isLocalMicOn {
11
guard let micTrack = LocalAudioTrack(options: nil, enabled: true, name: "mic") else {
12
return
13
}
14
15
self.micTrack = micTrack
16
room?.localParticipant?.publishAudioTrack(micTrack)
17
} else {
18
guard let micTrack = micTrack else {
19
return
20
}
21
22
room?.localParticipant?.unpublishAudioTrack(micTrack)
23
self.micTrack = nil
24
}
25
}
26
}

See the reference iOS video collaboration app(link takes you to an external page) for a similar implementation working in an app.

Turn the Camera On and Off

turn-the-camera-on-and-off page anchor

When the local participant turns off the camera, it is recommended to unpublish the camera track instead of disabling it(link takes you to an external page). Unpublishing the camera track will minimize resources consumed and there is no impact to the user experience.

1
var room: Room? // Set when connected to a video room
2
var cameraSource: CameraSource?
3
var cameraTrack: CameraTrack?
4
5
var isLocalCameraOn = false {
6
didSet {
7
guard oldValue != isLocalCameraOn else {
8
return
9
}
10
11
if isLocalCameraOn {
12
guard
13
let cameraSource = CameraSource(delegate: self),
14
let cameraTrack = LocalVideoTrack(source: cameraSource, enabled: true, name: "camera")
15
let captureDevice = CameraSource.captureDevice(position: .front),
16
else {
17
return
18
}
19
20
cameraSource.startCapture(device: captureDevice, completion: nil)
21
22
room?.localParticipant?.publishVideoTrack(cameraTrack)
23
self.cameraSource = cameraSource
24
self.cameraTrack = cameraTrack
25
} else {
26
if let cameraTrack = cameraTrack {
27
participant?.unpublishVideoTrack(cameraTrack)
28
}
29
30
cameraSource?.stopCapture()
31
cameraSource = nil
32
cameraTrack = nil
33
}
34
}
35
}

See the reference iOS video collaboration app(link takes you to an external page) for a similar implementation working in an app.

Display Media Status in the User Interface

display-media-status-in-the-user-interface page anchor

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.

1
extension RemoteParticipant {
2
var isMicOn: Bool {
3
// Make sure to use the same track name that your app is using to create the microphone track
4
guard let track = participant.remoteAudioTracks.first(where: { $0.trackName == "mic" }) else {
5
return false
6
}
7
8
return track.isTrackSubscribed && track.isTrackEnabled
9
}
10
11
var isCameraOn: Bool {
12
// Make sure to use the same track name that your app is using to create the camera track
13
guard let track = participant.remoteVideoTracks.first(where: { $0.trackName == "camera" }) else {
14
return false
15
}
16
17
return track.isTrackSubscribed && track.isTrackEnabled
18
}
19
}

See the reference iOS video collaboration app(link takes you to an external page) for a similar implementation working in an app.


Run the App in the Background

run-the-app-in-the-background page anchor

Handle Camera Interruptions

handle-camera-interruptions page anchor

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.

1
var cameraTrack: CameraTrack? // Set when camera is turned on
2
3
// CameraSourceDelegate
4
func cameraSourceWasInterrupted(source: CameraSource, reason: AVCaptureSession.InterruptionReason) {
5
cameraTrack?.isEnabled = false
6
}
7
8
func cameraSourceInterruptionEnded(source: CameraSource) {
9
cameraTrack?.isEnabled = true
10
}

See the reference iOS video collaboration app(link takes you to an external page) for a similar implementation working in an app.

Handle Audio Interruptions

handle-audio-interruptions page anchor

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.

1
// RoomDelegate function
2
func roomDidFailToConnect(room: Room, error: Error) {
3
// Handle error
4
}

The following table describes the most common connection errors and proposes ways for the application to handle them:

ErrorCodeCauseSolution
SignalingConnectionError53000The client could not establish a connection to Twilio's signaling serverUser should make sure to have a stable internet connection
SignalingServerBusyError53006Twilio's signaling server is too busy to accept new clientsUser should try joining the Room again after some time
RoomMaxParticipantsExceededError53105The Room cannot allow in any more Participants to joinYour app should notify the user that the Room is full
RoomNotFoundError53106The client attempted to connect to a Room that does not existIf 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
MediaConnectionError53405The client failed to establish a media connection with the Room1. 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.

1
// RoomDelegate function
2
func roomDidDisconnect(room: Room, error: Error?) {
3
if let error = error {
4
// Handle error
5
}
6
}

The following table describes the most common disconnection errors and proposes ways for the application to handle them:

ErrorCodeCauseSolution
SignalingConnectionDisconnectedError53001The client failed to reconnect to Twilio's signaling server after a network disruption or handoffUser should make sure to have a stable internet connection
SignalingConnectionTimeoutError53002The liveliness checks for the connection to Twilio's signaling server failed, or the current session expiredUser should rejoin the Room
ParticipantDuplicateIdentityError53205Another client joined the Room with the same identityYour app should make sure each client creates an AccessToken with a unique identity string
MediaConnectionError53405The client failed to re-establish its media connection with the Room after a network disruption or handoff1. 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
RoomNotFoundError53106The client tried to reconnect to Twilio's signaling server after a network disruption or handoff, but room they had joined ended while they were disconnectedYour app should notify user that Room has ended

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.