AgoraVideoSourceProtocol Category Reference

Conforms to NSObject
Declared in AgoraMediaIO.h

Overview

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

AgoraVideoSourceProtocol allows you to take the ownership of the video source and manipulate it. By default, when enabling real-time communications, the Agora SDK enables the default video input device (built-in camera) to start video streaming. By calling setVideoSource, you can change the default video input device, control it, and send the video source from the specified input device to the Agora Media Engine to handle the remaining video processes; such as video filtering and publishing the video to the RTC connection. Once you have implemented this interface, the Agora Media Engine automatically releases the ownership of the current video input device and passes the ownership to you, so that you can use the same video input device to capture the video stream. AgoraVideoSourceProtocol consists of the following methods:

Note:

  • All methods in AgoraVideoSourceProtocol are callbacks. The media engine maintains a finite state machine and uses these methods at the right time. Do not use these methods directly in the app.
  • These methods are synchronized.
  • If the media engine restarts during the process, these methods can be repeated for a couple of times.
  • These methods are not in the primary thread.

When using the AgoraVideoSourceProtocol, call AgoraVideoBufferType, AgoraVideoPixelFormat, and AgoraVideoRotation to set the buffer type, pixel format, and rotation angle of the transmitted video.

  consumer required method

See AgoraVideoFrameConsumer

@property (strong) id<AgoraVideoFrameConsumer> _Nullable consumer

Declared In

AgoraMediaIO.h

– shouldInitialize required method

Initializes the video source.

- (BOOL)shouldInitialize

Return Value

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

Discussion

The media engine calls this method to initialize the video source. You can also initialize the video source before this method is called and return YES to the media engine in this method. You need to pass YES or NO in this method to tell the media engine if the video source is initialized. When the video source is initialized, the media engine initializes the AgoraVideoFrameConsumer pointer in AgoraVideoSourceProtocol, then the video source sends the video frame to the media engine through the AgoraVideoFrameConsumer method.

Declared In

AgoraMediaIO.h

– shouldStart required method

Enables the video source.

- (void)shouldStart

Discussion

Call this method when the media engine is ready to start video streaming. You should start the video source to capture the video frame. Once the frame is ready, use AgoraVideoFrameConsumer to consume the video frame. Pass one of the following return values to the media engine:

  • YES: If the external video source is enabled and AgoraVideoFrameConsumer is called to receive video frames.
  • NO: If the external video source is not ready or fails to enable, the media engine stops and reports the error.

After YES is returned, video frames can be passed to the media engine through the preset AgoraVideoFrameConsumer interface method.

Declared In

AgoraMediaIO.h

– shouldStop required method

Disables the video source.

- (void)shouldStop

Discussion

Call this method when the media engine stops streaming. You should then stop capturing the video frame and consuming it. After this method is called, the video frames are discarded by the media engine.

Declared In

AgoraMediaIO.h

– shouldDispose required method

Releases the video source.

- (void)shouldDispose

Discussion

Call this method when AgoraVideoFrameConsumer is released by the media engine. You can now release the video source as well as AgoraVideoFrameConsumer.

Declared In

AgoraMediaIO.h

– bufferType required method

Retrieves the buffer type.

- (AgoraVideoBufferType)bufferType

Return Value

return AgoraVideoBufferType

Discussion

Passes the buffer type previously set in AgoraVideoBufferType to the media engine. This buffer type is used to set up the correct media engine environment.

Declared In

AgoraMediaIO.h