Pre-call Test - React Native

runPreCallTest() checks the camera and the microphone, then measures how well the network carries a call, before the user joins a room. Import it from @videosdk.live/react-native-sdk.

To learn how to use it on a join screen, see the Precall Setup guide.

runPreCallTest()

• runPreCallTest(options, onStatsChange?) runs the test and returns a Promise. The Promise resolves with the result, or rejects with a PreCallTestError.
• To cancel the test, call stopPreCallTest(). A cancelled test resolves with aborted: true.
• Only one test can run at a time. Joining a room stops a test that is still running.
• The test never asks the user for camera or microphone access. Call requestPermission() before you run it.

Parameters

options takes:

• token: String, REQUIRED. The authentication token.
• samplingDuration: Number, OPTIONAL. How long the network part of the test runs, in milliseconds, from 10000 to 120000. Default: 15000.
• videoTrack: CustomStreamTrack, OPTIONAL. A camera track from createCameraVideoTrack(). Pass the track your preview shows, so that the test does not open the camera again. The test never stops a track you pass.
• audioTrack: CustomStreamTrack, OPTIONAL. A microphone track from createMicrophoneAudioTrack(). The test never stops a track you pass.
• videoConfig: Object, OPTIONAL. The settings the test opens the camera with when you pass no videoTrack: cameraId, encoderConfig (default "h720p_w1280p"), facingMode, multiStream (default true), bitrateMode (default "BALANCED") and maxLayer, as in createCameraVideoTrack().
• audioConfig: Object, OPTIONAL. The settings the test opens the microphone with when you pass no audioTrack: microphoneId, encoderConfig (default "speech_standard") and noiseConfig, as in createMicrophoneAudioTrack().
• audioOnly: Boolean, OPTIONAL. Skips the camera test. Default: false.

The second argument, onStatsChange, is an OPTIONAL function. It is called each time the stats update while the test runs, and receives the same { audioOnly, uplink, downlink } object as networkQuality in the result. Pass it as the second argument; an onStatsChange inside options is not called.

Do not pass videoTrack and videoConfig together, or audioTrack and audioConfig together. Do not combine audioOnly: true with videoTrack or videoConfig.

Returns

• Promise<Object>, the result.

Example

import {
  runPreCallTest,
  stopPreCallTest,
  PreCallTestError,
} from "@videosdk.live/react-native-sdk";

runPreCallTest(
  { token: "<YOUR_AUTH_TOKEN>", samplingDuration: 15000 },
  (stats) => {
    console.log("Live stats:", stats);
  },
)
  .then((result) => {
    console.log("Network quality:", result.networkQuality);
  })
  .catch((err) => {
    if (err instanceof PreCallTestError) {
      console.log("Pre-call test failed:", err.code, err.message);
    }
  });

// To cancel the test before it completes:
// await stopPreCallTest();

---

stopPreCallTest()

• Stops the test that is running. That test then resolves with aborted: true.
• It does nothing when no test is running.

Returns

• Promise<void>, which resolves once the test has stopped.

---

Result

The Promise resolves with an object with these properties:

• aborted: true when the test was cancelled with stopPreCallTest(), otherwise false.
• testDuration: how long the test took, in milliseconds.
• camera: the camera result. On success, it has status: true, the tested track, its captureResolution (for example "1280x720") and fps, and the codec. When the camera could not be opened, it has status: false and an error with a code, a message and the name "PreCallTestError". It is absent with audioOnly: true, and when the test was cancelled before the camera check finished.
• microphone: the microphone result, with the same success and failure shapes as camera, without captureResolution and fps. It is absent when the test was cancelled before the microphone check finished.
• networkQuality: an object with audioOnly, uplink and downlink. It is absent when the network part did not run, for example when the test was cancelled.

A track the test opened itself is returned live as camera.track or microphone.track. It is a CustomStreamTrack: pass it to RoomProvider, or call stop() on it to close the device.

Each of networkQuality.uplink and networkQuality.downlink has:

• quality: a score from 1 (bad) to 5 (excellent), the lower of the audio and video scores. It is 0 when no score could be computed.
• factors: an array of strings that explain the score, such as rtt, packetLoss and jitter.
• audio and video: the measured stats, each with its own quality score. video is absent with audioOnly: true, and when the camera check failed.

audio has quality, rtt (ms), bitrate (bits per second), packetLoss (percent) and jitter (ms), plus bytesSent on the uplink and bytesReceived on the downlink. video has the same fields, plus fps and resolution, qualityLimitationReason on the uplink ("bandwidth", "cpu" or "none"), and framesDropped, framesDroppedRatio, freezeCount and totalFreezesDuration (seconds) on the downlink. A figure that was not measured is absent, so 0 is a real reading.

In TypeScript, the result types are exported as PreCallTestResult, PreCallMediaReport, PreCallNetworkQuality, PreCallDirectionQuality, PreCallAudioQuality, PreCallVideoQuality and PreCallTestErrorInfo.

---

PreCallTestError

PreCallTestError extends Error. Every failure of runPreCallTest() rejects with it.

• name: "PreCallTestError".
• code: String, the error code from the table below.
• message: String, the description of the error.

Code	When it occurs
ERROR_PRECALL_INVALID_TOKEN	token is missing, empty, or not a string.
ERROR_PRECALL_INVALID_CONFIG	samplingDuration is outside the 10000–120000 ms range, options that cannot go together were passed, or an encoderConfig is not a known profile.
ERROR_PRECALL_TEST_ALREADY_RUNNING	Another pre-call test is still running.
ERROR_PRECALL_AFTER_INIT	A room has already started joining. Run the test before you join, or after you leave.
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 token was rejected.
ERROR_CAMERA_NOT_FOUND / ERROR_MICROPHONE_NOT_FOUND	No such device is available.
ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED / ERROR_MICROPHONE_ACCESS_DENIED_OR_DISMISSED	Camera or microphone access has not been granted.
ERROR_CAMERA_IN_USE / ERROR_MICROPHONE_IN_USE	Another app is using the device.
ERROR_CAMERA_CONSTRAINT_NOT_SATISFIED / ERROR_MICROPHONE_CONSTRAINT_NOT_SATISFIED	The device does not support the requested settings.
ERROR_WEBCAM_TRACK_ENDED / ERROR_MICROPHONE_TRACK_ENDED	The track is not live.
ERROR_INVALID_CUSTOM_VIDEO_TRACK / ERROR_INVALID_CUSTOM_AUDIO_TRACK	The track you passed was already stopped, or has no track of that kind.
ERROR_VIDEO_SOURCE_INITIATION_FAILED / ERROR_AUDIO_SOURCE_INITIATION_FAILED	Any other failure to open the device.
ERROR_BRIDGE_UNEXPECTED	An unexpected failure that none of the codes above describes.