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)
- Retrieves the Buffer Type (bufferType)
- 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.
@property (strong) id<AgoraVideoFrameConsumer> _Nullable consumer
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.