Skip to main content
Version: 1.0

Enabling a video call from an audio call

You can switch to a video call in the middle of an audio call ("enable a video call") or switch back to an audio call during a video call ("disable a video call").

The process of making a request for enabling a video call and how peers respond to the request can vary depending on the call type. This page describes how to enable or disable a video call based on the call type.

Supported call typeMinimum SDK version
1-to-1 call, group call (conference)1-to-1 call: 0.8
Group call: 0.9

1-to-1 call​

To enable or disable a video call in 1-to-1 calls, use the following methods of PlanetKitCall.

MethodDescriptionRelated event callbacks
enableVideo()Makes a request for enabling a video call.onVideoEnabledByPeer
disableVideo()Makes a request for disabling a video call. You can provide a reason for disabling a video call.onVideoDisabledByPeer

Initial video state of the requester​

The initialMyVideoState parameter of enableVideo() determines the initial video state of the requester. The value of the parameter can be one of the following, which are defined in the PlanetKitInitialMyVideoState enum:

  • resume: The camera is turned on and the video captured by the camera is transmitted.
  • pause: The camera remains turned off and video is not transmitted.
Note
  • The default value of the initialMyVideoState parameter is resume.
  • If you set the parameter to pause, the requester's video is not transmitted. To capture and transmit the requester's video, you must call resumeMyVideo() of PlanetKitCall afterward.

Response types of a user​

In 1-to-1 calls, the type of user's response when a peer makes a request for enabling a video call can be set during the call setup process.

Response types are defined in PlanetKitResponseOnEnableVideo as follows:

  • pause: Pauses the user's video when a peer makes a request for enabling a video call
  • send: Sends the user's video when a peer makes a request for enabling a video call

You can set the response type as follows:

  • On the caller side, set the response type with setResponseOnEnableVideo() of PlanetKitMakeCallParamBuilder.
  • On the callee side, set the response type with setResponseOnEnableVideo() of PlanetKitVerifyCallParamBuilder.

Enabling a video call​

The video call requester always sends their video stream, but two scenarios are available on the receiver side. The scenario is selected by the value of the response type.

  • Scenario 1: Manually respond with video streaming
    • The response type of the receiver is pause.
    • In this scenario, a video call is started in a paused status. The receiver of the video call request (Client 02) can choose when to send their video stream.
      1-to-1 call enable video manual response sequence diagram
      Client 02 (Android/iOS PlanetKit) switches the audio playback medium to speakerphone if no external device is connected.
    • For more information on onPeerVideoPaused and onPeerVideoResumed, refer to Video pause event.
  • Scenario 2: Automatically respond with video streaming
    • The response type of the receiver is send.
    • The receiver of the video call request (Client 02) sends their stream when the request arrives.
      1-to-1 call enable video automatic response sequence diagram
      Client 02 (Android/iOS PlanetKit) switches the audio playback medium to speakerphone if no external device is connected.
Tip

It is recommended to select the receiver's scenario and set it up in advance. In other words, set the response type value to a constant such as pause or send.

Disabling a video call​

To stop video streaming during a video call, call disableVideo() with a disableReason value.

1-to-1 call disable video sequence diagram

Flow example for the decline case​

If the receiver of the enableVideo() request does not wish to participate in a video call, the user can decline the video call. It is assumed that the response type is pause. In this case, the call procedure should be as follows:

1-to-1 call decline video enable sequence diagram

Camera open failure case​

If a client receives the onVideoEnabledByPeer event but fails to open the camera, the client must call resumeMyVideo() after successfully reopening its camera device.

Group call​

To enable or disable a video call in group calls, use the following methods of PlanetKitConference.

MethodDescriptionRelated event callbacks
enableVideo()Makes a request for enabling a video call.onVideoUpdate
(state=enabled)
disableVideo()Makes a request for disabling a video call.
Note: Unlike 1-to-1 calls, disableReason is not required in group calls.		onVideoUpdate
(state=disabled)

There are three states delivered by onVideoUpdate: enabled, disabled, and paused.

If the state is paused, you must take necessary actions by referring to pauseReason. For more information, refer to Video pause event.

Initial video state of the requester​

The initialMyVideoState parameter of enableVideo() determines the initial video state of the requester. The value of the parameter can be one of the following, which are defined in the PlanetKitInitialMyVideoState enum:

  • resume: The camera is turned on and the video captured by the camera is transmitted.
  • pause: The camera remains turned off and video is not transmitted.
Note
  • The default value of the initialMyVideoState parameter is resume.
  • If you set the parameter to pause, the requester's video is not transmitted. To capture and transmit the requester's video, you must call resumeMyVideo() of PlanetKitConference afterward.

Enabling a video call​

After the requester calls enableVideo(), each of other participants must decide whether to receive the stream or not by calling startVideo() of PlanetKitPeerControl.

Group call enable video sequence diagram
Note

For more information on how to use PlanetKitPeerControl, refer to the group video call code example.

Disabling a video call​

To stop video streaming during a group video call, call disableVideo().

Group call disable video sequence diagram

APIs related to enabling and disabling a video call are as follows.

Common​

1-to-1 call​

Enums​

Methods​

Events​

Group call​

Methods​

Events​