Skip to main content
Version: 7.0

Video receiver

The video receiver feature provides a way to get video data without affecting the actual video stream. This feature allows your application to receive copies of video data and use them for various purposes.

Supported call typeMinimum SDK version
1-to-1 call, group call (conference)PlanetKit 7.0

Use cases​

The main use cases for video receivers are as follows.

  • Video analysis and quality monitoring
  • Call analytics and metrics collection
  • Thumbnail generation

Implementation steps​

To implement the video receiver feature, follow these steps.

1-to-1 call​

Implement a video receiver​

Create a class that inherits from IVideoReceiver to receive video data from 1-to-1 calls.

#include "PlanetKit.h"
#include "IVideoReceiver.h"

class VideoFrameReceiver : public PlanetKit::IVideoReceiver {
public:
    void OnVideo(const PlanetKit::SVideoFrame& sVideoFrame, PlanetKit::UserIdPtr pUserID) override {
        // Access video frame properties from SVideoFrame structure:
        // - sVideoFrame.pbuffer: Pointer to the frame buffer
        // - sVideoFrame.unBufferSize: Allocated buffer size
        // - sVideoFrame.unDataLength: Actual length (in bytes) of buffer data
        // - sVideoFrame.unWidth: Frame width in pixels
        // - sVideoFrame.unHeight: Frame height in pixels
        // - sVideoFrame.llTick: Tick count in microseconds
        // - sVideoFrame.llTimeStamp: Timestamp
        // - sVideoFrame.llDuration: Frame duration
        // - sVideoFrame.eRotation: Rotation angle
        // - sVideoFrame.bSubgroupMain: Whether frame belongs to main room
        // - sVideoFrame.szSubgroupName: Subgroup name (if bSubgroupMain is false)

        // For local user, pUserID's GetID() and GetServiceID() return empty strings
        if (pUserID && !pUserID->GetID().empty()) {
            // Peer's video frame
            // Access peer information:
            const PlanetKit::WString& userId = pUserID->GetID();
            const PlanetKit::WString& serviceId = pUserID->GetServiceID();
        } else {
            // Local user's video frame
        }

        // Use the video frame for your use case

        // Note: Copy data if you need it beyond this callback
    }
};

Set the video receiver​

Register the receiver with the PlanetKitCall (during call) or CameraController (preview mode, local video only) instance to start receiving video data.

Local video (preview mode)​
// Get camera controller instance
PlanetKit::CameraControllerPtr pCameraController = PlanetKit::PlanetKitManager::GetInstance()->GetCameraController();

// Create receiver instance
PlanetKit::IVideoReceiverPtr pMyVideoReceiver = PlanetKit::MakeAutoPtr<VideoFrameReceiver>();

// Start preview with receiver
bool success = pCameraController->StartPreview(pMyVideoReceiver);
if (!success) {
    // Handle error
}
Local video (during call)​
// Create receiver instance
PlanetKit::IVideoReceiverPtr pMyVideoReceiver = PlanetKit::MakeAutoPtr<VideoFrameReceiver>();

// Register receiver to get local video during call
bool success = m_pCall->AddMyVideoReceiver(pMyVideoReceiver);
if (!success) {
    // Handle error
}
Remote video​
// Create receiver instance
PlanetKit::IVideoReceiverPtr pPeerVideoReceiver = PlanetKit::MakeAutoPtr<VideoFrameReceiver>();

// Register receiver to get peer's video
bool success = m_pCall->AddPeerVideoReceiver(pPeerVideoReceiver);
if (!success) {
    // Handle error
}

Clear the video receiver​

Unregister the receiver to stop receiving video data.

// For local video (preview)
pCameraController->StopPreview();

// For local video (during call)
bool success = m_pCall->RemoveMyVideoReceiver(pMyVideoReceiver);
if (!success) {
    // Handle error
}

// For peer video
bool success = m_pCall->RemovePeerVideoReceiver(pPeerVideoReceiver);
if (!success) {
    // Handle error
}

Group call​

Implement a video receiver​

For group calls, use the same IVideoReceiver interface as shown in the 1-to-1 call case.

Set the video receiver​

Register the receiver with the PlanetKitConference (during conference) or CameraController (preview mode, local video only) instance to start receiving video data. For peer video, you can also use PeerControl API.

Local video (preview mode)​
// Get camera controller instance
PlanetKit::CameraControllerPtr pCameraController = PlanetKit::PlanetKitManager::GetInstance()->GetCameraController();

// Create receiver instance
PlanetKit::IVideoReceiverPtr pMyVideoReceiver = PlanetKit::MakeAutoPtr<VideoFrameReceiver>();

// Start preview with receiver
bool success = pCameraController->StartPreview(pMyVideoReceiver);
if (!success) {
    // Handle error
}
Local video (during conference)​
// Create receiver instance
PlanetKit::IVideoReceiverPtr pMyVideoReceiver = PlanetKit::MakeAutoPtr<VideoFrameReceiver>();

// Register receiver to get local video during conference
bool success = m_pConference->AddMyVideoReceiver(pMyVideoReceiver);
if (!success) {
    // Handle error
}
Remote video (using PlanetKitConference)​
// Create receiver instance
PlanetKit::IVideoReceiverPtr pPeerVideoReceiver = PlanetKit::MakeAutoPtr<VideoFrameReceiver>();

// Create user ID for the target peer
std::wstring strPeerUserId = "peer id";
std::wstring strPeerServiceId = "peer service id";
PlanetKit::UserIdPtr pPeerId = PlanetKit::UserId::Create(strPeerUserId.c_str(), strPeerServiceId.c_str());

// Register receiver to get specific peer's video
bool success = m_pConference->AddPeerVideoReceiver(pPeerID, pPeerVideoReceiver);
if (!success) {
    // Handle error
}
Remote video (using PeerControl)​
// Create an instance of PeerControl using PlanetKit::Peer::CreatePeerControl().
// For details, see https://docs.lineplanet.me/windows/getting-started/implement-first-group-video-call#create-a-peercontrol-instance.
PlanetKit::PeerControlPtr pPeerControl;

// Create receiver instance
PlanetKit::IVideoReceiverPtr pPeerVideoReceiver = PlanetKit::MakeAutoPtr<VideoFrameReceiver>();

// Register receiver through peer control
pPeerControl->RegisterReceiver(pPeerVideoReceiver);

Clear the video receiver​

Unregister the receiver to stop receiving video data.

// For local video (preview)
pCameraController->StopPreview();

// For local video (during conference)
m_pConference->RemoveMyVideoReceiver(pMyVideoReceiver);

// For peer video (using PlanetKitConference)
m_pConference->RemovePeerVideoReceiver(pPeerVideoReceiver);

// For peer video (using PeerControl)
pPeerControl->DeregisterReceiver(pPeerVideoReceiver);

The APIs related to the video receiver feature are as follows.

Common​

1-to-1 call​

Group call​