This topic describes the C++ APIs, callbacks, and data types of AOQ Client SDK for Windows.
AoqClientEngine class, and reports asynchronous events through the AoqEngineEventListener abstract class. All type definitions reside in the AoqClientSdk namespace, and the header file is AoqClientEngine.h.
const char* strings. They must remain valid at least until the corresponding call returns. The engine copies them internally as needed.API index
Engine lifecycle
| API | Description |
|---|---|
createEngine | Create an engine instance (singleton) |
destroy | Destroy the engine instance |
getVersion | Get the SDK version |
connect | Connect to the Relay server |
disconnect | Disconnect from the server |
Audio device management
| API | Description |
|---|---|
startAudioCapture | Open the audio capture device (microphone) |
stopAudioCapture | Close the audio capture device |
muteAudioCapture | Mute or unmute audio capture |
startAudioPlayer | Start audio rendering (remote audio playback) |
stopAudioPlayer | Stop audio rendering |
pauseAudioPlayer | Pause audio rendering (with optional fade-out) |
resumeAudioPlayer | Resume audio rendering (with optional fade-in) |
interruptAudioPlayer | Interrupt the current audio session |
enableLocalAudioVolumeIndication | Enable or disable local capture volume indication |
Audio encoding configuration
| API | Description |
|---|---|
setAudioEncoderConfig | Set audio encoding parameters |
setAudioDecoderConfig | Set audio decoding parameters |
Video device management
| API | Description |
|---|---|
startVideoCapture | Open the video capture device (camera) |
stopVideoCapture | Close the video capture device |
setLocalView | Set or remove the local video rendering window |
setRemoteView | Set or remove the remote video rendering window |
Video encoding and external input
| API | Description |
|---|---|
setVideoEncoderConfig | Set video encoding parameters |
setVideoDecoderConfig | Set video decoding parameters |
pushExternalVideoCapturedFrame | Push externally captured video frames |
pushExternalVideoEncodedFrame | Push externally encoded video frames |
Screen capture
| API | Description |
|---|---|
getScreenSourceList | Get the list of screen capture sources (desktop only) |
startScreenCapture | Start screen capture |
stopScreenCapture | Stop screen capture |
Media stream transmission control
| API | Description |
|---|---|
enableSendMediaStream | Enable or disable local media stream transmission |
Audio file playback
| API | Description |
|---|---|
startAudioFile | Start playing and publishing a local audio file |
stopAudioFile | Stop audio file playback |
pauseAudioFile | Pause audio file playback |
resumeAudioFile | Resume audio file playback |
getAudioFileDuration | Get the total duration of the audio file |
getAudioFileCurrentPosition | Get the current playback position of the audio file |
setAudioFilePositionMillis | Seek to a position in the audio file |
setAudioFileVolume | Set the audio file volume |
getAudioFileVolume | Get the current audio file volume |
External audio streams
| API | Description |
|---|---|
addAudioExternalStream | Add an external audio stream |
pushAudioExternalStreamData | Push external PCM audio data |
setAudioExternalStreamVolume | Set the external audio stream volume |
getAudioExternalStreamVolume | Get the external audio stream volume |
clearAudioExternalStreamBuffer | Clear the external audio stream buffer |
removeAudioExternalStream | Remove an external audio stream |
Real-time messages
| API | Description |
|---|---|
sendDataMsg | Send a real-time data message |
Audio frame callbacks
| API | Description |
|---|---|
setAudioFrameObserver | Set the audio frame callback listener |
enableAudioFrameObserver | Enable or disable audio frame callbacks at a specified stage |
Video frame callbacks
| API | Description |
|---|---|
setVideoFrameObserver | Set the video frame callback listener |
enableVideoFrameObserver | Enable or disable video frame callbacks at a specified stage |
AoqEngineEventListener
| API | Description |
|---|---|
onError | Engine error callback |
onWarning | Engine warning callback |
onConnectionStatusChange | Connection status change callback |
onStats | Engine statistics callback |
onAudioDeviceStateChanged | Audio device operation status change callback |
onAudioDeviceRouteChanged | Audio output route change callback |
onAudioFileState | Audio file playback status callback |
onLocalAudioVolumeIndication | Local capture volume indication callback |
onVideoDeviceStateChanged | Video device operation status change callback |
onDataMsg | Received real-time data message callback |
IAudioFrameObserver
| API | Description |
|---|---|
| onCapturedAudioFrame | Callback for raw captured audio. Enable it with enableAudioFrameObserver and audioSource = AoqAudioSourceCaptured. Supports configurable sample rate and channel count, and read/write access. |
| onProcessCapturedAudioFrame | Callback for audio after 3A processing. Enable it with enableAudioFrameObserver and audioSource = AoqAudioSourceProcessCaptured. Supports configurable sample rate and channel count, and read/write access. |
| onPublishAudioFrame | Callback for audio before publishing. Enable it with enableAudioFrameObserver and audioSource = AoqAudioSourcePublish. Supports configurable sample rate and channel count. Read-only access only. |
| onPlaybackAudioFrame | Callback for playback audio. Enable it with enableAudioFrameObserver and audioSource = AoqAudioSourcePlayback. Supports configurable sample rate and channel count, and read/write access. |
IVideoFrameObserver
| API | Description |
|---|---|
| onCapturedVideoFrame | Callback for locally captured raw video before preprocessing. Enable it with enableVideoFrameObserver and videoSource = AoqVideoSourceCaptured. |
| onPreEncodeVideoFrame | Callback for local raw video after preprocessing and before encoding. Enable it with enableVideoFrameObserver and videoSource = AoqVideoSourcePreEncode. |
| onRemoteVideoFrame | Callback for remote raw video after decoding and before rendering. Enable it with enableVideoFrameObserver and videoSource = AoqVideoSourceRemote. |
API details
Engine lifecycle
createEngine
Creates the engine instance. The SDK holds the engine as a global singleton, so calling this method again returns the existing instance.
Parameters | Type | Description |
|---|---|---|
|
| Engine creation configuration. For more information, see |
|
| Event callback listener. For more information, see |
nullptr is returned on failure.
destroy
Destroys the engine instance. After the engine is destroyed, you must call createEngine again before you can continue to use it.
getVersion
Gets the SDK version.
connect
Connects to the relay server. The application server obtains temporary AOQ connection parameters based on the protocol in use and sends them to the client. For more information, see Token authentication.
Parameters | Type | Description |
|---|---|---|
|
| Connection authentication configuration. For more information, see |
disconnect
Disconnects from the server.
Audio device management
startAudioCapture
Opens the audio capture device (microphone).
Parameters | Type | Description |
|---|---|---|
|
| Audio capture configuration. For more information, see |
stopAudioCapture
Closes the audio capture device.
muteAudioCapture
Mutes or unmutes audio capture.
Parameters | Type | Description |
|---|---|---|
|
|
|
startAudioPlayer
Starts audio rendering to play remote audio.
Parameters | Type | Description |
|---|---|---|
|
| Audio playback configuration. For more information, see |
stopAudioPlayer
Stops audio rendering.
pauseAudioPlayer
Pauses audio rendering, with fade-out supported.
Parameters | Type | Description |
|---|---|---|
|
| Fade-out duration, in milliseconds. 0 indicates immediate pause. |
resumeAudioPlayer
Resumes audio rendering, with fade-in supported.
Parameters | Type | Description |
|---|---|---|
|
| Fade-in duration, in milliseconds. 0 indicates immediate resumption. |
interruptAudioPlayer
Interrupts the current audio session and stops the audio that is currently playing.
Parameters | Type | Description |
|---|---|---|
|
| Track type. For more information, see |
|
| Fade-out duration, in milliseconds. 0 indicates immediate interruption. |
enableLocalAudioVolumeIndication
Enables or disables local capture volume indication. After it is enabled, the onLocalAudioVolumeIndication callback is triggered at the interval specified by config.interval. If config.interval <= 0, the callback is disabled. You must call this method after startAudioCapture to obtain volume data.
Parameters | Type | Description |
|---|---|---|
|
| Volume indication configuration. For more information, see |
Audio encoding configuration
setAudioEncoderConfig
Sets audio encoding parameters.
Parameters | Type | Description |
|---|---|---|
|
| Audio codec configuration. For more information, see |
setAudioDecoderConfig
Sets audio decoding parameters.
Parameters | Type | Description |
|---|---|---|
|
| Audio codec configuration. For more information, see |
Video device management
startVideoCapture
Opens the video capture device (camera). When isExternal=true is configured, the camera is not opened, and frames are fed by pushExternalVideoCapturedFrame.
Parameters | Type | Description |
|---|---|---|
|
| Video capture configuration. For more information, see |
stopVideoCapture
Closes the video capture device.
setLocalView
Sets or removes the local video rendering window. If canvas.view == nullptr, the binding is removed.
Parameters | Type | Description |
|---|---|---|
|
| Video track. Pass |
|
| Rendering canvas. For more information, see |
setRemoteView
Sets or removes the remote video rendering window. If canvas.view == nullptr, the binding is removed.
Parameters | Type | Description |
|---|---|---|
|
| Video track. Pass |
|
| Rendering canvas. For more information, see |
Video encoding and external input
setVideoEncoderConfig
Sets video encoding parameters and routes them based on config.trackType.
Parameters | Type | Description |
|---|---|---|
|
| Video codec configuration. For more information, see |
setVideoDecoderConfig
Sets video decoding parameters (a codec proposal on the subscribing side, which must be called before connect). The call is routed based on config.trackType.
Parameters | Type | Description |
|---|---|---|
|
| Video codec configuration. For more information, see |
pushExternalVideoCapturedFrame
Pushes an external video frame. You must first call startVideoCapture and configure isExternal=true. If external video capture is not started, AoqECVideoExternalCaptureNotEnabled (211) is returned. If the frame format is not supported, AoqECParamInvalid is returned.
Parameters | Type | Description |
|---|---|---|
|
| Routing target. Pass |
|
| External video frame data. For more information, see |
AoqECVideoExternalBufferFull (210) indicates that the buffer is full; AoqECVideoExternalCaptureNotEnabled (211) indicates that external video capture is not enabled; AoqECParamInvalid indicates an unsupported frame format; other non-zero values indicate other errors.
pushExternalVideoEncodedFrame
Pushes an externally encoded video frame directly, bypassing the encoder. You must first call setVideoEncoderConfig and configure isExternal=true. Only JPEG is currently supported.
Parameters | Type | Description |
|---|---|---|
|
| Routing target. Pass |
|
| Externally encoded frame data. For more information, see |
Screen capture
config specifies screen capture settings. Screen content is sent on the AoqTrackTypeScreen track.
Returns 0 on success or a nonzero value on failure. These methods return synchronously and do not provide an onScreenCaptureStateChanged callback.
Call getScreenSourceList to enumerate screens and windows, then pass the selected sourceId and sourceType in the capture configuration.
For external raw frames, set isExternal=true and supply raw Screen frames through pushExternalVideoCapturedFrame for SDK encoding. For external encoded frames, configure the Screen track for external encoding with setVideoEncoderConfig, then call pushExternalVideoEncodedFrame.
getScreenSourceList
AoqScreenSourceList::screenSourceListFree(list) after use to release its memory.
Media stream transmission control
enableSendMediaStream
Enables or disables sending of a local media stream. We recommend that you disable sending after initialization and enable it only after the onConnectionStatusChange callback reports AoqConnectionStatusConnected.
Parameters | Type | Description |
|---|---|---|
|
| Routing target. |
|
|
|
Audio file playback
startAudioFile
Starts playing a local audio file to the publishing stream.
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID. The business layer must ensure that it is unique. |
|
| Audio file mixing configuration. For more information, see |
stopAudioFile
Stops audio file playback.
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID |
pauseAudioFile
Pauses audio file playback.
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID |
resumeAudioFile
Resumes audio file playback.
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID |
getAudioFileDuration
Gets the total duration of the audio file.
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID |
-AoqErrorCode).
getAudioFileCurrentPosition
Gets the current playback position of the audio file.
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID |
-AoqErrorCode).
setAudioFilePositionMillis
Sets the playback position of the audio file (seek).
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID |
|
| Playback position, in milliseconds |
setAudioFileVolume
Sets the volume of the audio file.
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID |
|
| Audio stream direction. For more information, see |
|
| Volume value. Valid values: 0 to 100. |
getAudioFileVolume
Gets the current volume of the audio file.
Parameters | Type | Description |
|---|---|---|
|
| Audio file ID |
|
| Audio stream direction. For more information, see |
-AoqErrorCode).
External audio streams
addAudioExternalStream
Adds an external audio stream.
Parameters | Type | Description |
|---|---|---|
|
| External audio stream ID. The business layer must ensure that it is unique. |
|
| External audio stream configuration. For more information, see |
pushAudioExternalStreamData
Feeds external audio PCM data. If AoqECAudioExternalBufferFull (110) is returned, the SDK buffer is full, and we recommend that you wait about 20 ms and then send the current data frame again.
Parameters | Type | Description |
|---|---|---|
|
| External audio stream ID |
|
| Raw external audio data. For more information, see |
AoqECAudioExternalBufferFull return value.setAudioExternalStreamVolume
Sets the volume of an external audio stream.
Parameters | Type | Description |
|---|---|---|
|
| External audio stream ID |
|
| External audio stream type. For more information, see |
|
| Volume value. Valid values: 0 to 100. |
getAudioExternalStreamVolume
Gets the volume of an external audio stream.
Parameters | Type | Description |
|---|---|---|
|
| External audio stream ID |
|
| External audio stream type. For more information, see |
-AoqErrorCode).
clearAudioExternalStreamBuffer
Clears the buffer of an external audio stream.
Parameters | Type | Description |
|---|---|---|
|
| External audio stream ID |
|
| Fade-out duration. -1 uses the SDK's default fade-out, 0 clears everything without a fade-out, and a value greater than 0 keeps a fade-out of the specified number of milliseconds. |
removeAudioExternalStream
Removes an external audio stream.
Parameters | Type | Description |
|---|---|---|
|
| External audio stream ID |
Real-time messages
sendDataMsg
Sends a real-time data message.
Parameters | Type | Description |
|---|---|---|
|
| Message content. For more information, see |
Audio frame callbacks
setAudioFrameObserver
Sets the audio frame data callback listener. Pass nullptr to stop callbacks. After you set the listener, call enableAudioFrameObserver to enable the callback for the corresponding data source.
Parameters | Type | Description |
|---|---|---|
|
| Audio frame callback listener. For more information, see |
enableAudioFrameObserver
Enables or disables the audio frame callback at a specified position.
Parameters | Type | Description |
|---|---|---|
|
| Specifies whether to allow data callbacks |
|
| Type of the raw audio data source. For more information, see |
|
| Callback parameter settings. For more information, see |
Video frame callbacks
setVideoFrameObserver
Sets the video frame data callback listener. Pass nullptr to stop callbacks. After you set the listener, call enableVideoFrameObserver to enable the callback for the corresponding data source.
Parameters | Type | Description |
|---|---|---|
|
| Video frame callback listener. For more information, see |
enableVideoFrameObserver
Enables or disables the video frame callback at a specified position.
Parameters | Type | Description |
|---|---|---|
|
| Specifies whether to enable data callbacks at a position |
|
| Data source of the video frame callback (position in the pipeline). For more information, see |
|
| Callback parameter settings. For more information, see |
AoqEngineEventListener
AoqEngineEventListener is the unified entry point for all asynchronous event notifications from the SDK. It is an abstract class that you inherit and implement, and then pass in when you call createEngine. All callbacks may be triggered on internal threads, so you must handle thread safety yourself. State transitions: Disconnected → Connecting → Connected/Failed → Disconnected.
onError
Engine error callback.
Parameters | Type | Description |
|---|---|---|
|
| Error code. For more information, see |
|
| Error description |
onWarning
Engine warning callback.
Parameters | Type | Description |
|---|---|---|
|
| Warning code. For more information, see |
|
| Warning description |
onConnectionStatusChange
Engine connection status change callback.
Parameters | Type | Description |
|---|---|---|
|
| Connection status. For more information, see |
onStats
Engine statistics callback.
Parameters | Type | Description |
|---|---|---|
|
| Statistics data. For more information, see |
onAudioDeviceStateChanged
Callback for audio device capture and playback operation status changes.
Parameters | Type | Description |
|---|---|---|
|
| Audio device state. For more information, see |
onAudioDeviceRouteChanged
Audio output route change callback.
Parameters | Type | Description |
|---|---|---|
|
| Route type. For the valid values, see |
onAudioFileState
Callback for audio file playback status.
Parameters | Type | Description |
|---|---|---|
|
| File playback state. For more information, see |
onLocalAudioVolumeIndication
Local capture volume indication callback. To enable it, call enableLocalAudioVolumeIndication.
Parameters | Type | Description |
|---|---|---|
|
| Local volume information. For more information, see |
onVideoDeviceStateChanged
Callback for video device capture operation status changes.
Parameters | Type | Description |
|---|---|---|
|
| Video device state. For more information, see |
onDataMsg
Callback for a received real-time data message.
Parameters | Type | Description |
|---|---|---|
|
| Data message. For more information, see |
IAudioFrameObserver
Interface for audio frame data callbacks, which the caller implements by inheritance. Do not perform any time-consuming operations in the callbacks. Otherwise, audio anomalies may occur.
onCapturedAudioFrame
Callback for raw captured data. To enable it, call enableAudioFrameObserver and set audioSource = AoqAudioSourceCaptured. You can set the sample rate and the number of channels, and read-write mode is supported.
Parameters | Type | Description |
|---|---|---|
|
| Raw captured audio data. For more information, see |
onProcessCapturedAudioFrame
Callback for data after 3A processing. To enable it, call enableAudioFrameObserver and set audioSource = AoqAudioSourceProcessCaptured. You can set the sample rate and the number of channels, and read-write mode is supported.
Parameters | Type | Description |
|---|---|---|
|
| Raw audio data after 3A processing. For more information, see |
onPublishAudioFrame
Callback for publishing data. To enable it, call enableAudioFrameObserver and set audioSource = AoqAudioSourcePublish. You can set the sample rate and the number of channels, and only read-only mode is supported.
Parameters | Type | Description |
|---|---|---|
|
| Track type. For more information, see |
|
| Raw audio data to be published. For more information, see |
onPlaybackAudioFrame
Callback for playback data. To enable it, call enableAudioFrameObserver and set audioSource = AoqAudioSourcePlayback. You can set the sample rate and the number of channels, and read-write mode is supported.
Parameters | Type | Description |
|---|---|---|
|
| Raw audio data for playback. For more information, see |
IVideoFrameObserver
Interface for video frame data callbacks, which the caller implements by inheritance. Do not perform any time-consuming operations in the callbacks. Otherwise, video stuttering may occur. A return value of true indicates that the data is modified and must be written back to the SDK. Writing back takes effect only for I420. A return value of false indicates read-only. The data in frame is valid only during the callback. To use it asynchronously, copy it yourself.
onCapturedVideoFrame
Callback for local raw data after capture, before preprocessing. To enable it, call enableVideoFrameObserver and set videoSource = AoqVideoSourceCaptured.
Parameters | Type | Description |
|---|---|---|
|
| Captured video frame data. For more information, see |
| trackType | AoqTrackType | Video track type: Video or Screen. |
true indicates that the data is modified and must be written back to the SDK; false indicates read-only.
onPreEncodeVideoFrame
Callback for local raw data before encoding, after preprocessing. To enable it, call enableVideoFrameObserver and set videoSource = AoqVideoSourcePreEncode.
Parameters | Type | Description |
|---|---|---|
|
| Video track type. For more information, see |
|
| Video frame data before encoding. For more information, see |
true indicates that the data is modified and must be written back to the SDK; false indicates read-only.
onRemoteVideoFrame
Callback for remote raw data after decoding and before rendering. To enable it, call enableVideoFrameObserver and set videoSource = AoqVideoSourceRemote.
Parameters | Type | Description |
|---|---|---|
|
| Video track type. For more information, see |
|
| Remote video frame data. For more information, see |
true indicates that the data is modified and must be written back to the SDK; false indicates read-only.
Data types and enumerations
Common types
AoqCreateConfig
Engine creation configuration.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| SDK working directory |
|
|
| Specifies whether to save audio data (for debugging) |
|
|
| Extended parameters (a JSON string) |
| maxEncodedVideoFrameBytes | int | 190 × 1024 | Maximum encoded frame size in bytes. Applies only to the SDK internal JPEG encoder. A value of 0 disables the limit. |
| enableDropOversizedVideoFrame | bool | false | For the SDK internal JPEG encoder, whether to drop a frame that remains oversized at the lowest quality. |
AoqConnectConfig
Configuration for connecting to the relay server. relayEndpoints / publishTracks / subscribeTracks are C-style arrays with a length. The array memory is held by the caller and needs to remain valid only during the connect call.
Field | Type | Description |
|---|---|---|
|
| Connection authentication token |
|
| Session ID |
|
| Server certificate fingerprint |
|
| Workspace hash ID |
|
| Array of relay access points |
|
| Number of relay access points |
|
| Array of local publishing track attributes |
|
| Number of publishing tracks |
|
| Array of local subscribing track attributes |
|
| Number of subscribing tracks |
AoqRelayEndpoint
A relay access point.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Path index |
|
|
| Server address (domain name or IP address) |
|
|
| Server port |
| tcp_port | int | 0 | TCP fallback port. A value of 0 uses the SDK default port, 443. |
AoqTrackParam
The track attribute.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Track type |
|
|
| Streaming or non-streaming mode. Effective only for the audio downlink. |
AoqDataMsg
The message data structure. When it is used in a callback, it is guaranteed to be valid only during the callback. If you need to use it asynchronously, copy it yourself.
Field | Type | Description |
|---|---|---|
|
| Message content. It points to memory held by the caller. |
|
| Number of bytes |
Statistics types
AoqStats
Engine statistics. Each statistics array is provided as a pointer and a count.
Field | Type | Description |
|---|---|---|
|
| Array of publishing statistics for audio and the number of entries |
|
| Array of publishing statistics for video and the number of entries |
|
| Array of publishing statistics for data messages and the number of entries |
|
| Array of subscribing statistics for audio and the number of entries |
|
| Array of subscribing statistics for video and the number of entries |
|
| Array of subscribing statistics for data messages and the number of entries |
|
| Network statistics |
AoqNetworkStats
Network statistics.
Field | Type | Description |
|---|---|---|
|
| Send bitrate, in bit/s |
|
| Cumulative bytes sent |
|
| Receive bitrate, in bit/s |
|
| Cumulative bytes received |
|
| Packet loss rate, from 0 to 100 |
|
| Round-trip latency, in ms |
AoqAudioPublishStats
Publishing statistics for audio.
Field | Type | Description |
|---|---|---|
|
| Track type |
|
| Bitrate, in bit/s |
|
| Cumulative bytes |
|
| Encoding volume of the publishing stream |
AoqVideoPublishStats
Publishing statistics for video.
Field | Type | Description |
|---|---|---|
|
| Track type |
|
| Bitrate, in bit/s |
|
| Cumulative bytes |
|
| Encoding frame rate |
AoqDataMsgPublishStats
Publishing statistics for data messages.
Field | Type | Description |
|---|---|---|
|
| Track type |
|
| Bitrate, in bit/s |
|
| Cumulative bytes |
AoqAudioSubscribeStats
Subscribing statistics for audio.
Field | Type | Description |
|---|---|---|
|
| Track type |
|
| Bitrate, in bit/s |
|
| Cumulative bytes |
|
| Playback volume |
AoqVideoSubscribeStats
Subscribing statistics for video.
Field | Type | Description |
|---|---|---|
|
| Track type |
|
| Bitrate, in bit/s |
|
| Cumulative bytes |
|
| Decoding frame rate |
|
| Rendering frame rate |
AoqDataMsgSubscribeStats
Subscribing statistics for data messages.
Field | Type | Description |
|---|---|---|
|
| Track type |
|
| Bitrate, in bit/s |
|
| Cumulative bytes |
Enumerations
AoqErrorCode
Error code enumeration.
Enum value | Value | Description |
|---|---|---|
| 0 | Success |
| 1 | Invalid parameter |
| 2 | Invalid state |
| 3 | The API is called but is not implemented on the current platform or in the current mode |
| 100 | Generic audio error |
| 110 | External audio buffer is full |
| 120 | Generic audio device error |
| 121 | Recording permission not granted |
| 122 | Recording device is in use |
| 123 | Start recording in the background |
| 124 | Failed to start recording |
| 125 | Playback device is in use |
| 126 | Start playback in the background |
| 127 | Failed to start playback |
| 128 | Receiver mode requires VoIP to be enabled |
| 200 | Generic video error |
| 210 | External video buffer is full |
| 211 | External video capture is not enabled |
| 212 | External video encoding is not enabled |
| 220 | Generic video device error |
| 221 | Failed to open the camera |
| 222 | Camera permission not granted |
| 223 | Camera is in use |
| 224 | Camera runtime error |
| 230 | Generic video codec error |
| 231 | Failed to initialize the encoder |
| 240 | Generic video rendering error |
| 241 | Failed to create the rendering view |
| 242 | Rendering drawing error |
| AoqECScreen | 300 | General screen sharing error |
| AoqECScreenAuthFailed | 310 | Screen sharing permission denied |
| AoqECScreenStartFailed | 311 | Failed to start screen sharing |
AoqWarningCode
Warning code enumeration.
Enum value | Value | Description |
|---|---|---|
| 0 | No warning |
| 100 | Generic audio warning |
| 101 | Audio howling detected |
| 120 | Generic audio device warning |
| 121 | Microphone enumeration error |
| 122 | Microphone startup timed out |
| 123 | Recording error |
| 124 | Speaker enumeration error |
| 125 | Speaker startup timed out |
| 126 | Playback error |
| 200 | Generic video warning |
| 201 | Camera enumeration error |
| 202 | Video encoder switched |
| 203 | Video rendering downgraded |
AoqTrackType
Track type.
Enum value | Value | Description |
|---|---|---|
| 0 | Audio track |
| 1 | Video track |
| 2 | Data message track |
| AoqTrackTypeScreen | 3 | Screen sharing track. Uplink only. |
AoqEncoderType
Encoder type.
Enum value | Value | Description |
|---|---|---|
| 0 | Unknown format |
| 1 | Audio PCM |
| 2 | Audio Opus (plug-in based; contact the SDK team to have it built in or dynamically downloaded to the app) |
| 3 | Video H.264 |
| 4 | Video JPEG |
| 5 | Message text |
AoqTrackMode
Streaming or non-streaming mode. Effective only for the audio downlink.
Enum value | Value | Description |
|---|---|---|
| 0 | Segmented: data is packaged and delivered in semantic segments, such as a sentence. |
| 1 | Streaming: data is delivered continuously. |
AoqConnectionStatus
Engine connection status.
Enum value | Value | Description |
|---|---|---|
| 0 | Disconnected |
| 1 | Connecting |
| 2 | Connected |
| 3 | Connection failed |
Audio types
AoqAudioCaptureConfig
Audio capture configuration.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Specifies whether to use external capture |
|
|
| Number of audio capture channels. 1 and 2 are supported. |
AoqAudioPlaybackConfig
Audio playback configuration.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Specifies whether to use external playback |
|
|
| Number of audio playback channels. 1 and 2 are supported. |
AoqAudioCodecConfig
Audio codec configuration.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Track type |
|
|
| Codec format |
|
|
| Sample rate, in Hz. For encoding, Opus 8/16/48K and PCM 8/16/32/48K are supported. For decoding, 24K is additionally supported, but 24K is limited to Segment mode. Stream mode does not support 24K, and an invalid combination triggers the onError callback with AoqECParamInvalid during connect. |
|
|
| Number of channels. 1 and 2 are supported. |
|
|
| Bitrate, in bit/s |
AoqAudioDeviceState
Audio device state.
Field | Type | Description |
|---|---|---|
|
| Status code |
|
| Error code ( |
AoqAudioDeviceStateCode
Audio device state code.
Enum value | Value | Description |
|---|---|---|
| 0 | No state |
| 1 | Capture starting |
| 2 | Capture started |
| 3 | Capture stopping |
| 4 | Capture stopped |
| 5 | Capture failed |
| 6 | Playback starting |
| 7 | Playback started |
| 8 | Playback stopping |
| 9 | Playback stopped |
| 10 | Playback failed |
AoqAudioDeviceRouteType
Audio device route type.
Enum value | Value | Description |
|---|---|---|
| 0 | Default |
| 1 | Headphones |
| 2 | Receiver |
| 3 | Headphones without a microphone |
| 4 | Built-in speaker |
| 5 | USB |
| 6 | Bluetooth |
| 7 | Bluetooth A2DP |
AoqAudioFileMixConfig
Configuration for playing an audio file to the publishing stream.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| File name (including the path). Required. |
|
|
| Number of loops. -1 indicates unlimited looping. |
|
|
| Start playback position, in ms |
|
|
| Publishing volume. Valid values: 0 to 100. |
|
|
| Playback volume. Valid values: 0 to 100. |
AoqAudioFileState
Audio file state.
Field | Type | Description |
|---|---|---|
|
| File ID |
|
| Status code |
|
| Error code |
AoqAudioFileStateCode
Audio file state code.
Enum value | Value | Description |
|---|---|---|
| 0 | No state |
| 1 | Started |
| 2 | Stopped |
| 3 | Paused |
| 4 | Resumed |
| 5 | Playback completed |
| 6 | Buffering |
| 7 | Buffering ended |
| 8 | Playback failed |
AoqAudioFileErrorCode
Audio file playback error code.
Enum value | Value | Description |
|---|---|---|
| 0 | No error |
| 1 | Failed to open the file |
| 2 | Failed to decode the file |
AoqAudioExternalStreamConfig
External audio stream configuration.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Audio track type |
|
|
| Audio stream format. PCM is supported. |
|
|
| Number of channels. It is limited by the audio codec of the publishing stream, which supports 1 and 2. Additional channels are ignored. |
|
|
| Sample rate, in Hz. 8, 12, 16, 24, 32, 44.1, 48, 64, 88.2, 96, 176.4, and 192K are supported. |
|
|
| Playback volume. Valid values: 0 to 100. |
|
|
| Publishing volume. Valid values: 0 to 100. |
|
|
| Maximum buffer duration, in ms. Valid values: 100 and above. If the buffered duration in the SDK exceeds this value, Push fails. |
|
|
| Specifies whether to apply 3A processing to the input PCM |
AoqAudioFrameData
Audio data.
Field | Type | Description |
|---|---|---|
|
| Pointer to the audio data |
|
| Number of samples (per channel) |
|
| Bytes per sample |
|
| Number of channels |
|
| Number of samples per second |
|
| PCM input round (used for the consumption completion notification of |
|
| Timestamp |
|
| Data length |
|
| Valid in data callbacks. |
AoqAudioStreamDirection
Audio stream direction.
Enum value | Value | Description |
|---|---|---|
| 0 | Publishing audio |
| 1 | Playback audio |
AoqAudioExternalStreamToggle
External audio stream control.
Enum value | Value | Description |
|---|---|---|
| 0 | Recovered |
| 1 | Paused |
AoqAudioSource
Type of the audio data source.
Enum value | Value | Description |
|---|---|---|
| 0 | Captured audio data |
| 1 | Audio data after 3A processing |
| 2 | Audio data to be published (requires a successful Connect) |
| 3 | Audio data to be played |
AoqAudioObserverMode
Audio frame callback mode.
Enum value | Value | Description |
|---|---|---|
| 0 | Read-only |
| 1 | Read-write |
AoqAudioObserverConfig
Parameter settings for audio data callbacks.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Sample rate of the callback audio. It is limited by the source. Resampling is performed if the rates do not match. 8, 12, 16, 24, 32, 44.1, 48, 64, 88.2, 96, 176.4, and 192K are supported. |
|
|
| Number of audio channels in the callback. 1 and 2 are supported. This parameter is limited by the codec parameters of the subscribing stream. |
|
|
| Callback mode |
AoqAudioVolumeIndicationConfig
Local volume indication configuration.
| Field | Type | Default | Description |
|---|---|---|---|
| reportSpeech | bool | false | Whether to detect speech. |
| interval | int | 0 | Callback interval in milliseconds. Values of 0 or less disable callbacks; values between 0 and 10 use 10. |
| smooth | int | 3 | Smoothing factor, from 0 to 10. Higher values produce smoother results. |
AoqAudioVolume
Local volume information.
| Field | Type | Default | Description |
|---|---|---|---|
| isSpeech | bool | false | Whether speech is detected. |
| volume | int | 0 | Smoothed instantaneous volume, from 0 to 255. |
Video types
AoqVideoCaptureConfig
Video capture configuration.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Capture width, in pixels. This parameter is ineffective when |
|
|
| Capture height, in pixels. This parameter is ineffective when |
|
|
| Capture frame rate. This parameter is ineffective when |
|
|
| Specifies whether to use external capture. If it is |
AoqVideoCanvas
Data structure for video rendering. view is an opaque pointer to the platform-native view handle. On Windows, pass the window handle HWND. The caller must ensure that the lifecycle of view outlasts the period during which it is set by setLocalView / setRemoteView.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Handle of the display view ( |
|
|
| Rendering mode |
AoqRenderMode
Rendering display mode.
Enum value | Value | Description |
|---|---|---|
| 0 | Auto mode |
| 1 | Stretch-to-fill mode. When the aspect ratios do not match, the image is stretched to the target ratio and becomes distorted. |
| 2 | Letterbox mode. When the aspect ratios do not match, black bars are added to the top and bottom or the left and right. |
| 3 | Crop mode. When the aspect ratios do not match, the width or height is cropped and part of the image is lost. |
AoqVideoPixelFormat
Video pixel format.
Enum value | Value | Description |
|---|---|---|
| 0 | Unknown format |
| 1 | I420 |
| 2 | NV12 |
| 3 | NV21 |
| 4 | BGRA |
| 5 | RGBA |
AoqVideoFrame
External video data.
Field | Type | Description |
|---|---|---|
|
| Pixel format |
|
| Width, in pixels |
|
| Height, in pixels |
|
| Pointer to packed-format data (NV12/NV21/BGRA/RGBA) |
|
| Number of bytes of packed data |
|
| Pointers to the data of the three I420 planes |
|
| Stride of the three I420 planes |
|
| Timestamp, in ms. If it is 0, the SDK fills it in with the local clock. |
nativePixelBuffer | void* | Cross-platform field. Not used on Windows. |
textureId | int | Cross-platform field. Not used on Windows. |
transformMatrix | float[16] | Cross-platform field. Not used on Windows. |
AoqVideoEncodedFrame
An externally encoded video frame. The caller performs the encoding, and the SDK packages and sends the frame directly without re-encoding.
Field | Type | Description |
|---|---|---|
|
| Codec format |
|
| Pointer to the encoded data |
|
| Number of bytes of the encoded data |
|
| Width, in pixels |
|
| Height, in pixels |
|
| Timestamp, in ms. If it is 0, the SDK fills it in with the local clock. |
AoqVideoCodecType
The codec type of the externally encoded frame.
Enum value | Value | Description |
|---|---|---|
| 0 | JPEG |
AoqVideoDeviceState
Video device state.
Field | Type | Description |
|---|---|---|
|
| Status code |
|
| Error code ( |
AoqVideoDeviceStateCode
Video device state code.
Enum value | Value | Description |
|---|---|---|
| 0 | No state |
| 1 | Camera starting |
| 2 | Camera started |
| 3 | Camera stopping |
| 4 | Camera stopped |
| 5 | Failed to start the camera (for example, permission denied or the device is unavailable) |
AoqMirrorMode
Mirror mode.
Enum value | Value | Description |
|---|---|---|
| 0 | Disable mirroring |
| 1 | Enable mirroring |
AoqOrientationMode
Orientation mode.
Enum value | Value | Description |
|---|---|---|
| 0 | Auto |
| 1 | Portrait |
| 2 | Landscape |
AoqVideoCodecConfig
Video codec parameters, which are shared by encoding and decoding. For decoding, only trackType / codecType / width / height / fps / bitrate take effect and participate in negotiation as a subscription proposal, whereas minBitrate / keyframeInterval / mirrorMode / orientationMode / isExternal are used only for encoding.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| External encoding mode. When it is |
|
|
| Track type |
|
|
| Codec format |
|
|
| Resolution width |
|
|
| Resolution height |
|
|
| Frame rate |
|
|
| Initial bitrate, in bit/s |
|
|
| Minimum bitrate, in bit/s |
|
|
| Keyframe interval, in seconds |
|
|
| Mirror mode |
|
|
| Orientation mode |
AoqVideoSource
Data source of the video frame callback (position in the pipeline).
Enum value | Value | Description |
|---|---|---|
| 0 | Captured video data before preprocessing |
| 1 | Video data before encoding, after preprocessing |
| 2 | Remote video data after decoding and before rendering |
AoqVideoObserverMode
Video frame callback mode.
Enum value | Value | Description |
|---|---|---|
| 0 | Read-only |
| 1 | Read-write |
AoqVideoObserverAlignment
Width alignment method for video output.
Enum value | Value | Description |
|---|---|---|
| 0 | Default |
| 1 | Even-number alignment |
| 2 | 4-byte alignment |
| 3 | 8-byte alignment |
| 4 | 16-byte alignment |
AoqVideoObserverConfig
Parameter settings for video data callbacks.
Field | Type | Default value | Description |
|---|---|---|---|
|
|
| Expected pixel format of the callback data |
|
|
| Width alignment policy |
|
|
| Callback mode. ReadWrite is supported only for I420. |
|
|
| Specifies whether to mirror the callback data |
| trackType | AoqTrackType | AoqTrackTypeVideo | Video track to observe. Supports Video and Screen only. |
Screen capture types
AoqScreenCaptureStateCode
Screen capture state enumeration. The type is defined, but the current SDK does not provide a corresponding state callback.
| Enum value | Value | Description |
|---|---|---|
| AoqScreenCaptureNone | 0 | None |
| AoqScreenCaptureStarting | 1 | Starting |
| AoqScreenCaptureStarted | 2 | Started |
| AoqScreenCaptureStopping | 3 | Stopping |
| AoqScreenCaptureStopped | 4 | Stopped |
| AoqScreenCaptureFail | 5 | Failed |
AoqScreenCaptureState
| Field | Type | Description |
|---|---|---|
| state | AoqScreenCaptureStateCode | Screen capture state code. |
| reason | int | Error code from AoqErrorCode. 0 indicates a normal state. |
AoqScreenSourceList
| Field/Method | Type | Description |
|---|---|---|
| sourceCount | int | Number of sources |
| sourceList | const AoqScreenSourceInfo* | Source array. Release with screenSourceListFree(list) after use. |
| screenSourceListFree(list) | static void | Frees the list memory. The caller must call this method to avoid a memory leak. |
AoqScreenSourceInfo
| Field | Type | Default | Description |
|---|---|---|---|
| sourceType | AoqScreenShareSourceType | Desktop | Source type |
| sourceId | int64_t | 0 | Source ID |
| sourceName | const char* | nullptr | Source name |
| sourceIsSelf | bool | false | Whether the window belongs to the current process |
AoqScreenShareSourceType
| Value | Number | Description |
|---|---|---|
| AoqScreenShareSourceTypeDesktop | 0 | Entire desktop |
| AoqScreenShareSourceTypeWindow | 1 | A specific window |
AoqScreenCaptureConfig
| Field | Type | Default | Description |
|---|---|---|---|
| isExternal | bool | false | Whether the application supplies raw screen frames. |
| sourceId | int64_t | 0 | Screen source ID. |
| sourceType | AoqScreenShareSourceType | AoqScreenShareSourceTypeDesktop | Screen source type. |
| appGroup | const char* | nullptr | For iOS only. Not used on this platform. |