Skip to main content

AOQ Web SDK API reference

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

APIDescription
createEngineCreate a singleton engine
createAoqClientEngineEquivalent named factory function
destroyDestroy the engine
getVersionGet the SDK version
isAoqSupportedCheck browser capabilities
connectInitiate a connection
disconnectDisconnect

Audio device management

APIDescription
startAudioCaptureStart audio capture
stopAudioCaptureStop audio capture
muteAudioCaptureMute audio capture
startAudioPlayerStart audio playback
stopAudioPlayerStop audio playback
pauseAudioPlayerPause playback with fade-out
resumeAudioPlayerResume playback with default fade-in
interruptAudioPlayerInterrupt playback

Audio encoding configuration

APIDescription
setAudioEncoderConfigSet audio encoding parameters
setAudioDecoderConfigSet audio decoding parameters

Local volume indication

APIDescription
enableLocalAudioVolumeIndicationEnable local volume indication

Video device management

APIDescription
startVideoCaptureStart video capture
getCamerasEnumerate cameras
switchCameraSwitch cameras by direction preference or device ID
stopVideoCaptureStop video capture
setLocalViewSet the local video container
setRemoteViewSet the remote video container

Video encoding configuration

APIDescription
setVideoEncoderConfigSet video encoding parameters
setVideoDecoderConfigSet video decoding parameters

Media stream transmission control

APIDescription
enableSendMediaStreamEnable or disable media stream transmission

Real-time messages

APIDescription
sendDataMsgSend a data message

Event callbacks

APIDescription
onErrorError callback
onWarningWarning callback
onConnectionStatusChangeConnection status changes
onStatsStatistics
onAudioDeviceStateChangedAudio device state changes
onAudioDeviceRouteChangedAudio route changes
onAudioFileStateReserved audio file state event; not currently emitted
onLocalAudioVolumeIndicationLocal volume indication
onVideoDeviceStateChangedVideo device state changes
onDataMsgData messages

API details

Engine lifecycle

createEngine

Creates a singleton engine. Repeated calls return the existing instance.
static createEngine(config: AoqCreateConfig): AoqClientEngine | null
ParameterTypeDescription
configAoqCreateConfigEngine 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
ParameterTypeDescription
configAoqCreateConfigRequired; {} 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
ParameterTypeDescription
configAoqConnectConfigConnection 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>
ParameterTypeDescription
configAoqAudioCaptureConfigAudio 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
ParameterTypeDescription
mutebooleantrue: mute; false: unmute
Returns 0 on success.

startAudioPlayer

Starts the audio player and initializes the output device asynchronously.
startAudioPlayer(config: AoqAudioPlaybackConfig): Promise<number>
ParameterTypeDescription
configAoqAudioPlaybackConfigAudio 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
ParameterTypeDescription
fadeMsnumberFade-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
ParameterTypeDescription
fadeMsnumberReserved 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
ParameterTypeDescription
trackTypeAoqTrackTypeCompatibility parameter. Pass Audio. Currently, this parameter does not select a playback stream.
fadeMsnumberFade-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
ParameterTypeDescription
configAoqAudioCodecConfigAudio 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
ParameterTypeDescription
configAoqAudioCodecConfigAudio 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
ParameterTypeDescription
configAoqAudioVolumeIndicationConfigVolume 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
ParameterTypeDescription
configAoqVideoCaptureConfigVideo 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
ParameterTypeRequiredDescription
cameraPreferenceAoqCameraDirection | stringNoPreferred 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
ParameterTypeDescription
trackTypeAoqTrackTypeOnly AoqTrackTypeVideo is supported. Other types return AoqECUnSupport(3).
canvasAoqVideoCanvas | nullRendering 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
ParameterTypeDescription
trackTypeAoqTrackTypeOnly AoqTrackTypeVideo is supported. Other types return AoqECUnSupport(3).
canvasAoqVideoCanvas | nullRendering 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
ParameterTypeDescription
configAoqVideoCodecConfigVideo 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
ParameterTypeDescription
configAoqVideoCodecConfigVideo 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
ParameterTypeDescription
trackTypeAoqTrackTypeMedia track type
enablebooleantrue: 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
ParameterTypeDescription
msgAoqDataMsgMessage 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);
EventCallback signatureDescription
onError(code: number, message: string) => voidError callback
onWarning(code: number, message: string) => voidWarning callback
onConnectionStatusChange(status: AoqConnectionStatus) => voidConnection status changes
onStats(stats: AoqStats) => voidStatistics
onAudioDeviceStateChanged(state: AoqAudioDeviceState) => voidAudio device state changes
onAudioDeviceRouteChanged(routeType: AoqAudioDeviceRouteType) => voidAudio route changes
onAudioFileState(state: AoqAudioFileState) => voidReserved; not currently emitted
onLocalAudioVolumeIndication(volume: AoqAudioVolume) => voidLocal volume indication
onVideoDeviceStateChanged(state: AoqVideoDeviceState) => voidVideo device state changes
onDataMsg(msg: AoqDataMsg) => voidData 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) => { /* 在此处理回调 */ });
ParameterTypeDescription
codenumberError code; see AoqErrorCode
messagestringError description

onWarning

Reports engine warnings for nonfatal conditions that require attention.
engine.on('onWarning', (code: number, message: string) => { /* 在此处理回调 */ });
ParameterTypeDescription
codenumberWarning code; see AoqWarningCode
messagestringWarning description

onConnectionStatusChange

Reports connection status changes.
engine.on('onConnectionStatusChange', (status: AoqConnectionStatus) => { /* 在此处理回调 */ });
ParameterTypeDescription
statusAoqConnectionStatusCurrent 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) => { /* 在此处理回调 */ });
ParameterTypeDescription
statsAoqStatsStatistics object

onAudioDeviceStateChanged

Reports audio capture and playback device operation state changes.
engine.on('onAudioDeviceStateChanged', (state: AoqAudioDeviceState) => { /* 在此处理回调 */ });
ParameterTypeDescription
stateAoqAudioDeviceStateAudio 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) => { /* 在此处理回调 */ });
ParameterTypeDescription
routeTypeAoqAudioDeviceRouteTypeRoute 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) => { /* 在此处理回调 */ });
ParameterTypeDescription
stateAoqAudioFileStateAudio file state

onLocalAudioVolumeIndication

Reports local capture volume. Call enableLocalAudioVolumeIndication to enable it first.
engine.on('onLocalAudioVolumeIndication', (volume: AoqAudioVolume) => { /* 在此处理回调 */ });
ParameterTypeDescription
volumeAoqAudioVolumeVolume information

onVideoDeviceStateChanged

Reports video capture device operation state changes.
engine.on('onVideoDeviceStateChanged', (state: AoqVideoDeviceState) => { /* 在此处理回调 */ });
ParameterTypeDescription
stateAoqVideoDeviceStateVideo device state

onDataMsg

Reports received data messages.
engine.on('onDataMsg', (msg: AoqDataMsg) => { /* 使用 msg.data 读取消息数据 */ });
ParameterTypeDescription
msgAoqDataMsgReceived 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.
FieldTypeRequiredDefaultDescription
workDirstringNo—Reserved; the Web SDK does not use this field to select a storage directory
enableDumpAudiobooleanNofalseSave audio debug data. Obtain authorization and control access to user audio.
enableDumpExportbooleanNofalseEffective only when enableDumpAudio=true. Asynchronously exports a dump ZIP and removes the corresponding OPFS files on destruction.
maxEncodedVideoFrameBytesnumberNo194560 (190×1024)JPEG target maximum frame size in bytes. 0 disables the limit. Oversized frames are reduced in quality; invalid values use the default.
enableDropOversizedVideoFramebooleanNofalseDrop 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.
extrasstringNo—JSON object string. Invalid JSON, a non-object value, or an invalid remote rendering policy makes createEngine return null.
Supported extras fields:
JSON fieldTypeDefaultDescription
remoteVideoRenderer'auto' | 'video' | 'canvas''auto'Remote rendering policy. auto prefers video and falls back to canvas when needed.
user_specified_enable_av_syncbooleantrueEnable audio/video synchronization. Use a JSON boolean.
user_specified_audio_playback_transport'message-port'AutomaticForce 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.
FieldTypeRequiredDefaultDescription
tokenstringYes—Nonempty temporary client token corresponding to aoqTokenForClient, not an API key
sidstringYes—Nonempty session ID. Use the complete sid string from the authentication response.
wtBaseUrlstringNoDerived from RelayPreferred HTTPS WT URL for a single route. Ignored for multiple routes, which connect to /aoq on each host and port.
signedSidstringYes (at runtime)—Complete signed SID, typically the complete sid from authentication. Optional in TypeScript, but required by the current WT connection flow.
certFingerprintstring | string[]Conditional—Shared SHA-256 WT certificate fingerprint. Routes without their own fingerprint must be able to use this value.
workspaceIdHashstringNo—Corresponds to extraInfo.workspaceIdHash. Do not substitute the original Workspace ID.
relayEndpointsAoqRelayEndpoint[]Yes—Complete endpoint list with at least one entry
publishTracksAoqTrackParam[]Yes—Uplink tracks. May be empty, but cannot be empty together with subscribeTracks.
subscribeTracksAoqTrackParam[]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.
FieldTypeRequiredDefaultDescription
routeIndexnumberYes (at runtime)—Unique integer from 0 to 2147483647. The lowest index is used initially. Optional in TypeScript.
certFingerprintstring | string[]ConditionalShared fingerprintNonempty route fingerprints override the shared value. Required if no shared fingerprint is available.
endpointstringYes—WT host name or IP, without a scheme, path, whitespace, user information, or query string. IPv6 is supported.
portnumberYes—WT port, an integer from 1 to 65535

AoqTrackParam

Track properties.
FieldTypeRequiredDefaultDescription
trackTypeAoqTrackTypeYes—Audio, Video, or Data. No duplicates within a direction. Screen is not currently supported.
trackModeAoqTrackModeNoSegment for audio downlinkControls 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.
FieldTypeDefaultDescription
supportedboolean—Whether the environment has basic AOQ connection capabilities
missingFeaturesAoqMissingFeature[]—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.
FieldTypeRequiredDefaultDescription
channelnumberNo1Requested capture channels: 1 (mono) or 2 (stereo). Actual settings may be determined by the device track.

AoqAudioPlaybackConfig

Audio playback configuration.
FieldTypeRequiredDefaultDescription
channelnumberNo1Requested playback channels: 1 or 2. Output uses the actual AudioContext sample rate.
playOnlyAndIgnoreMutebooleanNofalseFor 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.
FieldTypeRequiredDefaultDescription
trackTypeAoqTrackTypeNo—Reserved; not currently used to select an audio stream
codecTypeAoqEncoderTypeNoAoqEncoderTypeAudioPCMPCM / Opus. Must match the peer's negotiated configuration.
sampleRatenumberNo48000Sample rate in Hz. Negotiated values: 8000, 12000, 16000, 24000, 32000, 44100, 48000. The browser must also support the selected encoding.
channelnumberNo1Number of channels: 1 or 2
bitratenumberNo32000 (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.
FieldTypeRequiredDefaultDescription
intervalnumberNo0Callback interval in ms. Values <=0 disable callbacks; positive values below 10 are treated as 10.
smoothnumberNo3Volume smoothing factor, 0..10. Larger values provide more smoothing.
reportSpeechbooleanNofalseWhether to report voice activity (VAD)

AoqAudioVolume

Local volume information.
FieldTypeDefaultDescription
volumenumber—Smoothed instantaneous volume, range [0-255]
isSpeechboolean—Optional voice activity flag, meaningful only when reportSpeech=true. Handle missing values.

AoqAudioDeviceState

Audio device state callback data.
FieldTypeDefaultDescription
stateAoqAudioDeviceStateCode—Audio device state code
reasonnumber—Reason code; see AoqErrorCode

AoqAudioFileState

Reserved audio file playback state structure; the Web SDK does not currently emit the corresponding event.
FieldTypeDefaultDescription
fileIdstring—Audio file ID
stateCodeAoqAudioFileStateCode—File playback state code
errorCodenumber—Error code

Video types

AoqVideoCaptureConfig

Video capture configuration.
FieldTypeRequiredDefaultDescription
widthnumberNo1280Requested capture width in pixels, using an ideal constraint. Actual width is selected by the browser/device.
heightnumberNo720Requested capture height in pixels, using an ideal constraint. Actual height is selected by the browser/device.
fpsnumberNo15Requested capture frame rate, using ideal and max constraints
cameraPreferenceAoqCameraDirection | stringNoBrowser choiceCamera direction or device ID preference using ideal constraints. Fallback is allowed; blank strings are invalid.

AoqVideoCodecConfig

Video codec configuration.
FieldTypeRequiredDefaultDescription
trackTypeAoqTrackTypeNo—Reserved; not currently used to select a video stream
codecTypeAoqEncoderTypeNoAoqEncoderTypeVideoH264H.264 / JPEG. Must match the peer's negotiated configuration.
widthnumberNo540Target encoding width or negotiated downlink width in pixels. Must be a positive integer when connecting.
heightnumberNo960Target encoding height or negotiated downlink height in pixels. Must be a positive integer when connecting.
fpsnumberNo5Encoding frame rate or negotiated downlink frame rate. Must be a positive integer when connecting.
bitratenumberNo500000 (encoding)Positive target encoding bitrate in bps. Not used for decoding.
minBitratenumberNo128000Minimum 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.
keyframeIntervalnumberNo2H.264 keyframe interval in seconds, treated as at least 1 second for encoding. Not used for JPEG or decoding.

AoqVideoCanvas

Video rendering container configuration.
FieldTypeRequiredDefaultDescription
viewHTMLElement | stringYes—Regular container element or its DOM ID without #. Do not use video, audio, canvas, img, or void elements directly.
renderModeAoqRenderModeNoAoqRenderModeAuto(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.
FieldTypeDefaultDescription
stateAoqVideoDeviceStateCode—Video device state code
reasonnumber—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.
FieldTypeRequiredDefaultDescription
dataUint8ArrayYes—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.
FieldTypeDefaultDescription
audioPublishStatsAoqAudioPublishStats[]—Audio publishing statistics
audioSubscribeStatsAoqAudioSubscribeStats[]—Audio subscription statistics
videoPublishStatsAoqVideoPublishStats[]—Video publishing statistics
videoSubscribeStatsAoqVideoSubscribeStats[]—Video subscription statistics
dataMsgPublishStatsAoqDataMsgPublishStats[]—Data message publishing statistics
dataMsgSubscribeStatsAoqDataMsgSubscribeStats[]—Data message subscription statistics
networkStatsAoqNetworkStats—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.
FieldTypeDefaultDescription
trackTypeAoqTrackType—Track type
bitratenumber—Total connection uplink application bitrate in bps, not a separate audio bitrate
bytesnumber—Total connection uplink application bytes, not a separate audio total
encodeVolumenumber0Placeholder. Use onLocalAudioVolumeIndication for capture volume.

AoqAudioSubscribeStats

Audio subscription statistics.
FieldTypeDefaultDescription
trackTypeAoqTrackType—Track type
bitratenumber—Total connection downlink application bitrate in bps, not a separate audio bitrate
bytesnumber—Total connection downlink application bytes, not a separate audio total
playVolumenumber0Placeholder; does not indicate whether playback is muted

AoqVideoPublishStats

Video publishing statistics.
FieldTypeDefaultDescription
trackTypeAoqTrackType—Track type
bitratenumber0Placeholder; separate video bitrate is not currently reported
bytesnumber0Placeholder; separate video byte count is not currently reported
encodeFpsnumber—Encoding frame rate

AoqVideoSubscribeStats

Video subscription statistics.
FieldTypeDefaultDescription
trackTypeAoqTrackType—Track type
bitratenumber0Placeholder; separate video bitrate is not currently reported
bytesnumber0Placeholder; separate video byte count is not currently reported
decodeFpsnumber—Decoding frame rate
renderFpsnumber—Rendering frame rate

AoqDataMsgPublishStats

Data message publishing statistics.
FieldTypeDefaultDescription
trackTypeAoqTrackType—Track type
bitratenumber—Current bitrate in bps
bytesnumber—Cumulative bytes sent
The type is defined, but onStats does not currently populate this array.

AoqDataMsgSubscribeStats

Data message subscription statistics.
FieldTypeDefaultDescription
trackTypeAoqTrackType—Track type
bitratenumber—Current bitrate in bps
bytesnumber—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.
FieldTypeDefaultDescription
sendBitratenumber—Uplink bitrate in bps
sendBytesnumber—Cumulative uplink bytes
recvBitratenumber—Downlink bitrate in bps
recvBytesnumber—Cumulative downlink bytes
lossnumber—Optional uplink loss ratio (0–1). Uses browser QUIC observations when available, otherwise a Relay Datagram estimate. Omitted if unknown.
rttnumber—Optional round-trip time in ms; omitted if unknown
bwenumber—Optional effective Client→Relay application send budget in bps; omitted when unknown or stale
audioReserveBpsnumber—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 memberValueDescription
AoqTrackTypeAudio0Audio
AoqTrackTypeVideo1Video
AoqTrackTypeData2Data messages
AoqTrackTypeScreen3Reserved; not supported in the current connection flow

AoqTrackMode

Audio transport mode.
Enum memberValueDescription
AoqTrackModeSegment0Segment mode
AoqTrackModeStream1Realtime stream mode

AoqEncoderType

Track media format.
Enum memberValueDescription
AoqEncoderTypeUnknown0Unknown
AoqEncoderTypeAudioPCM1PCM audio
AoqEncoderTypeAudioOpus2Opus audio
AoqEncoderTypeVideoH2643H.264 video
AoqEncoderTypeVideoJpeg4JPEG video
AoqEncoderTypeDataText5Text data

AoqConnectionStatus

Engine connection status.
Enum memberValueDescription
AoqConnectionStatusDisconnected0Disconnected
AoqConnectionStatusConnecting1Connecting
AoqConnectionStatusConnected2Connected
AoqConnectionStatusFailed3Connection failed

AoqErrorCode

Error codes.
Enum memberValueDescription
AoqECOK0Success
AoqECParamInvalid1Invalid parameter
AoqECStateInvalid2Invalid state
AoqECUnSupport3Not implemented for the current platform/mode
AoqECAudio100General audio error
AoqECAudioExternalBufferFull110External audio buffer full
AoqECAudioDevice120General audio device error
AoqECAudioDeviceRecordingAuthFailed121Microphone permission denied
AoqECAudioDeviceRecordingOccupied122Microphone in use
AoqECAudioDeviceRecordingBackgroundStart123Capture started in background
AoqECAudioDeviceRecordingStartFail124Capture failed to start
AoqECAudioDevicePlayoutOccupied125Playback device in use
AoqECAudioDevicePlayoutBackgroundStart126Playback started in background
AoqECAudioDevicePlayoutStartFail127Playback failed to start
AoqECAudioDeviceEarpieceRequiresVoipMode128Earpiece requires VoIP mode
AoqECVideo200General video error
AoqECVideoExternalBufferFull210External video buffer full
AoqECVideoExternalCaptureNotEnabled211External video capture not enabled
AoqECVideoExternalEncoderNotEnabled212External video encoder not enabled
AoqECVideoDevice220General video device error
AoqECVideoDeviceCameraOpenFail221Camera failed to open
AoqECVideoDeviceCameraAuthFailed222Camera permission denied
AoqECVideoDeviceCameraOccupied223Camera in use
AoqECVideoDeviceCameraRunningError224Camera runtime error
AoqECVideoCodec230General video codec error
AoqECVideoCodecEncoderInitFail231Video encoder initialization failed
AoqECVideoRender240General video rendering error
AoqECVideoRenderCreateFail241Renderer creation failed
AoqECVideoRenderDrawError242Rendering draw error

AoqWarningCode

Warning codes.
Enum memberValueDescription
AoqWCOK0Normal
AoqWCAudio100General audio warning
AoqWCAudioHowling101Acoustic feedback detected
AoqWCAudioDevice120General audio device warning
AoqWCAudioDeviceMicEnumerateError121Microphone enumeration error
AoqWCAudioDeviceMicStartTimeout122Microphone start timeout
AoqWCAudioDeviceRecordingError123Capture error
AoqWCAudioDeviceSpeakerEnumerateError124Speaker enumeration error
AoqWCAudioDeviceSpeakerStartTimeout125Speaker start timeout
AoqWCAudioDevicePlayoutError126Playback error
AoqWCAudioDeviceSilentMode127Device in silent mode
AoqWCVideo200General video warning
AoqWCVideoCameraEnumerateError201Camera enumeration error
AoqWCVideoEncoderSwitched202Video encoder switched
AoqWCVideoRenderDowngrade203Rendering fallback

AoqAudioDeviceStateCode

Audio device state codes.
Enum memberValueDescription
AoqAudioDeviceNone0No state
AoqAudioDeviceRecordStarting1Capture starting
AoqAudioDeviceRecordStarted2Capture started
AoqAudioDeviceRecordStopping3Capture stopping
AoqAudioDeviceRecordStopped4Capture stopped
AoqAudioDeviceRecordFail5Capture failed
AoqAudioDevicePlayStarting6Playback starting
AoqAudioDevicePlayStarted7Playback started
AoqAudioDevicePlayStopping8Playback stopping
AoqAudioDevicePlayStopped9Playback stopped
AoqAudioDevicePlayFail10Playback failed

AoqAudioDeviceRouteType

Audio device route types.
Enum memberValueDescription
AoqAudioDeviceRouteDefault0Default route
AoqAudioDeviceRouteHeadset1Headset
AoqAudioDeviceRouteSpeakerPhone4Built-in speaker
AoqAudioDeviceRouteUsb5USB device
AoqAudioDeviceRouteBluetooth6Bluetooth device

AoqAudioFileStateCode

Audio file playback state codes.
Enum memberValueDescription
AoqAudioFileNone0No state
AoqAudioFileStarted1Playback started
AoqAudioFileStopped2Playback stopped
AoqAudioFilePaused3Playback paused
AoqAudioFileResumed4Playback resumed
AoqAudioFileEnded5Playback ended
AoqAudioFileBuffering6Buffering
AoqAudioFileBufferingEnd7Buffering ended
AoqAudioFileFailed8Playback failed

AoqCameraDirection

Enum memberValueDescription
AoqCameraDirectionFront0Prefer front-facing
AoqCameraDirectionBack1Prefer rear-facing

AoqVideoDeviceStateCode

Video device state codes.
Enum memberValueDescription
AoqVideoDeviceNone0No state
AoqVideoDeviceCaptureStarting1Capture starting
AoqVideoDeviceCaptureStarted2Capture started
AoqVideoDeviceCaptureStopping3Capture stopping
AoqVideoDeviceCaptureStopped4Capture stopped
AoqVideoDeviceCaptureFail5Capture failed

AoqMirrorMode

Reserved mirror mode enum. The Web SDK has no configuration or API that uses it.
Enum memberValueDescription
AoqMirrorModeDisabled0Mirroring disabled
AoqMirrorModeEnabled1Mirroring enabled

AoqOrientationMode

Reserved orientation mode enum. The Web SDK has no configuration or API that uses it.
Enum memberValueDescription
AoqOrientationModeAuto0Automatic
AoqOrientationModePortrait1Portrait
AoqOrientationModeLandscape2Landscape

AoqRenderMode

Video fitting modes.
Enum memberValueDescription
AoqRenderModeAuto0Default: fit the full image and preserve aspect ratio
AoqRenderModeStretch1Stretch to fill the container
AoqRenderModeFill2Fit the full image and preserve aspect ratio, allowing black bars
AoqRenderModeCrop3Fill 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.
CategoryPublic declarationsCurrent scope
Audio file mixingAoqAudioFileMixConfig, AoqAudioFileState, AoqAudioFileStateCodeNo file playback or mixing controls; file state events are not emitted
External audio and observersAoqAudioExternalStreamConfig, AoqAudioExternalFrameMeta, AoqAudioObserverParams, AoqAudioSource, AoqAudioStreamDirectionNo external audio input or audio frame observer registration methods
External video and observersAoqExternalVideoFrameMeta, AoqExternalVideoEncodedFrameMeta, AoqVideoObserverParams, AoqVideoSource, AoqVideoPixelFormat, AoqVideoObserverAlignment, AoqVideoCodecTypeNo external video frame input or video frame observer registration methods. Codec configuration uses AoqEncoderType.
Mirroring and orientationAoqMirrorMode, AoqOrientationModeNo corresponding configuration fields or methods. Local preview mirroring is automatic.
Low-level audio devicesAoqAudioDeviceEvent, AudioDeviceApiError, AudioDeviceErrorCodeLow-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.