本文にスキップする
Under translation
このページは現在翻訳中です。
Version: 5.5

Custom audio 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 use audio from an external source instead of the user's microphone input.

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.

Use cases​

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

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

Implementation steps​

Here’s how to use the custom media stream feature to send audio from an external source.

Prepare a custom media stream from an external audio source​

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

// Example of audio source
const createMediaStreamFromSample = async () => {
    const audio = new Audio('/sample_audio.mp3');
    audio.loop = true;

    const audioContext = new (window.AudioContext || window.webkitAudioContext)();
    const source = audioContext.createMediaElementSource(audio);
    const destination = audioContext.createMediaStreamDestination();

    source.connect(destination);
    await audio.play();

    return destination.stream;
};

// MediaStream of audio source
const sampleCustomMediaStream = await createMediaStreamFromSample();

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 audio stream
    })
    .catch((error) => {
        // Failed to set custom audio stream
    });
Note
  • If an audio of a custom media stream is set, calling muteMyAudio() will not clear the custom media stream settings or use the audio from the microphone.
  • Changing the audio source by calling changeAudioInputDevice() or changing media source by calling disableVideo() will clear the audio 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 custom media stream with audio is set in the call​

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

if (planetKit.hasSetCustomMediaStreamWithAudio()) {
    // Currently custom media stream with audio is set
}

APIs related to the custom audio stream feature are as follows: