본문으로 건너뛰기
Version: 1.0

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

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

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

지원 통화 유형최소 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)가 자신의 비디오 스트림을 보낼 시점을 선택할 수 있습니다.
      1대1 통화 영상 통화 활성화 수동 응답 시퀀스 다이어그램
      외부 기기가 연결되지 않았다면, Client02(iOS/Android PlanetKit)는 오디오 플레이백 미디어를 스피커폰으로 바꿉니다.
    • 관련 이벤트인 onPeerVideoPaused과 onPeerVideoResumed에 대한 자세한 내용은 비디오 일시 중지 이벤트를 참고하세요.
  • 시나리오 2: 비디오 스트리밍을 보내면서 함께 자동으로 응답
    • 수신자의 응답 유형이 send인 경우입니다.
    • 이 시나리오에서는 영상 통화 요청을 받은 사용자(Client 02)가 요청을 받았을 때 자신의 비디오 스트림을 보냅니다.
      1대1 통화 영상 통화 활성화 자동 응답 시퀀스 다이어그램
      외부 기기가 연결되지 않았다면, Client02(iOS/Android PlanetKit)는 오디오 플레이백 미디어를 스피커폰으로 바꿉니다.
Tip

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

영상 통화 비활성화​

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

1대1 통��화 영상 통화 비활성화 시퀀스 다이어그램

거절하는 흐름 예시​

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

1대1 통화 비디오 통화 거절 시퀀스 다이어그램

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

클라이언트가 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는 다음과 같습니다.

공통​

1대1 통화​

Enum​

메서드​

이벤트​

그룹 통화​

메서드​

이벤트​

관련 문서​