영상 통화 활성화

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

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

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

1대1 통화

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

메서드	설명	관련 이벤트 콜백
enableVideo()	영상 통화 활성화를 요청합니다.	onVideoEnabledByPeer
disableVideo()	영상 통화 비활성화를 요청합니다. 영상 통화를 비활성화하는 이유를 제공할 수 있습니다.	onVideoDisabledByPeer

요청자의 초기 비디오 상태

enableVideo()의 initialMyVideoState 파라미터로 요청자의 초기 비디오 상태를 설정할 수 있습니다. 이 파라미터의 값은 PlanetKitInitialMyVideoState 열거형에 정의된 다음 값 중 하나가 될 수 있습니다.

• resume: 카메라가 켜지고 카메라에서 캡처한 비디오가 전송됩니다.
• pause: 카메라가 꺼진 상태로 유지되고 비디오가 전송되지 않습니다.

Note

• initialMyVideoState 파라미터의 기본값은 resume입니다.
• 이 파라미터를 pause로 설정하면 요청자의 비디오가 전송되지 않습니다. 요청자의 비디오를 캡처하고 전송하려면 이후에 PlanetKitCall의 resumeMyVideo()를 호출해야 합니다.

사용자의 응답 유형

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

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

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

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

• 발신자 측에서는 PlanetKitMakeCallParamBuilder의 setResponseOnEnableVideo()를 사용하여 응답 유형을 설정합니다.
• 수신자 측에서는 PlanetKitVerifyCallParamBuilder의 setResponseOnEnableVideo()를 사용하여 응답 유형을 설정합니다.

영상 통화 활성화

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

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

    

    외부 기기가 연결되지 않았다면, Client02(iOS/Android PlanetKit)는 오디오 플레이백 미디어를 스피커폰으로 바꿉니다.
  • 관련 이벤트인 onPeerVideoPaused과 onPeerVideoResumed에 대한 자세한 내용은 비디오 일시 중지 이벤트를 참고하세요.
• 시나리오 2: 비디오 스트리밍을 보내면서 함께 자동으로 응답
  • 수신자의 응답 유형이 send인 경우입니다.
  • 이 시나리오에서는 영상 통화 요청을 받은 사용자(Client 02)가 요청을 받았을 때 자신의 비디오 스트림을 보냅니다.

    

    외부 기기가 연결되지 않았다면, Client02(iOS/Android PlanetKit)는 오디오 플레이백 미디어를 스피커폰으로 바꿉니다.

Tip

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

영상 통화 비활성화

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

거절하는 흐름 예시

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

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

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

그룹 통화

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

메서드	설명	관련 이벤트 콜백
enableVideo()	영상 통화 활성화를 요청합니다.	onVideoUpdate (state=enabled)
disableVideo()	영상 통화 비활성화를 요청합니다. 참고: 1대1 통화와 달리 그룹 통화에서는 disableReason이 필요하지 않습니다.	onVideoUpdate (state=disabled)

onVideoUpdate에서는 enabled, disabled, paused 세 가지 상태를 전달합니다.

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

요청자의 초기 비디오 상태

enableVideo()의 initialMyVideoState 파라미터로 요청자의 초기 비디오 상태를 설정할 수 있습니다. 이 파라미터의 값은 PlanetKitInitialMyVideoState 열거형에 정의된 다음 값 중 하나가 될 수 있습니다.

• resume: 카메라가 켜지고 카메라에서 캡처한 비디오가 전송됩니다.
• pause: 카메라가 꺼진 상태로 유지되고 비디오가 전송되지 않습니다.

Note

• initialMyVideoState 파라미터의 기본값은 resume입니다.
• 이 파라미터를 pause로 설정하면 요청자의 비디오가 전송되지 않습니다. 요청자의 비디오를 캡처하고 전송하려면 이후에 PlanetKitConference의 resumeMyVideo()를 호출해야 합니다.

영상 통화 활성화

영상 통화 요청자가 enableVideo()를 호출하면 다른 참여자는 각자 PlanetKitPeerControl의 startVideo()를 호출해 그 스트림을 받을지 말지 결정해야 합니다.

Note

PlanetKitPeerControl 사용 방법에 대한 자세한 내용은 그룹 영상 통화 예제 코드를 참고하세요.

영상 통화 비활성화

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

관련 API

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

공통

• PlanetKitInitialMyVideoState

1대1 통화

Enum

• PlanetKitResponseOnEnableVideo

메서드

• PlanetKitMakeCallParamBuilder의 setResponseOnEnableVideo()
• PlanetKitVerifyCallParamBuilder의 setResponseOnEnableVideo()
• PlanetKitCall의 enableVideo()
• PlanetKitCall의 disableVideo()
• PlanetKitCall의 resumeMyVideo()

이벤트

• onVideoEnabledByPeer
• onVideoDisabledByPeer

그룹 통화

메서드

• PlanetKitConference의 enableVideo()
• PlanetKitConference의 disableVideo()
• PlanetKitConference의 resumeMyVideo()

이벤트

• onVideoUpdate

관련 문서

• 초기 비디오 상태
• 비디오 일시 중지 이벤트