AgoraVideoSourceProtocol Protocol Reference
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:
- Initializes the Video Source (shouldInitialize)
- Enables the Video Source (shouldStart)
- Disables the Video Source (shouldStop)
- Releases the Video Source (shouldDispose)
- Gets the Buffer Type (AgoraVideoBufferType)
- Gets the capture type of the custom video source (AgoraVideoCaptureType)
- Gets the content hint of the custom video source (AgoraVideoContentHint)
- All methods in
AgoraVideoSourceProtocolare 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.
An AgoraVideoFrameConsumer object that the SDK passes to you. You need to reserve this object and use it to send the video frame to the SDK once the custom video source is started. See AgoraVideoFrameConsumer.
@property (strong) id<AgoraVideoFrameConsumer> _Nullable consumer
Note: The SDK does not support the alpha channel, and discards any alpha value passed to the SDK.
Initializes the video source.
- 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.
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.
Enables the video source.
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.
Disables the video source.
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.
Gets the capture type of the custom video source.
Before you initialize the custom video source, the SDK triggers this callback to query the capture type of the video source. You must specify the capture type in the return value and then pass it to the SDK. The SDK enables the corresponding video processing algorithm according to the capture type after receiving the video frame.
Gets the content hint of the custom video source.
If you specify the custom video source as a screen-sharing video, the SDK triggers this callback to query the content hint of the video source before you initialize the video source. You must specify the content hint in the return value and then pass it to the SDK. The SDK enables the corresponding video processing algorithm according to the content hint after receiving the video frame.