Skip to main content

AOQ Web SDK API リファレンス

AOQ Web SDK は、ブラウザーでのリアルタイム音声、映像、データのやり取りをサポートします。本リファレンスでは、エンジン管理、音声・映像のキャプチャと再生、データメッセージ、イベントコールバックの API を説明します。

SDK のインストール

AOQ Web SDK は WebTransport(HTTP/3 / QUIC)でサーバーに接続し、Worker 内で音声、映像、データメッセージを送受信します。WebTransport 対応ブラウザーと HTTPS のセキュアコンテキストが必要です。AoqClientEngine.isAoqSupported() でブラウザーの基本機能を確認できます。 npm で SDK をインストールします。
npm install aoq-web-sdk@1.0.1-60040320
または、SDK ダウンロードからインストールパッケージを取得し、プロジェクトディレクトリで次のコマンドを実行します。パッケージのパスを実際の場所に置き換えてください。
npm install ./aoq-web-sdk-1.0.1-60040320.tgz

API 一覧

エンジンのライフサイクル

API説明
createEngineシングルトンエンジンの作成
createAoqClientEngine同等の名前付きファクトリー関数
destroyエンジンの破棄
getVersionSDK バージョンの取得
isAoqSupportedブラウザー機能の確認
connect接続の開始
disconnect切断

音声デバイスの管理

API説明
startAudioCapture音声キャプチャの開始
stopAudioCapture音声キャプチャの停止
muteAudioCapture音声キャプチャのミュート
startAudioPlayer音声再生の開始
stopAudioPlayer音声再生の停止
pauseAudioPlayerフェードアウト付き再生一時停止
resumeAudioPlayerデフォルトのフェードインで再生再開
interruptAudioPlayer再生の中断

音声エンコード設定

API説明
setAudioEncoderConfig音声エンコードパラメーターの設定
setAudioDecoderConfig音声デコードパラメーターの設定

ローカル音量通知

API説明
enableLocalAudioVolumeIndicationローカル音量通知の有効化

映像デバイスの管理

API説明
startVideoCapture映像キャプチャの開始
getCamerasカメラの列挙
switchCamera向きの優先設定またはデバイス ID によるカメラ切り替え
stopVideoCapture映像キャプチャの停止
setLocalViewローカル映像コンテナーの設定
setRemoteViewリモート映像コンテナーの設定

映像エンコード設定

API説明
setVideoEncoderConfig映像エンコードパラメーターの設定
setVideoDecoderConfig映像デコードパラメーターの設定

メディアストリームの送信制御

API説明
enableSendMediaStreamメディアストリーム送信の有効化と無効化

リアルタイムメッセージ

API説明
sendDataMsgデータメッセージの送信

イベントコールバック

API説明
onErrorエラーコールバック
onWarning警告コールバック
onConnectionStatusChange接続状態の変更
onStats統計情報
onAudioDeviceStateChanged音声デバイスの状態変更
onAudioDeviceRouteChanged音声ルートの変更
onAudioFileState予約済み音声ファイル状態イベント。現在は発生しません
onLocalAudioVolumeIndicationローカル音量通知
onVideoDeviceStateChanged映像デバイスの状態変更
onDataMsgデータメッセージ

API 詳細

エンジンのライフサイクル

createEngine

シングルトンのエンジンを作成します。繰り返し呼び出すと既存のインスタンスを返します。
static createEngine(config: AoqCreateConfig): AoqClientEngine | null
パラメーター型説明
configAoqCreateConfigエンジン作成設定
成功時は AoqClientEngine インスタンス、失敗時は null を返します。 初期化済みのシングルトンには設定を再適用しません。新しい設定で作成するには、既存のエンジンを破棄してください。

createAoqClientEngine

パッケージがエクスポートする名前付きファクトリーで、AoqClientEngine.createEngine(config) と同等です。インスタンスメソッドではなく、追加の初期化も不要です。
function createAoqClientEngine(config: AoqCreateConfig): AoqClientEngine | null
パラメーター型説明
configAoqCreateConfig必須。{} も有効です。繰り返し作成しても設定は再適用されません。
成功時はシングルトンエンジン、失敗時は null を返します。
import { createAoqClientEngine } from 'aoq-web-sdk';

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

destroy

エンジンを破棄し、リソース解放を開始して、すべてのイベントリスナーを削除します。
static destroy(): number
成功時は 0、インスタンスがない場合は AoqECStateInvalid(2) を返します。 このメソッドは同期的に戻ります。ログ保存や任意のダンプ出力はバックグラウンドで非同期実行され、戻った時点で未完了の場合があります。SDK を再使用するには createEngine で作成し直してください。破棄済みインスタンスは再使用できません。

getVersion

SDK のバージョンを取得します。
static getVersion(): string
インストール済みパッケージのバージョン文字列を返します。ドキュメント改訂番号やソースのコミット ID ではありません。

isAoqSupported

AOQ 接続に必要なブラウザーの基本機能を確認します。
static isAoqSupported(): Promise<AoqSupportResult>
対応状況と不足機能を含む Promise<AoqSupportResult> を返します。 Worker 内で WebTransport を検査し、タイムアウトは 5 秒です。ネットワーク到達性、サーバー設定、認証、デバイス権限、個別のメディア設定は検査しません。supported: true は接続や通話の成功を保証しません。

connect

サーバーへの接続を開始します。
connect(config: AoqConnectConfig): number
パラメーター型説明
configAoqConnectConfigトークン、セッション ID、Relay エンドポイントなどの接続認証情報
リクエストの受理時に 0 を返します。 エンジン作成、イベント登録、コーデック設定の後に呼び出します。通常は Disconnected から接続し、Failed からの再試行も可能です。それ以外の状態では AoqECStateInvalid(2) を返します。無効なトラック、メディア、接続設定、または必要な WebCodecs 機能なしでの Opus 選択は AoqECParamInvalid(1) になる場合があります。Network Worker が利用できない場合は AoqECStateInvalid(2) を返します。 結果は onConnectionStatusChange で非同期通知されます。Connected は MEDIA_SETUP が完了し、メディアトラックがバインドされた状態です。モデルのデータプロトコルに従ってセッションを設定し、アプリケーションの準備完了を確認してから音声や映像の送信を有効にしてください。

disconnect

サーバーとの接続を切断します。
disconnect(): number
リクエストの受理時に 0 を返します。 結果は onConnectionStatusChange で通知されます。AoqConnectionStatusDisconnected を待ってからコーデック設定を変更し、再接続してください。切断済みの場合は AoqECStateInvalid(2) を返します。切断してもデバイスは停止しないため、通話終了時はキャプチャと再生の停止メソッドも呼び出してください。

音声デバイスの管理

startAudioCapture

マイクのキャプチャを開始し、デバイス権限を非同期で要求します。
startAudioCapture(config: AoqAudioCaptureConfig): Promise<number>
パラメーター型説明
configAoqAudioCaptureConfig音声キャプチャ設定
Promise<number> を返します。0 は成功です。 初回または未許可の場合、ブラウザーがマイク権限を要求することがあります。キャプチャ状態は onAudioDeviceStateChanged で通知されます。 輻輳時、送信キューで約 100 ms 待機した上り音声は、遅延の蓄積を防ぐため破棄されます。送信開始済みの音声は取り消しません。この値はエンドツーエンド遅延の上限ではありません。

stopAudioCapture

音声キャプチャを停止します。
stopAudioCapture(): number
成功時に 0 を返します。 デバイスが未起動または停止済みの場合、AoqECStateInvalid(2) を返します。

muteAudioCapture

音声キャプチャをミュートまたは解除します。ミュート中もキャプチャは続きますが、無音フレームを送信します。
muteAudioCapture(mute: boolean): number
パラメーター型説明
mutebooleantrue:ミュート、false:解除
成功時に 0 を返します。

startAudioPlayer

音声プレーヤーを開始し、出力デバイスを非同期で初期化します。
startAudioPlayer(config: AoqAudioPlaybackConfig): Promise<number>
パラメーター型説明
configAoqAudioPlaybackConfig音声再生設定
Promise<number> を返します。0 は成功です。 再生状態は onAudioDeviceStateChanged で通知されます。 ユーザーのクリックイベントから呼び出し、自動再生制限に対応してください。開始中または開始済みの場合は AoqECStateInvalid(2) を返します。 Realtime モード(下り音声の trackMode が Stream)では、プレーヤー開始前の受信音声も蓄積せず継続的に消費します。初回を含め毎回の開始で以前の音声を消去し、新規受信分から再生します。Segment モードは未再生分を保持します。

stopAudioPlayer

音声プレーヤーを停止します。
stopAudioPlayer(): number
成功時に 0 を返します。 デバイスが未起動または停止済みの場合、AoqECStateInvalid(2) を返します。 Realtime モードでは出力停止後も受信音声の消費と映像再生が続きます。再開時は新しい音声のみ再生します。一時停止や中断状態は再起動後も保持されます。Segment モードは未再生分を保持します。

pauseAudioPlayer

フェードアウト後に再生を一時停止します。再開には resumeAudioPlayer を呼び出します。
pauseAudioPlayer(fadeMs: number): number
パラメーター型説明
fadeMsnumberフェードアウト時間(ms)。実デバイスのサンプルレートでサンプル数に丸めます。0 は無効化、負数や非有限値は 100 ms を使用します。
制御リクエストの受理時に 0 を返します。フェードアウトは未完了の場合があり、プレーヤーが再生中であることも保証しません。 Segment モードは未再生音声と読み取り位置を保持して、その位置から再開します。Realtime モードは待機音声を破棄し、停止中も受信分を消費して現在のリアルタイム位置から再開します。一時停止中の音声は再生しません。

resumeAudioPlayer

一時停止または中断した再生をデフォルトのフェードインで再開します。Segment は 2 ms、Realtime は 100 ms です。
resumeAudioPlayer(fadeMs: number): number
パラメーター型説明
fadeMsnumber予約済みで、現在は指定時間を無視します。デフォルトのフェードインを使用し、0 でも無効化できません。
制御リクエストの受理時に 0 を返します。再開処理は未完了の場合があります。

interruptAudioPlayer

再生を中断し、フェードアウト後に残りの未再生音声を破棄します。Segment の一時停止とは異なり、再開しても破棄分は再生しません。
interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number
パラメーター型説明
trackTypeAoqTrackType互換性パラメーター。Audio を指定してください。現在はこの値で再生ストリームを選択しません。
fadeMsnumberフェードアウト時間(ms)。実デバイスのサンプルレートでサンプル数に丸めます。0 は無効化、負数や非有限値は 100 ms を使用します。
制御リクエストの受理時に 0 を返します。中断は未完了の場合があり、プレーヤーが再生中であることも保証しません。 サーバーが次のラウンドの音声を送信すると自動再開します。resumeAudioPlayer でも再開できます。 一時停止中の中断要求は無視されますが、0 を返す場合があります。その後 Segment は停止前の残りを再生します。一時停止から中断する手順で再生キューは消去できません。

音声エンコード設定

setAudioEncoderConfig

音声エンコードパラメーターを設定します。
setAudioEncoderConfig(config: AoqAudioCodecConfig): number
パラメーター型説明
configAoqAudioCodecConfig音声エンコード設定
成功時に 0 を返します。 connect() 前、エンジンが Disconnected のときに呼び出します。接続処理中や接続済みでは AoqECStateInvalid(2) を返します。切断して Disconnected を待ち、設定してから再接続してください。 0 は設定要求の受理を表します。音声形式は接続時に再検証されます。Opus にはブラウザーの WebCodecs 対応も必要です。

setAudioDecoderConfig

音声デコードパラメーターを設定します。
setAudioDecoderConfig(config: AoqAudioCodecConfig): number
パラメーター型説明
configAoqAudioCodecConfig音声デコード設定
成功時に 0 を返します。 connect() 前、エンジンが Disconnected のときに呼び出します。接続処理中や接続済みでは AoqECStateInvalid(2) を返します。

ローカル音量通知

enableLocalAudioVolumeIndication

onLocalAudioVolumeIndication によるローカルキャプチャ音量の定期通知を有効化または無効化します。
enableLocalAudioVolumeIndication(config: AoqAudioVolumeIndicationConfig): number
パラメーター型説明
configAoqAudioVolumeIndicationConfig音量通知設定
成功時に 0 を返します。 interval を 0 または負数にするとコールバックを無効化します。

映像デバイスの管理

startVideoCapture

カメラのキャプチャを開始します。
startVideoCapture(config: AoqVideoCaptureConfig): number
パラメーター型説明
configAoqVideoCaptureConfig映像キャプチャ設定
成功時に 0 を返します。 0 は非同期キャプチャ要求の受理を表します。成否は onVideoDeviceStateChanged で通知され、カメラが起動済みとは限りません。 cameraPreference は向きの列挙値またはデバイス ID を指定します。省略時はブラウザーが選択します。要求を満たせない場合、別の使用可能なカメラにフォールバックできます。

getCameras

getCameras(): Promise<MediaDeviceInfo[]>
ブラウザーに表示される videoinput を列挙します。カメラを開いたり権限を要求したりしません。許可前は名前や ID が不完全な場合があります。許可後やデバイス変更後に再列挙できます。未初期化または列挙失敗時は Promise が拒否されます。

switchCamera

switchCamera(cameraPreference?: AoqCameraDirection | string): number
パラメーター型必須説明
cameraPreferenceAoqCameraDirection | stringいいえ向きまたはデバイス ID の優先設定。省略すると以前の設定を消去し、ブラウザーが再選択します。
向きと ID は ideal 制約で、別カメラへのフォールバックが可能です。0 は受理を表し、状態は onVideoDeviceStateChanged、失敗は onError で通知します。未キャプチャ、開始中、切り替え中は AoqECStateInvalid(2)、無効な向きや空白 ID は AoqECParamInvalid(1) を返します。 切り替えは旧デバイスを解放し、対象を開いて初回フレームを待ちます。旧トラックが Worker に移管された場合(後でメインスレッドに戻った場合も含む)、解放確認を最大 2 秒待ちます。確認タイムアウトでは対象を開かず復旧も行わず失敗を報告します。各試行は最大 15 秒です。失敗時は元のデバイス設定で一度復旧を試み、復旧成功でも切り替え失敗を報告します。成功時は CaptureStarted(reason=0)、失敗して復旧済みなら CaptureStarted(reason=エラーコード)、復旧不可なら CaptureFail(reason=エラーコード) です。明示対象がすでに満たされる場合は再オープンせず非同期で CaptureStarted を通知します。実デバイス ID は通知しません。送信スイッチ、コーデック設定、プレビューバインドは維持します。キャプチャ停止で切り替えを中止でき、破棄後は通知しません。 切り替え時に映像が短時間途切れる場合があります。キャプチャの時間軸は連続しますが、ハードウェアレベルの音声・映像同期は保証しません。実デバイスはブラウザーが選択するため、要求した設定を選択済みデバイスとして UI に表示しないでください。

stopVideoCapture

映像キャプチャを停止します。
stopVideoCapture(): number
成功時に 0 を返します。 デバイスが未起動または停止済みの場合、AoqECStateInvalid(2) を返します。

setLocalView

ローカル映像コンテナーを設定します。SDK は内部に描画要素を作成します。
setLocalView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number
パラメーター型説明
trackTypeAoqTrackTypeAoqTrackTypeVideo のみ対応します。他の型は AoqECUnSupport(3) を返します。
canvasAoqVideoCanvas | null描画コンテナー設定。null でバインドを解除します。
成功時に 0 を返します。 コンテナーの寸法を明示してください。SDK は内部に描画要素を作成します。 寸法を明示した通常の DOM コンテナー(div など)を使用します。video、audio、canvas、img、空要素は直接指定できません。コンテナー、ID、renderMode が無効な場合は AoqECParamInvalid(1) を返し、以前のバインドを維持します。0 は受理を表し、初回フレームが描画済みとは限りません。

setRemoteView

リモート映像コンテナーを設定します。SDK は内部に描画要素を作成します。
setRemoteView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number
パラメーター型説明
trackTypeAoqTrackTypeAoqTrackTypeVideo のみ対応します。他の型は AoqECUnSupport(3) を返します。
canvasAoqVideoCanvas | null描画コンテナー設定。null でバインドを解除します。
成功時に 0 を返します。 寸法を明示した通常の DOM コンテナー(div など)を使用します。video、audio、canvas、img、空要素は直接指定できません。コンテナー、ID、renderMode が無効な場合は AoqECParamInvalid(1) を返し、以前のバインドを維持します。0 は受理を表し、初回フレームが描画済みとは限りません。

映像エンコード設定

setVideoEncoderConfig

映像エンコードパラメーターを設定します。
setVideoEncoderConfig(config: AoqVideoCodecConfig): number
パラメーター型説明
configAoqVideoCodecConfig映像エンコード設定
成功時に 0 を返します。 エンジンが Disconnected のときに呼び出します。接続処理中や接続済みでは AoqECStateInvalid(2) を返します。初回接続と映像キャプチャの前に設定してください。設定は統合・キャッシュされ、後続のストリーム確立に使われます。既存のキャプチャやエンコーダーは即時再設定されません。

setVideoDecoderConfig

映像デコードパラメーターを設定します。
setVideoDecoderConfig(config: AoqVideoCodecConfig): number
パラメーター型説明
configAoqVideoCodecConfig映像デコード設定
成功時に 0 を返します。 connect() 前、エンジンが Disconnected のときに呼び出します。接続処理中や接続済みでは AoqECStateInvalid(2) を返します。

メディアストリームの送信制御

enableSendMediaStream

音声または映像トラックの送信を有効化または無効化します。
enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number
パラメーター型説明
trackTypeAoqTrackTypeメディアトラックの種類
enablebooleantrue:送信有効、false:送信無効
成功時に 0 を返します。 Audio と Video のみ制御し、Data は対象外です。他の値は 0 を返しても効果がない場合があります。送信停止ではキャプチャデバイスを停止しないため、該当する stop...Capture() を呼び出してください。

リアルタイムメッセージ

sendDataMsg

Uint8Array に格納した UTF-8 テキスト(アプリケーションの JSON など)を相手側へ送信します。現在の WT 経路では任意のバイナリや SDK 内部制御メッセージは送信できません。
sendDataMsg(msg: AoqDataMsg): number
パラメーター型説明
msgAoqDataMsgメッセージオブジェクト。msg.data は空でない UTF-8 バイト列です
成功時に 0 を返します。 接続済みかつトラック準備済みで、publishTracks に Data が必要です。メッセージがない、または msg.data が Uint8Array でない場合は AoqECParamInvalid(1)、未準備なら AoqECStateInvalid(2) を返します。送信ストリームが無効またはメッセージが空なら現在は -1 を返します。0 はローカル受理で、相手側の受信確認ではありません。UTF-8 検証や後続送信で onError が発生する場合があります。 msg.data の元の ArrayBuffer は移管されて無効になる場合があり、共有する他のビューも影響を受けます。元データが必要なら data.slice() のコピーを渡してください。フロントエンドのメッセージやログで API キーや一時認証情報を送信しないでください。
const data = new TextEncoder().encode(JSON.stringify({ type: 'user_message', text: '你好' }));
const code = engine.sendDataMsg({ data });
if (code !== 0) console.error('消息未受理', code);
JSON 例はエンコード方法のみを示します。実際のフィールドと業務の準備完了手順はモデルのデータメッセージプロトコルに従ってください。

イベントコールバック

engine.on('eventName', callback) で購読し、engine.once(...) で一度だけ受信し、同じ関数参照の engine.off('eventName', callback) で解除します。破棄時に全リスナーを削除します。接続やデバイス開始の前に登録し、コールバックの処理を軽量にしてください。
import { AoqConnectionStatus } from 'aoq-web-sdk';

const handleStatus = (status: AoqConnectionStatus) => console.log('连接状态', status);
engine.on('onConnectionStatusChange', handleStatus);
engine.off('onConnectionStatusChange', handleStatus);
イベントコールバックシグネチャ説明
onError(code: number, message: string) => voidエラーコールバック
onWarning(code: number, message: string) => void警告コールバック
onConnectionStatusChange(status: AoqConnectionStatus) => void接続状態の変更
onStats(stats: AoqStats) => void統計情報
onAudioDeviceStateChanged(state: AoqAudioDeviceState) => void音声デバイスの状態変更
onAudioDeviceRouteChanged(routeType: AoqAudioDeviceRouteType) => void音声ルートの変更
onAudioFileState(state: AoqAudioFileState) => void予約済み。現在は発生しません
onLocalAudioVolumeIndication(volume: AoqAudioVolume) => voidローカル音量通知
onVideoDeviceStateChanged(state: AoqVideoDeviceState) => void映像デバイスの状態変更
onDataMsg(msg: AoqDataMsg) => voidデータメッセージ

onError

同期戻り値以外の非同期エラーや実行時エラーを報告します。code と message、接続・デバイス状態を併せて診断してください。エラーが接続全体の終了を意味するとは限りません。ネットワークエラーが汎用状態コードを使う場合もあり、数値だけで発生段階を判定しないでください。
engine.on('onError', (code: number, message: string) => { /* 在此处理回调 */ });
パラメーター型説明
codenumberエラーコード。AoqErrorCode を参照
messagestringエラーの説明

onWarning

注意が必要な致命的でない状態をエンジンの警告として通知します。
engine.on('onWarning', (code: number, message: string) => { /* 在此处理回调 */ });
パラメーター型説明
codenumber警告コード。AoqWarningCode を参照
messagestring警告の説明

onConnectionStatusChange

接続状態の変更を通知します。
engine.on('onConnectionStatusChange', (status: AoqConnectionStatus) => { /* 在此处理回调 */ });
パラメーター型説明
statusAoqConnectionStatus現在の接続状態

onStats

Connected 中は約 1 秒ごとに統計を通知し、その状態を離れると停止します。フィールドの対応状況は AoqStats を参照してください。プレースホルダー値は測定値ではありません。
engine.on('onStats', (stats: AoqStats) => { /* 在此处理回调 */ });
パラメーター型説明
statsAoqStats統計情報オブジェクト

onAudioDeviceStateChanged

音声のキャプチャ・再生デバイスの操作状態変更を通知します。
engine.on('onAudioDeviceStateChanged', (state: AoqAudioDeviceState) => { /* 在此处理回调 */ });
パラメーター型説明
stateAoqAudioDeviceState音声デバイスの状態

onAudioDeviceRouteChanged

出力デバイス一覧の変更時に、ブラウザーのラベルからルート種別を推定します。誤判定や通知漏れがあり、実際の出力ルートの確認にはなりません。許可前や情報不足ではデフォルト値を返す場合があります。
engine.on('onAudioDeviceRouteChanged', (routeType: AoqAudioDeviceRouteType) => { /* 在此处理回调 */ });
パラメーター型説明
routeTypeAoqAudioDeviceRouteTypeラベルから推定したルートであり、実際の出力デバイスの確認ではありません

onAudioFileState

予約済みの音声ファイル状態コールバック。現在の AoqClientEngine にファイル再生制御はなく、このイベントも発生しません。
engine.on('onAudioFileState', (state: AoqAudioFileState) => { /* 在此处理回调 */ });
パラメーター型説明
stateAoqAudioFileState音声ファイルの状態

onLocalAudioVolumeIndication

ローカルキャプチャ音量を通知します。先に enableLocalAudioVolumeIndication で有効化してください。
engine.on('onLocalAudioVolumeIndication', (volume: AoqAudioVolume) => { /* 在此处理回调 */ });
パラメーター型説明
volumeAoqAudioVolume音量情報

onVideoDeviceStateChanged

映像キャプチャデバイスの操作状態変更を通知します。
engine.on('onVideoDeviceStateChanged', (state: AoqVideoDeviceState) => { /* 在此处理回调 */ });
パラメーター型説明
stateAoqVideoDeviceState映像デバイスの状態

onDataMsg

受信したデータメッセージを通知します。
engine.on('onDataMsg', (msg: AoqDataMsg) => { /* 使用 msg.data 读取消息数据 */ });
パラメーター型説明
msgAoqDataMsg受信メッセージオブジェクト。TextDecoder で msg.data の UTF-8 テキストを読み取ります。
受信には subscribeTracks に Data を含めます。コールバックの引数はオブジェクトであり、Uint8Array そのものではありません。業務 JSON の解析と検証はアプリケーションで行います。

データ型と列挙型

共通の型

AoqCreateConfig

エンジン作成設定。
フィールド型必須デフォルト説明
workDirstringいいえ—予約済み。Web SDK はこの値で保存ディレクトリを指定しません
enableDumpAudiobooleanいいえfalse音声デバッグデータを保存します。ユーザー音声の許可を取得し、アクセスを制御してください。
enableDumpExportbooleanいいえfalseenableDumpAudio=true の場合のみ有効。破棄時にダンプ ZIP を非同期で出力し、該当 OPFS ファイルを削除します。
maxEncodedVideoFrameBytesnumberいいえ194560 (190×1024)JPEG 単一フレームの目標上限(バイト)。0 は無効化。超過時は画質を下げ、無効値はデフォルトを使います。
enableDropOversizedVideoFramebooleanいいえfalse最低 JPEG 品質でも超過する場合に破棄するか。false では超過フレームを送信する場合があります。上限 0 ではこの理由で破棄しません。
extrasstringいいえ—JSON オブジェクト文字列。無効な JSON、非オブジェクト値、無効なリモート描画方針では createEngine が null を返します。
利用可能な extras フィールド:
JSON フィールド型デフォルト説明
remoteVideoRenderer'auto' | 'video' | 'canvas''auto'リモート描画方針。auto は video を優先し、必要に応じて canvas に切り替えます。
user_specified_enable_av_syncbooleantrue音声・映像同期を有効にするか。JSON の真偽値を使用してください。
user_specified_audio_playback_transport'message-port'自動MessagePort 再生を指定します。省略時は環境により共有メモリか MessagePort を選択します。
これらのフィールドでは HTTP 応答ヘッダーの変更や公開診断 API の有効化は行いません。

AoqConnectConfig

接続認証設定。
フィールド型必須デフォルト説明
tokenstringはい—aoqTokenForClient に対応する空でない一時クライアントトークン。API キーではありません
sidstringはい—空でないセッション ID。認証応答の完全な sid 文字列を使います。
wtBaseUrlstringいいえRelay から構成単一路線で優先する HTTPS WT URL。複数ルートでは無視し、各ホスト・ポートの /aoq に接続します。
signedSidstringはい(実行時)—完全な署名済み SID。通常は認証応答の完全な sid。TypeScript では省略可能ですが、現在の WT 接続では必須です。
certFingerprintstring | string[]条件付き—共通の WT 証明書 SHA-256 フィンガープリント。独自値のないルートで利用できる必要があります。
workspaceIdHashstringいいえ—extraInfo.workspaceIdHash に対応します。元の Workspace ID で代用しないでください。
relayEndpointsAoqRelayEndpoint[]はい—完全な接続先一覧。少なくとも 1 件必要です
publishTracksAoqTrackParam[]はい—上りトラック一覧。空でも構いませんが、subscribeTracks と同時に空にはできません。
subscribeTracksAoqTrackParam[]はい—下りトラック一覧。空でも構いません。同一方向の重複と Screen は未対応です。
バックエンドから完全で有効な接続情報を返してください。アダプターで clientRelayEndpoints[].route_index を routeIndex に変換します。SID、接続先、ルート番号、フィンガープリントを独自に作成しないでください。 WT フィンガープリントは実際の WebTransport 接続先証明書と一致させます。sha256/<hex> は接頭辞を除き、64 桁の 16 進数を検証します。共通値もルート値も文字列または配列で指定でき、全要素が有効である必要があります。いずれか一致すれば検証に成功します。空でないルート値が共通値より優先され、空配列は未設定です。汎用フィンガープリントや検証を省略する設定はありません。 signedSid や有効なフィンガープリントがないと、connect() が 0 を返しても非同期接続に失敗する場合があります。状態イベントと onError を処理してください。

AoqRelayEndpoint

Relay エンドポイント。
フィールド型必須デフォルト説明
routeIndexnumberはい(実行時)—0~2147483647 の一意な整数。初回は最小番号を選択します。TypeScript では省略可能です。
certFingerprintstring | string[]条件付き共通フィンガープリント空でないルート値が共通値を上書きします。共通フィンガープリントがない場合は必須です。
endpointstringはい—スキーム、パス、空白、ユーザー情報、クエリを含まない WT ホスト名/IP。IPv6 に対応します。
portnumberはい—WT ポート。1~65535 の整数

AoqTrackParam

トラック属性。
フィールド型必須デフォルト説明
trackTypeAoqTrackTypeはい—Audio、Video、Data。同一方向で重複不可。Screen は現在未対応です。
trackModeAoqTrackModeいいえ音声ダウンリンクは Segment音声下りのみを制御します。PCM / Opus の既定値は Segment、Stream を明示すると Realtime です。音声上りは常に Realtime。上り、映像、データでは無視します。

AoqSupportResult

ブラウザー機能の検査結果。
フィールド型デフォルト説明
supportedboolean—環境に AOQ 接続の基本機能があるか
missingFeaturesAoqMissingFeature[]—検出された事前検査の失敗。'secure-context'、'worker'、'web-transport' を含む場合があります

AoqMissingFeature

基本機能の検査失敗:'secure-context' | 'worker' | 'web-transport'。worker は Worker API 不在だけでなく、配置ポリシーの制限、起動・実行失敗、検査タイムアウトも示します。すべてのメディア機能を評価する一覧ではありません。

音声の型

AoqAudioCaptureConfig

音声キャプチャ設定。
フィールド型必須デフォルト説明
channelnumberいいえ1要求するチャネル数。1(モノラル)/ 2(ステレオ)。実際の値はデバイストラック設定で決まる場合があります。

AoqAudioPlaybackConfig

音声再生設定。
フィールド型必須デフォルト説明
channelnumberいいえ1要求する再生チャネル数。1 / 2。出力は実際の AudioContext サンプルレートを使用します。
playOnlyAndIgnoreMutebooleanいいえfalse再生専用。ブラウザー対応時に audioSession を playback とし、iOS ミュートスイッチの影響を回避します。マイクも使う場合は false のままにしてください。未対応環境ではミュート無視は保証しません。

AoqAudioCodecConfig

音声コーデック設定。
フィールド型必須デフォルト説明
trackTypeAoqTrackTypeいいえ—予約済み。現在は音声ストリーム選択には使いません
codecTypeAoqEncoderTypeいいえAoqEncoderTypeAudioPCMPCM / Opus。相手とネゴシエートした設定と一致させます。
sampleRatenumberいいえ48000サンプルレート(Hz)。ネゴシエーション対応値は 8000、12000、16000、24000、32000、44100、48000。個別のエンコードはブラウザー対応も必要です。
channelnumberいいえ1チャネル数。1 または 2
bitratenumberいいえ32000 (Opus エンコード)bps 単位。Opus エンコードのみ使用します。PCM はサンプルレート、チャネル数、ビット深度で決まります。デコードでは使いません。

AoqAudioVolumeIndicationConfig

ローカル音量通知設定。
フィールド型必須デフォルト説明
intervalnumberいいえ0通知間隔(ms)。<=0 は無効化、0 より大きく 10 未満なら 10 として扱います。
smoothnumberいいえ3音量平滑化係数。0..10。大きいほど滑らかになります。
reportSpeechbooleanいいえfalse音声活動(VAD)を通知するか

AoqAudioVolume

ローカル音量情報。
フィールド型デフォルト説明
volumenumber—平滑化済みの瞬時音量。範囲 [0-255]
isSpeechboolean—省略可能な音声活動フラグ。reportSpeech=true の場合のみ有意です。欠落を処理してください。

AoqAudioDeviceState

音声デバイス状態の通知データ。
フィールド型デフォルト説明
stateAoqAudioDeviceStateCode—音声デバイス状態コード
reasonnumber—理由コード。AoqErrorCode を参照

AoqAudioFileState

予約済みの音声ファイル再生状態。現在の Web SDK では対応イベントは発生しません。
フィールド型デフォルト説明
fileIdstring—音声ファイル ID
stateCodeAoqAudioFileStateCode—ファイル再生状態コード
errorCodenumber—エラーコード

映像の型

AoqVideoCaptureConfig

映像キャプチャ設定。
フィールド型必須デフォルト説明
widthnumberいいえ1280要求キャプチャ幅(ピクセル、ideal 制約)。実際はブラウザー/デバイスが決定します。
heightnumberいいえ720要求キャプチャ高さ(ピクセル、ideal 制約)。実際はブラウザー/デバイスが決定します。
fpsnumberいいえ15要求キャプチャフレームレート。ideal と max 制約
cameraPreferenceAoqCameraDirection | stringいいえブラウザーが選択カメラの向きまたは ID の優先設定。ideal 制約でフォールバック可能。空白文字列は無効です。

AoqVideoCodecConfig

映像コーデック設定。
フィールド型必須デフォルト説明
trackTypeAoqTrackTypeいいえ—予約済み。現在は映像ストリーム選択には使いません
codecTypeAoqEncoderTypeいいえAoqEncoderTypeVideoH264H.264 / JPEG。相手とネゴシエートした設定と一致させます。
widthnumberいいえ540エンコード目標幅/下りネゴシエーション幅(ピクセル)。接続時は正の整数が必要です。
heightnumberいいえ960エンコード目標高さ/下りネゴシエーション高さ(ピクセル)。接続時は正の整数が必要です。
fpsnumberいいえ5エンコード/下りネゴシエーションのフレームレート。接続時は正の整数が必要です。
bitratenumberいいえ500000 (エンコード)正のエンコード目標ビットレート(bps)。デコードでは使いません。
minBitratenumberいいえ128000最低目標ビットレート(bps)。省略または 0 は 128000 とし、ユーザー目標以下に制限します。BWE 予算が 0 でも H.264 エンコードは停止しません。デコードでは使いません。
keyframeIntervalnumberいいえ2H.264 キーフレーム間隔(秒)。エンコード時は最小 1 秒として扱います。JPEG/デコードでは使いません。

AoqVideoCanvas

映像描画コンテナー設定。
フィールド型必須デフォルト説明
viewHTMLElement | stringはい—通常のコンテナー要素または DOM ID(# なし)。video、audio、canvas、img、空要素の直接指定は不可です。
renderModeAoqRenderModeいいえAoqRenderModeAuto(0)映像のフィット方式
実際のキャプチャトラックが前面向きなら、ローカルプレビューを CSS で自動反転します。向き不明なら反転しません。エンコード画素は変わりません。個別のミラーや向きの設定はありません。無効な置換では元のバインドを維持します。null による解除は SDK 所有の描画ノードのみ削除し、業務ノードは残します。

AoqVideoDeviceState

映像デバイス状態の通知データ。
フィールド型デフォルト説明
stateAoqVideoDeviceStateCode—映像デバイス状態コード
reasonnumber—理由コード。明示停止は 0、Web トラックの予期しない終了は AoqECVideoDevice(220)

データメッセージの型

AoqDataMsg

公開 sendDataMsg / onDataMsg 共通の構造です。文字列や Uint8Array の直接指定は受け付けません。WT 経路ではバイト配列で UTF-8 テキストを運びます。
フィールド型必須デフォルト説明
dataUint8Arrayはい—送信時は空でない有効な UTF-8。受信時は msg.data を読み取ります。

統計情報の型

AoqStats

エンジン統計情報の概要。以下のフィールドは型定義上すべて省略可能です。欠落を処理してください。
フィールド型デフォルト説明
audioPublishStatsAoqAudioPublishStats[]—音声送信の統計一覧
audioSubscribeStatsAoqAudioSubscribeStats[]—音声受信の統計一覧
videoPublishStatsAoqVideoPublishStats[]—映像送信の統計一覧
videoSubscribeStatsAoqVideoSubscribeStats[]—映像受信の統計一覧
dataMsgPublishStatsAoqDataMsgPublishStats[]—データメッセージ送信の統計一覧
dataMsgSubscribeStatsAoqDataMsgSubscribeStats[]—データメッセージ受信の統計一覧
networkStatsAoqNetworkStats—ネットワーク統計
現在 onStats は dataMsgPublishStats / dataMsgSubscribeStats を設定しません。音声の bitrate / bytes は独立した音声量ではなく接続全体の値で、encodeVolume / playVolume は 0 固定です。映像の bitrate / bytes も 0 固定で、フレームレートのみ映像エンジンの値です。全体量は networkStats、キャプチャ音量は onLocalAudioVolumeIndication を使ってください。

AoqAudioPublishStats

音声送信の統計。
フィールド型デフォルト説明
trackTypeAoqTrackType—トラックの種類
bitratenumber—接続全体の上りアプリケーションビットレート(bps)。音声単独ではありません
bytesnumber—接続全体の上りアプリケーションバイト数。音声単独ではありません
encodeVolumenumber0プレースホルダー。音量は onLocalAudioVolumeIndication を使用してください。

AoqAudioSubscribeStats

音声受信の統計。
フィールド型デフォルト説明
trackTypeAoqTrackType—トラックの種類
bitratenumber—接続全体の下りアプリケーションビットレート(bps)。音声単独ではありません
bytesnumber—接続全体の下りアプリケーションバイト数。音声単独ではありません
playVolumenumber0プレースホルダー。再生ミュートの判定には使えません

AoqVideoPublishStats

映像送信の統計。
フィールド型デフォルト説明
trackTypeAoqTrackType—トラックの種類
bitratenumber0プレースホルダー。映像単独のビットレートは現在未提供です
bytesnumber0プレースホルダー。映像単独のバイト数は現在未提供です
encodeFpsnumber—エンコードフレームレート

AoqVideoSubscribeStats

映像受信の統計。
フィールド型デフォルト説明
trackTypeAoqTrackType—トラックの種類
bitratenumber0プレースホルダー。映像単独のビットレートは現在未提供です
bytesnumber0プレースホルダー。映像単独のバイト数は現在未提供です
decodeFpsnumber—デコードフレームレート
renderFpsnumber—描画フレームレート

AoqDataMsgPublishStats

データメッセージ送信の統計。
フィールド型デフォルト説明
trackTypeAoqTrackType—トラックの種類
bitratenumber—現在のビットレート(bps)
bytesnumber—累積送信バイト数
型は定義済みですが、現在 onStats はこの配列を設定しません。

AoqDataMsgSubscribeStats

データメッセージ受信の統計。
フィールド型デフォルト説明
trackTypeAoqTrackType—トラックの種類
bitratenumber—現在のビットレート(bps)
bytesnumber—累積受信バイト数
型は定義済みですが、現在 onStats はこの配列を設定しません。

AoqNetworkStats

ネットワーク統計。ビットレートは業務ペイロードの bit/s、累積量は同じ基準のバイト数です。プローブと転送プロトコルのオーバーヘッドは含みません。
フィールド型デフォルト説明
sendBitratenumber—上りビットレート(bps)
sendBytesnumber—累積上りバイト数
recvBitratenumber—下りビットレート(bps)
recvBytesnumber—累積下りバイト数
lossnumber—省略可能な上り損失率(0–1)。ブラウザーの QUIC 観測を優先し、なければ Relay Datagram 推定を使います。不明なら省略します。
rttnumber—省略可能な往復時間(ms)。不明なら省略
bwenumber—Client→Relay の有効な業務送信予算(bps)、省略可能。不明または期限切れなら省略
audioReserveBpsnumber—現在のエンコード音声のペイロード予約ビットレート(bps)、省略可能。RED 冗長性と転送オーバーヘッドを含まず、実音声トラフィックではありません。

列挙型

AoqTrackType

トラックのメディア種別。
列挙値値説明
AoqTrackTypeAudio0音声
AoqTrackTypeVideo1映像
AoqTrackTypeData2データメッセージ
AoqTrackTypeScreen3予約済み。現在の接続処理では未対応です

AoqTrackMode

音声転送モード。
列挙値値説明
AoqTrackModeSegment0Segment モード
AoqTrackModeStream1Realtime ストリームモード

AoqEncoderType

トラックのメディア形式。
列挙値値説明
AoqEncoderTypeUnknown0不明
AoqEncoderTypeAudioPCM1PCM 音声
AoqEncoderTypeAudioOpus2Opus 音声
AoqEncoderTypeVideoH2643H.264 映像
AoqEncoderTypeVideoJpeg4JPEG 映像
AoqEncoderTypeDataText5テキストデータ

AoqConnectionStatus

エンジンの接続状態。
列挙値値説明
AoqConnectionStatusDisconnected0切断済み
AoqConnectionStatusConnecting1接続中
AoqConnectionStatusConnected2接続済み
AoqConnectionStatusFailed3接続失敗

AoqErrorCode

エラーコード。
列挙値値説明
AoqECOK0成功
AoqECParamInvalid1無効なパラメーター
AoqECStateInvalid2無効な状態
AoqECUnSupport3現在のプラットフォーム/モードでは未実装
AoqECAudio100音声全般のエラー
AoqECAudioExternalBufferFull110外部音声バッファー満杯
AoqECAudioDevice120音声デバイス全般のエラー
AoqECAudioDeviceRecordingAuthFailed121マイク権限の拒否
AoqECAudioDeviceRecordingOccupied122マイク使用中
AoqECAudioDeviceRecordingBackgroundStart123バックグラウンドでキャプチャ開始
AoqECAudioDeviceRecordingStartFail124キャプチャ開始失敗
AoqECAudioDevicePlayoutOccupied125再生デバイス使用中
AoqECAudioDevicePlayoutBackgroundStart126バックグラウンドで再生開始
AoqECAudioDevicePlayoutStartFail127再生開始失敗
AoqECAudioDeviceEarpieceRequiresVoipMode128受話口には VoIP モードが必要
AoqECVideo200映像全般のエラー
AoqECVideoExternalBufferFull210外部映像バッファー満杯
AoqECVideoExternalCaptureNotEnabled211外部映像キャプチャ未有効化
AoqECVideoExternalEncoderNotEnabled212外部映像エンコーダー未有効化
AoqECVideoDevice220映像デバイス全般のエラー
AoqECVideoDeviceCameraOpenFail221カメラのオープン失敗
AoqECVideoDeviceCameraAuthFailed222カメラ権限の拒否
AoqECVideoDeviceCameraOccupied223カメラ使用中
AoqECVideoDeviceCameraRunningError224カメラ実行時エラー
AoqECVideoCodec230映像コーデック全般のエラー
AoqECVideoCodecEncoderInitFail231映像エンコーダー初期化失敗
AoqECVideoRender240映像描画全般のエラー
AoqECVideoRenderCreateFail241レンダラー作成失敗
AoqECVideoRenderDrawError242描画エラー

AoqWarningCode

警告コード。
列挙値値説明
AoqWCOK0正常
AoqWCAudio100音声全般の警告
AoqWCAudioHowling101ハウリング検出
AoqWCAudioDevice120音声デバイス全般の警告
AoqWCAudioDeviceMicEnumerateError121マイク列挙エラー
AoqWCAudioDeviceMicStartTimeout122マイク開始タイムアウト
AoqWCAudioDeviceRecordingError123キャプチャエラー
AoqWCAudioDeviceSpeakerEnumerateError124スピーカー列挙エラー
AoqWCAudioDeviceSpeakerStartTimeout125スピーカー開始タイムアウト
AoqWCAudioDevicePlayoutError126再生エラー
AoqWCAudioDeviceSilentMode127デバイスがサイレントモード
AoqWCVideo200映像全般の警告
AoqWCVideoCameraEnumerateError201カメラ列挙エラー
AoqWCVideoEncoderSwitched202映像エンコーダー切り替え済み
AoqWCVideoRenderDowngrade203描画のフォールバック

AoqAudioDeviceStateCode

音声デバイス状態コード。
列挙値値説明
AoqAudioDeviceNone0状態なし
AoqAudioDeviceRecordStarting1キャプチャ開始中
AoqAudioDeviceRecordStarted2キャプチャ開始済み
AoqAudioDeviceRecordStopping3キャプチャ停止中
AoqAudioDeviceRecordStopped4キャプチャ停止済み
AoqAudioDeviceRecordFail5キャプチャ失敗
AoqAudioDevicePlayStarting6再生開始中
AoqAudioDevicePlayStarted7再生開始済み
AoqAudioDevicePlayStopping8再生停止中
AoqAudioDevicePlayStopped9再生停止済み
AoqAudioDevicePlayFail10再生失敗

AoqAudioDeviceRouteType

音声デバイスのルート種別。
列挙値値説明
AoqAudioDeviceRouteDefault0デフォルトルート
AoqAudioDeviceRouteHeadset1ヘッドセット
AoqAudioDeviceRouteSpeakerPhone4内蔵スピーカー
AoqAudioDeviceRouteUsb5USB デバイス
AoqAudioDeviceRouteBluetooth6Bluetooth デバイス

AoqAudioFileStateCode

音声ファイル再生状態コード。
列挙値値説明
AoqAudioFileNone0状態なし
AoqAudioFileStarted1再生開始済み
AoqAudioFileStopped2再生停止済み
AoqAudioFilePaused3再生一時停止中
AoqAudioFileResumed4再生再開済み
AoqAudioFileEnded5再生終了
AoqAudioFileBuffering6バッファリング中
AoqAudioFileBufferingEnd7バッファリング完了
AoqAudioFileFailed8再生失敗

AoqCameraDirection

列挙値値説明
AoqCameraDirectionFront0前面カメラを優先
AoqCameraDirectionBack1背面カメラを優先

AoqVideoDeviceStateCode

映像デバイス状態コード。
列挙値値説明
AoqVideoDeviceNone0状態なし
AoqVideoDeviceCaptureStarting1キャプチャ開始中
AoqVideoDeviceCaptureStarted2キャプチャ開始済み
AoqVideoDeviceCaptureStopping3キャプチャ停止中
AoqVideoDeviceCaptureStopped4キャプチャ停止済み
AoqVideoDeviceCaptureFail5キャプチャ失敗

AoqMirrorMode

予約済みミラーモード列挙型。現在の Web SDK には使用する設定や API がありません。
列挙値値説明
AoqMirrorModeDisabled0ミラー無効
AoqMirrorModeEnabled1ミラー有効

AoqOrientationMode

予約済み向きモード列挙型。現在の Web SDK には使用する設定や API がありません。
列挙値値説明
AoqOrientationModeAuto0自動
AoqOrientationModePortrait1縦向き
AoqOrientationModeLandscape2横向き

AoqRenderMode

映像フィット方式。
列挙値値説明
AoqRenderModeAuto0デフォルト:縦横比を保って全体表示
AoqRenderModeStretch1コンテナー全体に引き伸ばす
AoqRenderModeFill2縦横比を保って全体表示。黒帯を許可
AoqRenderModeCrop3縦横比を保って全体を埋め、超過部分を切り取る

その他の公開宣言

IAoqEngineEvents は予約済みの onAudioFileState を含む 10 個のイベントコールバックシグネチャを定義します。イベント名で購読すると TypeScript の引数推論を利用できます。 以下の型や列挙型はエクスポートされていますが、現在の Web エンジンには対応する制御/監視 API がありません。他プラットフォームの同名宣言から Web 対応を推測しないでください。
分類公開宣言現在の対応範囲
音声ファイルのミキシングAoqAudioFileMixConfig, AoqAudioFileState, AoqAudioFileStateCodeファイル再生/ミキシング制御なし。ファイル状態イベントは発生しません
外部音声とオブザーバーAoqAudioExternalStreamConfig, AoqAudioExternalFrameMeta, AoqAudioObserverParams, AoqAudioSource, AoqAudioStreamDirection外部音声入力や音声フレームオブザーバー登録のメソッドはありません
外部映像とオブザーバーAoqExternalVideoFrameMeta, AoqExternalVideoEncodedFrameMeta, AoqVideoObserverParams, AoqVideoSource, AoqVideoPixelFormat, AoqVideoObserverAlignment, AoqVideoCodecType外部映像フレーム入力や映像フレームオブザーバー登録はありません。コーデック設定は AoqEncoderType を使います。
ミラーと向きAoqMirrorMode, AoqOrientationMode対応する設定やメソッドはありません。ローカルプレビューのミラーは自動です。
低レベル音声デバイスAoqAudioDeviceEvent, AudioDeviceApiError, AudioDeviceErrorCode低レベルデバイスの宣言であり、エンジンの追加イベントや戻りコード全体の契約ではありません
AOQ_TRACK_AUDIO と AOQ_TRACK_DATA は文字列定数 'aoq_track_audio' と 'aoq_track_data' です。接続やビューのトラック選択用ではありません。これらの API には AoqTrackType を使用してください。 エラーと警告の列挙型にはプラットフォーム共通の値が残っています。Web SDK がすべての値を生成するとは限りません。利用可否は本書のメソッドと呼び出し条件を参照してください。