음성 통화 중 영상 통화 활성화

음성 통화 중에 영상 통화로 전환하거나 영상 통화 중에 음성 통화로 다시 전환할 수 있습니다. 이를 각각 영상 통화를 활성화하거나 비활성화한다고 표현합니다.

영상 통화 활성화를 요청하는 절차와 피어가 요청에 응답하는 방법은 통화 유형에 따라 다를 수 있습니다. 이 페이지에서는 통화 유형에 따라 영상 통화를 활성화하거나 비활성화하는 방법을 설명합니다.

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

1대1 통화

1대1 통화에서 영상 통화를 활성화 또는 비활성화하려면 Call의 다음 메서드를 사용하세요.

메서드	설명	관련 이벤트 콜백
enableVideo()	영상 통화 활성화를 요청합니다.	evtVideoEnabledByPeer
disableVideo()	영상 통화 비활성화를 요청합니다.	evtVideoDisabledByPeer

요청자의 초기 비디오 상태

enableVideo()의 EnableVideoOptions에 불리언 유형의 cameraOn을 추가해 요청자의 초기 비디오 상태를 설정할 수 있습니다. cameraOn의 값에 따라 초기 비디오 상태는 다음과 같이 설정됩니다.

• cameraOn이 true인 경우 카메라가 켜지고 카메라에서 캡처한 비디오가 전송됩니다.
• cameraOn이 false인 경우 카메라가 꺼진 상태로 유지되고 비디오가 전송되지 않습니다.

Note

• EnableVideoOptions의 cameraOn의 기본값은 true입니다.
• cameraOn을 false로 설정하면 요청자의 비디오가 전송되지 않습니다. 이후 요청자의 비디오를 캡처하고 전송하려면 resumeMyVideo()를 호출해야 합니다.
• WebPlanetKit 5.2 이전 버전에서는 cameraOn 기능을 videoEnabled라는 이름으로 제공하고 있습니다.

응답 유형

1대1 통화에서 상대방이 영상 통화를 요청했을 때 사용자가 응답하는 유형은 콜 셋업(call setup) 과정에서 설정할 수 있습니다.

응답 유형은 RESPONSE_ENABLE_VIDEO에 다음과 같이 정의됩니다.

• PAUSE: 상대방이 영상 통화 활성화를 요청하면 사용자의 비디오를 일시 중지합니다.
• SEND: 상대방이 영상 통화 활성화를 요청하면 사용자의 비디오를 전송합니다.

다음과 같이 응답 유형을 설정할 수 있습니다.

• 발신자 측에서는 MakeCallParams의 responseOnEnableVideo로 응답 유형을 설정합니다.
• 수신자 측에서는 VerifyCallParams의 responseOnEnableVideo로 응답 유형을 설정합니다.

영상 통화 활성화

영상 통화 요청자 쪽은 항상 자신의 카메라 스트림을 보내지만, 수신자에게는 2가지 시나리오가 있습니다. 시나리오는 응답 유형의 값에 따라 선택됩니다.

• 시나리오 1: 비디오 스트리밍을 보내면서 수동으로 응답
  • 수신자의 응답 유형이 PAUSE인 경우입니다.
  • 이 시나리오에서는 비디오를 일시 중지한 상태로 영상 통화를 시작합니다. 영상 통화 요청을 받은 사용자(Client 02)가 자신의 비디오 스트림을 보낼 시점을 선택할 수 있습니다.

    

  • 관련 이벤트인 evtPeerVideoPaused과 evtPeerVideoResumed에 대한 자세한 내용은 비디오 일시 중지 이벤트를 참고하세요.
• 시나리오 2: 비디오 스트리밍을 보내면서 함께 자동으로 응답
  • 수신자의 응답 유형이 SEND인 경우입니다.
  • 이 시나리오에서는 영상 통화 요청을 받은 사용자(Client 02)가 요청을 받았을 때 자신의 비디오 스트림을 보냅니다.

    

Tip

미리 수신자의 시나리오를 선택하고 설정하는 것을 권장합니다. 즉, 응답 유형 필드값을 PAUSE 또는 SEND 등의 상수로 설정해 사용하세요.

영상 통화 비활성화

영상 통화 도중에 비디오 스트리밍을 중지하고 싶으면, disableVideo()를 호출하세요.

Note

네이티브 PlanetKit과 달리 WebPlanetKit은 1대1 통화에서 disableVideo() 호출 시 disableReason을 전달하는 기능을 지원하지 않습니다.

거절하는 흐름 예시

enableVideo() 요청의 수신자가 영상 통화에 참여하고 싶지 않으면 요청을 거절할 수 있습니다. 여기서 응답 유형은 PAUSE라고 가정합니다. 이때 통화 절차는 아래와 같아야 합니다.

카메라 초기화에 실패하는 경우

클라이언트가 evtVideoEnabledByPeer 이벤트를 받았지만 카메라를 초기화(open)하는 데 실패했다면, 클라이언트는 다시 카메라 초기화해서 성공한 다음에 resumeMyVideo()를 호출해야 합니다.

그룹 통화

그룹 통화에서 영상 통화를 활성화하거나 비활성화하려면 Conference의 다음 메서드를 사용하세요.

메서드	설명	관련 이벤트 콜백
enableVideo()	영상 통화 활성화를 요청합니다.	evtPeersVideoUpdated (state=ENABLED)
disableVideo()	영상 통화 비활성화를 요청합니다.	evtPeersVideoUpdated (state=DISABLED)

evtPeersVideoUpdated에서는 ENABLED, DISABLED, PAUSED 세 가지 상태를 전달합니다.

상태가 PAUSED인 경우 pauseReason을 참조하여 필요한 작업을 수행해야 합니다. 자세한 내용은 비디오 일시 중지 이벤트를 참고하세요.

요청자의 초기 비디오 상태

enableVideo()의 EnableVideoOptions에 불리언 유형의 cameraOn을 추가해 요청자의 초기 비디오 상태를 설정할 수 있습니다. cameraOn의 값에 따라 초기 비디오 상태는 다음과 같이 설정됩니다.

• cameraOn이 true인 경우 카메라가 켜지고 카메라에서 캡처한 비디오가 전송됩니다.
• cameraOn이 false인 경우 카메라가 꺼진 상태로 유지되고 비디오가 전송되지 않습니다.

Note

• EnableVideoOptions의 cameraOn의 기본값은 true입니다.
• cameraOn을 false로 설정하면 요청자의 비디오가 전송되지 않습니다. 이후 요청자의 비디오를 캡처하고 전송하려면 resumeMyVideo()를 호출해야 합니다.
• WebPlanetKit 5.2 이전 버전에서는 cameraOn 기능을 videoEnabled라는 이름으로 제공하고 있습니다.

영상 통화 활성화

enableVideo()를 호출하면 영상 통화 요청자는 항상 자신의 카메라 스트림을 보냅니다. 다른 참여자는 각자 requestPeerVideo()를 호출해 그 스트림을 받을지 말지 결정해야 합니다.

영상 통화 비활성화

그룹 영상 통화 도중에 비디오 스트림을 중지하려면 disableVideo()를 호출합니다.

인터페이스 변경

그룹 통화에서 영상 통화 활성화와 관련된 이벤트의 인터페이스에 다음과 같은 변경이 있었습니다.

SDK version	Group call
WebPlanetKit 5.0 이상	evtPeersVideoUpdated
WebPlanetKit 4.0~4.2	evtConfVideoUpdated

관련 API

영상 통화 활성화 및 비활성화와 관련된 API는 다음과 같습니다.

1대1 통화

Enum

• RESPONSE_ENABLE_VIDEO

메서드

• MakeCallParams의 responseOnEnableVideo
• VerifyCallParams의 responseOnEnableVideo
• Call의 enableVideo()
• Call의 disableVideo()
• Call의 resumeMyVideo()

이벤트

• evtVideoEnabledByPeer
• evtVideoDisabledByPeer

그룹 통화

메서드

• Conference의 enableVideo()
• Conference의 disableVideo()
• Conference의 resumeMyVideo()

이벤트

• evtPeersVideoUpdated

관련 문서

• 비디오 일시 중지 이벤트