The AOQ Web SDK supports real-time audio, video, and data interaction in browsers. This reference covers engine management, audio and video capture and playback, data messages, and event callbacks.
Install the SDK
The AOQ Web SDK connects to the server using WebTransport (HTTP/3 / QUIC) and exchanges audio, video, and data messages in a Worker. It requires a browser with WebTransport support and an HTTPS secure context. Use AoqClientEngine.isAoqSupported() to check basic browser capabilities.
Install the SDK using npm:
API overview
Engine lifecycle
| API | Description |
|---|---|
| createEngine | Create a singleton engine |
| createAoqClientEngine | Equivalent named factory function |
| destroy | Destroy the engine |
| getVersion | Get the SDK version |
| isAoqSupported | Check browser capabilities |
| connect | Initiate a connection |
| disconnect | Disconnect |
Audio device management
| API | Description |
|---|---|
| startAudioCapture | Start audio capture |
| stopAudioCapture | Stop audio capture |
| muteAudioCapture | Mute audio capture |
| startAudioPlayer | Start audio playback |
| stopAudioPlayer | Stop audio playback |
| pauseAudioPlayer | Pause playback with fade-out |
| resumeAudioPlayer | Resume playback with default fade-in |
| interruptAudioPlayer | Interrupt playback |
Audio encoding configuration
| API | Description |
|---|---|
| setAudioEncoderConfig | Set audio encoding parameters |
| setAudioDecoderConfig | Set audio decoding parameters |
Local volume indication
| API | Description |
|---|---|
| enableLocalAudioVolumeIndication | Enable local volume indication |
Video device management
| API | Description |
|---|---|
| startVideoCapture | Start video capture |
| getCameras | Enumerate cameras |
| switchCamera | Switch cameras by direction preference or device ID |
| stopVideoCapture | Stop video capture |
| setLocalView | Set the local video container |
| setRemoteView | Set the remote video container |
Video encoding configuration
| API | Description |
|---|---|
| setVideoEncoderConfig | Set video encoding parameters |
| setVideoDecoderConfig | Set video decoding parameters |
Media stream transmission control
| API | Description |
|---|---|
| enableSendMediaStream | Enable or disable media stream transmission |
Real-time messages
| API | Description |
|---|---|
| sendDataMsg | Send a data message |
Event callbacks
| API | Description |
|---|---|
| onError | Error callback |
| onWarning | Warning callback |
| onConnectionStatusChange | Connection status changes |
| onStats | Statistics |
| onAudioDeviceStateChanged | Audio device state changes |
| onAudioDeviceRouteChanged | Audio route changes |
| onAudioFileState | Reserved audio file state event; not currently emitted |
| onLocalAudioVolumeIndication | Local volume indication |
| onVideoDeviceStateChanged | Video device state changes |
| onDataMsg | Data messages |
API details
Engine lifecycle
createEngine
Creates a singleton engine. Repeated calls return the existing instance.
| Parameter | Type | Description |
|---|---|---|
config | AoqCreateConfig | Engine creation configuration |
AoqClientEngine instance on success, or null on failure.
An initialized singleton is returned without reapplying configuration. Destroy it before creating an engine with new configuration.
createAoqClientEngine
A named factory exported by the package, equivalent to AoqClientEngine.createEngine(config). It is not an instance method and requires no additional initialization.
| Parameter | Type | Description |
|---|---|---|
config | AoqCreateConfig | Required; {} is valid. Repeated creation does not reapply configuration. |
null on failure.
destroy
Destroys the engine, starts resource cleanup, and removes all event listeners.
0 on success, or AoqECStateInvalid(2) if no instance exists.
This method returns synchronously. Log saving and optional dump export run asynchronously in the background and may not be complete when it returns. Create a new engine with createEngine before using the SDK again; the destroyed instance cannot be reused.
getVersion
Gets the SDK version.
isAoqSupported
Checks whether the browser has the basic capabilities required for an AOQ connection.
Promise<AoqSupportResult> with the support result and missing capabilities.
The check probes WebTransport in a Worker with a 5-second timeout. It does not check network reachability, server configuration, authentication, device permissions, or specific media configurations. supported: true does not guarantee a successful connection or call.
connect
Initiates a connection to the server.
| Parameter | Type | Description |
|---|---|---|
config | AoqConnectConfig | Connection credentials, including the token, session ID, and relay endpoints |
0 when the request is accepted.
Call after creating the engine, registering events, and configuring codecs. Connections normally start from Disconnected; retrying from Failed is also allowed. Other states return AoqECStateInvalid(2). Invalid track, media, or connection parameters, or selecting Opus without the required WebCodecs capabilities, can return AoqECParamInvalid(1). An unavailable Network Worker returns AoqECStateInvalid(2).
Connection results are reported asynchronously through onConnectionStatusChange. Connected means MEDIA_SETUP has completed and media tracks are bound. Configure the session using the model's data protocol and confirm application readiness before enabling audio or video transmission.
disconnect
Disconnects from the server.
0 when the request is accepted.
The result is reported through onConnectionStatusChange. Wait for AoqConnectionStatusDisconnected before changing codec configuration and reconnecting. Calling when already disconnected returns AoqECStateInvalid(2). Disconnecting does not stop devices; also call the capture and playback stop methods when ending a call.
Audio device management
startAudioCapture
Starts microphone capture and requests device permission asynchronously.
| Parameter | Type | Description |
|---|---|---|
config | AoqAudioCaptureConfig | Audio capture configuration |
Promise<number>; 0 indicates success.
The browser may request microphone permission on first use or if permission has not been granted. Capture state changes are reported through onAudioDeviceStateChanged.
During congestion, uplink audio waiting in the send queue for approximately 100 ms is dropped to avoid accumulating latency. Audio whose transmission has started is not withdrawn. This threshold is not an end-to-end latency limit.
stopAudioCapture
Stops audio capture.
0 on success.
Returns AoqECStateInvalid(2) if the device has not started or has already stopped.
muteAudioCapture
Mutes or unmutes audio capture. Capture continues while muted, but silent frames are sent.
| Parameter | Type | Description |
|---|---|---|
mute | boolean | true: mute; false: unmute |
0 on success.
startAudioPlayer
Starts the audio player and initializes the output device asynchronously.
| Parameter | Type | Description |
|---|---|---|
config | AoqAudioPlaybackConfig | Audio playback configuration |
Promise<number>; 0 indicates success.
Playback state changes are reported through onAudioDeviceStateChanged.
Call from a user click handler and handle browser autoplay restrictions. Calling while the player is starting or already started returns AoqECStateInvalid(2).
In Realtime mode (audio downlink trackMode is Stream), audio received before the player starts is continuously consumed without building up. Every start, including the first, clears earlier audio and plays newly received audio only. Segment mode retains unplayed audio.
stopAudioPlayer
Stops the audio player.
0 on success.
Returns AoqECStateInvalid(2) if the device has not started or has already stopped.
In Realtime mode, incoming audio continues to be consumed after device output stops, and video continues playing. Starting again plays only new audio. Existing pause or interruption state is retained across restart. Segment mode retains unplayed audio.
pauseAudioPlayer
Pauses playback after fading out. Call resumeAudioPlayer to resume.
| Parameter | Type | Description |
|---|---|---|
fadeMs | number | Fade-out duration in ms, rounded to a sample count at the actual device sample rate. 0 disables fading; negative or non-finite values use 100 ms. |
0 when the control request is accepted. Playback or fade-out may not have completed, and the player may not be playing.
Segment mode preserves unplayed audio and the read position, then resumes from that position. Realtime mode discards queued audio and continues consuming incoming audio while paused, then resumes from the current live position without replaying audio received during the pause.
resumeAudioPlayer
Resumes paused or interrupted playback with the default fade-in: 2 ms in Segment mode and 100 ms in Realtime mode.
| Parameter | Type | Description |
|---|---|---|
fadeMs | number | Reserved and currently ignored. The default fade-in is used; passing 0 does not disable it. |
0 when the control request is accepted; resumption may not yet be complete.
interruptAudioPlayer
Interrupts playback and discards the remaining unplayed audio after fade-out. Unlike a pause in Segment mode, discarded audio is not replayed after resumption.
| Parameter | Type | Description |
|---|---|---|
trackType | AoqTrackType | Compatibility parameter. Pass Audio. Currently, this parameter does not select a playback stream. |
fadeMs | number | Fade-out duration in ms, rounded to a sample count at the actual device sample rate. 0 disables fading; negative or non-finite values use 100 ms. |
0 when the control request is accepted. Interruption may not yet be complete, and the player may not be playing.
Playback resumes automatically when the server sends audio for a new round. You can also call resumeAudioPlayer.
Interruption requests made while paused are ignored but may still return 0. Segment mode then resumes the audio retained before the pause. A pause followed by an interruption does not clear the playback queue.
Audio encoding configuration
setAudioEncoderConfig
Sets audio encoding parameters.
| Parameter | Type | Description |
|---|---|---|
config | AoqAudioCodecConfig | Audio encoding configuration |
0 on success.
Call before connect() while the engine is Disconnected. Changes while connecting or connected return AoqECStateInvalid(2). Disconnect and wait for Disconnected, configure the codec, and reconnect.
A return value of 0 means the configuration request is accepted. The audio format is validated again during connection establishment. Opus also requires browser WebCodecs support.
setAudioDecoderConfig
Sets audio decoding parameters.
| Parameter | Type | Description |
|---|---|---|
config | AoqAudioCodecConfig | Audio decoding configuration |
0 on success.
Call before connect() while the engine is Disconnected. Changes while connecting or connected return AoqECStateInvalid(2).
Local volume indication
enableLocalAudioVolumeIndication
Enables or disables periodic local capture volume notifications through onLocalAudioVolumeIndication.
| Parameter | Type | Description |
|---|---|---|
config | AoqAudioVolumeIndicationConfig | Volume indication configuration |
0 on success.
Set interval to 0 or a negative value to disable callbacks.
Video device management
startVideoCapture
Starts camera capture.
| Parameter | Type | Description |
|---|---|---|
config | AoqVideoCaptureConfig | Video capture configuration |
0 on success.
A return value of 0 means the asynchronous capture request is accepted. Success or failure is reported through onVideoDeviceStateChanged; it does not mean the camera is already running.
cameraPreference accepts a direction enum or device ID. If omitted, the browser chooses the camera. The browser may fall back to another available camera if the requested direction or ID cannot be satisfied.
getCameras
videoinput devices without opening a camera or requesting permission. Names or IDs may be incomplete before permission is granted. Enumerate again after authorization or device changes. The Promise rejects if the engine is uninitialized or enumeration fails.
switchCamera
| Parameter | Type | Required | Description |
|---|---|---|---|
cameraPreference | AoqCameraDirection | string | No | Preferred direction or device ID. Omit to clear the previous preference and let the browser choose again. |
0 means the request is accepted. State is reported through onVideoDeviceStateChanged, and failures through onError. Returns AoqECStateInvalid(2) when capture is inactive, starting, or switching, and AoqECParamInvalid(1) for an invalid direction or blank ID.
Switching releases the old device, opens the target, and waits for its first frame. If the old camera track was transferred to a Worker, including cases that later fell back to the main thread, release confirmation is awaited for up to 2 seconds. A confirmation timeout reports failure without opening or restoring a device. Each attempt takes at most 15 seconds. On failure, one attempt is made to restore capture using the original device preference; even successful restoration still reports the switch as failed. Success reports CaptureStarted(reason=0); failure with capture restored reports CaptureStarted(reason=error code); failed restoration reports CaptureFail(reason=error code). If the explicit target is already satisfied, CaptureStarted is emitted asynchronously without reopening it. Callbacks do not include the actual device ID. Switching preserves the transmission switch, codec configuration, and preview binding. Stopping capture cancels switching; destroying the engine suppresses further callbacks.
Switching may briefly interrupt video. The capture timeline remains continuous, but hardware-level audio/video synchronization is not guaranteed. The browser selects the actual device; do not display the requested preference as the confirmed selected device.
stopVideoCapture
Stops video capture.
0 on success.
Returns AoqECStateInvalid(2) if the device has not started or has already stopped.
setLocalView
Sets the local video container. The SDK creates rendering elements inside it.
| Parameter | Type | Description |
|---|---|---|
trackType | AoqTrackType | Only AoqTrackTypeVideo is supported. Other types return AoqECUnSupport(3). |
canvas | AoqVideoCanvas | null | Rendering container configuration. Pass null to unbind. |
0 on success.
Give the container explicit dimensions. The SDK creates its rendering elements inside the container.
Use a regular DOM container with explicit dimensions, such as a div. Do not pass video, audio, canvas, img, or void elements directly. Invalid containers, missing IDs, or invalid renderMode values return AoqECParamInvalid(1) and preserve the previous binding. 0 means the binding is accepted; the first frame may not yet be rendered.
setRemoteView
Sets the remote video container. The SDK creates rendering elements inside it.
| Parameter | Type | Description |
|---|---|---|
trackType | AoqTrackType | Only AoqTrackTypeVideo is supported. Other types return AoqECUnSupport(3). |
canvas | AoqVideoCanvas | null | Rendering container configuration. Pass null to unbind. |
0 on success.
Use a regular DOM container with explicit dimensions, such as a div. Do not pass video, audio, canvas, img, or void elements directly. Invalid containers, missing IDs, or invalid renderMode values return AoqECParamInvalid(1) and preserve the previous binding. 0 means the binding is accepted; the first frame may not yet be rendered.
Video encoding configuration
setVideoEncoderConfig
Sets video encoding parameters.
| Parameter | Type | Description |
|---|---|---|
config | AoqVideoCodecConfig | Video encoding configuration |
0 on success.
Call while the engine is Disconnected. Calling while connecting or connected returns AoqECStateInvalid(2). Configure before the first connection and video capture. Configuration is merged and cached for subsequent stream establishment; existing capture or encoders are not immediately reconfigured.
setVideoDecoderConfig
Sets video decoding parameters.
| Parameter | Type | Description |
|---|---|---|
config | AoqVideoCodecConfig | Video decoding configuration |
0 on success.
Call before connect() while the engine is Disconnected. Changes while connecting or connected return AoqECStateInvalid(2).
Media stream transmission control
enableSendMediaStream
Enables or disables transmission of audio or video tracks.
| Parameter | Type | Description |
|---|---|---|
trackType | AoqTrackType | Media track type |
enable | boolean | true: enable transmission; false: disable transmission |
0 on success.
Only Audio and Video are controlled, not Data. Other track values may return 0 without taking effect. Disabling transmission does not stop capture devices; call the corresponding stop...Capture() method to stop a device.
Real-time messages
sendDataMsg
Sends UTF-8 text carried in a Uint8Array to the peer, such as application JSON. The current WT path does not support arbitrary binary payloads or sending SDK internal control messages with this method.
| Parameter | Type | Description |
|---|---|---|
msg | AoqDataMsg | Message object; msg.data must contain nonempty UTF-8 bytes |
0 on success.
Requires a connected engine with ready media tracks and Data in publishTracks. A missing message or a msg.data value that is not a Uint8Array returns AoqECParamInvalid(1). A connection that is not ready returns AoqECStateInvalid(2). An inactive send stream or empty message currently returns -1. 0 means local acceptance, not peer delivery acknowledgment. UTF-8 validation or later transmission can still fail through onError.
The underlying ArrayBuffer of msg.data may be transferred and detached, also affecting other views sharing that buffer. Pass a data.slice() copy if the original data must remain available. Do not send API keys or temporary credentials in frontend messages or logs.
Event callbacks
Subscribe with engine.on('eventName', callback), listen once with engine.once(...), and unsubscribe with engine.off('eventName', callback) using the same function reference. Destroying the engine removes all listeners. Register before connecting or starting devices, and keep callbacks lightweight.
| Event | Callback signature | Description |
|---|---|---|
onError | (code: number, message: string) => void | Error callback |
onWarning | (code: number, message: string) => void | Warning callback |
onConnectionStatusChange | (status: AoqConnectionStatus) => void | Connection status changes |
onStats | (stats: AoqStats) => void | Statistics |
onAudioDeviceStateChanged | (state: AoqAudioDeviceState) => void | Audio device state changes |
onAudioDeviceRouteChanged | (routeType: AoqAudioDeviceRouteType) => void | Audio route changes |
onAudioFileState | (state: AoqAudioFileState) => void | Reserved; not currently emitted |
onLocalAudioVolumeIndication | (volume: AoqAudioVolume) => void | Local volume indication |
onVideoDeviceStateChanged | (state: AoqVideoDeviceState) => void | Video device state changes |
onDataMsg | (msg: AoqDataMsg) => void | Data messages |
onError
Reports asynchronous or runtime errors not covered by synchronous return values. Use code and message to troubleshoot, together with connection and device states. An error does not necessarily end the connection. Network errors may use general state error codes; the numeric code alone does not identify the failure stage.
| Parameter | Type | Description |
|---|---|---|
code | number | Error code; see AoqErrorCode |
message | string | Error description |
onWarning
Reports engine warnings for nonfatal conditions that require attention.
| Parameter | Type | Description |
|---|---|---|
code | number | Warning code; see AoqWarningCode |
message | string | Warning description |
onConnectionStatusChange
Reports connection status changes.
| Parameter | Type | Description |
|---|---|---|
status | AoqConnectionStatus | Current connection status |
onStats
Reports statistics approximately once per second while Connected and stops after leaving that state. See AoqStats for field availability. Placeholder values are not measurements.
| Parameter | Type | Description |
|---|---|---|
stats | AoqStats | Statistics object |
onAudioDeviceStateChanged
Reports audio capture and playback device operation state changes.
| Parameter | Type | Description |
|---|---|---|
state | AoqAudioDeviceState | Audio device state |
onAudioDeviceRouteChanged
When the output device list changes, the SDK makes a best-effort inference of the route type from browser device labels. It may misidentify or miss changes and is not confirmation of the actual output route. The default type may be returned before authorization or when device information is incomplete.
| Parameter | Type | Description |
|---|---|---|
routeType | AoqAudioDeviceRouteType | Route type inferred from device labels, not confirmation of the actual output device |
onAudioFileState
Reserved audio file state callback. The current AoqClientEngine exposes no file playback controls and does not emit this event.
| Parameter | Type | Description |
|---|---|---|
state | AoqAudioFileState | Audio file state |
onLocalAudioVolumeIndication
Reports local capture volume. Call enableLocalAudioVolumeIndication to enable it first.
| Parameter | Type | Description |
|---|---|---|
volume | AoqAudioVolume | Volume information |
onVideoDeviceStateChanged
Reports video capture device operation state changes.
| Parameter | Type | Description |
|---|---|---|
state | AoqVideoDeviceState | Video device state |
onDataMsg
Reports received data messages.
| Parameter | Type | Description |
|---|---|---|
msg | AoqDataMsg | Received message object. Use TextDecoder to read UTF-8 text from msg.data. |
subscribeTracks to receive messages. The callback receives an object, not a bare Uint8Array. Application code must parse and validate application JSON.
Data types and enums
Common types
AoqCreateConfig
Engine creation configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
workDir | string | No | — | Reserved; the Web SDK does not use this field to select a storage directory |
enableDumpAudio | boolean | No | false | Save audio debug data. Obtain authorization and control access to user audio. |
enableDumpExport | boolean | No | false | Effective only when enableDumpAudio=true. Asynchronously exports a dump ZIP and removes the corresponding OPFS files on destruction. |
maxEncodedVideoFrameBytes | number | No | 194560 (190×1024) | JPEG target maximum frame size in bytes. 0 disables the limit. Oversized frames are reduced in quality; invalid values use the default. |
enableDropOversizedVideoFrame | boolean | No | false | Drop JPEG frames that remain oversized at minimum quality. When false, oversized frames may still be sent. Does not drop for this reason when the size limit is 0. |
extras | string | No | — | JSON object string. Invalid JSON, a non-object value, or an invalid remote rendering policy makes createEngine return null. |
extras fields:
| JSON field | Type | Default | Description |
|---|---|---|---|
remoteVideoRenderer | 'auto' | 'video' | 'canvas' | 'auto' | Remote rendering policy. auto prefers video and falls back to canvas when needed. |
user_specified_enable_av_sync | boolean | true | Enable audio/video synchronization. Use a JSON boolean. |
user_specified_audio_playback_transport | 'message-port' | Automatic | Force MessagePort playback. If omitted, shared memory or MessagePort is selected based on the environment. |
AoqConnectConfig
Connection authentication configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
token | string | Yes | — | Nonempty temporary client token corresponding to aoqTokenForClient, not an API key |
sid | string | Yes | — | Nonempty session ID. Use the complete sid string from the authentication response. |
wtBaseUrl | string | No | Derived from Relay | Preferred HTTPS WT URL for a single route. Ignored for multiple routes, which connect to /aoq on each host and port. |
signedSid | string | Yes (at runtime) | — | Complete signed SID, typically the complete sid from authentication. Optional in TypeScript, but required by the current WT connection flow. |
certFingerprint | string | string[] | Conditional | — | Shared SHA-256 WT certificate fingerprint. Routes without their own fingerprint must be able to use this value. |
workspaceIdHash | string | No | — | Corresponds to extraInfo.workspaceIdHash. Do not substitute the original Workspace ID. |
relayEndpoints | AoqRelayEndpoint[] | Yes | — | Complete endpoint list with at least one entry |
publishTracks | AoqTrackParam[] | Yes | — | Uplink tracks. May be empty, but cannot be empty together with subscribeTracks. |
subscribeTracks | AoqTrackParam[] | Yes | — | Downlink tracks. May be empty. Duplicate tracks within a direction and Screen tracks are not supported. |
clientRelayEndpoints[].route_index to routeIndex in the adapter. Do not fabricate SIDs, endpoints, route indexes, or fingerprints.
WT fingerprints must match the actual WebTransport endpoint certificate. For a backend value in sha256/<hex> format, remove the prefix and validate 64 hexadecimal digits. Shared and per-route fingerprints accept a string or string array; every array entry must be valid, and a match with any entry is sufficient. Nonempty route fingerprints override the shared value; an empty array is treated as unconfigured. The SDK provides neither a universal fingerprint nor an option to skip validation.
Missing signedSid or valid fingerprints can cause asynchronous connection failure even after connect() returns 0. Handle status events and onError.
AoqRelayEndpoint
Relay endpoint.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
routeIndex | number | Yes (at runtime) | — | Unique integer from 0 to 2147483647. The lowest index is used initially. Optional in TypeScript. |
certFingerprint | string | string[] | Conditional | Shared fingerprint | Nonempty route fingerprints override the shared value. Required if no shared fingerprint is available. |
endpoint | string | Yes | — | WT host name or IP, without a scheme, path, whitespace, user information, or query string. IPv6 is supported. |
port | number | Yes | — | WT port, an integer from 1 to 65535 |
AoqTrackParam
Track properties.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
trackType | AoqTrackType | Yes | — | Audio, Video, or Data. No duplicates within a direction. Screen is not currently supported. |
trackMode | AoqTrackMode | No | Segment for audio downlink | Controls audio downlink only. PCM / Opus default to Segment; explicitly select Stream for Realtime. Audio uplink always uses Realtime. Uplink, video, and data ignore this field. |
AoqSupportResult
Browser capability check result.
| Field | Type | Default | Description |
|---|---|---|---|
supported | boolean | — | Whether the environment has basic AOQ connection capabilities |
missingFeatures | AoqMissingFeature[] | — | Observed precheck failures, potentially including 'secure-context', 'worker', and 'web-transport' |
AoqMissingFeature
Basic precheck failures: 'secure-context' | 'worker' | 'web-transport'. worker can also indicate blocked deployment policies, startup or execution failures, or a probe timeout, rather than a missing Worker API. This list is not a complete media capability assessment.
Audio types
AoqAudioCaptureConfig
Audio capture configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
channel | number | No | 1 | Requested capture channels: 1 (mono) or 2 (stereo). Actual settings may be determined by the device track. |
AoqAudioPlaybackConfig
Audio playback configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
channel | number | No | 1 | Requested playback channels: 1 or 2. Output uses the actual AudioContext sample rate. |
playOnlyAndIgnoreMute | boolean | No | false | For playback-only use. Sets audioSession to playback where supported to avoid the iOS mute switch. Keep false when microphone capture is needed. Ignoring mute is not guaranteed without browser support. |
AoqAudioCodecConfig
Audio codec configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
trackType | AoqTrackType | No | — | Reserved; not currently used to select an audio stream |
codecType | AoqEncoderType | No | AoqEncoderTypeAudioPCM | PCM / Opus. Must match the peer's negotiated configuration. |
sampleRate | number | No | 48000 | Sample rate in Hz. Negotiated values: 8000, 12000, 16000, 24000, 32000, 44100, 48000. The browser must also support the selected encoding. |
channel | number | No | 1 | Number of channels: 1 or 2 |
bitrate | number | No | 32000 (Opus encoding) | In bps; used for Opus encoding only. PCM bitrate follows sample rate, channel count, and bit depth. Not used for decoding. |
AoqAudioVolumeIndicationConfig
Local volume indication configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
interval | number | No | 0 | Callback interval in ms. Values <=0 disable callbacks; positive values below 10 are treated as 10. |
smooth | number | No | 3 | Volume smoothing factor, 0..10. Larger values provide more smoothing. |
reportSpeech | boolean | No | false | Whether to report voice activity (VAD) |
AoqAudioVolume
Local volume information.
| Field | Type | Default | Description |
|---|---|---|---|
volume | number | — | Smoothed instantaneous volume, range [0-255] |
isSpeech | boolean | — | Optional voice activity flag, meaningful only when reportSpeech=true. Handle missing values. |
AoqAudioDeviceState
Audio device state callback data.
| Field | Type | Default | Description |
|---|---|---|---|
state | AoqAudioDeviceStateCode | — | Audio device state code |
reason | number | — | Reason code; see AoqErrorCode |
AoqAudioFileState
Reserved audio file playback state structure; the Web SDK does not currently emit the corresponding event.
| Field | Type | Default | Description |
|---|---|---|---|
fileId | string | — | Audio file ID |
stateCode | AoqAudioFileStateCode | — | File playback state code |
errorCode | number | — | Error code |
Video types
AoqVideoCaptureConfig
Video capture configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
width | number | No | 1280 | Requested capture width in pixels, using an ideal constraint. Actual width is selected by the browser/device. |
height | number | No | 720 | Requested capture height in pixels, using an ideal constraint. Actual height is selected by the browser/device. |
fps | number | No | 15 | Requested capture frame rate, using ideal and max constraints |
cameraPreference | AoqCameraDirection | string | No | Browser choice | Camera direction or device ID preference using ideal constraints. Fallback is allowed; blank strings are invalid. |
AoqVideoCodecConfig
Video codec configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
trackType | AoqTrackType | No | — | Reserved; not currently used to select a video stream |
codecType | AoqEncoderType | No | AoqEncoderTypeVideoH264 | H.264 / JPEG. Must match the peer's negotiated configuration. |
width | number | No | 540 | Target encoding width or negotiated downlink width in pixels. Must be a positive integer when connecting. |
height | number | No | 960 | Target encoding height or negotiated downlink height in pixels. Must be a positive integer when connecting. |
fps | number | No | 5 | Encoding frame rate or negotiated downlink frame rate. Must be a positive integer when connecting. |
bitrate | number | No | 500000 (encoding) | Positive target encoding bitrate in bps. Not used for decoding. |
minBitrate | number | No | 128000 | Minimum target encoding bitrate in bps. Omitted or 0 uses 128000, capped at the user's target. H.264 encoding does not pause when the BWE budget reaches 0. Not used for decoding. |
keyframeInterval | number | No | 2 | H.264 keyframe interval in seconds, treated as at least 1 second for encoding. Not used for JPEG or decoding. |
AoqVideoCanvas
Video rendering container configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
view | HTMLElement | string | Yes | — | Regular container element or its DOM ID without #. Do not use video, audio, canvas, img, or void elements directly. |
renderMode | AoqRenderMode | No | AoqRenderModeAuto(0) | Video fitting mode |
AoqVideoDeviceState
Video device state callback data.
| Field | Type | Default | Description |
|---|---|---|---|
state | AoqVideoDeviceStateCode | — | Video device state code |
reason | number | — | Reason code: 0 for an explicit stop; AoqECVideoDevice(220) for an unexpected Web track end |
Data message types
AoqDataMsg
The shared structure for public sendDataMsg and onDataMsg. These APIs do not accept a bare string or Uint8Array. The WT path carries UTF-8 text in a byte array.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
data | Uint8Array | Yes | — | Nonempty valid UTF-8 when sending. Read msg.data when receiving. |
Statistics types
AoqStats
Engine statistics summary. All fields below are optional in the type definition; handle missing values.
| Field | Type | Default | Description |
|---|---|---|---|
audioPublishStats | AoqAudioPublishStats[] | — | Audio publishing statistics |
audioSubscribeStats | AoqAudioSubscribeStats[] | — | Audio subscription statistics |
videoPublishStats | AoqVideoPublishStats[] | — | Video publishing statistics |
videoSubscribeStats | AoqVideoSubscribeStats[] | — | Video subscription statistics |
dataMsgPublishStats | AoqDataMsgPublishStats[] | — | Data message publishing statistics |
dataMsgSubscribeStats | AoqDataMsgSubscribeStats[] | — | Data message subscription statistics |
networkStats | AoqNetworkStats | — | Network statistics |
AoqAudioPublishStats
Audio publishing statistics.
| Field | Type | Default | Description |
|---|---|---|---|
trackType | AoqTrackType | — | Track type |
bitrate | number | — | Total connection uplink application bitrate in bps, not a separate audio bitrate |
bytes | number | — | Total connection uplink application bytes, not a separate audio total |
encodeVolume | number | 0 | Placeholder. Use onLocalAudioVolumeIndication for capture volume. |
AoqAudioSubscribeStats
Audio subscription statistics.
| Field | Type | Default | Description |
|---|---|---|---|
trackType | AoqTrackType | — | Track type |
bitrate | number | — | Total connection downlink application bitrate in bps, not a separate audio bitrate |
bytes | number | — | Total connection downlink application bytes, not a separate audio total |
playVolume | number | 0 | Placeholder; does not indicate whether playback is muted |
AoqVideoPublishStats
Video publishing statistics.
| Field | Type | Default | Description |
|---|---|---|---|
trackType | AoqTrackType | — | Track type |
bitrate | number | 0 | Placeholder; separate video bitrate is not currently reported |
bytes | number | 0 | Placeholder; separate video byte count is not currently reported |
encodeFps | number | — | Encoding frame rate |
AoqVideoSubscribeStats
Video subscription statistics.
| Field | Type | Default | Description |
|---|---|---|---|
trackType | AoqTrackType | — | Track type |
bitrate | number | 0 | Placeholder; separate video bitrate is not currently reported |
bytes | number | 0 | Placeholder; separate video byte count is not currently reported |
decodeFps | number | — | Decoding frame rate |
renderFps | number | — | Rendering frame rate |
AoqDataMsgPublishStats
Data message publishing statistics.
| Field | Type | Default | Description |
|---|---|---|---|
trackType | AoqTrackType | — | Track type |
bitrate | number | — | Current bitrate in bps |
bytes | number | — | Cumulative bytes sent |
AoqDataMsgSubscribeStats
Data message subscription statistics.
| Field | Type | Default | Description |
|---|---|---|---|
trackType | AoqTrackType | — | Track type |
bitrate | number | — | Current bitrate in bps |
bytes | number | — | Cumulative bytes received |
AoqNetworkStats
Network statistics. Bitrates measure application payload bits/s, and totals use the same payload basis in bytes. Probe and transport protocol overhead is excluded.
| Field | Type | Default | Description |
|---|---|---|---|
sendBitrate | number | — | Uplink bitrate in bps |
sendBytes | number | — | Cumulative uplink bytes |
recvBitrate | number | — | Downlink bitrate in bps |
recvBytes | number | — | Cumulative downlink bytes |
loss | number | — | Optional uplink loss ratio (0–1). Uses browser QUIC observations when available, otherwise a Relay Datagram estimate. Omitted if unknown. |
rtt | number | — | Optional round-trip time in ms; omitted if unknown |
bwe | number | — | Optional effective Client→Relay application send budget in bps; omitted when unknown or stale |
audioReserveBps | number | — | Optional payload bitrate reserved for the current encoded audio in bps. Excludes RED redundancy and transport overhead; not actual audio traffic. |
Enums
AoqTrackType
Track media type.
| Enum member | Value | Description |
|---|---|---|
AoqTrackTypeAudio | 0 | Audio |
AoqTrackTypeVideo | 1 | Video |
AoqTrackTypeData | 2 | Data messages |
AoqTrackTypeScreen | 3 | Reserved; not supported in the current connection flow |
AoqTrackMode
Audio transport mode.
| Enum member | Value | Description |
|---|---|---|
AoqTrackModeSegment | 0 | Segment mode |
AoqTrackModeStream | 1 | Realtime stream mode |
AoqEncoderType
Track media format.
| Enum member | Value | Description |
|---|---|---|
AoqEncoderTypeUnknown | 0 | Unknown |
AoqEncoderTypeAudioPCM | 1 | PCM audio |
AoqEncoderTypeAudioOpus | 2 | Opus audio |
AoqEncoderTypeVideoH264 | 3 | H.264 video |
AoqEncoderTypeVideoJpeg | 4 | JPEG video |
AoqEncoderTypeDataText | 5 | Text data |
AoqConnectionStatus
Engine connection status.
| Enum member | Value | Description |
|---|---|---|
AoqConnectionStatusDisconnected | 0 | Disconnected |
AoqConnectionStatusConnecting | 1 | Connecting |
AoqConnectionStatusConnected | 2 | Connected |
AoqConnectionStatusFailed | 3 | Connection failed |
AoqErrorCode
Error codes.
| Enum member | Value | Description |
|---|---|---|
AoqECOK | 0 | Success |
AoqECParamInvalid | 1 | Invalid parameter |
AoqECStateInvalid | 2 | Invalid state |
AoqECUnSupport | 3 | Not implemented for the current platform/mode |
AoqECAudio | 100 | General audio error |
AoqECAudioExternalBufferFull | 110 | External audio buffer full |
AoqECAudioDevice | 120 | General audio device error |
AoqECAudioDeviceRecordingAuthFailed | 121 | Microphone permission denied |
AoqECAudioDeviceRecordingOccupied | 122 | Microphone in use |
AoqECAudioDeviceRecordingBackgroundStart | 123 | Capture started in background |
AoqECAudioDeviceRecordingStartFail | 124 | Capture failed to start |
AoqECAudioDevicePlayoutOccupied | 125 | Playback device in use |
AoqECAudioDevicePlayoutBackgroundStart | 126 | Playback started in background |
AoqECAudioDevicePlayoutStartFail | 127 | Playback failed to start |
AoqECAudioDeviceEarpieceRequiresVoipMode | 128 | Earpiece requires VoIP mode |
AoqECVideo | 200 | General video error |
AoqECVideoExternalBufferFull | 210 | External video buffer full |
AoqECVideoExternalCaptureNotEnabled | 211 | External video capture not enabled |
AoqECVideoExternalEncoderNotEnabled | 212 | External video encoder not enabled |
AoqECVideoDevice | 220 | General video device error |
AoqECVideoDeviceCameraOpenFail | 221 | Camera failed to open |
AoqECVideoDeviceCameraAuthFailed | 222 | Camera permission denied |
AoqECVideoDeviceCameraOccupied | 223 | Camera in use |
AoqECVideoDeviceCameraRunningError | 224 | Camera runtime error |
AoqECVideoCodec | 230 | General video codec error |
AoqECVideoCodecEncoderInitFail | 231 | Video encoder initialization failed |
AoqECVideoRender | 240 | General video rendering error |
AoqECVideoRenderCreateFail | 241 | Renderer creation failed |
AoqECVideoRenderDrawError | 242 | Rendering draw error |
AoqWarningCode
Warning codes.
| Enum member | Value | Description |
|---|---|---|
AoqWCOK | 0 | Normal |
AoqWCAudio | 100 | General audio warning |
AoqWCAudioHowling | 101 | Acoustic feedback detected |
AoqWCAudioDevice | 120 | General audio device warning |
AoqWCAudioDeviceMicEnumerateError | 121 | Microphone enumeration error |
AoqWCAudioDeviceMicStartTimeout | 122 | Microphone start timeout |
AoqWCAudioDeviceRecordingError | 123 | Capture error |
AoqWCAudioDeviceSpeakerEnumerateError | 124 | Speaker enumeration error |
AoqWCAudioDeviceSpeakerStartTimeout | 125 | Speaker start timeout |
AoqWCAudioDevicePlayoutError | 126 | Playback error |
AoqWCAudioDeviceSilentMode | 127 | Device in silent mode |
AoqWCVideo | 200 | General video warning |
AoqWCVideoCameraEnumerateError | 201 | Camera enumeration error |
AoqWCVideoEncoderSwitched | 202 | Video encoder switched |
AoqWCVideoRenderDowngrade | 203 | Rendering fallback |
AoqAudioDeviceStateCode
Audio device state codes.
| Enum member | Value | Description |
|---|---|---|
AoqAudioDeviceNone | 0 | No state |
AoqAudioDeviceRecordStarting | 1 | Capture starting |
AoqAudioDeviceRecordStarted | 2 | Capture started |
AoqAudioDeviceRecordStopping | 3 | Capture stopping |
AoqAudioDeviceRecordStopped | 4 | Capture stopped |
AoqAudioDeviceRecordFail | 5 | Capture failed |
AoqAudioDevicePlayStarting | 6 | Playback starting |
AoqAudioDevicePlayStarted | 7 | Playback started |
AoqAudioDevicePlayStopping | 8 | Playback stopping |
AoqAudioDevicePlayStopped | 9 | Playback stopped |
AoqAudioDevicePlayFail | 10 | Playback failed |
AoqAudioDeviceRouteType
Audio device route types.
| Enum member | Value | Description |
|---|---|---|
AoqAudioDeviceRouteDefault | 0 | Default route |
AoqAudioDeviceRouteHeadset | 1 | Headset |
AoqAudioDeviceRouteSpeakerPhone | 4 | Built-in speaker |
AoqAudioDeviceRouteUsb | 5 | USB device |
AoqAudioDeviceRouteBluetooth | 6 | Bluetooth device |
AoqAudioFileStateCode
Audio file playback state codes.
| Enum member | Value | Description |
|---|---|---|
AoqAudioFileNone | 0 | No state |
AoqAudioFileStarted | 1 | Playback started |
AoqAudioFileStopped | 2 | Playback stopped |
AoqAudioFilePaused | 3 | Playback paused |
AoqAudioFileResumed | 4 | Playback resumed |
AoqAudioFileEnded | 5 | Playback ended |
AoqAudioFileBuffering | 6 | Buffering |
AoqAudioFileBufferingEnd | 7 | Buffering ended |
AoqAudioFileFailed | 8 | Playback failed |
AoqCameraDirection
| Enum member | Value | Description |
|---|---|---|
AoqCameraDirectionFront | 0 | Prefer front-facing |
AoqCameraDirectionBack | 1 | Prefer rear-facing |
AoqVideoDeviceStateCode
Video device state codes.
| Enum member | Value | Description |
|---|---|---|
AoqVideoDeviceNone | 0 | No state |
AoqVideoDeviceCaptureStarting | 1 | Capture starting |
AoqVideoDeviceCaptureStarted | 2 | Capture started |
AoqVideoDeviceCaptureStopping | 3 | Capture stopping |
AoqVideoDeviceCaptureStopped | 4 | Capture stopped |
AoqVideoDeviceCaptureFail | 5 | Capture failed |
AoqMirrorMode
Reserved mirror mode enum. The Web SDK has no configuration or API that uses it.
| Enum member | Value | Description |
|---|---|---|
AoqMirrorModeDisabled | 0 | Mirroring disabled |
AoqMirrorModeEnabled | 1 | Mirroring enabled |
AoqOrientationMode
Reserved orientation mode enum. The Web SDK has no configuration or API that uses it.
| Enum member | Value | Description |
|---|---|---|
AoqOrientationModeAuto | 0 | Automatic |
AoqOrientationModePortrait | 1 | Portrait |
AoqOrientationModeLandscape | 2 | Landscape |
AoqRenderMode
Video fitting modes.
| Enum member | Value | Description |
|---|---|---|
AoqRenderModeAuto | 0 | Default: fit the full image and preserve aspect ratio |
AoqRenderModeStretch | 1 | Stretch to fill the container |
AoqRenderModeFill | 2 | Fit the full image and preserve aspect ratio, allowing black bars |
AoqRenderModeCrop | 3 | Fill while preserving aspect ratio; crop overflow |
Other public declarations
IAoqEngineEvents defines the 10 event callback signatures, including the reserved onAudioFileState event. Subscribing by event name provides TypeScript parameter inference.
The following types and enums are exported, but the current Web engine exposes no corresponding control or observer APIs. Identically named declarations on other platforms do not imply Web support.
| Category | Public declarations | Current scope |
|---|---|---|
| Audio file mixing | AoqAudioFileMixConfig, AoqAudioFileState, AoqAudioFileStateCode | No file playback or mixing controls; file state events are not emitted |
| External audio and observers | AoqAudioExternalStreamConfig, AoqAudioExternalFrameMeta, AoqAudioObserverParams, AoqAudioSource, AoqAudioStreamDirection | No external audio input or audio frame observer registration methods |
| External video and observers | AoqExternalVideoFrameMeta, AoqExternalVideoEncodedFrameMeta, AoqVideoObserverParams, AoqVideoSource, AoqVideoPixelFormat, AoqVideoObserverAlignment, AoqVideoCodecType | No external video frame input or video frame observer registration methods. Codec configuration uses AoqEncoderType. |
| Mirroring and orientation | AoqMirrorMode, AoqOrientationMode | No corresponding configuration fields or methods. Local preview mirroring is automatic. |
| Low-level audio devices | AoqAudioDeviceEvent, AudioDeviceApiError, AudioDeviceErrorCode | Low-level device declarations, not additional engine events or the complete engine return-code contract |
AOQ_TRACK_AUDIO and AOQ_TRACK_DATA are the string constants 'aoq_track_audio' and 'aoq_track_data'. They are not track selectors for connection or view methods; use AoqTrackType for those APIs.
Error and warning enums retain cross-platform values. Not all values are necessarily produced by the Web SDK. Use the methods and conditions documented here to determine availability.