Version: 6.0

커스텀 오디오 스트림

WebPlanetKit은 통화 시작 시 기본적으로 마이크와 카메라 장치에서 MediaStream을 생성해 통화에 사용합니다. 하지만 애플리케이션의 요구사항에 따라 이를 변경해야 할 필요가 있을 수 있습니다. 사용자의 마이크 입력 대신 외부 소스에서 가져온 오디오를 사용하는 것이 한 가지 예입니다.

이러한 요구를 충족할 수 있도록 WebPlanetKit은 원하는 MediaStream을 직접 공급할 수 있는 커스텀 미디어 스트림(custom media stream) 기능을 제공합니다. 이 기능을 이용해 사용자가 원하는 MediaStream을 직접 WebPlanetKit 모듈에 렌더링하고 상대방에게 전달할 수 있습니다.

지원 통화 유형	최소 SDK 버전
1대1 통화, 그룹 통화(컨퍼런스)	WebPlanetKit 5.3

Note

가상 배경 기능을 사용할 때에는 커스텀 미디어 스트림을 설정할 수 없습니다.

활용 사례

아래와 같은 애플리케이션 요구사항이 있을 때 커스텀 미디어 스트림를 활용해 구현할 수 있습니다.

오디오 파일을 오디오 소스로 사용하고자 할 때
웹 스트리밍을 받아서 오디오 소스로 사용하고자 할 때
애플리케이션에서 직접 MediaStream을 구성하고 사용하고 싶을 때

구현 절차

커스텀 미디어 스트림 기능을 이용해 외부 소스에서 가져온 오디오를 전송하는 방법은 다음과 같습니다.

외부 오디오 소스로 커스텀 미디어 스트림 준비하기

외부 오디오 소스를 사용해 커스텀 미디어 스트림으로 설정할 MediaStream을 준비하세요.

// 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();

커스텀 미디어 스트림으로 통화 시작하기

준비한 커스텀 미디어 스트림으로 통화를 시작할 수 있습니다. MakeCallParams나 VerifyCallParams 혹은 ConferenceParams의 customMediaStream에 준비한 커스텀 미디어 스트림을 설정하세요.

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

planetKit.joinConference(conferenceParams);

통화 중 커스텀 미디어 스트림 설정하기

통화 중에 준비한 커스텀 미디어 스트림을 설정해 사용하려면 커스텀 미디어 스트림을 인자로 넣고 setCustomMediaStream()를 호출하세요.

planetKit.setCustomMediaStream(sampleCustomMediaStream)
    .then(() => {
        // Successfully set custom audio stream
    })
    .catch((error) => {
        // Failed to set custom audio stream
    });

Note

커스텀 미디어 스트림의 오디오가 설정돼 있을 때에는 muteMyAudio()를 호출하더라도 커스텀 미디어 스트림 설정이 해제되지 않으며 마이크의 오디오가 사용되지 않습니다.
changeAudioInputDevice()를 호출해서 오디오 소스를 변경하거나 disableVideo()를 호출해서 미디어 소스를 변경하는 경우 커스텀 미디어 스트림의 오디오 설정이 해제됩니다.

커스텀 미디어 스트림 해제하기

커스텀 미디어 스트림을 사용하다가 다시 마이크와 카메라 장치에서 생성된 MediaStream을 사용하려면 unsetCustomMediaStream()을 호출하세요.

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

통화에 커스텀 미디어 스트림의 오디오가 설정돼 있는지 확인하기

통화에 커스텀 미디어 스트림의 오디오가 설정돼 있는지 확인하려면 hasSetCustomMediaStreamWithAudio()를 호출하세요.

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

활용 사례​

구현 절차​

외부 오디오 소스로 커스텀 미디어 스트림 준비하기​

커스텀 미디어 스트림으로 통화 시작하기​

통화 중 커스텀 미디어 스트림 설정하기​

커스텀 미디어 스트림 해제하기​

통화에 커스텀 미디어 스트림의 오디오가 설정돼 있는지 확인하기​

관련 API​