그룹 영상 통화
그룹 영상 통화를 구현하는 예제 코드입니다.
필수 조건
시작하기 전에 다음 작업을 수행해야 합니다.
- PlanetKit을 초기화하세요.
- 적절한 액세스 토큰을 획득하세요.
- 그룹 통화 흐름에서 전반적인 API 사용 과정을 확인하세요.
오디오 및 비디오 엘리먼트 구현
그룹 영상 통화에서 그룹 음성을 재생하기 위한 오디오 엘리먼트와 비디오 영상을 재생할 비디오 엘리먼트를 준비합니다.
<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는 생략합니다.
- 로컬 사용자의 초기 오디오 상태는
ConferenceParams의micOn으로 설정할 수 있습니다.micOn의 기본값은true입니다.micOn을false로 설정하면 통화 시작 시 마이크가 활성화되지 않고 오디오가 전송되지 않습니다. 통화가 연결된 후muteMyAudio(false)를 호출하면 로컬 사용자의 오디오를 전송할 수 있습니다.
- 로컬 사용자의 초기 비디오 상태는
ConferenceParams의cameraOn으로 설정할 수 있습니다.cameraOn의 기본값은true입니다.cameraOn을false로 설정하면 통화 시작 시 카메라가 켜지지 않고 비디오가 전송되지 않습니다. 통화가 연결된 후resumeMyVideo()를 호출하면 로컬 사용자의 비디오를 전송할 수 있습니다.
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',
micOn: false,
cameraOn: false,
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,
evtMyAudioMuted: () => {},
evtMyAudioUnmuted: () => {},
evtMyVideoStatusUpdated: (myVideoStatus) => {}
},
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
});
로컬 사용자의 미디어 상태 확인(선택 사항)
delegate에 등록한 evtMyAudioMuted와 evtMyAudioUnmuted 콜백은 로컬 사용자의 오디오가 음 소거되거나 음 소거 해제될 때 호출됩니다. evtMyVideoStatusUpdated 콜백은 로컬 사용자의 비디오 상태가 변경될 때 호출됩니다. 이 이벤트는 UI 업데이트 등에 활용할 수 있습니다.
getMyMediaStatus()를 호출하면 현재 로컬 사용자의 미디어 상태를 즉시 확인할 수 있습니다(통화가 연결되지 않은 경우 undefined 반환).
const status = planetKit.getMyMediaStatus();
if (status) {
// status.isMyAudioMuted: Whether the local user's audio is muted
// status.myVideoStatus.state: The local user's video state
// status.myVideoStatus.pauseReason: The reason the video is paused, if applicable
}
그룹 통화 퇴장
그룹 통화에서 퇴장하려면 leaveConference()를 호출하세요.
planetKit.leaveConference();