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.

Video receiver for the local user​

Implement a video receiver for the local user​

Create a class that conforms to PlanetKitVideoOutputDelegate to receive the local user's video data.

import PlanetKit

class LocalVideoReceiver: NSObject, PlanetKitVideoOutputDelegate {
    func videoOutput(_ videoBuffer: PlanetKitVideoBuffer) {
        // Access video buffer properties
        let sampleBuffer = videoBuffer.sampleBuffer  // CMSampleBuffer?: video sample buffer
        let timestamp = videoBuffer.timestamp        // CMTime: timestamp
        let rotation = videoBuffer.rotation          // PlanetKitVideoRotation: rotation angle
        let position = videoBuffer.position          // PlanetKitCameraPosition: camera position
        let source = videoBuffer.source              // PlanetKitVideoSource: video source
        let sender = videoBuffer.sender              // PlanetKitUserId?: sender (nil for local user)

        // Extract pixel buffer from sample buffer if needed
        guard let sampleBuffer = sampleBuffer,
              let pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer) else {
            return
        }

        // Get video dimensions from pixel buffer
        let width = CVPixelBufferGetWidth(pixelBuffer)
        let height = CVPixelBufferGetHeight(pixelBuffer)

        // Use the video buffer for your use case
        // Note: The buffer is only valid during this callback
        // Retain the sample buffer if you need it beyond this callback
    }
}

Set the video receiver​

Register the video receiver to the local video stream to start receiving video data.

// For 1-to-1 call
let localReceiver = LocalVideoReceiver()
call.myVideoStream.addReceiver(localReceiver)

// For group call
let localReceiver = LocalVideoReceiver()
conference.myVideoStream.addReceiver(localReceiver)

Clear the video receiver​

Unregister the video receiver to stop receiving video data.

// For 1-to-1 call
call.myVideoStream.removeReceiver(localReceiver)

// For group call
conference.myVideoStream.removeReceiver(localReceiver)

Video receiver for peers​

Implement a video receiver for peers​

Create a class that conforms to PlanetKitVideoOutputDelegate to receive peer's video data.

import PlanetKit

class PeerVideoReceiver: NSObject, PlanetKitVideoOutputDelegate {
    func videoOutput(_ videoBuffer: PlanetKitVideoBuffer) {
        // Access video buffer properties
        let sampleBuffer = videoBuffer.sampleBuffer  // CMSampleBuffer?: video sample buffer
        let timestamp = videoBuffer.timestamp        // CMTime: timestamp
        let rotation = videoBuffer.rotation          // PlanetKitVideoRotation: rotation angle
        let position = videoBuffer.position          // PlanetKitCameraPosition: camera position
        let source = videoBuffer.source              // PlanetKitVideoSource: video source
        let sender = videoBuffer.sender              // PlanetKitUserId?: sender (identifies the peer)

        // Extract pixel buffer from sample buffer if needed
        guard let sampleBuffer = sampleBuffer,
              let pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer) else {
            return
        }

        // Get video dimensions from pixel buffer
        let width = CVPixelBufferGetWidth(pixelBuffer)
        let height = CVPixelBufferGetHeight(pixelBuffer)

        // Use the video buffer for your use case
        // Note: The buffer is only valid during this callback
        // Retain the sample buffer if you need it beyond this callback
    }
}

Set the video receiver​

The approach differs between 1-to-1 calls and group calls.

For 1-to-1 call​

Register the video receiver to the peer's video stream.

let peerReceiver = PeerVideoReceiver()
call.peerVideoStream.addReceiver(peerReceiver)
For group call​

Call startVideo() of PlanetKitPeerControl with the video receiver as an argument to start receiving video from a specific peer.

// Create the peer control instance for the target peer
guard let peerControl = conference.createPeerControl(peer: peer) else {
    print("Failed to create peer control")
    return
}

// Create receiver instance
let peerReceiver = PeerVideoReceiver()

// Start receiving video with specified maximum resolution
peerControl.startVideo(
    maxResolution: .vga640x480,
    delegate: peerReceiver,
    subgroupName: nil
) { success in
    if success {
        print("Successfully started receiving peer video")
    } else {
        print("Failed to start receiving peer video")
    }
}

// Alternative: Use the callback with resolution details
peerControl.startVideo(
    maxResolution: .vga640x480,
    delegate: peerReceiver,
    subgroupName: nil
) { success, requestedResolution, receivedResolution, failReason in
    if success {
        print("Started receiving peer video")
        print("Requested resolution: \(requestedResolution)")
        print("Actual resolution: \(receivedResolution)")
    } else {
        print("Failed to start receiving peer video: \(failReason)")
    }
}

Clear the video receiver​

For 1-to-1 call​

Unregister the video receiver from the peer's video stream.

call.peerVideoStream.removeReceiver(peerReceiver)
For group call​

Call stopVideo() of PlanetKitPeerControl to stop receiving video from the peer.

peerControl.stopVideo { success in
    if success {
        print("Successfully stopped receiving peer video")
    } else {
        print("Failed to stop receiving peer video")
    }
}

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

Common​

1-to-1 call​

Group call​