Skip to contentSkip to navigationSkip to topbar
On this page

Twilio Video Quickstart for iOS


Build your video application with the Twilio Video iOS SDK.

(information)

Info

Before getting started, we recommend you take a look at the open source Twilio Video iOS App(link takes you to an external page) and Twilio Video Quickstart for iOS(link takes you to an external page).

Use of this software is subject to the Twilio Terms of Service(link takes you to an external page). Please review ACKNOWLEDGEMENTS.md for licenses of dependent software embedded in the downloaded package.


Video API overview

video-api-overview page anchor

The Twilio Video API includes the following resources:

  • Room: The real-time audio, data, video and screen-share session. It's the basic building block for a Twilio Video application.
  • Participants: The client applications that are connected to a Room and sharing audio, data, and video media with one another.
  • Tracks: The audio, data, and video media streams that are shared within a Room.
  • LocalTracks: The audio, data, and video captured from the local client's media sources (for example, microphone and camera).
  • RemoteTracks: The audio, data, and video tracks from other participants connected to the Room.

To start using the Video iOS SDK in your apps, you need to perform a few tasks first.

(information)

SDK support

The iOS SDK supports iOS 12.2 or higher. It's built for arm64 and x86_64 architectures with Bitcode slices for arm64 devices.

The TwilioVideo.framework is built with Xcode 13. 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 13.x.

Step 1: Get the Video iOS SDK

step-1-get-the-video-ios-sdk page anchor

Install the Twilio Video iOS SDK dynamic framework with Swift Package Manager, with CocoaPods, or manually.

Swift Package Manager

swift-package-manager page anchor
  1. Add the https://github.com/twilio/twilio-video-ios repository as a Swift Package.
  2. In your Xcode project, go to Build Settings.
  3. Search for Other Linker Flags and add -ObjC.
  1. Add the following lines to your podfile:

    1
    source 'https://github.com/CocoaPods/Specs'
    2
    3
    platform :ios, '12.2'
    4
    5
    target 'TARGET_NAME' do
    6
    pod 'TwilioVideo', '~> 5'
    7
    end
  2. Run pod install to install the dependencies to your project.

The TwilioVideo.xcframework is distributed as a dynamic iOS framework that you can drag and drop into your existing projects.

You can browse all Twilio Video iOS releases(link takes you to an external page) or download the latest Video dynamic framework(link takes you to an external page) directly.

Once you've downloaded and unpacked the XCFramework, do the following:

  1. Navigate to your Xcode project's General settings page.
  2. Drag and drop TwilioVideo.xcframework onto the Frameworks, Libraries, and Embedded Content section.
  3. Make sure that Copy items if needed is checked and click Finish. Make sure that Embed & Sign is checked.
  4. Go to the Build Settings tab.
  5. Search for Other Linker Flags and add -ObjC.

Step 2: Get an API key

step-2-get-an-api-key page anchor

API keys represent credentials to access the Twilio API. You use them to:

Learn more about API keys.

Step 3: Generate an Access Token

step-3-generate-an-access-token page anchor

To execute the code samples below, you'll need to generate an Access Token. An Access Token is a short-lived credential used to authenticate your client-side application to Twilio.

You can generate an Access Token using either the Twilio CLI or a Twilio Helper Library.

For application testing purposes, the Twilio CLI provides a quick way to generate Access Tokens that you can then copy and paste it into your application. In a production application, you should use the Twilio Helper Libraries because your back-end server will need to generate an Access Token for every user in your application.

To use the CLI, you will need to install the Twilio CLI and log in to your Twilio account from the command line. For instructions, see the CLI quickstart. Then, you can install the Token CLI plugin(link takes you to an external page) with the following command:

twilio plugins:install @twilio-labs/plugin-token

To generate an Access Token, run the following command. --identity is a required argument and should be a string that represents the user identity for this Access Token.

twilio token:video --identity=<identity>

You can find examples of how to generate an Access Token for a participant using Twilio's Helper Libraries in User Identity and Access Token.


You can call TwilioVideo.connect() to connect to a Room from your iOS application. Once connected, you can send and receive audio and video streams with other Participants who are connected to the Room.

1
@IBAction func createARoom(sender: AnyObject) {
2
let connectOptions = ConnectOptions(token: accessToken) { (builder) in
3
builder.roomName = "my-room"
4
}
5
room = TwilioVideoSDK.connect(options: connectOptions, delegate: self)
6
}
7
8
// MARK: RoomDelegate
9
10
func roomDidConnect(room: Room) {
11
print("Did connect to Room")
12
13
if let localParticipant = room.localParticipant {
14
print("Local identity \(localParticipant.identity)")
15
16
// Set the delegate of the local particiant to receive callbacks
17
localParticipant.delegate = self
18
}
19
}

You must pass the Access Token when connecting to a Room. You may also optionally pass the following:

  • roomName: The room name to dynamically specify the name of the Room you want to join. You can also encode the Room name in the Access Token, which will let the user connect to only the Room specified in the token.
  • localAudioTracks, localVideoTracks or localDataTracks: The local audio, video, or data tracks to begin sharing your local media with other Participants in the Room upon connecting.
  • An ICE transport policy, which allows you to force calls through TURN relay for testing purposes.

The name of the Room specifies which Room you want to join. If you have enabled client-side Room ("ad-hoc Room") creation for your account and a Room by that name doesn't already exist, it will be created upon connection. If a Room by that name is already active, you'll be connected to the Room and receive notifications from any other Participants also connected to the same Room. Room names must be unique within an Account.

(information)

Default Room settings

If you have enabled client-side Room creation, any new Room you create via the iOS SDK will follow the default Room settings that you've specified in your account. These settings include options like a StatusCallback URL where you can receive Room creation and other webhook events, the maximum number of Participants, automatic recording, and more. You can view and update your default Room settings in the Twilio Console(link takes you to an external page).

You can also create a Room using the Rooms REST API. Look at the REST API Rooms resource docs for more details.


To join an existing Room, pass the Room name to the connect method, just as you would when creating a Room.

Once in a Room, you'll receive a room:participantDidConnect: callback for each Participant that successfully joins. Querying the remoteParticipants getter will return any existing Participants who have already joined the Room.

1
@IBAction func joinRoom(sender: AnyObject) {
2
let connectOptions = ConnectOptions(token: accessToken) { (builder) in
3
builder.roomName = "existing-room"
4
})
5
room = TwilioVideoSDK.connect(options: connectOptions, delegate: self)
6
}
7
8
// MARK: RoomDelegate
9
10
func roomDidConnect(room: Room) {
11
print("Did connect to room")
12
13
if let localParticipant = room.localParticipant {
14
print("Local identity \(localParticipant.identity)")
15
16
// Set the delegate of the local particiant to receive callbacks
17
localParticipant.delegate = self
18
}
19
}

You can capture local media from your device's microphone, camera or screen-share on different platforms in the following ways:

  • Begin capturing audio data by creating a TVILocalAudioTrack.
  • Begin capturing video by creating a TVILocalVideoTrack with an associated TVIVideoCapturer. The Video iOS SDK provides customizable video capturers for both camera and screen sharing.
1
// Create an audio track
2
var localAudioTrack = LocalAudioTrack()
3
4
// Create a data track
5
var localDataTrack = LocalDataTrack()
6
7
// Create a CameraSource to provide content for the video track
8
var localVideoTrack : LocalVideoTrack?
9
10
// Create a video track with the capturer.
11
if let camera = CameraSource(delegate: self) {
12
localVideoTrack = LocalVideoTrack(source: camera)
13
}

Specify tracks at connect time

specify-tracks-at-connect-time page anchor

When the client joins a Room, the client can specify which tracks they want to share with other Participants. The following code is how we share the audio and video track we created earlier:

1
let connectOptions = ConnectOptions(token: accessToken) { (builder) in
2
builder.roomName = "my-room"
3
4
if let audioTrack = localAudioTrack {
5
builder.audioTracks = [ audioTrack ]
6
}
7
if let dataTrack = localDataTrack {
8
builder.dataTracks = [ dataTrack ]
9
}
10
if let videoTrack = localVideoTrack {
11
builder.videoTracks = [ videoTrack ]
12
}
13
}
14
15
var room = TwilioVideoSDK.connect(options: connectOptions, delegate: self)

Connect as a publish-only Participant

connect-as-a-publish-only-participant page anchor

For some use cases, such as a ReplayKit broadcast extension(link takes you to an external page), you may want to connect as a publish-only Participant that's not subscribed to any tracks. You can disable automatic subscription behavior via connectOptions.

1
let connectOptions = ConnectOptions(token: accessToken) { (builder) in
2
builder.isAutomaticSubscriptionEnabled = false
3
builder.roomName = "my-room"
4
5
if let audioTrack = localAudioTrack {
6
builder.audioTracks = [ audioTrack ]
7
}
8
}
9
10
var room = TwilioVideo.connect(options: connectOptions, delegate: self)

Working with remote Participants

working-with-remote-participants page anchor

Handle connected Participants

handle-connected-participants page anchor

When you join a Room, Participants may already be present. You can check for existing Participants in the roomDidConnect: callback by using the remoteParticipants getter. To receive RemoteParticipantDelegate callbacks you will need to set the RemoteParticipant.delegate property for each connected remote Participant.

1
room = TwilioVideo.connect(options: connectOptions, delegate: self)
2
3
// MARK: RoomDelegate
4
5
func roomDidConnect(room: Room) {
6
// The Local Participant
7
if let localParticipant = room.localParticipant {
8
print("Local identity \(localParticipant.identity)")
9
10
// Set the delegate of the local participant to receive callbacks
11
localParticipant.delegate = self
12
}
13
14
// Connected participants already in the room
15
print("Number of connected Participants \(room.remoteParticipants.count)")
16
17
// Set the delegate of the remote participants to receive callbacks
18
for remoteParticipant in room.remoteParticipants {
19
remoteParticipant.delegate = self
20
}
21
}
22
23
func participantDidConnect(room: Room, participant: RemoteParticipant) {
24
print ("Participant \(participant.identity) has joined Room \(room.name)")
25
26
// Set the delegate of the remote participant to receive callbacks
27
participant.delegate = self
28
}
29
30
func participantDidDisconnect(room: Room, participant: RemoteParticipant) {
31
print ("Participant \(participant.identity) has left Room \(room.name)")
32
}

Handle Participant connection events

handle-participant-connection-events page anchor

When Participants connect or disconnect from a Room that you're connected to, you'll be notified via an event listener. Similar to Room events, Twilio will send Participant events if the StatusCallback webhook URL is set when the Room is created. These events help your application keep track of the participants who join or leave a Room.

1
// MARK: RoomDelegate
2
3
// First, we set a Participant Delegate when a Participant first connects:
4
func participantDidConnect(room: Room, participant: RemoteParticipant) {
5
print("Participant connected: \(participant.identity)")
6
participant.delegate = self
7
}

Display a remote Participant's video

display-a-remote-participants-video page anchor

To see the video tracks being sent by remote Participants, we need to render them to the screen:

1
// MARK: RemoteParticipantDelegate
2
3
/*
4
* In the Participant Delegate, we can respond when the Participant adds a Video
5
* Track by rendering it on screen.
6
*/
7
func didSubscribeToVideoTrack(videoTrack: RemoteVideoTrack,
8
publication: RemoteVideoTrackPublication,
9
participant: RemoteParticipant) {
10
11
print("Participant \(participant.identity) added a video track.")
12
13
if let remoteView = VideoView.init(frame: self.view.bounds,
14
delegate:self) {
15
16
videoTrack.addRenderer(remoteView)
17
self.view.addSubview(remoteView)
18
self.remoteView = remoteView
19
}
20
}
21
22
// MARK: VideoViewDelegate
23
24
// Lastly, we can subscribe to important events on the VideoView
25
func videoViewDimensionsDidChange(view: VideoView, dimensions: CMVideoDimensions) {
26
print("The dimensions of the video track changed to: \(dimensions.width)x\(dimensions.height)")
27
self.view.setNeedsLayout()
28
}

Display a camera preview

display-a-camera-preview page anchor

Sometimes you need to make sure you're looking fantastic before entering a Room. We get it. The iOS SDK provides a means to render a local camera preview outside the context of an active Room:

1
// Use CameraSource to produce video from the device's front camera.
2
3
if let camera = CameraSource(delegate: self),
4
let videoTrack = LocalVideoTrack(source: camera) {
5
6
// VideoView is a VideoRenderer and can be added to any VideoTrack.
7
let renderer = VideoView(frame: view.bounds)
8
}
9
if let camera = TVICameraCapturer(source: .frontCamera),
10
let videoTrack = TVILocalVideoTrack(capturer: camera) {
11
12
// TVIVideoView is a TVIVideoRenderer and can be added to any TVIVideoTrack.
13
let renderer = TVIVideoView(frame: view.bounds)
14
15
// Add renderer to the video track
16
videoTrack.addRenderer(renderer)
17
18
self.localVideoTrack = videoTrack
19
self.camera = camera
20
self.view.addSubview(renderer)
21
} else {
22
print("Couldn't create CameraCapturer or LocalVideoTrack")
23
}

You can disconnect from a Room you're currently participating in. Other Participants will receive a participantDisconnected event.

1
// To disconnect from a Room, we call:
2
room?.disconnect()
3
4
// This results in a callback to RoomDelegate#roomDidDisconnect(room: Room, error: Error?)
5
6
// MARK: RoomDelegate
7
8
func roomDidDisconnect(room: Room, error: Error?) {
9
print("Disconnected from room \(room.name)")
10
}

The Video SDK will raise notifications when a Room is reconnecting due to a network disruption. A Room reconnection is triggered due to a signaling or media reconnection event.

1
// MARK: RoomDelegate
2
3
// Error will be either TwilioVideoSDK.Error.signalingConnectionError or TwilioVideoSDK.Error.mediaConnectionError
4
func roomIsReconnecting(room: Room, error: Error) {
5
print("Reconnecting to room \(room.name), error = \(String(describing: error))")
6
}
7
8
func roomDidReconnect(room: Room) {
9
print("Reconnected to room \(room.name)")
10
}

To keep a Room connection running in the background, select the Audio, AirPlay, and Picture in Picture mode from the Capabilities project settings page in Xcode.

Background modes.

Twilio Video requires user permission for features like sharing video from the camera or audio from the microphone. Consider how your applications might function with reduced functionality in case some permissions (for example, the camera) are declined.

Friendly namePrivacy usage description keyiOS versionRecommendation
CameraNSCameraUsageDescriptionAllRequest permissions using AVCaptureDevice.requestAccess(for:completionHandler:)(link takes you to an external page) before calling TwilioVideoSDK.connect(options:delegate:)(link takes you to an external page) with a TVICameraSource.
MicrophoneNSMicrophoneUsageDescriptionAllRequest permissions using AVAudioSession.requestRecordPermission()(link takes you to an external page) before calling TwilioVideoSDK.connect(options:delegate:)(link takes you to an external page) when Participants publish or subscribe to audio tracks with TVIDefaultAudioDevice.
Custom audio devices do not require microphone permissions for playback only use cases. See video-quickstart-ios/issues/207(link takes you to an external page) for more information.
Local networkNSLocalNetworkUsageDescription14.0+This permission isn't recommended unless your app is already using NWConnection(link takes you to an external page) APIs on the local network.

Reconnections and the UIApplication lifecycle

reconnections-and-the-uiapplication-lifecycle page anchor

When an application is put into the background, both the signaling and media connections close, which triggers the reconnecting delegate method. This occurs when connected to a Room with no shared audio tracks.


The Twilio Video API allows you to control your video applications from your backend server via HTTP requests.

Learn more about the Video API.


To enable debug level logging, add the following code in your application:

TwilioVideoSDK.setLogLevel(.debug)

Providing debugging information helps us diagnose and respond quickly. When submitting issues or support tickets, include the following information:

  • Description: Describe the issue.
  • Steps to reproduce: List the steps required to reproduce the issue.
  • Code: Include relevant code snippets that would help in reproduction and troubleshooting of the issue.
  • Expected behavior: Describe what you expected to happen.
  • Actual behavior: Describe what actually happened.
  • Reproduction frequency: Indicate how often the isssue occurs in percentage (for example, 50% of the time).
  • Logs: Include any log output generated when the issue occurs.
  • Video iOS SDK version: Include the version of the Video iOS SDK where this issue occurs.
  • Xcode version: Include the version of Xcode where this issue occurs.
  • iOS version: Include the version of iOS where this issue occurs.
  • iOS device: Include the details of the iOS device where this issue occurs.
  • Room SID: Include the Room SID. It can be useful for tracing backend issues.

After gathering the required information, you can create a GitHub issue for the Twilio Video iOS SDK(link takes you to an external page) or the Twilio Video iOS Quickstart app(link takes you to an external page), or open a support ticket through the Twilio Help Center Assistant(link takes you to an external page).