본문으로 건너뛰기
Version: 5.3

그룹 영상 통화

그룹 영상 통화를 구현하는 예제 코드입니다.

필수 조건​

시작하기 전에 다음 작업을 수행해야 합니다.

오디오 및 비디오 엘리먼트 구현​​

그룹 영상 통화에서 그룹 음성을 재생하기 위한 오디오 엘리먼트와 비디오 영상을 재생할 비디오 엘리먼트를 준비합니다.

<html>
    <div>
        <video id="my-video" muted autoplay playsinline></video>
        <audio id="room-audio" autoplay></audio>
    </div>
</html>

<script>
    const myVideoElement = document.getElementById("my-video");
    const roomAudioElement = document.getElementById("room-audio");
</script>

로컬 사용자의 비디오 미리보기(선택 사항)​

WebPlanetKit에서는 사용자가 MediaStream을 쉽게 생성하고 관리할 수 있는 MediaStreamManager를 제공합니다. 이 MediaStreamManager를 이용하면 로컬 사용자가 통화 세션과 관계없이 자신의 비디오를 미리 볼 수 있는 비디오 미리보기 기능을 제공할 수 있습니다.

MediaStreamManager를 활용한 비디오 미리보기 예제 코드를 살펴보겠습니다. 먼저 비디오 미리보기 영상을 재생할 비디오 엘리먼트를 준비합니다.

<html>
    <div>
        <video id="preview-video" muted autoplay playsinline></video>
    </div>
</html>

MediaStreamManager를 사용해 'preview-video' 비디오 엘리먼트에 영상을 재생합니다.

// Init MediaStreamManager
import { MediaStreamManager } from "@line/planetKit";

const mediaStreamManager = new MediaStreamManager();
const previewVideoElement = document.getElementById('preview-video');

// Create media stream with param
const mediaStreamParam = {
  videoElement: previewVideoElement
};
const mediaStream = await mediaStreamManager.createMediaStream(mediaStreamParam);

비디오 미리보기 기능에서 사용한 MediaStreamManager를 joinConference()의 ConferenceParams에 추가하면 비디오 미리보기를 위해 생성한 MediaStream을 통화에도 사용할 수 있습니다.

만약 생성한 MediaStreamManager를 통화에 사용하지 않는다면 MediaStreamManager의 releaseMediaStream()을 사용해 정리합니다.

그룹 통화 입장​

그룹 통화 생성과 설정을 위한 ConferenceParams 객체를 만듭니다. 이 예제에서는 앞서 비디오 미리보기 기능에서 생성한 MediaStreamManager를 사용합니다. 만약 MediaStreamManager로 만든 MediaStream을 사용하지 않는다면 mediaStreamManager는 생략합니다.

const onEvtConnected = () => {
    // Triggered when conference join is completed
};

const onEvtDisconnected = (disconnectedParam) => {
    // Triggered when the local user leaves the conference
};

const onEvtPeerListUpdated = (peerListUpdatedParam) => {
    // Triggered when one or more peers join or leave
};

const onEvtPeersVideoUpdated = (peersVideoUpdatedParam) => {
    // Triggered when the video status of one or more peers are changed
};

const conferenceParams = {
    myId: 'MY_ID',
    myServiceId: 'MY_SERVICE_ID',
    roomId: 'ROOM_ID',
    roomServiceId: 'ROOM_SERVICE_ID',
    accessToken: 'ACCESS_TOKEN',
    mediaType: 'video',
    mediaHtmlElement: {
        myVideo: myVideoElement
        roomAudio: roomAudioElement
    },
    delegate: {
        // For each of the following, add your own implementation or assign an event handler that matches the signature
        evtConnected: onEvtConnected,
        evtDisconnected: onEvtDisconnected,
        evtPeerListUpdated: onEvtPeerListUpdated,
        evtPeersVideoUpdated: onEvtPeersVideoUpdated
    },
    mediaStreamManager: mediaStreamManager // Optional
};

ConferenceParams 객체를 인자로 joinConference()를 호출하세요. joinConference() 호출에 실패한 경우 아래 두 경우로 나눠 실패 원인을 확인할 수 있습니다.

  • 통화 입장 시도 시 실패하는 경우
    • Promise.reject()로 반환되는 JoinConferenceError에서 START_FAIL_REASON을 확인해 실패 원인을 파악할 수 있습니다.
  • 통화 입장 후 실패하는 경우
    • 통화 연결 후에는 ConferenceParams.delegate의 evtDisconnected 이벤트를 통해 실패 원인을 확인할 수 있습니다. 통화 종료 이유와 관련된 자세한 내용은 통화 종료 이유를 참고하세요.
planetKit.joinConference(conferenceParams)
    .then(() => {
        // Successfully joined a conference
    })
    .catch((joinConferenceError) => {
        // Failed to join a conference
        // joinConferenceError.reason: START_FAIL_REASON
        // joinConferenceError.message: A descriptive message about the failure.
    });

상대방 그룹 통화 입장 및 퇴장 확인​

상대방이 그룹 통화에 입장하거나 퇴장하면 ConferenceParams.delegate의 evtPeerListUpdated 이벤트를 통해 확인할 수 있습니다.

// Example function called in the evtPeerListUpdated callback.
const onEvtPeerListUpdated = (peerListUpdatedParam) => {
    // Triggered when one or more peers join or leave
    const { addedPeers, removedPeers, totalPeersCount } = peerListUpdatedParam;

    // Process added peers
    addedPeers.forEach(peer => {
        console.log(`${peer.userId} is added`);
    });

    // Process removed peers
    removedPeers.forEach(peer => {
        console.log(`${peer.userId} is removed`);
    });
};

상대방 비디오를 수신하고 렌더링​

상대방의 비디오를 수신하고 렌더링하려면 상대방의 사용자 ID와 요청할 해상도, 비디오를 렌더링할 비디오 엘리먼트를 인자로 requestPeerVideo()를 호출하세요.

<html>
    <div>
        <video id="peer-video" muted autoplay playsinline></video>
    </div>
</html>
// Example params to request peer video
const peerVideoElement = document.getElementById('peer-video');
const requestVideoParams = {
    userId: 'userId',
    resolution: 'vga',
    videoViewElement: peerVideoElement
};

// Request the video of peer
planetKit.requestPeerVideo(requestVideoParams)
    .then(() => {
        // Successfully requested peer's video
    })
    .catch((error) => {
        // Failed to request peer's video
    });

상대방 비디오를 렌더링하는 뷰 변경​

상대방의 비디오를 렌더링하는 비디오 엘리먼트를 변경하려면 상대방의 사용자 ID와 새 비디오 엘리먼트를 인자로 changePeerView()를 호출하세요. 이때 cleanOldElement 인자를 함께 전달하면 이전에 렌더링하던 비디오 엘리먼트의 비디오를 정지하고 렌더링되던 비디오를 제거합니다.

const newPeerVideoElement = document.getElementById('new-peer-video');
const cleanOldElement = true;

planetKit.changePeerView(userId, newPeerVideoElement, cleanOldElement)
    .then(() => {
        // Successfully changed peer's view
    })
    .catch((error) => {
        // Failed to change peer's view
    });

상대방 비디오 수신 중지​

상대방 비디오 수신을 중지하려면 상대방 사용자 ID를 인자로 removePeerVideo()를 호출하세요.

planetKit.removePeerVideo(userId)
    .then(() => {
        // Successfully removed peer's video
    })
    .catch((error) => {
        // Failed to remove peer's video
    });

그룹 통화 퇴장​

그룹 통화에서 퇴장하려면 leaveConference()를 호출하세요.

planetKit.leaveConference();

관련 예제 코드​

관련 문서​