Custom Video Sources - iOS

To deliver high-quality livestreams, it's essential to fine-tune the video tracks being broadcasted. Whether you’re hosting a webinar, or streaming an event, using custom video tracks gives you better control over stream quality and performance.

Custom Video Track

In a livestream, your webcam feed plays a central role. With custom video tracks, you can:

• Define the resolution and frame rate using encoder settings, and the camera used for the livestream.

How to Create a Custom Video Track ?

• You can create a Video Track using createCameraVideoTrack() method of VideoSDK class.

• This method can be used to create video track using different encoding parameters, camera facing mode and the camera to use (cameraId). It returns a CustomStreamTrack, or throws if the track can't be created.

• It is async throws, so call it with try await inside a Task.

• To use a specific camera, pass its deviceId from VideoSDK.getCameras() as cameraId. When it is set, it decides the camera instead of facingMode. If no camera matches, the method throws ERROR_INVALID_CUSTOM_TRACK_CONFIG.

• The camera opens when the track is created, but the method never asks for camera permission. Ask for permission first, for example with await AVCaptureDevice.requestAccess(for: .video), and create the track after access is granted. Until then, the method throws ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED.

• The method waits up to 2 seconds for the camera to open, and throws the errors that happen in that time, such as ERROR_CAMERA_IN_USE. If the camera fails after that, the track ends and its onEnded handler receives the error.

• If you create a track and don't use it, call stop() on it to release the camera.

Example

Swift

Task {
do {
  let videoMediaTrack = try await VideoSDK.createCameraVideoTrack(
    // This will accept the enum value of CustomCameraTrackConfig which contains resolution (height x width) of video you want to capture.
    encoderConfig: .h720p_w1280p, // .h540p_w960p | .h720p_w1280p ... // Default : .h720p_w1280p

    // It will specify whether to use front or back camera for the video track.
    facingMode: .front, // .back,  Default : .front

    // We will discuss this parameter in next step.
    multiStream: true, // false,  Default : true

    // Optional: the deviceId of the camera to use, from VideoSDK.getCameras(). When set, it decides the camera instead of facingMode.
    cameraId: nil, // Default : nil

    // The video codec. H264, VP9 and AV1 need multiStream: false.
    codec: .VP8 // .H264 | .VP9 | .AV1 (use these with multiStream: false), Default : .VP8
  )
  // Pass videoMediaTrack to createRoom() or changeCam(customCameraTrack:)
} catch {
  print("Failed to create the video track: \(error)")
}
}

caution

The capabilities of the device have a significant impact on how custom track configurations behave. Assuming a case where you set encoder configuration to 1080p but the webcam only supports 720p, then VideoSDK captures at the highest resolution the webcam supports, which is 720p, and scales the video up to 1080p. The video is sent at 1080p, but it is not sharper than what the webcam captured.

What is multiStream?

• It will specify if the stream should send multiple resolution layers or single resolution layer.

multiStream : true By default, VideoSDK sends multiple resolution video streams to the server (whether you are using custom video track or not). For instance, if your video track is 720p, VideoSDK sends 720p along with 360p and 180p streams. This allows VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth.

multiStream : false If you want to restrict the VideoSDK to send only one stream to maintain quality, you can set multiStream to false.

danger

setQuality would not have any effect if multiStream is set to false.

note

Currently, VideoSDK supports multiStream only for VP8. Set multiStream: false when you create an H264, VP9 or AV1 track. Otherwise VideoSDK sends a single stream and reports ERROR_MULTISTREAM_NOT_SUPPORTED through onError(error:).

How to Setup a Custom Video Track ?

The custom track can be set up both before and after the initialization of the Room.

1. Setting up a Custom Track during the initialization of a room
2. Setting up a Custom Track with methods

1. Setting up a Custom Track during the initialization of a room

If you are passing camEnabled: true in createRoom() and want to use custom tracks from the start of the live stream, you can pass the custom track in customCameraTrack as shown below.

caution

• With camEnabled: false, the camera stays off when you join, so the custom track is not sent. When you turn the camera on later with enableCam(), VideoSDK uses the settings of this track.

• Custom video track's facingMode (or cameraId, when set) takes precedence over the defaultCamera specified in createRoom(). Ensure you set facingMode appropriately to achieve the desired camera orientation.

Example

Swift

import VideoSDKRTC

Task {
    do {
        let videoMediaTrack = try await VideoSDK.createCameraVideoTrack(
            encoderConfig: .h720p_w1280p,
            facingMode: .front,
            multiStream: true,
            codec: .VP8 // .H264 | .VP9 | .AV1 with multiStream: false
        )

        let room = try VideoSDK.createRoom(
            roomId: roomId,
            token: token,
            participantName: name,
            micEnabled: micEnabled, // optional, default: true
            camEnabled: cameraEnabled, // optional, default: true
            // Pass the custom track here which will be used when the camera is auto started
            customCameraTrack: videoMediaTrack
        )
    } catch {
        print("Failed to set up the live stream: \(error)")
    }
}

2. Setting up a Custom Track with methods

In order to switch tracks during the live stream, you have to pass the new track to the changeCam(customCameraTrack:) method of Room. If the camera is on, VideoSDK turns it off and on again with the new track, so the new settings apply at once. If the camera is off, it turns on with the new track.

You can also pass a track to enableCam(customCameraTrack:) when you turn the camera on. Both methods are async throws, so call them with try await inside a Task.

tip

If changeCam(customCameraTrack:) fails, VideoSDK stops the track you passed. Create a new track before you try again.

Example

Swift

import VideoSDKRTC

@IBAction func changeVideoTrackTapped(_ sender: Any) {
    Task {
        do {
            let videoMediaTrack = try await VideoSDK.createCameraVideoTrack(
                encoderConfig: .h360p_w480p,
                facingMode: .front,
                multiStream: false,
                codec: .H264 // .VP8
            )
            try await self.room?.changeCam(customCameraTrack: videoMediaTrack)
        } catch {
            print("Failed to change the video track: \(error)")
        }
    }
}

Which Configuration is suitable for Device ?

This section shows the encoder(Resolution) and multiStream configuration to use for each number of participants.

API Reference

The API references for all the methods and events utilised in this guide are provided below.

• createCameraVideoTrack()
• createRoom()
• changeCam()
• enableCam()