Skip to main content
Version: 4.x.x

VideoSDK Class Methods - iOS

createRoom()​

  • Creates a Room. The room has not joined yet. Call join() on it to join.
  • Pass your token here. There is no separate config step. To generate a token, see this documentation.
  • Only roomId and token are required. See Creating a Room for all the parameters.
  • createRoom() throws, so call it with try.

Throws​

  • VideoSDKError.ERROR_INVALID_PARAMETER (3073) if roomId or token is empty. The token itself is checked when you join the room.

Returns​

  • Room

Example​

do {
    room = try VideoSDK.createRoom(
        roomId: "abc-1234-xyz",
        token: "<YOUR_TOKEN>",
        participantName: "John Doe",
        micEnabled: true,
        camEnabled: true
    )
} catch {
    print("Room setup failed: \(error)")
}

getAudioPermissionStatus()​

  • Returns the microphone permission status of your app.

Returns​

  • AuthorisationStatus
    • .notDetermined: the user has not been asked yet.
    • .restricted: access is blocked on the device, for example by parental controls. The user cannot change it.
    • .denied: the user denied access. They can allow it in the Settings app.
    • .authorized: the user allowed access.

Example​

if VideoSDK.getAudioPermissionStatus() == .authorized {
    print("Microphone access is allowed")
}

getVideoPermissionStatus()​

  • Returns the camera permission status of your app.

Returns​

  • AuthorisationStatus
    • .notDetermined: the user has not been asked yet.
    • .restricted: access is blocked on the device, for example by parental controls. The user cannot change it.
    • .denied: the user denied access. They can allow it in the Settings app.
    • .authorized: the user allowed access.

Example​

if VideoSDK.getVideoPermissionStatus() == .authorized {
    print("Camera access is allowed")
}

getAudioPermission()​

  • It prompts the system alert to access the microphone for your app.

  • It will only prompt when the status for the audio permission is .notDetermined.

  • It returns before the user answers. To wait for the answer, call await AVCaptureDevice.requestAccess(for: .audio) instead.

  • If the status is .denied, iOS does not show the alert again. Ask the user to allow microphone access in the Settings app, as shown in the getVideoPermission() example.

  • See our guide on handling permissions before a call here.

Returns​

  • Void

Example​

VideoSDK.getAudioPermission()

getVideoPermission()​

  • It prompts the system alert to access the camera for your app.

  • It will only prompt when the status for the video permission is .notDetermined.

  • It returns before the user answers. To wait for the answer, call await AVCaptureDevice.requestAccess(for: .video) instead.

  • If the status is .denied, iOS does not show the alert again. Ask the user to allow camera access in the Settings app.

  • See our guide on handling permissions before a call here.

Returns​

  • Void

Example​

switch VideoSDK.getVideoPermissionStatus() {
case .notDetermined:
    VideoSDK.getVideoPermission()
case .denied:
    // Open your app's page in the Settings app
    if let settingsURL = URL(string: UIApplication.openSettingsURLString) {
        UIApplication.shared.open(settingsURL)
    }
default:
    break
}

getCameras()​

  • Lists the front and back cameras the SDK can open (the wide-angle camera on each side), as CameraDeviceInfo values.
  • Pass a camera's deviceId to changeCam(deviceId:) of the room, or as cameraId to createCameraVideoTrack(). The deviceId is the camera's AVCaptureDevice.uniqueID, not its name.

Returns​

  • [CameraDeviceInfo]

Example​

let cameras = VideoSDK.getCameras()
for camera in cameras {
    print(camera.label, camera.deviceId, camera.facingMode?.rawValue ?? "external")
}
// Sample output:
// Front Camera com.apple.avfoundation.avcapturedevice.built-in_video:1 front
// Back Camera com.apple.avfoundation.avcapturedevice.built-in_video:0 back

getMics()​

  • Lists the audio devices you can choose from, as MicrophoneDeviceInfo values. The list starts with Speaker, the loudspeaker output, followed by the microphones that are available, such as iPhone Microphone or a connected headset.
  • Pass a device to setAudioDevice(_:) of the room, its deviceId to changeMic(deviceId:) of the room, or its deviceId as microphoneId to createMicrophoneAudioTrack().

Returns​

  • [MicrophoneDeviceInfo]

Example​

let mics = VideoSDK.getMics()
print(mics.map(\.label))
// Sample output: ["Speaker", "iPhone Microphone"]

getDevices()​

  • Lists every camera and audio device in one array: the result of getCameras() followed by the result of getMics().
  • Check for CameraDeviceInfo or MicrophoneDeviceInfo, or read kind, to tell them apart.

Returns​

  • [DeviceInfo]

Example​

for device in VideoSDK.getDevices() {
    if let camera = device as? CameraDeviceInfo {
        print("Camera: \(camera.label)")
    } else {
        print("Audio device: \(device.label)")
    }
}

getSelectedVideoDevice()​

  • Returns the camera the SDK opens or is using.
  • Returns nil when there is no camera on that side.

Returns​

  • CameraDeviceInfo?

Example​

if let camera = VideoSDK.getSelectedVideoDevice() {
    print("Current camera: \(camera.label)")
}

getSelectedAudioDevice()​

  • Returns the audio device in use: Speaker while audio plays on the loudspeaker, otherwise the current microphone input.
  • Returns nil when neither is known.

Returns​

  • MicrophoneDeviceInfo?

Example​

if let device = VideoSDK.getSelectedAudioDevice() {
    print("Current audio device: \(device.label)")
}

createCameraVideoTrack()​

  • Creates a custom camera video track with the encoder settings you choose. Pass it to createRoom(customCameraTrack:), or to enableCam(customCameraTrack:) or changeCam(customCameraTrack:) of the room.
  • It opens the camera for a local preview. Nothing is sent until a room publishes the track.
  • It is async throws. Call it with try await.
  • It never asks for camera permission. Until access is granted, it throws ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED. Ask first with getVideoPermission().
  • It waits up to 2 seconds for the camera to open and throws the errors that happen in that time. If the camera fails after that, the track ends and its onEnded handler receives the error.
  • See Custom Tracks for more about custom tracks.

Parameters​

  • encoderConfig: CustomCameraTrackConfig?, default .h720p_w1280p. The resolution and frame rate of the track.
  • facingMode: FacingMode?, default .front. .front or .back. If there is no camera on that side, the other camera is used.
  • multiStream: Bool?, default true. When true, the track is sent in several resolution layers.
  • cameraId: String?, default nil. The deviceId of a camera from getCameras(). When you set it, it picks the camera instead of facingMode.
  • maxLayer: EncodingLayer?, default .MAX_LAYER_3. Used only when multiStream is true.
  • bitrateMode: BitrateMode?, default .BALANCED.
  • codec: VideoCodec?, default .VP8.

Throws​

  • VideoSDKError:
    • ERROR_INVALID_CUSTOM_TRACK_CONFIG (3071) when no camera has the deviceId you passed as cameraId.
    • ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED (3017) when camera access is not granted.
    • ERROR_CAMERA_NOT_FOUND (3021) when the device has no camera.
    • ERROR_CAMERA_IN_USE (3023) when another app is using the camera.
    • ERROR_VIDEO_SOURCE_INITIATION_FAILED (3026) when the camera could not be opened.

Returns​

  • CustomStreamTrack

Example​

Task {
    do {
        let cameraTrack = try await VideoSDK.createCameraVideoTrack(
            encoderConfig: .h720p_w1280p,
            facingMode: .front,
            multiStream: true
        )
        try await room?.enableCam(customCameraTrack: cameraTrack)
    } catch let error as VideoSDKError {
        print("Could not turn on the camera: \(error.message)")
    } catch {
        print("Could not turn on the camera: \(error)")
    }
}

createMicrophoneAudioTrack()​

  • Creates a custom microphone audio track with the audio processing and encoder settings you choose. Pass it to createRoom(customMicrophoneTrack:), or to unmuteMic(customMicrophoneTrack:) or changeMic(customMicrophoneTrack:) of the room.
  • It is async throws. Call it with try await.
  • It never asks for microphone permission. Until access is granted, it throws ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED. Ask first with getAudioPermission().
  • It waits up to 2 seconds for the microphone to open and throws the errors that happen in that time. If the microphone fails after that, the track ends and its onEnded handler receives the error.

Parameters​

  • encoderConfig: CustomMicrophoneTrackConfig?, default .speech_standard.
  • microphoneId: String?, default nil. The deviceId of a microphone from getMics().
  • noiseConfig: NoiseConfig?, default nil. Turns noise suppression, echo cancellation, automatic gain control and the high-pass filter on or off. See Custom Audio Track.

Throws​

  • VideoSDKError:
    • ERROR_INVALID_CUSTOM_TRACK_CONFIG (3071) when no microphone has the deviceId you passed as microphoneId.
    • ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED (3018) when microphone access is not granted.
    • ERROR_MICROPHONE_NOT_FOUND (3022) when the device has no microphone.
    • ERROR_MICROPHONE_IN_USE (3024) when another app is using the microphone.

Returns​

  • CustomStreamTrack

Example​

Task {
    do {
        let microphoneTrack = try await VideoSDK.createMicrophoneAudioTrack(
            encoderConfig: .speech_standard,
            noiseConfig: NoiseConfig(
                noiseSuppression: true,
                echoCancellation: true,
                autoGainControl: true,
                highPassFilter: false
            )
        )
        try await room?.unmuteMic(customMicrophoneTrack: microphoneTrack)
    } catch {
        print("Could not turn on the microphone: \(error)")
    }
}

createScreenShareVideoTrack()​

  • Creates a screen-share track with the encoder settings you choose. Pass it to enableScreenShare(_:) of the room to start sharing.
  • It does not start capture. Capture starts after the user confirms the system picker that enableScreenShare(_:) shows.

Parameters​

  • encoderConfig: CustomScreenShareTrackConfig, default .h720p_15fps. One of .h360p_30fps, .h480p_15fps, .h480p_30fps, .h720p_5fps, .h720p_15fps, .h720p_30fps, .h1080p_15fps or .h1080p_30fps.
  • multiStream: Bool, default false. When true, the share is sent in three quality layers. When false, it is sent in one layer.
  • withAudio: Bool, default false. Accepted and ignored: screen share on iOS carries no audio.

Returns​

  • CustomStreamTrack. It holds only the share settings: its videoTrack and audioTrack are nil.

Example​

let screenShareTrack = VideoSDK.createScreenShareVideoTrack(encoderConfig: .h1080p_15fps)

Task {
    do {
        try await room?.enableScreenShare(screenShareTrack)
    } catch {
        print("Could not start screen share: \(error)")
    }
}

setKeyProvider()​

  • Sets the BaseKeyProvider that holds the end-to-end encryption (E2EE) keys. Call it before you join the room.
  • A shared key (setSharedKey(_:)) encrypts the whole room. Without one, only participants given a key with setParticipantKey() are encrypted.
  • To turn E2EE off for the next join, call removeKeyProvider().
  • See E2EE for the methods of BaseKeyProvider.

Parameters​

  • provider: BaseKeyProvider

Returns​

  • Void

Example​

do {
    let keyProvider = BaseKeyProvider()
    try keyProvider.setSharedKey("<YOUR_SHARED_KEY>")
    VideoSDK.setKeyProvider(keyProvider)
} catch {
    print("Could not set the encryption key: \(error)")
}

removeKeyProvider()​

  • Turns E2EE off for the next join and forgets the provider set with setKeyProvider().

Returns​

  • Void

Example​

VideoSDK.removeKeyProvider()

getKeyProvider()​

Returns​

  • BaseKeyProvider?

Example​

let e2eeConfigured = VideoSDK.getKeyProvider() != nil

setParticipantKey()​

  • Sets, changes or removes the E2EE key of one participant. It takes effect at once, also while in a room.
  • Set a key provider with setKeyProvider() first. Without one, it throws ERROR_INVALID_PARAMETER (3073).
  • The key is also saved in that provider, so a rejoin uses the same keys.
  • Participant keys are not used while a shared key is set.
  • The ID and key are used exactly as you pass them.
  • See E2EE for the methods of BaseKeyProvider.

Parameters​

  • participantId: String
  • key: String?. Pass nil to remove the participant's key.

Returns​

  • Void

Example​

do {
    try VideoSDK.setParticipantKey("<PARTICIPANT_ID>", key: "<NEW_KEY>")
} catch {
    print("Could not set the participant key: \(error)")
}

runPreCallTest()​

  • Checks the camera and microphone, and then measures the upload and download network quality, before the user joins a room.
  • It is async throws. Call it with try await.
  • Camera and microphone access must already be granted.
  • If you do not pass your own tracks in the options, the SDK opens the camera and microphone itself. A track the SDK opened that passed the check stays open and is returned in the result's camera.track and microphone.track. Call stop() on it when you are done.
  • Run it before createRoom(), or after you leave the room. Only one test can run at a time.
  • Cancelling the calling Task stops the test, like stopPreCallTest().
  • See Pre-call Test for the option and result types, and Precall Setup for a full pre-call flow.

Parameters​

  • options: PreCallTestOptions. The token, how long to measure the network (samplingDuration, 10 000 to 120 000 ms, default 15 000) and the devices to test.
  • onStatsChange: optional closure that receives the latest PreCallNetworkQuality on the main thread while the test runs.

Throws​

  • PreCallTestError with a string code, such as ERROR_PRECALL_INVALID_TOKEN, ERROR_PRECALL_TEST_ALREADY_RUNNING or ERROR_PRECALL_AFTER_INIT.

Returns​

  • PreCallTestResult with the camera, microphone and networkQuality results. Its aborted property is true when the test was stopped.

Example​

Task {
    do {
        let result = try await VideoSDK.runPreCallTest(
            PreCallTestOptions(token: "<YOUR_TOKEN>", samplingDuration: 15_000)
        ) { stats in
            print("Upload quality: \(stats.uplink.quality)")
        }
        print("Download quality: \(result.networkQuality?.downlink.quality ?? 0)")
    } catch let error as PreCallTestError {
        print("Pre-call test failed: \(error.code) \(error.message)")
    } catch {
        print("Pre-call test failed: \(error)")
    }
}

stopPreCallTest()​

  • Stops the running pre-call test and returns once it has stopped. The pending runPreCallTest() call then returns a result whose aborted property is true.
  • Calling it when no test is running does nothing.

Returns​

  • Void

Example​

Task {
    await VideoSDK.stopPreCallTest()
}

setScreenFlash()​

  • Sets the screen flash that lights the user's face when you call captureImage(width:height:flash:) with flash: .ON on a camera that has no torch, such as most front cameras.
  • WhiteOverlayScreenFlash covers a window in warm white at full brightness while the photo is taken.
  • The SDK keeps the screen flash until you replace it.

Parameters​

  • flash: ScreenFlash?. The screen flash to use, for example WhiteOverlayScreenFlash(window:). Pass nil to remove it.

Returns​

  • Void

Example​

VideoSDK.setScreenFlash(WhiteOverlayScreenFlash(window: view.window))

setLogLevel()​

  • Sets how much the SDK logs to the Xcode console. Before you call it, the level is .INFO. If you call it without a level, it uses .INFO.
  • From least to most verbose: .NONE, .ERROR, .WARN, .INFO, .DEBUG, .ALL. Each level includes the ones before it.
  • See Log Level for more details.

Parameters​

  • level: LogLevel, default .INFO.

Returns​

  • Void

Example​

VideoSDK.setLogLevel(level: .DEBUG)

getLogLevel()​

  • Returns the level you set with setLogLevel(), or .INFO if you have not set one.

Returns​

  • LogLevel

Example​

if VideoSDK.getLogLevel() == .DEBUG {
    print("Debug logs are on")
}

Device types​

DeviceInfo​

  • A device the SDK can use: a camera or an audio device. getDevices() returns both kinds in one array.
  • Two DeviceInfo values are equal when their kind and deviceId match.

Properties​

  • label: String. The name to show in a picker.
  • kind: MediaKind. .video for a camera, .audio for an audio device.
  • deviceId: String. The ID to pass back to the SDK, for example as cameraId or to changeMic(deviceId:).

CameraDeviceInfo​

  • A camera, listed by getCameras(). It is a DeviceInfo with kind .video.
  • Its label is the camera's name and its deviceId is AVCaptureDevice.uniqueID.

Properties​

  • facingMode: FacingMode?. Which way the lens points, or nil for a camera that is neither front nor back.

MicrophoneDeviceInfo​

  • An audio device, listed by getMics(). It is a DeviceInfo with kind .audio.
  • It is either a microphone input or the Speaker output. Its deviceId is the input port's unique ID, or Speaker for the loudspeaker. Its label is the name to show, such as Speaker or Headphones.

FacingMode​

  • Which way a camera points. Used by createCameraVideoTrack(facingMode:), createRoom(defaultCamera:) and CameraDeviceInfo.facingMode.

Values​

  • .front: the front (user-facing) camera.
  • .back: the back (environment-facing) camera.

Got a Question? Ask us on discord

Last updated on by Vaibhavdixit14
Previous
Pre-call Test
Next

Was this helpful?

Not helpfulHelpful