AgoraVideoDataFrameProtocol Category Reference

Conforms to NSObject
Declared in AgoraVideoFrame.h

Overview

The protocol of the raw video data.

Note: This protocol applies to iOS only.

– onCaptureVideoFrame: required method

Gets the video data captured by the local camera.

- (BOOL)onCaptureVideoFrame:(AgoraVideoDataFrame *)videoFrame

Parameters

videoFrame

The video frame. See AgoraVideoDataFrame.

Return Value

  • YES: If the video frame processing fails, the video frame is not passed back to the SDK.
  • NO: If the video frame processing fails, the video frame is still passed back to the SDK.

Availability

v3.4.5

After you successfully register the raw video frame protocol, the SDK triggers this callback each time a video frame is received. You can get the video data captured by the local camera in videoFrame and then process the video data according to your scenario. After processing, you can use videoFrame to pass the processed video data back to the SDK.

Note:

  • This callback applies to iOS only.
  • If you get the video data in RGBA color encoding format, Agora does not support using this callback to send the processed data in RGBA color encoding format back to the SDK.
  • The video data obtained through this callback has not undergone preprocessing, such as watermarking, cropping content, rotating, or image enhancement.

Declared In

AgoraVideoFrame.h

– onPreEncodeVideoFrame: required method

Gets the local pre-encoded video data.

- (BOOL)onPreEncodeVideoFrame:(AgoraVideoDataFrame *)videoFrame

Parameters

videoFrame

The video frame. See AgoraVideoDataFrame.

Return Value

  • YES: If the video frame processing fails, the video frame is not passed back to the SDK.
  • NO: If the video frame processing fails, the video frame is still passed back to the SDK.

Availability

v3.4.5

After you successfully register the raw video frame protocol and use getObservedFramePosition to set the observation AgoraVideoFramePositionPreEncoder (1 << 2), the SDK triggers this callback each time a video frame is received. You can get the local pre-encoded video data in videoFrame and then process the video data according to your scenario. After processing, you can use videoFrame to pass the processed video data back to the SDK.

Note:

  • This callback applies to iOS only.
  • If you get the video data in RGBA color encoding format, Agora does not support using this callback to send the processed data in RGBA color encoding format back to the SDK.
  • The video data obtained through this callback has not undergone preprocessing, such as watermarking, cropping content, rotating, or image enhancement.

Declared In

AgoraVideoFrame.h

– onRenderVideoFrame:forUid: required method

Gets the incoming remote video data.

- (BOOL)onRenderVideoFrame:(AgoraVideoDataFrame *)videoFrame forUid:(unsigned int)uid

Parameters

videoFrame

The video frame. See AgoraVideoDataFrame.

uid

The user ID of the remote user.

Return Value

  • YES: If the video frame processing fails, the video frame is not passed back to the SDK.
  • NO: If the video frame processing fails, the video frame is still passed back to the SDK.

Availability

v3.4.5

After you successfully register the raw video frame and set the return value of isMultipleChannelFrameWanted as NO, the SDK triggers this callback each time a video frame is received. You can get the incoming remote video data in videoFrame and then process the video data according to your scenario. After processing, you can use videoFrame to pass the processed video data back to the SDK.

Note:

  • This callback applies to iOS only.
  • If you get the video data in RGBA color encoding format, Agora does not support using this callback to send the processed data in RGBA color encoding format back to the SDK.

Declared In

AgoraVideoFrame.h

– getVideoFormatPreference required method

Sets the format of the raw video data output by the SDK.

- (AgoraVideoFrameType)getVideoFormatPreference

Return Value

The color encoding format of the raw video data output by the SDK. See AgoraVideoFrameType.

Availability

v3.4.5

If you want to get raw video data in a color encoding format other than YUV 420, you need to implement the getVideoFormatPreference callback in AgoraVideoDataFrameProtocol. After you successfully register the raw video frame protocol, the SDK triggers this callback each time a video frame is received. You need to set the desired color encoding format of the video data in the return value of this callback.

Discussion

Note: This method applies to iOS only.

Declared In

AgoraVideoFrame.h

– getRotationApplied required method

Sets whether to rotate the raw video data output by the SDK.

- (BOOL)getRotationApplied

Return Value

Whether to rotate the raw video data output by the SDK:

  • YES: Rotate the raw video data.
  • NO: (Default) Do not rotate the raw video data.

Availability

v3.4.5

If you want to get raw video data that has been rotated according to the value of rotation in AgoraVideoDataFrame, you need to implement the getRotationApplied callback in AgoraVideoDataFrameProtocol. After you successfully register the raw video frame protocol, the SDK triggers this callback each time a video frame is received. You need to set whether to rotate the observed raw video data in the return value of this callback.

Note:

  • This method applies to iOS only.
  • This function supports video data in RGBA and YUV 420 color encoding formats only.

Declared In

AgoraVideoFrame.h

– getMirrorApplied required method

Sets whether to mirror the raw video data output by the SDK.

- (BOOL)getMirrorApplied

Return Value

Whether to mirror the raw video data output by the SDK:

  • YES: Mirror the raw video data.
  • NO: (Default) Do not mirror the raw video data.

Availability

v3.4.5

If you want to get the mirrored raw video data, you need to implement the getMirrorApplied callback in AgoraVideoDataFrameProtocol. After you successfully register the raw video frame observer, the SDK triggers this callback each time a video frame is received. You need to set whether to mirror the observed raw video data in the return value of this callback.

Note:

  • This method applies to iOS only.
  • This function supports video data in RGBA and YUV 420 color encoding formats only.

Declared In

AgoraVideoFrame.h

– getObservedFramePosition required method

Sets the video observation positions.

- (AgoraVideoFramePosition)getObservedFramePosition

Return Value

The bit mask of the observation positions. See AgoraVideoFramePosition.

Availability

v3.4.5

After you successfully register the raw video frame observer, the SDK uses the getObservedFramePosition callback to determine at each specific video-frame processing node whether to trigger the following callbacks:

You can set the position or positions that you want to observe by modifying the return value of getObservedFramePosition according to your scenario.

Note:

  • This method applies to iOS only.
  • To observe multiple positions, use | (the OR operator).
  • The default return value of this callback is AgoraVideoFramePositionPostCapture (1 << 0) and AgoraVideoFramePositionPreRenderer (1 << 1).
  • To conserve system resources of the device, you can reduce the number of observation positions appropriately according to your scenario.

Declared In

AgoraVideoFrame.h

– isMultipleChannelFrameWanted required method

Sets whether the SDK outputs remote video data received in multiple channels.

- (BOOL)isMultipleChannelFrameWanted

Return Value

Whether the SDK outputs remote video data received in multiple channels:

  • YES: The SDK uses onRenderVideoFrameEx to output remote video data received in multiple channels.
  • NO: (Default) The SDK uses onRenderVideoFrame to output remote video data received in a single channel.

Availability

v3.4.5

In a multi-channel (AgoraRtcChannel) scenario, if you want to get the remote video data received in multiple channels, you need to implement the isMultipleChannelFrameWanted callback in AgoraVideoDataFrameProtocol and set the return value of this callback to YES. The SDK triggers the onRenderVideoFrameEx callback each time a video frame is received, from which you can get the expected multi-channel video data.

Note:

  • This method applies to iOS only.
  • The SDK chooses to trigger either the onRenderVideoFrame or onRenderVideoFrameEx callback depending on the return value that you set in the isMultipleChannelFrameWanted callback. Agora recommends that you set the return value as YES in a multi-channel scenario.

Declared In

AgoraVideoFrame.h

– onRenderVideoFrameEx:forUid:inChannel: required method

Gets the remote video data received in multiple channels.

- (BOOL)onRenderVideoFrameEx:(AgoraVideoDataFrame *)videoFrame forUid:(unsigned int)uid inChannel:(NSString *)channelId

Parameters

videoFrame

The video frame. See AgoraVideoDataFrame.

uid

The user ID of the remote user.

channelId

The channel name.

Return Value

  • YES: If the video frame processing fails, the video frame is not passed back to the SDK.
  • NO: If the video frame processing fails, the video frame is still passed back to the SDK.

Availability

v3.4.5

After you successfully register the raw video frame protocol and set the return value of isMultipleChannelFrameWanted as YES, the SDK triggers this callback each time a video frame is received. You get the remote video data received in multiple channels in videoFrame and then process the video data according to your scenario. After processing, you can pass the processed video data back to the SDK.

Note:

  • This callback applies to iOS only.
  • If you get the video data in RGBA color encoding format, Agora does not support using this callback to send the processed data in RGBA color encoding format back to the SDK.

Declared In

AgoraVideoFrame.h