AgoraVideoSourceProtocol Protocol 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:
- 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)
Note:
- 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.
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
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 consumerDiscussion
Note: The SDK does not support the alpha channel, and discards any alpha value passed to the SDK.
Declared In
AgoraMediaIO.h
– shouldInitialize
required method
Initializes the video source.
- (BOOL)shouldInitializeReturn 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)shouldStartDiscussion
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)shouldStopDiscussion
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)shouldDisposeDiscussion
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
Gets the buffer type.
- (AgoraVideoBufferType)bufferTypeReturn 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
– captureType
required method
Gets the capture type of the custom video source.
- (AgoraVideoCaptureType)captureTypeReturn Value
Availability
v3.1.0
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.
Declared In
AgoraMediaIO.h
– contentHint
required method
Gets the content hint of the custom video source.
- (AgoraVideoContentHint)contentHintReturn Value
Availability
v3.1.0
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.
Declared In
AgoraMediaIO.h
