Agora Objective-C API Reference for iOS/macOS

AgoraVideoSinkProtocol Protocol Reference

Conforms to NSObject
Declared in AgoraMediaIO.h

Overview

Defines a set of protocols to implement the custom video sink and pass it to the underlying media engine to replace the default video sink.

AgoraVideoSinkProtocol allows you to implement the custom video source. By default, when you try to enable real-time communications, the Agora SDK enables the default video sink to start video rendering. By calling setLocalVideoRenderer and setRemoteVideoRenderer, you can change the default video sink. Once you implement this interface, you receive callbacks from the media engine to indicate the state of the custom video sink, the underlying media engine, and enable their synchronization. Follow each callback to handle the resource allocation, and to release and receive the video frame from the media engine. AgoraVideoSinkProtocol defines a set of protocols to create a customized video sink. The AgoraVideoFrameConsumer interface passes the video frames to the media engine, which then passes them to the renderer. After a customized video sink is created, the app passes it to the media engine, see setLocalVideoRenderer and setRemoteVideoRenderer. AgoraVideoSinkProtocol consists of the following methods:

Note: All methods defined in AgoraVideoSinkProtocol are callbacks. The media engine uses these methods to inform the customized renderer of its internal changes. An example is shown in the following steps to customize the video sink:

  1. Call bufferType and AgoraVideoPixelFormat to set the buffer type and pixel format of the video frame.
  2. Implement shouldInitialize, shouldStart, shouldStop, and shouldDispose to manage the customized video sink.
  3. Implement the buffer type and pixel format as specified in AgoraVideoFrameConsumer.
  4. Create the customized video sink object.
  5. Call the setLocalVideoRenderer and setRemoteVideoRenderer methods to set the local and remote renderers.
  6. The media engine calls functions in AgoraVideoSinkProtocol according to its internal state.

– shouldInitialize required method

Initializes the video sink.

- (BOOL)shouldInitialize

Return Value

  • YES: If the video sink is initialized.
  • NO: If the video sink is not ready or fails to initialize, the media engine stops and reports the error.

Discussion

You can also initialize the video sink before this method is called and return YES in this method.

Declared In

AgoraMediaIO.h

– shouldStart required method

Enables the video sink.

- (void)shouldStart

Discussion

Call this method when the media engine starts streaming.

  • YES: If the video sink is ready. The media engine provides the video frame to the custom video sink by calling the AgoraVideoFrameConsumer interface.
  • NO: If the video sink is not ready.

Declared In

AgoraMediaIO.h

– shouldStop required method

Disables the video sink.

- (void)shouldStop

Discussion

Call this method when the media engine stops video streaming. You should then stop the video sink.

Declared In

AgoraMediaIO.h

– shouldDispose required method

Releases the video sink.

- (void)shouldDispose

Discussion

Call this method when the media engine wants to release the video sink resources.

Declared In

AgoraMediaIO.h

– bufferType required method

Retrieves the buffer type and passes the buffer type specified in AgoraVideoBufferType to the media engine.

- (AgoraVideoBufferType)bufferType

Return Value

bufferType AgoraVideoBufferType

Declared In

AgoraMediaIO.h

– pixelFormat required method

Retrieves the pixel format and passes it to the media engine.

- (AgoraVideoPixelFormat)pixelFormat

Return Value

pixelFormat AgoraVideoPixelFormat

Declared In

AgoraMediaIO.h

– renderPixelBuffer:rotation:

(Optional) Outputs the video in the pixel buffer.

- (void)renderPixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer rotation:(AgoraVideoRotation)rotation

Parameters

pixelBuffer

Video in the pixel buffer.

rotation

Clockwise rotating angle of the video frame. See AgoraVideoRotation.

Declared In

AgoraMediaIO.h

– renderRawData:size:rotation:

(Optional) Outputs the video in the raw data.

- (void)renderRawData:(void *_Nonnull)rawData size:(CGSize)size rotation:(AgoraVideoRotation)rotation

Parameters

rawData

Raw video data.

size

Size of the raw video.

rotation

Clockwise rotating angle of the video frame. See AgoraVideoRotation.

Declared In

AgoraMediaIO.h

Is this page helpful?