Version: 4.x.x

Pre-call Test - iOS

runPreCallTest() of the VideoSDK class checks the camera and microphone, and then measures the network, before the user joins a room. stopPreCallTest() stops a running test. This page lists the types that the test uses. For a full pre-call flow, see Precall Setup.

PreCallTestOptions

struct PreCallTestOptions

The options you pass to runPreCallTest(). Create them with PreCallTestOptions(token:samplingDuration:audioOnly:videoTrack:audioTrack:videoConfig:audioConfig:). Only token is required.

token: String - The authentication token.
samplingDuration: Int? - How long to measure the network, in milliseconds, from 10000 to 120000. Defaults to 15000.
audioOnly: Bool - Skip the camera and test with audio only. Defaults to false.
videoTrack: CustomStreamTrack? - A camera track you created with createCameraVideoTrack(). It is tested as it is, and the SDK never stops it.
audioTrack: CustomStreamTrack? - A microphone track you created with createMicrophoneAudioTrack(). It is tested as it is, and the SDK never stops it.
videoConfig: PreCallVideoConfig? - How the SDK opens the camera when you pass no videoTrack.
audioConfig: PreCallAudioConfig? - How the SDK opens the microphone when you pass no audioTrack.

Pass videoTrack or videoConfig, not both, and audioTrack or audioConfig, not both. Otherwise the test throws ERROR_PRECALL_INVALID_CONFIG.

If your app already shows tracks on its pre-call screen, pass them as videoTrack and audioTrack. When the SDK opens the camera or microphone itself, the track you created earlier for that device ends.

Example

let options = PreCallTestOptions(
    token: "<YOUR_TOKEN>",
    samplingDuration: 20_000,
    videoConfig: PreCallVideoConfig(encoderConfig: .h540p_w960p, facingMode: .front),
    audioConfig: PreCallAudioConfig(encoderConfig: .speech_standard)
)

PreCallVideoConfig

struct PreCallVideoConfig

How the SDK opens the camera for the test. Every parameter of PreCallVideoConfig(cameraId:encoderConfig:facingMode:optimizationMode:multiStream:bitrateMode:maxLayer:) is optional. A nil value uses the default.

cameraId: String? - The deviceId of a camera from getCameras(). An unknown ID fails the camera check.
encoderConfig: CustomCameraTrackConfig? - The resolution and frame rate. Defaults to .h720p_w1280p.
facingMode: FacingMode? - The front (.front) or back (.back) camera. Defaults to .front.
optimizationMode: PreCallOptimizationMode? - .text, .motion or .detail. It is reported to the test and does not change how the camera captures.
multiStream: Bool? - Send the video in several resolution layers. Defaults to true.
bitrateMode: BitrateMode? - Defaults to .BALANCED.
maxLayer: EncodingLayer? - The highest layer to send when multiStream is true.

PreCallAudioConfig

struct PreCallAudioConfig

How the SDK opens the microphone for the test. Every parameter of PreCallAudioConfig(microphoneId:encoderConfig:noiseConfig:) is optional.

microphoneId: String? - The deviceId of a microphone from getMics(). An unknown ID fails the microphone check.
encoderConfig: CustomMicrophoneTrackConfig? - Defaults to .speech_standard.
noiseConfig: NoiseConfig? - Noise suppression, echo cancellation and automatic gain control. highPassFilter is ignored in the test.

PreCallTestResult

struct PreCallTestResult

What runPreCallTest() returns.

aborted: Bool - true when the test was stopped before it finished, for example by stopPreCallTest().
testDuration: Int - How long the test ran, in milliseconds.
camera: PreCallMediaReport? - The camera check. nil for an audio-only test.
microphone: PreCallMediaReport? - The microphone check.
networkQuality: PreCallNetworkQuality? - The network results. nil when the network part of the test did not run.

PreCallMediaReport

struct PreCallMediaReport

The result of the camera or microphone check.

status: Bool - true when the device opened and captured media.
track: CustomStreamTrack? - The track that was tested. A track that the SDK opened stays open after the test: use it in the room, or call its stop(). nil when the device could not be opened.
captureResolution: String? - The captured size, such as "1280x720". Camera only.
fps: Int? - The captured frames per second. Camera only.
codec: String? - The codec the test used for this media.
error: PreCallTestError? - Why the check failed, when status is false.

PreCallNetworkQuality

struct PreCallNetworkQuality

The network results. onStatsChange of runPreCallTest() receives the latest values while the test runs, and the result holds the final ones.

audioOnly: Bool - true when the test ran without video.
uplink: PreCallDirectionQuality - Sending from this device.
downlink: PreCallDirectionQuality - Receiving on this device.

PreCallDirectionQuality

struct PreCallDirectionQuality

The results for one direction.

quality: Int - The score for this direction, from 1 (bad) to 5 (excellent). It is the lower of the audio and video scores. 0 means nothing was measured.
factors: [String] - What lowered the score, such as "rtt", "packetLoss" or "jitter".
audio: PreCallAudioQuality? - The audio values. nil when no audio was measured.
video: PreCallVideoQuality? - The video values. nil when no video was measured.

PreCallAudioQuality

struct PreCallAudioQuality

quality: Int - The audio score, from 1 (bad) to 5 (excellent), or 0 when unknown.
rtt: Int? - Round-trip time, in milliseconds.
bitrate: Int? - In bits per second.
packetLoss: Double? - Lost packets, in percent.
jitter: Int? - In milliseconds.
bytesSent: Int64? - Uplink only.
bytesReceived: Int64? - Downlink only.

PreCallVideoQuality

struct PreCallVideoQuality

It has the fields of PreCallAudioQuality for video, plus:

fps: Int? - Frames per second.
resolution: String? - The size, such as "1280x720".
qualityLimitationReason: String? - Why the sending quality was lowered, if it was. Uplink only.
framesDropped: Int64? - Downlink only.
freezeCount: Int64? - Downlink only.
framesDroppedRatio: Double? - Downlink only.
totalFreezesDuration: Double? - The total time the video was frozen, in seconds. Downlink only.

PreCallTestError

struct PreCallTestError: Error

The error that runPreCallTest() throws, and the error of a failed PreCallMediaReport.

code: String - The error code, such as "ERROR_PRECALL_INVALID_TOKEN". It is a string, not a number.
name: String - Always "PreCallTestError".
message: String - What went wrong.

Code	When
`ERROR_PRECALL_INVALID_TOKEN`	The token is empty.
`ERROR_PRECALL_INVALID_CONFIG`	The options break a rule, for example `samplingDuration` is out of range. `message` says which one.
`ERROR_PRECALL_AFTER_INIT`	A room is created. Run the test before `createRoom()`, or after you leave the room.
`ERROR_PRECALL_TEST_ALREADY_RUNNING`	Another test is still running.
`ERROR_PRECALL_MEDIA_CHECK_FAILED`	Neither the camera nor the microphone could be opened.
`ERROR_PRECALL_TEST_FAILED`	The network test could not be completed, for example because the server refused the token.

When only one device fails its check, the test does not throw. That device's report has status set to false and carries the error, such as ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED.

Example

Task {
    do {
        let result = try await VideoSDK.runPreCallTest(PreCallTestOptions(token: "<YOUR_TOKEN>"))
        if let camera = result.camera, !camera.status {
            print("Camera check failed: \(camera.error?.code ?? "unknown")")
        }
    } catch let error as PreCallTestError {
        print("Pre-call test failed: \(error.code) \(error.message)")
    } catch {
        print("Pre-call test failed: \(error)")
    }
}

Got a Question? Ask us on discord

PreCallTestOptions​

Example​

PreCallVideoConfig​

PreCallAudioConfig​

PreCallTestResult​

PreCallMediaReport​

PreCallNetworkQuality​

PreCallDirectionQuality​

PreCallAudioQuality​

PreCallVideoQuality​

PreCallTestError​

Example​

PreCallTestOptions

Example

PreCallVideoConfig

PreCallAudioConfig

PreCallTestResult

PreCallMediaReport

PreCallNetworkQuality

PreCallDirectionQuality

PreCallAudioQuality

PreCallVideoQuality

PreCallTestError

Example