Skip to main content
Version: 5.x.x

Pre-call Test - Flutter

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

Run the test before you join a room, and only one test at a time. Creating a room does not stop a test that is still running, so stop it before you create and join the room.

runPreCallTest()​

VideoSDK.runPreCallTest(options, {onStatsChange}) returns a Future<PreCallTestResult>.

  • It completes with the PreCallTestResult when the test ends, also when it is stopped. It fails with a PreCallTestException when the test fails.
  • onStatsChange receives the latest PreCallNetworkQuality while the test measures the network.
  • VideoSDK.stopPreCallTest() stops the running test and completes once it has ended. The test's Future then completes with aborted set to true. When the stop fails, it throws a PreCallTestException.

Example​

try {
  final PreCallTestResult result = await VideoSDK.runPreCallTest(
    PreCallTestOptions(token: "<TOKEN>"),
    onStatsChange: (PreCallNetworkQuality stats) {
      print("Uplink quality so far: ${stats.uplink.quality}");
    },
  );
  print("Downlink quality: ${result.networkQuality?.downlink.quality}");
} on PreCallTestException catch (error) {
  print("Pre-call test failed: ${error.code} ${error.message}");
}

// To stop it early, for example when the user leaves the screen:
await VideoSDK.stopPreCallTest();

PreCallTestOptions​

The options that you pass to runPreCallTest(). 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 audio only. Defaults to false.
  • videoTrack: CustomStreamTrack? - A camera track that you created with createCameraVideoTrack(). The test uses it as it is and does not stop it.
  • audioTrack: CustomStreamTrack? - A microphone track that you created with createMicrophoneAudioTrack(). The test uses it as it is and does not stop it.
  • videoConfig: PreCallVideoConfig? - How the test opens the camera when you pass no videoTrack.
  • audioConfig: PreCallAudioConfig? - How the test opens the microphone when you pass no audioTrack.

Pass videoTrack or videoConfig, not both, and audioTrack or audioConfig, not both. With audioOnly: true, pass no video option. Otherwise the test fails with ERROR_PRECALL_INVALID_CONFIG.

Example​

final PreCallTestOptions options = PreCallTestOptions(
  token: "<TOKEN>",
  samplingDuration: 20000,
  videoConfig: const PreCallVideoConfig(
    encoderConfig: CustomCameraTrackConfig.h540p_w960p,
    facingMode: FacingMode.FRONT,
  ),
  audioConfig: const PreCallAudioConfig(
    encoderConfig: CustomMicrophoneTrackConfig.SPEECH_STANDARD,
  ),
);

PreCallVideoConfig​

How the test opens the camera. Every field is optional, and a field you leave out uses the default.

  • cameraId: String? - The deviceId of a camera from getCameras().
  • encoderConfig: CustomCameraTrackConfig? - The resolution. Defaults to h720p_w1280p. Use one of the values listed in Custom Tracks.
  • facingMode: FacingMode? - The front or back camera, when you pass no cameraId. Defaults to FacingMode.FRONT.
  • multiStream: bool? - Send the video in several resolution layers. Defaults to true.
  • bitrateMode: BitrateMode? - Defaults to BitrateMode.BALANCED.
  • maxLayer: EncodingLayer? - The highest number of layers to send, EncodingLayer.MAX_LAYER_2 or EncodingLayer.MAX_LAYER_3, when multiStream is true.

PreCallAudioConfig​

How the test opens the microphone. Every field is optional.

  • microphoneId: String? - The deviceId of a microphone from getMics().
  • encoderConfig: CustomMicrophoneTrackConfig? - Defaults to SPEECH_STANDARD.
  • noiseConfig: NoiseConfig? - noiseSuppression, echoCancellation, autoGainControl and highPassFilter.

PreCallTestResult​

What runPreCallTest() completes with.

  • aborted: bool - true when the test was stopped before it finished.
  • testDuration: int - How long the test ran, in milliseconds.
  • camera: PreCallMediaReport? - The camera check. null for an audio-only test, or when the test was stopped before the camera was checked.
  • microphone: PreCallMediaReport? - The microphone check. null when the test was stopped before the microphone was checked.
  • networkQuality: PreCallNetworkQuality? - The network results. null when the network part of the test did not run, for example because the test was stopped.
  • toJson(): Map<String, dynamic> - The whole result as a read-only map, for logging or for your server. It does not include the tracks.

PreCallMediaReport​

The result of the camera or the microphone check.

  • status: bool - true when the device opened and captured media.
  • track: CustomStreamTrack? - The track that was tested. If you passed videoTrack or audioTrack, it is that same track. If the test opened the device itself, it is a new track that stays open after the test and belongs to your app: pass it to createRoom() as customCameraTrack or customMicrophoneTrack, or call its stop(). null 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 sent the media with, such as "VP8" or "opus". Set only after the network part of the test succeeded.
  • error: PreCallTestException? - Why the check failed, when status is false.

PreCallNetworkQuality​

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

PreCallDirectionQuality​

The results for one direction.

  • quality: int - The score, from 1 (bad) to 5 (excellent). 0 means it is not known yet.
  • factors: List<String> - What lowered the score, such as rtt, packetLoss, jitter, bandwidth or freeze. Empty when nothing did.
  • audio: PreCallAudioQuality? - The audio values. null when no audio was measured.
  • video: PreCallVideoQuality? - The video values. null when no video was measured.

PreCallAudioQuality​

  • quality: int - The audio score, from 1 (bad) to 5 (excellent), or 0 when it is not known.
  • rtt: int? - Round-trip time, in milliseconds.
  • bitrate: int? - In bits per second.
  • packetLoss: double? - Lost packets, in percent.
  • jitter: int? - In milliseconds.
  • bytesSent: int? - Uplink only.
  • bytesReceived: int? - Downlink only.

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 sent video was limited: none, bandwidth, cpu or other. Uplink only.
  • framesDropped: int? - Downlink only.
  • freezeCount: int? - Downlink only.
  • framesDroppedRatio: double? - Downlink only.
  • totalFreezesDuration: double? - How long the video was frozen in total. Downlink only.

PreCallTestException​

The exception that runPreCallTest() fails with, and the error of a PreCallMediaReport whose check failed. VideoSDK.stopPreCallTest() throws it too.

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

Pre-call test errors lists the codes. When the test opens the devices itself and only one of them fails, the test still completes. That device's report has status set to false and an error with a code such as ERROR_CAMERA_IN_USE.

Example​

try {
  final PreCallTestResult result = await VideoSDK.runPreCallTest(
    PreCallTestOptions(token: "<TOKEN>"),
  );
  final PreCallMediaReport? camera = result.camera;
  if (camera != null && !camera.status) {
    print("Camera check failed: ${camera.error?.code}");
  }
} on PreCallTestException catch (error) {
  print("Pre-call test failed: ${error.code} ${error.message}");
}

Got a Question? Ask us on discord

Last updated on by saksham-videosdk
Previous
Intro to Video SDK Room Class
Next

Was this helpful?

Not helpfulHelpful