AOQ Web SDK API reference

Updated at:

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:

npm install aoq-web-sdk@1.0.1-60040320

Alternatively, obtain the installation package from SDK download and run the following command in your project directory. Replace the package path with its actual location.

npm install ./aoq-web-sdk-1.0.1-60040320.tgz

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.

static createEngine(config: AoqCreateConfig): AoqClientEngine | null

Parameter

Type

Description

config

AoqCreateConfig

Engine creation configuration

Returns an 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.

function createAoqClientEngine(config: AoqCreateConfig): AoqClientEngine | null

Parameter

Type

Description

config

AoqCreateConfig

Required; {} is valid. Repeated creation does not reapply configuration.

Returns the singleton engine on success, or null on failure.

import { createAoqClientEngine } from 'aoq-web-sdk';

const engine = createAoqClientEngine({});
if (!engine) throw new Error('创建引擎失败');

destroy

Destroys the engine, starts resource cleanup, and removes all event listeners.

static destroy(): number

Returns 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.

static getVersion(): string

Returns the installed package version as a string, not a document revision or source commit ID.

isAoqSupported

Checks whether the browser has the basic capabilities required for an AOQ connection.

static isAoqSupported(): Promise<AoqSupportResult>

Returns 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.

connect(config: AoqConnectConfig): number

Parameter

Type

Description

config

AoqConnectConfig

Connection credentials, including the token, session ID, and relay endpoints

Returns 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.

disconnect(): number

Returns 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.

startAudioCapture(config: AoqAudioCaptureConfig): Promise<number>

Parameter

Type

Description

config

AoqAudioCaptureConfig

Audio capture configuration

Returns 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.

stopAudioCapture(): number

Returns 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.

muteAudioCapture(mute: boolean): number

Parameter

Type

Description

mute

boolean

true: mute; false: unmute

Returns 0 on success.

startAudioPlayer

Starts the audio player and initializes the output device asynchronously.

startAudioPlayer(config: AoqAudioPlaybackConfig): Promise<number>

Parameter

Type

Description

config

AoqAudioPlaybackConfig

Audio playback configuration

Returns 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.

stopAudioPlayer(): number

Returns 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.

pauseAudioPlayer(fadeMs: number): number

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.

Returns 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.

resumeAudioPlayer(fadeMs: number): number

Parameter

Type

Description

fadeMs

number

Reserved and currently ignored. The default fade-in is used; passing 0 does not disable it.

Returns 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.

interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number

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.

Returns 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.

setAudioEncoderConfig(config: AoqAudioCodecConfig): number

Parameter

Type

Description

config

AoqAudioCodecConfig

Audio encoding configuration

Returns 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.

setAudioDecoderConfig(config: AoqAudioCodecConfig): number

Parameter

Type

Description

config

AoqAudioCodecConfig

Audio decoding configuration

Returns 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.

enableLocalAudioVolumeIndication(config: AoqAudioVolumeIndicationConfig): number

Parameter

Type

Description

config

AoqAudioVolumeIndicationConfig

Volume indication configuration

Returns 0 on success.

Set interval to 0 or a negative value to disable callbacks.


Video device management

startVideoCapture

Starts camera capture.

startVideoCapture(config: AoqVideoCaptureConfig): number

Parameter

Type

Description

config

AoqVideoCaptureConfig

Video capture configuration

Returns 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

getCameras(): Promise<MediaDeviceInfo[]>

Enumerates browser-visible 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

switchCamera(cameraPreference?: AoqCameraDirection | string): number

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.

Direction and device ID use ideal constraints, allowing fallback to other cameras. 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.

stopVideoCapture(): number

Returns 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.

setLocalView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number

Parameter

Type

Description

trackType

AoqTrackType

Only AoqTrackTypeVideo is supported. Other types return AoqECUnSupport(3).

canvas

AoqVideoCanvas | null

Rendering container configuration. Pass null to unbind.

Returns 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.

setRemoteView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number

Parameter

Type

Description

trackType

AoqTrackType

Only AoqTrackTypeVideo is supported. Other types return AoqECUnSupport(3).

canvas

AoqVideoCanvas | null

Rendering container configuration. Pass null to unbind.

Returns 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.

setVideoEncoderConfig(config: AoqVideoCodecConfig): number

Parameter

Type

Description

config

AoqVideoCodecConfig

Video encoding configuration

Returns 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.

setVideoDecoderConfig(config: AoqVideoCodecConfig): number

Parameter

Type

Description

config

AoqVideoCodecConfig

Video decoding configuration

Returns 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.

enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number

Parameter

Type

Description

trackType

AoqTrackType

Media track type

enable

boolean

true: enable transmission; false: disable transmission

Returns 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.

sendDataMsg(msg: AoqDataMsg): number

Parameter

Type

Description

msg

AoqDataMsg

Message object; msg.data must contain nonempty UTF-8 bytes

Returns 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.

const data = new TextEncoder().encode(JSON.stringify({ type: 'user_message', text: '你好' }));
const code = engine.sendDataMsg({ data });
if (code !== 0) console.error('消息未受理', code);

The JSON example only demonstrates encoding. Follow the selected model's data message protocol for actual fields and application readiness.


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.

import { AoqConnectionStatus } from 'aoq-web-sdk';

const handleStatus = (status: AoqConnectionStatus) => console.log('连接状态', status);
engine.on('onConnectionStatusChange', handleStatus);
engine.off('onConnectionStatusChange', handleStatus);

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.

engine.on('onError', (code: number, message: string) => { /* 在此处理回调 */ });

Parameter

Type

Description

code

number

Error code; see AoqErrorCode

message

string

Error description

onWarning

Reports engine warnings for nonfatal conditions that require attention.

engine.on('onWarning', (code: number, message: string) => { /* 在此处理回调 */ });

Parameter

Type

Description

code

number

Warning code; see AoqWarningCode

message

string

Warning description

onConnectionStatusChange

Reports connection status changes.

engine.on('onConnectionStatusChange', (status: AoqConnectionStatus) => { /* 在此处理回调 */ });

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.

engine.on('onStats', (stats: AoqStats) => { /* 在此处理回调 */ });

Parameter

Type

Description

stats

AoqStats

Statistics object

onAudioDeviceStateChanged

Reports audio capture and playback device operation state changes.

engine.on('onAudioDeviceStateChanged', (state: AoqAudioDeviceState) => { /* 在此处理回调 */ });

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.

engine.on('onAudioDeviceRouteChanged', (routeType: AoqAudioDeviceRouteType) => { /* 在此处理回调 */ });

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.

engine.on('onAudioFileState', (state: AoqAudioFileState) => { /* 在此处理回调 */ });

Parameter

Type

Description

state

AoqAudioFileState

Audio file state

onLocalAudioVolumeIndication

Reports local capture volume. Call enableLocalAudioVolumeIndication to enable it first.

engine.on('onLocalAudioVolumeIndication', (volume: AoqAudioVolume) => { /* 在此处理回调 */ });

Parameter

Type

Description

volume

AoqAudioVolume

Volume information

onVideoDeviceStateChanged

Reports video capture device operation state changes.

engine.on('onVideoDeviceStateChanged', (state: AoqVideoDeviceState) => { /* 在此处理回调 */ });

Parameter

Type

Description

state

AoqVideoDeviceState

Video device state

onDataMsg

Reports received data messages.

engine.on('onDataMsg', (msg: AoqDataMsg) => { /* 使用 msg.data 读取消息数据 */ });

Parameter

Type

Description

msg

AoqDataMsg

Received message object. Use TextDecoder to read UTF-8 text from msg.data.

Include Data in 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.

Supported 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.

These fields do not modify HTTP response headers or enable public diagnostic APIs.

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.

The application backend must return complete, valid connection credentials. Map 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

Local preview is CSS-mirrored automatically when the actual capture track is front-facing; an unknown direction is not mirrored. Encoded pixels are unchanged. No separate mirror or orientation configuration is available. Invalid replacements preserve the existing binding. Unbinding with null removes only SDK-owned rendering nodes, preserving application nodes.

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

onStats does not currently populate dataMsgPublishStats or dataMsgSubscribeStats. Audio bitrate / bytes contain connection totals rather than separate audio traffic; encodeVolume / playVolume are fixed at 0. Video bitrate / bytes are also fixed at 0; only frame rates come from the video engine. Use networkStats for total traffic and onLocalAudioVolumeIndication for capture volume.

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

The type is defined, but onStats does not currently populate this array.

AoqDataMsgSubscribeStats

Data message subscription statistics.

Field

Type

Default

Description

trackType

AoqTrackType

—

Track type

bitrate

number

—

Current bitrate in bps

bytes

number

—

Cumulative bytes received

The type is defined, but onStats does not currently populate this array.

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.