Skip to main content
Version: 5.3

Custom media stream

By default, WebPlanetKit creates a set of MediaStream from the microphone and camera devices when a call starts and uses them for the call. However, you may need to change this depending on your application's requirements. One example is to display video from an external source instead of the user's video.

To meet these needs, WebPlanetKit provides the custom media stream feature that allows users to directly supply the MediaStream they want. This feature allows users to render the MediaStream they want to the WebPlanetKit module and send it to the peer.

Supported call typeMinimum SDK version
1-to-1 call, group call (conference)WebPlanetKit 5.3
Note

You cannot set a custom media stream when using the virtual background feature.

Implementation steps​

Here's how to use the custom media stream feature to display video from an external source on the screen.

Prepare a custom media stream from an external video source​

Prepare a MediaStream to be set as a custom media stream using an external video source.

// Example of video source
const videoElement = document.createElement('video');
videoElement.src = '/sample_video.mp4';
videoElement.loop = true;
videoElement.width = 1280;
videoElement.height = 720;
videoElement.autoplay = true;
videoElement.playsInline = true;

// MediaStream of video source
const sampleCustomMediaStream = videoElement.captureStream();

Start a call with a custom media stream​

You can start a call with a prepared custom media stream. Set the prepared custom media stream in customMediaStream of MakeCallParams, VerifyCallParams, or ConferenceParams.

const conferenceParams = {
    ...,
    customMediaStream: sampleCustomMediaStream
}

planetKit.joinConference(conferenceParams);

Set a custom media stream during a call​

To set and use the prepared custom media stream during a call, call setCustomMediaStream() with the custom media stream as an argument.

planetKit.setCustomMediaStream(sampleCustomMediaStream)
    .then(() => {
        // Successfully set custom media stream
    })
    .catch((error) => {
        // Failed to set custom media stream
    });
Note
  • If you call pauseMyVideo() when a video of a custom media stream is set, calling resumeMyVideo() will not resume the video. However, this does not clear custom media stream settings.
  • Changing the video source by calling disableVideo() or changeVideoInputDevice() will clear the video setting for the custom media stream.

Clear a custom media stream​

While using a custom media stream, call unsetCustomMediaStream() to go back to using MediaStream generated from microphone and camera devices.

planetKit.unsetCustomMediaStream()
    .then(() => {
        // Successfully unset custom media stream
    })
    .catch((error) => {
        // Failed to unset custom media stream
    });

Check whether a video from a custom media stream is set in the call​

To check whether a video of a custom media stream is set on a call, call hasSetCustomMediaStreamWithVideo().

if (planetKit.hasSetCustomMediaStreamWithVideo()) {
    // Currently custom media stream with video is set
}

Use cases​

You can use the custom media stream feature for the following application requirements:

  • Using a video file as a video source
  • Receiving web streaming and using it as a video source
  • Configuring and using MediaStream directly in your application