Custom Video Sources - Flutter

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
• Select a bitrate mode that suits your stream (e.g., high quality for viewers on strong networks, bandwidth optimized for weak ones).
• Apply real-time video effects, such as background blur, using VideoSDK.setVideoEffects().

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, bitrate mode and codec.
• This method does not ask for camera permission, so call VideoSDK.requestPermissions() before you create the track.
• If the track cannot be created, the method throws a VideoSDKError, for example 3017 without camera permission, 3021 when there is no camera, 3023 when the camera is in use, or 3026 when the camera fails to open.
• The camera opens when the track is created. If you do not use the track, call stop() on it to close the camera.

// The SDK does not ask for camera permission.
final permissions = await VideoSDK.requestPermissions(Permissions.VIDEO);
if (permissions['video'] != true) return;

try {
  CustomStreamTrack videoTrack = await VideoSDK.createCameraVideoTrack(
        encoderConfig: CustomCameraTrackConfig.h1080p_w1920p,
        multiStream: false,
        facingMode: FacingMode.FRONT,
      );
} on VideoSDKError catch (error) {
  log("Could not create the track: ${error.code} ${error.name}");
}

Use the encoder configs listed in the Custom Tracks reference. Other CustomCameraTrackConfig values, such as h1440p_w1920p, are not supported.

caution

The behavior of custom track configurations is influenced by the capabilities of the device. For example, if you set the encoder configuration to 1080p but the webcam only supports 720p, the encoder configuration will automatically adjust to the highest resolution that the device can handle, which in this case is 720p.

What is bitrateMode?

• This parameter specifies how the encoder trades video quality against bandwidth. The default is BitrateMode.BALANCED.
• BitrateMode.BANDWIDTH_OPTIMIZED : This mode uses less bandwidth at the cost of video quality.
  • Use it when hosts or viewers are on poor or unstable networks.
• BitrateMode.BALANCED : This mode balances video quality and bandwidth usage.
  • It suits most livestreams.
• BitrateMode.HIGH_QUALITY : This mode gives the best video quality and uses more bandwidth.
  • Use it when viewers are expected to have strong network connections.

What is multiStream?

• By enabling multiStream, your livestream will broadcast multiple resolutions (e.g., 720p, 360p, 180p), allowing viewers to receive the best stream quality based on their network. The multiStream : true configuration indicates that VideoSDK, by default, sends multiple resolution video streams to the server. For example, a 1280x720 track sends streams in 1280x720, 640x360 and 320x180 resolution. This enables VideoSDK to deliver the appropriate stream to each participant based on their network bandwidth. The number of streams depends on the track's resolution, as described in the Simulcast guide.

Setting multiStream : false restricts VideoSDK to send only one stream, helping to maintain quality by focusing on a single resolution.

danger

The setQuality parameter will not have any effect if multiStream is set to false.

How to Setup a Custom Video Track ?

You can plug in your custom video track either before going live or dynamically while the session is ongoing.

1. Setup during live stream initialization
2. Setup dynamically using methods

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

If you are passing camEnabled: true in the createRoom and want to use custom tracks from start of the livestream, you can pass custom track in the createRoom params as shown below.

CustomStreamTrack? videoTrack;
try {
  videoTrack = await VideoSDK.createCameraVideoTrack(
        encoderConfig: CustomCameraTrackConfig.h1080p_w1920p,
        multiStream: false,
        facingMode: FacingMode.FRONT,
      );
} on VideoSDKError catch (error) {
  log("Could not create the track: ${error.code} ${error.name}");
}

Room room = VideoSDK.createRoom(
      roomId: widget.livestreamId,
      token: widget.token,
      participantName: widget.participantName,
      micEnabled: widget.micEnabled,
      camEnabled: widget.camEnabled,
      maxResolution: MaxResolution.HD,
      defaultCamera: FacingMode.FRONT,
      multiStream: false,

      // Pass the custom track here
      customCameraTrack: videoTrack, // custom video track :: optional
    );

2. Setting up a Custom Track with methods

In order to switch tracks during the livestream, you have to pass the CustomStreamTrack in the room.enableCam() method.

note

Call disableCam() before you create a new track. While the camera is on, enableCam() with a track throws 3054 and releases the track.

try {
  // The camera must be off before you pass a new track
  if (room.isCamEnabled) await room.disableCam();

  CustomStreamTrack track = await VideoSDK.createCameraVideoTrack(
    facingMode: FacingMode.BACK,
    encoderConfig: CustomCameraTrackConfig.h1080p_w1920p,
    multiStream: true,
  );
  await room.enableCam(track);
} on VideoSDKError catch (error) {
  log("Could not enable the camera with the custom track: ${error.code} ${error.name}");
}

info

enableCam() takes only a track created with the createCameraVideoTrack method. Video from other sources, such as a stream from another plugin, is not supported.

Which configuration is suitable for me ?

In this section, the focus is on understanding participant size wise encoder(Resolution) and multiStream configuration.

API Reference

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

• Custom Video Track
• requestPermissions()
• createRoom()
• enableCam()
• disableCam()