Skip to main content

Référence de l'API Electron du SDK Client AOQ

Cette rubrique décrit les API TypeScript, les événements et les types de données du SDK Client AOQ pour Electron. Le SDK prend en charge macOS x64/arm64 et Windows x64, et nécessite Node.js 16 ou une version ultérieure.

Le SDK AOQ fournit des API vidéo générales. Qwen-Audio-Realtime ne prend pas en charge l’entrée ni la sortie vidéo. Pour les capacités de médias des autres modèles, consultez leur documentation de connexion.
Package applicable : aoq-electron-sdk (npm). Plates-formes prises en charge : macOS (x64 / arm64) et Windows x64. Node.js >= 16.

Détails des API

Point d'entrée du moteur et cycle de vie

createAoqClientEngine

Récupère l'instance wrapper du moteur. Il s'agit d'un singleton initialisé paresseusement au niveau du module. Un nouvel appel à cette méthode renvoie la même instance, ce qui correspond à la sémantique singleton du moteur natif. C'est également l'exportation par défaut du package.
import createAoqClientEngine from 'aoq-electron-sdk';
export function createAoqClientEngine(): IAoqClientEngine
Valeur de retour : l'instance de moteur IAoqClientEngine. Notez que cette méthode crée uniquement la couche wrapper JS et le pont natif. Pour créer réellement le moteur, vous devez également appeler createEngine().

createEngine

Crée l'instance native du moteur. Le moteur étant un singleton global, un nouvel appel à cette méthode renvoie directement un succès.
createEngine(config: AoqCreateConfig): number

Paramètres

Type

Description

config

AoqCreateConfig

Configuration de création du moteur

Valeur de retour : 0 en cas de succès ; -1 indique que la création a échoué ou que le paramètre n'est pas un JSON valide.
Sous Windows, createEngine() attache une pompe de messages Win32 de 16 ms à la boucle libuv du thread JS actuel (nécessaire pour la capture caméra), et l'arrête lors de l'appel à destroy(). Par conséquent, évitez de bloquer le thread JS de manière synchrone pendant une longue période après createEngine().

destroy

Détruit l'instance du moteur et libère toutes les ressources.
destroy(): number
Valeur de retour : 0 indique un succès ; une valeur différente de 0 indique un échec. Si le moteur n'est pas créé, 0 est renvoyé.

getVersion

Récupère la version actuelle du SDK. Il n'est pas nécessaire d'appeler createEngine() au préalable.
getVersion(): string
Valeur de retour : la chaîne de version, par exemple « 1.2.0 ». Une chaîne vide est renvoyée si la version ne peut pas être obtenue.

connect

Se connecte au serveur relais. Le serveur d'application obtient les paramètres de connexion AOQ temporaires basés sur le protocole utilisé et les envoie au client. Pour plus d'informations, consultez Authentification par jeton.
connect(config: AoqConnectConfig): number

Paramètres

Type

Description

config

AoqConnectConfig

Configuration de connexion, incluant le jeton, le SID, la liste des points d'accès relais et les listes de pistes de publication et d'abonnement

Valeur de retour : 0 indique que l'appel est distribué et s'exécute de manière asynchrone ; une valeur différente de 0 indique un échec de validation des paramètres. Le résultat de la connexion est notifié via l'événement onConnectionStatusChange.

disconnect

Se déconnecte du serveur et libère les ressources associées à la connexion.
disconnect(): number
Valeur de retour : 0 indique que l'appel est distribué et s'exécute de manière asynchrone ; une valeur différente de 0 indique un échec.

Gestion des périphériques audio

startAudioCapture

startAudioCapture(config: AoqAudioCaptureConfig): number
Ouvre le périphérique de capture audio (microphone). La première capture déclenche une demande d'autorisation système. Sur macOS, vous devez déclarer NSMicrophoneUsageDescription dans le fichier Info.plist de l'application.

stopAudioCapture

stopAudioCapture(): number
Ferme le périphérique de capture audio.

muteAudioCapture

muteAudioCapture(mute: boolean): number
Active ou désactive la mise en sourdine de la capture audio. mute=true active la mise en sourdine, et false la désactive.

startAudioPlayer

startAudioPlayer(config: AoqAudioPlaybackConfig): number
Démarre le rendu audio pour lire l'audio distant.

stopAudioPlayer / pauseAudioPlayer / resumeAudioPlayer

stopAudioPlayer(): number
pauseAudioPlayer(fadeMs: number): number
resumeAudioPlayer(fadeMs: number): number
fadeMs : durée de l'atténuation ou de l'augmentation progressive, en millisecondes. 0 indique une exécution immédiate.

interruptAudioPlayer

interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number
Interrompt la session audio en cours et supprime les données descendantes mises en mémoire tampon de la session actuelle.

Paramètres

Type

Description

trackType

AoqTrackType

Type de piste

fadeMs

number

Durée de l'atténuation progressive, en millisecondes

Configuration du codec audio

setAudioEncoderConfig(config: AoqAudioCodecConfig): number
setAudioDecoderConfig(config: AoqAudioCodecConfig): number
Nous vous recommandons d'appeler cette méthode avant connect(). Pour utiliser Opus (AoqEncoderTypeAudioOpus), le plug-in PluginOpus doit être intégré au SDK ou distribué avec le package.

Gestion des périphériques vidéo

startVideoCapture(config: AoqVideoCaptureConfig): number
stopVideoCapture(): number
Ouvre ou ferme le périphérique de capture vidéo. Sur macOS, vous devez déclarer NSCameraUsageDescription dans Info.plist. Lorsque config.isExternal=true, la caméra n'est pas ouverte et les trames sont transmises via pushExternalVideoCapturedFrame.
Le moteur de rendu Electron est un environnement Chromium et ne peut pas intégrer de vues natives, donc setLocalView / setRemoteView / switchCamera ne sont pas fournis. Pour la prévisualisation, utilisez l'observateur de trames avec YUVCanvasRenderer (voir 2.13).

Codec vidéo et entrée externe

setVideoEncoderConfig(config: AoqVideoCodecConfig): number
setVideoDecoderConfig(config: AoqVideoCodecConfig): number
pushExternalVideoCapturedFrame(meta: AoqExternalVideoFrameMeta, buffer: Uint8Array): number
pushExternalVideoEncodedFrame(meta: AoqExternalVideoEncodedFrameMeta, buffer: Uint8Array): number

Paramètres

Type

Description

meta

AoqExternalVideoFrameMeta / AoqExternalVideoEncodedFrameMeta

Métadonnées de la trame (dimensions, format et horodatage)

buffer

Uint8Array

Données de la trame (données de pixels ou données encodées)

Remarques :
  • pushExternalVideoCapturedFrame n'est consommé qu'après startVideoCapture({ isExternal: true }). Elle renvoie 211 lorsque la capture externe n'est pas activée et 210 lorsque le tampon est plein.
  • Les formats AoqVideoPixelFormatI420 et les formats compactés (NV12 / NV21 / BGRA / RGBA) sont pris en charge. Pour I420, buffer doit utiliser une disposition compacte (stride = width), avec les plans Y / U / V concaténés dans l'ordre.
  • pushExternalVideoEncodedFrame nécessite d'abord setVideoEncoderConfig({ isExternal: true }). Elle renvoie 212 si elle n'est pas activée. Seul JPEG est actuellement pris en charge.
  • Lorsque meta.timeStamp est 0, le SDK le remplit avec l'heure locale.

Contrôle du flux multimédia

enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number
Spécifie s'il faut envoyer un flux multimédia local spécifique. Nous vous recommandons d'appeler enableSendMediaStream(trackType, false) après l'initialisation et d'activer l'envoi uniquement lorsque onConnectionStatusChange signale AoqConnectionStatusConnected.

Lecture de fichiers audio

startAudioFile(config: AoqAudioFileMixConfig): number
stopAudioFile(fileId: string): number
pauseAudioFile(fileId: string): number
resumeAudioFile(fileId: string): number
getAudioFileDuration(fileId: string): number
getAudioFileCurrentPosition(fileId: string): number
setAudioFilePositionMillis(fileId: string, positionMs: number): number
setAudioFileVolume(fileId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioFileVolume(fileId: string, type: AoqAudioStreamDirection): number

Paramètres

Type

Description

config

AoqAudioFileMixConfig

Configuration de mixage de fichier. fileId est transmis en tant que champ de configuration.

fileId

string

Identifiant de fichier, défini par l'appelant. Les appels d'API suivants l'utilisent pour localiser le fichier.

positionMs

number

Position de lecture cible, en millisecondes

type

AoqAudioStreamDirection

Volume de publication ou volume de lecture local

volume

number

Volume. Valeurs valides : 0 à 100.

Description de la valeur de retour :
  • getAudioFileDuration / getAudioFileCurrentPosition renvoient le nombre de millisecondes ;
  • getAudioFileVolume renvoie le volume actuel ;
  • Les getters ci-dessus renvoient -1 lorsque le moteur n'est pas créé.
Les changements d'état de lecture sont signalés via l'événement onAudioFileState.

Flux audio externes

addAudioExternalStream(config: AoqAudioExternalStreamConfig): number
removeAudioExternalStream(streamId: string): number
pushAudioExternalStreamData(meta: AoqAudioExternalFrameMeta, buffer: Uint8Array): number
setAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection): number
clearAudioExternalStreamBuffer(streamId: string, fadeoutMs: number): number

Paramètres

Type

Description

config

AoqAudioExternalStreamConfig

Configuration du flux audio externe. streamId est transmis en tant que champ de configuration.

streamId

string

Identifiant de flux, défini par l'appelant

meta

AoqAudioExternalFrameMeta

Métadonnées de la trame PCM. streamId est transmis en tant que champ de métadonnées.

buffer

Uint8Array

Données PCM

fadeoutMs

number

Durée de l'atténuation progressive lors du vidage du tampon, en millisecondes

Remarques :
  • pushAudioExternalStreamData renvoie 110 (tampon audio externe plein) lorsque la durée mise en mémoire tampon dépasse maxBufferDuration.
  • getAudioExternalStreamVolume renvoie le volume actuel. Elle renvoie -1 lorsque le moteur n'est pas créé.
  • clearAudioExternalStreamBuffer n'a pas de valeur de retour côté natif et renvoie toujours 0 en cas d'appel réussi.

Types de données et énumérations

Tous les types sont exportés depuis la racine du package, ce qui vous permet d'utiliser directement l'instruction import { ... } from 'aoq-electron-sdk'. Les énumérations sont des types TypeScript enum disponibles au moment de l'exécution, tandis que les interfaces (interface) servent uniquement de contraintes de type. Si un champ marqué comme facultatif n'est pas spécifié, la valeur par défaut indiquée dans le tableau est utilisée.

Types généraux

AoqCreateConfig

Champ

Type

Obligatoire

Valeur par défaut

Description

workDir

string

Non

""

Répertoire de travail du SDK (pour les journaux et les fichiers temporaires)

enableDumpAudio

boolean

Non

false

Indique s'il faut enregistrer les données audio (à des fins de débogage)

extras

string

Non

""

Paramètres étendus (chaîne JSON)

Le champ isBTScoMode sur Android est spécifique aux appareils mobiles et n'est pas fourni par Electron.

AoqConnectConfig

Champ

Type

Obligatoire

Valeur par défaut

Description

token

string

Oui

-

Jeton d'authentification de connexion

sid

string

Oui

-

ID de session

certFingerprint

string

Non

""

Empreinte du certificat serveur

workspaceIdHash

string

Non

Aucune

Hachage de l'ID d'espace de travail. Une chaîne vide équivaut à l'absence de paramètre.

relayEndpoints

Array

Oui

-

Liste des points de relais

publishTracks

Array

Oui

-

Liste des pistes publiées localement

subscribeTracks

Array

Oui

-

Liste des pistes auxquelles on s'abonne localement

AoqRelayEndpoint

Champ

Type

Obligatoire

Valeur par défaut

Description

routeIndex

number

Non

-1

Index de route

endpoint

string

Oui

-

Nom de domaine ou adresse IP du serveur de relais

port

number

Oui

-

Port du serveur de relais

AoqTrackParam

Champ

Type

Obligatoire

Valeur par défaut

Description

trackType

AoqTrackType

Oui

-

Type de piste

trackMode

AoqTrackMode

Non

AoqTrackModeSegment

Mode streaming ou non streaming. Effectif uniquement pour la liaison descendante audio.

Types de statistiques

AoqStats

Résumé des statistiques du moteur, rapporté périodiquement via onStats. Un champ de type tableau est vide lorsqu'il ne contient aucune donnée, et networkStats n'est pas transmis en l'absence de données.

Champ

Type

Description

audioPublishStats

Array

Statistiques de publication audio

videoPublishStats

Array

Statistiques de publication vidéo

dataMsgPublishStats

Array

Statistiques de publication des messages de données

audioSubscribeStats

Array

Statistiques d'abonnement audio

videoSubscribeStats

Array

Statistiques d'abonnement vidéo

dataMsgSubscribeStats

Array

Statistiques d'abonnement aux messages de données

networkStats

AoqNetworkStats

Statistiques réseau

AoqAudioPublishStats

Champ

Type

Description

trackType

AoqTrackType

Type de piste

bitrate

number

Débit binaire, en bit/s

bytes

number

Nombre cumulé d'octets envoyés

encodeVolume

number

Volume d'encodage du flux publié

AoqAudioSubscribeStats

Champ

Type

Description

trackType

AoqTrackType

Type de piste

bitrate

number

Débit binaire, en bit/s

bytes

number

Nombre cumulé d'octets reçus

playVolume

number

Volume de lecture

AoqVideoPublishStats

Champ

Type

Description

trackType

AoqTrackType

Type de piste

bitrate

number

Débit binaire, en bit/s

bytes

number

Nombre cumulé d'octets envoyés

encodeFps

number

Fréquence d'images d'encodage

AoqVideoSubscribeStats

Champ

Type

Description

trackType

AoqTrackType

Type de piste

bitrate

number

Débit binaire, en bit/s

bytes

number

Nombre cumulé d'octets reçus

decodeFps

number

Fréquence d'images de décodage

renderFps

number

Fréquence d'images de rendu

AoqDataMsgPublishStats / AoqDataMsgSubscribeStats

Champ

Type

Description

trackType

AoqTrackType

Type de piste

bitrate

number

Débit binaire, en bit/s

bytes

number

Nombre cumulé d'octets envoyés et reçus

AoqNetworkStats

Champ

Type

Description

sendBitrate

number

Débit binaire d'envoi, en bit/s

sendBytes

number

Nombre cumulé d'octets envoyés

recvBitrate

number

Débit binaire de réception, en bit/s

recvBytes

number

Nombre cumulé d'octets reçus

loss

number

Taux de perte de paquets, de 0 à 100

rtt

number

Latence aller-retour, en ms

Énumérations

AoqTrackType

Valeur d'énumération

Valeur

Description

AoqTrackTypeAudio

0

Piste audio

AoqTrackTypeVideo

1

Piste vidéo

AoqTrackTypeData

2

Piste de messages de données

AoqTrackMode

Valeur d'énumération

Valeur

Description

AoqTrackModeSegment

0

Segmenté : les données sont encapsulées et transmises par segments sémantiques, tels qu'une phrase.

AoqTrackModeStream

1

En continu : les données sont transmises en flux continu.

AoqEncoderType

Valeur d'énumération

Valeur

Description

AoqEncoderTypeUnknown

0

Format inconnu

AoqEncoderTypeAudioPCM

1

Audio PCM

AoqEncoderTypeAudioOpus

2

Audio Opus (basé sur un plug-in ; nécessite PluginOpus)

AoqEncoderTypeVideoH264

3

Vidéo H.264

AoqEncoderTypeVideoJpeg

4

Vidéo JPEG

AoqEncoderTypeDataText

5

Texte du message

AoqConnectionStatus

Valeur d'énumération

Valeur

Description

AoqConnectionStatusDisconnected

0

Déconnecté

AoqConnectionStatusConnecting

1

Connexion en cours

AoqConnectionStatusConnected

2

Connecté

AoqConnectionStatusFailed

3

Échec de la connexion

AoqMirrorMode

Valeur d'énumération

Valeur

Description

AoqMirrorModeDisabled

0

Mise en miroir désactivée

AoqMirrorModeEnabled

1

Mise en miroir activée

AoqOrientationMode

Valeur d'énumération

Valeur

Description

AoqOrientationModeAuto

0

Ajustement automatique

AoqOrientationModePortrait

1

Portrait

AoqOrientationModeLandscape

2

Paysage

AoqErrorCode

Les codes d'erreur sont définis au niveau natif. Le paramètre code de onError et les valeurs de retour de l'API utilisent toutes deux ces valeurs (la couche TS ne les exporte pas sous forme d'enum).

Valeur d'énumération

Valeur

Description

AoqErrorCodeOK

0

Succès

AoqErrorCodeParamInvalid

1

Paramètre non valide

AoqErrorCodeStateInvalid

2

État non valide

AoqErrorCodeUnSupport

3

Non pris en charge sur la plateforme actuelle ou dans le mode actuel

AoqErrorCodeAudio

100

Erreur audio générique

AoqErrorCodeAudioExternalBufferFull

110

Le tampon audio externe est plein

AoqErrorCodeAudioDevice

120

Erreur générique du périphérique audio

AoqErrorCodeAudioDeviceRecordingAuthFailed

121

Autorisation d'enregistrement non accordée

AoqErrorCodeAudioDeviceRecordingOccupied

122

Le périphérique d'enregistrement est utilisé

AoqErrorCodeAudioDeviceRecordingBackgroundStart

123

Échec du démarrage de l'enregistrement en arrière-plan

AoqErrorCodeAudioDeviceRecordingStartFail

124

Échec du démarrage de l'enregistrement

AoqErrorCodeAudioDevicePlayoutOccupied

125

Le périphérique de lecture est utilisé

AoqErrorCodeAudioDevicePlayoutBackgroundStart

126

Échec du démarrage de la lecture en arrière-plan

AoqErrorCodeAudioDevicePlayoutStartFail

127

Échec du démarrage de la lecture

AoqErrorCodeVideo

200

Erreur vidéo générique

AoqErrorCodeVideoExternalBufferFull

210

Le tampon vidéo externe est plein

AoqErrorCodeVideoExternalCaptureNotEnabled

211

La capture vidéo externe n'est pas activée

AoqErrorCodeVideoExternalEncoderNotEnabled

212

L'encodage vidéo externe n'est pas activé

AoqErrorCodeVideoDevice

220

Erreur générique du périphérique vidéo

AoqErrorCodeVideoDeviceCameraOpenFail

221

Échec de l'ouverture de la caméra

AoqErrorCodeVideoDeviceCameraAuthFailed

222

Autorisation d'accès à la caméra non accordée

AoqErrorCodeVideoDeviceCameraOccupied

223

La caméra est utilisée

AoqErrorCodeVideoDeviceCameraRunningError

224

Exception d'exécution de la caméra

AoqErrorCodeVideoCodec

230

Erreur générique du codec vidéo

AoqErrorCodeVideoCodecEncoderInitFail

231

Échec de l'initialisation de l'encodeur vidéo

AoqErrorCodeVideoRender

240

Erreur générique du rendu vidéo

AoqErrorCodeVideoRenderCreateFail

241

Échec de la création du rendu vidéo

AoqErrorCodeVideoRenderDrawError

242

Erreur de dessin lors du rendu vidéo

En plus des codes d'erreur natifs ci-dessus, la couche Electron renvoie -1 lorsque le moteur n'est pas créé ou a été détruit, ou lorsqu'un paramètre n'est pas au format JSON valide.

AoqWarningCode

Valeur d'énumération

Valeur

Description

AoqWCOK

0

Aucun avertissement

AoqWCAudio

100

Avertissement audio générique

AoqWCAudioHowling

101

Larsen audio détecté

AoqWCAudioDevice

120

Avertissement générique du périphérique audio

AoqWCAudioDeviceMicEnumerateError

121

Erreur d'énumération du microphone

AoqWCAudioDeviceMicStartTimeout

122

Délai d'attente dépassé lors du démarrage du microphone

AoqWCAudioDeviceRecordingError

123

Erreur lors de l'enregistrement

AoqWCAudioDeviceSpeakerEnumerateError

124

Erreur d'énumération du haut-parleur

AoqWCAudioDeviceSpeakerStartTimeout

125

Délai d'attente dépassé lors du démarrage du haut-parleur

AoqWCAudioDevicePlayoutError

126

Erreur lors de la lecture

AoqWCVideo

200

Avertissement vidéo générique

AoqWCVideoCameraEnumerateError

201

Erreur d'énumération de la caméra

AoqWCVideoEncoderSwitched

202

Encodeur vidéo commuté

AoqWCVideoRenderDowngrade

203

Rétrogradation du rendu vidéo

Types audio

AoqAudioCaptureConfig

Field

Type

Required

Default value

Description

isExternal

boolean

No

false

Indique s'il faut utiliser le mode de capture externe

channel

number

No

1

Nombre de canaux de capture audio. Les valeurs 1 et 2 sont prises en charge.

AoqAudioPlaybackConfig

Field

Type

Required

Default value

Description

isExternal

boolean

No

false

Indique s'il faut utiliser le mode de lecture externe

channel

number

No

1

Nombre de canaux de lecture audio. Les valeurs 1 et 2 sont prises en charge.

Les champs isVoipMode et isDefaultSpeaker sont spécifiques aux appareils mobiles et ne sont pas fournis par Electron.

AoqAudioCodecConfig

Field

Type

Required

Default value

Description

trackType

AoqTrackType

No

AoqTrackTypeAudio

Type de piste

codecType

AoqEncoderType

No

AoqEncoderTypeAudioPCM

Format du codec

sampleRate

number

No

48000

Fréquence d'échantillonnage, en Hz. Pour l'encodage, les formats Opus 8/16/48K et PCM 8/16/32/48K sont pris en charge. Pour le décodage, la valeur 24K est également prise en charge, mais uniquement en mode Segment.

channel

number

No

1

Nombre de canaux. Les valeurs 1 et 2 sont prises en charge.

bitrate

number

No

32000

Débit binaire, en bit/s

AoqAudioDeviceRouteType

Le tableau suivant répertorie les valeurs valides de routeType pour onAudioDeviceRouteChanged. Ces valeurs sont définies par la couche native et ne sont pas exportées sous forme d'enum par la couche TypeScript.

Enum value

Value

Description

AoqAudioDeviceRouteDefault

0

Route par défaut

AoqAudioDeviceRouteHeadset

1

Casque avec microphone

AoqAudioDeviceRouteEarpiece

2

Écouteur

AoqAudioDeviceRouteHeadsetNoMic

3

Casque sans microphone

AoqAudioDeviceRouteSpeakerPhone

4

Haut-parleur

AoqAudioDeviceRouteUsb

5

Périphérique audio USB

AoqAudioDeviceRouteBluetooth

6

Mode Bluetooth SCO

AoqAudioDeviceRouteBluetoothA2dp

7

Mode Bluetooth A2DP

AoqAudioDeviceStateCode

Enum value

Value

Description

AoqAudioDeviceNone

0

Aucun état

AoqAudioDeviceRecordStarting

1

Démarrage de la capture

AoqAudioDeviceRecordStarted

2

Capture démarrée

AoqAudioDeviceRecordStopping

3

Arrêt de la capture

AoqAudioDeviceRecordStopped

4

Capture arrêtée

AoqAudioDeviceRecordFail

5

Échec de la capture

AoqAudioDevicePlayStarting

6

Démarrage de la lecture

AoqAudioDevicePlayStarted

7

Lecture démarrée

AoqAudioDevicePlayStopping

8

Arrêt de la lecture

AoqAudioDevicePlayStopped

9

Lecture arrêtée

AoqAudioDevicePlayFail

10

Échec de la lecture

AoqAudioDeviceState

Field

Type

Description

state

AoqAudioDeviceStateCode

État de fonctionnement du périphérique

reason

number

Code de la raison de l'erreur. Consultez AoqErrorCode.

Types de fichiers audio

AoqAudioFileMixConfig

Field

Type

Required

Default value

Description

fileId

string

Yes

-

Identifiant du fichier. Les appels d'API ultérieurs l'utilisent pour localiser le fichier.

fileName

string

Yes

-

Nom du fichier (incluant le chemin)

cycles

number

No

-1

Nombre de boucles. La valeur -1 indique une boucle illimitée.

startPosMs

number

No

0

Position de début de la lecture, en millisecondes

publishVolume

number

No

100

Volume de publication. Valeurs valides : 0 à 100.

playoutVolume

number

No

100

Volume de lecture. Valeurs valides : 0 à 100.

AoqAudioFileStateCode

Enum value

Value

Description

AoqAudioFileNone

0

Aucun état

AoqAudioFileStarted

1

Lecture démarrée

AoqAudioFileStopped

2

Lecture arrêtée

AoqAudioFilePaused

3

Lecture mise en pause

AoqAudioFileResumed

4

Lecture reprise

AoqAudioFileEnded

5

Lecture terminée

AoqAudioFileBuffering

6

Mise en tampon de la lecture

AoqAudioFileBufferingEnd

7

Mise en tampon terminée

AoqAudioFileFailed

8

Échec de la lecture

AoqAudioFileErrorCode

Le tableau suivant répertorie les valeurs valides de AoqAudioFileState.errorCode. Ces valeurs sont définies par la couche native et sont transmises sous forme de valeurs number par la couche TypeScript.

Enum value

Value

Description

AoqAudioFileNoError

0

Aucune erreur

AoqAudioFileOpenFailed

1

Échec de l'ouverture du fichier

AoqAudioFileDecodeFailed

2

Échec du décodage du fichier

AoqAudioFileState

Field

Type

Description

fileId

string

Identifiant du fichier

stateCode

AoqAudioFileStateCode

Code d'état de la lecture du fichier

errorCode

number

Code d'erreur du fichier. Consultez AoqAudioFileErrorCode.

Types de flux audio externes

AoqAudioStreamDirection

Valeur d'énumération

Valeur

Description

AoqAudioStreamPublish

0

Flux de publication

AoqAudioStreamPlayout

1

Flux de lecture (lecture locale)

AoqAudioExternalStreamConfig

Champ

Type

Obligatoire

Valeur par défaut

Description

streamId

string

Oui

-

Identifiant du flux

trackType

AoqTrackType

Non

AoqTrackTypeAudio

Type de piste audio

codecType

AoqEncoderType

Non

AoqEncoderTypeAudioPCM

Format du flux audio. Seul le format PCM est pris en charge actuellement.

channels

number

Non

1

Nombre de canaux. Cette valeur dépend du codec du flux de publication. Les valeurs 1 et 2 sont prises en charge.

sampleRate

number

Non

48000

Fréquence d'échantillonnage, en Hz. Les valeurs suivantes sont prises en charge : 8, 12, 16, 24, 32, 44,1, 48, 64, 88,2, 96, 176,4 et 192K.

playoutVolume

number

Non

100

Volume de lecture. Valeurs valides : de 0 à 100.

publishVolume

number

Non

100

Volume de publication. Valeurs valides : de 0 à 100.

maxBufferDuration

number

Non

600000

Durée maximale du tampon, en millisecondes. Valeurs valides : 100 et plus. Si la durée dépasse cette valeur, l'envoi échoue.

enable3A

boolean

Non

false

Indique s'il faut appliquer le traitement 3A au flux PCM entrant

AoqAudioExternalFrameMeta

Métadonnées d'une trame audio externe. Les données PCM sont transmises séparément via le paramètre buffer.

Champ

Type

Obligatoire

Valeur par défaut

Description

streamId

string

Oui

-

Identifiant du flux audio externe cible

numOfSamples

number

Oui

0

Nombre d'échantillons (par canal)

bytesPerSample

number

Oui

2

Nombre d'octets par échantillon

numOfChannels

number

Oui

1

Nombre de canaux

samplesPerSec

number

Oui

48000

Nombre d'échantillons par seconde (fréquence d'échantillonnage)

pushSequence

number

Non

0

Tour d'entrée PCM

timeStamp

number

Non

0

Horodatage

AoqAudioFrameEvent

Données d'événement de l'observateur de trames audio.

Champ

Type

Description

trackType

AoqTrackType

Type de piste

numOfSamples

number

Nombre d'échantillons (par canal)

bytesPerSample

number

Nombre d'octets par échantillon

numOfChannels

number

Nombre de canaux

samplesPerSec

number

Nombre d'échantillons par seconde (fréquence d'échantillonnage)

timeStamp

number

Horodatage

autoGenMute

boolean

La valeur true indique des données silencieuses générées par le SDK

buffer

Uint8Array

Données PCM audio (déjà copiées côté natif)

AoqAudioSource

Valeur d'énumération

Valeur

Description

AoqAudioSourceCaptured

0

Données audio capturées

AoqAudioSourceProcessCaptured

1

Données audio après traitement 3A

AoqAudioSourcePublish

2

Données audio à publier (nécessite une connexion établie avec succès)

AoqAudioSourcePlayback

3

Données audio à lire

AoqAudioObserverParams

Champ

Type

Obligatoire

Valeur par défaut

Description

enabled

boolean

Oui

false

Activez ou désactivez le rappel à cet emplacement

audioSource

AoqAudioSource

Oui

AoqAudioSourceCaptured

Emplacement du rappel

sampleRate

number

Non

48000

Fréquence d'échantillonnage de l'audio du rappel, en Hz. Un rééchantillonnage est effectué si les fréquences ne correspondent pas.

channels

number

Non

1

Nombre de canaux audio dans le rappel. Les valeurs 1 et 2 sont prises en charge.

Le mode de rappel est fixé en lecture seule. Electron ne propose pas de mode lecture-écriture.

AoqAudioVolumeIndicationConfig

Champ

Type

Obligatoire

Valeur par défaut

Description

interval

number

Non

0

Intervalle de rappel, en millisecondes. Une valeur inférieure ou égale à 0 désactive le rappel. Une valeur supérieure à 0 et inférieure à 10 est traitée comme 10.

smooth

number

Non

3

Coefficient de lissage du volume. Une valeur plus élevée produit une sortie plus lisse. Valeurs valides : de 0 à 10.

AoqAudioVolume

Champ

Type

Description

volume

number

Volume instantané lissé. Valeurs valides : de 0 à 255.

Types vidéo

AoqVideoCaptureConfig

Field

Type

Required

Default value

Description

width

number

No

1280

Largeur de capture, en pixels. Ce paramètre est ignoré lorsque isExternal=true.

height

number

No

720

Hauteur de capture, en pixels. Ce paramètre est ignoré lorsque isExternal=true.

fps

number

No

15

Fréquence d'images de capture. Ce paramètre est ignoré lorsque isExternal=true (le rythme est déterminé par la livraison des images).

isExternal

boolean

No

false

Indique s'il faut utiliser une capture externe. Si la valeur est true, la caméra n'est pas ouverte.

cameraDirection est un champ réservé aux appareils mobiles et n'existe pas sur les plateformes de bureau.

AoqVideoCodecConfig

L'encodage et le décodage partagent la même structure (setVideoEncoderConfig / setVideoDecoderConfig).

Field

Type

Required

Default value

Description

isExternal

boolean

No

false

Lorsque ce paramètre est défini sur true, le SDK n'effectue ni capture ni encodage, et les images sont poussées directement via pushExternalVideoEncodedFrame.

trackType

AoqTrackType

No

AoqTrackTypeVideo

Type de piste

codecType

AoqEncoderType

No

AoqEncoderTypeVideoH264

Format de codec

width

number

No

540

Largeur d'encodage, en pixels

height

number

No

960

Hauteur d'encodage, en pixels

fps

number

No

5

Fréquence d'images d'encodage

bitrate

number

No

500000

Débit binaire initial, en bit/s

minBitrate

number

No

128000

Débit binaire minimal, en bit/s

keyframeInterval

number

No

2

Intervalle entre les images clés, en secondes

mirrorMode

AoqMirrorMode

No

AoqMirrorModeDisabled

Mode miroir

orientationMode

AoqOrientationMode

No

AoqOrientationModeAuto

Mode d'orientation vidéo

AoqVideoPixelFormat

Formats de pixels pris en charge côté Electron (à l'exclusion des formats texture / CVPixelBuffer sur les plateformes mobiles).

Enum value

Value

Description

AoqVideoPixelFormatUnknown

0

Format inconnu

AoqVideoPixelFormatI420

1

I420 (format YUV planaire)

AoqVideoPixelFormatNV12

2

NV12 (format YUV semi-planaire)

AoqVideoPixelFormatNV21

3

NV21 (format YUV semi-planaire)

AoqVideoPixelFormatBGRA

4

BGRA (32 bits)

AoqVideoPixelFormatRGBA

5

RGBA (32 bits)

AoqExternalVideoFrameMeta

Métadonnées d'une image vidéo brute externe. Les données de pixel sont transmises séparément via le paramètre buffer.

Field

Type

Required

Default value

Description

trackType

AoqTrackType

No

AoqTrackTypeVideo

Type de piste

format

AoqVideoPixelFormat

Yes

-

Format de pixel

width

number

Yes

-

Largeur de la vidéo, en pixels

height

number

Yes

-

Hauteur de la vidéo, en pixels

timeStamp

number

No

0

Horodatage, en millisecondes. Si la valeur est 0, le SDK la remplit avec l'heure locale.

Lorsque format = I420, le buffer doit utiliser une disposition compacte (stride = width), avec les plans Y / U / V concaténés dans l'ordre. Pour les autres formats packés, transmettez directement tous les octets de l'image.

AoqVideoCodecType

Enum value

Value

Description

AoqVideoCodecTypeJPEG

0

Encodage JPEG

AoqExternalVideoEncodedFrameMeta

Métadonnées d'une image vidéo encodée externe. Les données encodées sont transmises séparément via le paramètre buffer.

Field

Type

Required

Default value

Description

trackType

AoqTrackType

No

AoqTrackTypeVideo

Type de piste

codec

AoqVideoCodecType

No

AoqVideoCodecTypeJPEG

Format de codec

width

number

Yes

-

Largeur, en pixels

height

number

Yes

-

Hauteur, en pixels

timeStamp

number

No

0

Horodatage, en millisecondes. Si la valeur est 0, le SDK la remplit avec l'heure locale.

AoqVideoDeviceStateCode

Enum value

Value

Description

AoqVideoDeviceNone

0

Aucun état

AoqVideoDeviceCaptureStarting

1

Démarrage de la capture

AoqVideoDeviceCaptureStarted

2

Capture démarrée

AoqVideoDeviceCaptureStopping

3

Arrêt de la capture

AoqVideoDeviceCaptureStopped

4

Capture arrêtée

AoqVideoDeviceCaptureFail

5

Échec de la capture (par exemple, autorisation refusée ou périphérique indisponible)

AoqVideoDeviceState

Field

Type

Description

state

AoqVideoDeviceStateCode

État de l'opération de capture du périphérique

reason

number

Code d'erreur. Consultez AoqErrorCode.

Types de rappel de trame vidéo

AoqVideoSource

Enum value

Value

Description

AoqVideoSourceCaptured

0

Données vidéo capturées avant le prétraitement

AoqVideoSourcePreEncode

1

Données vidéo après prétraitement, avant l'encodage

AoqVideoSourceRemote

2

Données vidéo distantes après décodage et avant le rendu

AoqVideoObserverAlignment

Enum value

Value

Description

AoqVideoObserverAlignmentDefault

0

Alignement par défaut

AoqVideoObserverAlignmentEven

1

Alignement sur nombre pair

AoqVideoObserverAlignment4

2

Alignement sur 4 octets

AoqVideoObserverAlignment8

3

Alignement sur 8 octets

AoqVideoObserverAlignment16

4

Alignement sur 16 octets

AoqVideoObserverParams

Field

Type

Required

Default value

Description

enabled

boolean

Yes

false

Active ou désactive le rappel à cette position

videoSource

AoqVideoSource

Yes

AoqVideoSourceCaptured

Position du rappel

format

AoqVideoPixelFormat

No

AoqVideoPixelFormatI420

Format de pixel attendu pour les données de rappel

alignment

AoqVideoObserverAlignment

No

AoqVideoObserverAlignmentDefault

Politique d'alignement de la width

mirrorApplied

boolean

No

false

Indique si les données de rappel doivent être mises en miroir

Le mode de rappel est fixé en lecture seule. Electron ne propose pas de mode lecture-écriture. Sélectionnez I420 lorsque vous utilisez le YUVCanvasRenderer intégré pour le rendu.

AoqVideoFrameEvent

Données d'événement de l'observateur de trames vidéo.

Field

Type

Description

trackType

AoqTrackType

Type de piste

format

AoqVideoPixelFormat

Format de pixel

width

number

Largeur, en pixels

height

number

Hauteur, en pixels

strideY

number

Pas (stride) du plan Y (effectif uniquement pour I420)

strideU

number

Pas (stride) du plan U (effectif uniquement pour I420)

strideV

number

Pas (stride) du plan V (effectif uniquement pour I420)

timeStamp

number

Horodatage, en millisecondes

buffer

Uint8Array

Données de la trame. Pour I420, il s'agit des plans Y / U / V concaténés selon le pas (stride). Les autres formats packés sont transmis sous forme de données brutes.

Types de messages de données

Electron n'utilise pas le type wrapper AoqDataMsg. Les messages de données sont envoyés et reçus directement sous forme de données binaires :

Direction

Type

Description

Send

Uint8Array or string

sendDataMsg(data). Les chaînes sont encodées en UTF-8.

Receive

Uint8Array

onDataMsg(data). Les données sont déjà copiées côté natif et peuvent être conservées de manière asynchrone.

Messagerie en temps réel

sendDataMsg(data: Uint8Array | string): number
Envoie un message de données en temps réel. Si vous transmettez une string, elle est encodée en interne en UTF-8 dans un Buffer avant l'envoi. Les messages provenant du pair sont signalés via le rappel d'événement onDataMsg.

Rappels de trames audio

setAudioFrameObserver(enable: boolean): number
enableAudioFrameObserver(params: AoqAudioObserverParams): number

Parameters

Type

Description

enable

boolean

true enregistre l'observateur de trames audio intégré ; false le désenregistre

params

AoqAudioObserverParams

Spécifiez la position du rappel, son état activé/désactivé et le format de rappel

Utilisation : appelez d'abord setAudioFrameObserver(true) pour enregistrer l'observateur. Ensuite, appelez enableAudioFrameObserver pour chaque position requise. Les données sont transmises via les événements correspondants.
engine.setAudioFrameObserver(true)
engine.enableAudioFrameObserver({
  enabled: true,
  audioSource: AoqAudioSource.AoqAudioSourceCaptured,
  sampleRate: 48000,
  channels: 1
})
engine.on('onCapturedAudioFrame', (frame) => { /* frame.buffer contains PCM data */ })
L'observateur de trames côté Electron prend uniquement en charge le mode lecture seule et ne permet pas de réécrire les données de trame dans le rappel (le côté natif est fixé sur ReadOnly).

Indication du volume local

enableLocalAudioVolumeIndication(config: AoqAudioVolumeIndicationConfig): number
Active ou désactive l'indication du volume de capture local. Si config.interval <= 0, le rappel est désactivé. Une fois activé, onLocalAudioVolumeIndication est déclenché à l'intervalle spécifié par config.interval. Vous devez appeler cette méthode après startAudioCapture() pour obtenir les données de volume.

Rappels de trames vidéo

setVideoFrameObserver(enable: boolean): number
enableVideoFrameObserver(params: AoqVideoObserverParams): number

Parameters

Type

Description

enable

boolean

true enregistre l'observateur de trames vidéo intégré ; false le désenregistre

params

AoqVideoObserverParams

Spécifiez la position du rappel, son état activé/désactivé, le format de pixel et la politique d'alignement

Les données de rappel sont transmises sous forme d'AoqVideoFrameEvent via onCapturedVideoFrame / onPreEncodeVideoFrame / onRemoteVideoFrame. Pour I420, le buffer contient les plans Y / U / V concaténés selon le pas (stride). Les autres formats packés sont transmis sous forme de données brutes. Seul le mode lecture seule est pris en charge.

Rendu vidéo (YUVCanvasRenderer)

Le moteur de rendu logiciel intégré au SDK. Il assure la prévisualisation pour les appels setLocalView / setRemoteView sur les plateformes mobiles.
import { YUVCanvasRenderer } from 'aoq-electron-sdk';

class YUVCanvasRenderer {
  bind(canvas: HTMLCanvasElement): void
  unbind(): void
  get bound(): boolean
  drawFrame(frame: AoqVideoFrameEvent): void
}

API

Description

bind

Lie un canvas (un nouveau lien remplace le précédent)

unbind

Détache le lien et efface l'image

bound

Indique si un lien est actif

drawFrame

Affiche une image ; seul le format I420 est pris en charge. La méthode retourne silencieusement si le format n'est pas I420 ou si la taille ou la longueur du buffer est insuffisante

const renderer = new YUVCanvasRenderer()
renderer.bind(document.getElementById('preview'))

engine.setVideoFrameObserver(true)
engine.enableVideoFrameObserver({
  enabled: true,
  videoSource: AoqVideoSource.AoqVideoSourceCaptured,
  format: AoqVideoPixelFormat.AoqVideoPixelFormatI420
})
engine.on('onCapturedVideoFrame', (frame) => renderer.drawFrame(frame))
Pour gérer le mode de remplissage du rendu (étirement ou recadrage), utilisez la propriété CSS object-fit appliquée au canvas.

Événements du moteur (IAoqEngineEvents)

Le moteur hérite de EventEmitter<IAoqEngineEvents>. Les événements constituent le point de sortie unique pour toutes les notifications asynchrones du SDK et correspondent un à un aux rappels natifs AoqEngineEventListener. Inutile d'enregistrer les événements qui ne vous intéressent pas.
engine.on('onError', (code, message) => {})
engine.off('onError', handler)
engine.once('onStats', (stats) => {})
engine.removeAllListeners()

onError

onError: (code: number, message: string) => void
Rappel d'erreur du moteur. Le paramètre code correspond à une valeur AoqErrorCode (voir section 3.3).

onWarning

onWarning: (code: number, message: string) => void
Rappel d'avertissement du moteur. Le paramètre code correspond à une valeur AoqWarningCode (voir section 3.3).

onConnectionStatusChange

onConnectionStatusChange: (status: AoqConnectionStatus) => void
Rappel de changement d'état de la connexion. Transitions d'état : Disconnected -> Connecting -> Connected / Failed -> Disconnected.

onStats

onStats: (stats: AoqStats) => void
Rappel des statistiques du moteur. Le SDK rapporte périodiquement les statistiques de publication et d'abonnement audio/vidéo ainsi que les métriques réseau. Utilisez ces données pour surveiller en temps réel la qualité des appels et l'état du réseau, et pour diagnostiquer les problèmes audio et vidéo.

Paramètres

Type

Description

stats

AoqStats

Statistiques de publication et d'abonnement ainsi que métriques réseau pour l'audio, la vidéo et les messages de données

onAudioDeviceStateChanged

onAudioDeviceStateChanged: (state: AoqAudioDeviceState) => void
Rappel des changements d'état des opérations de capture et de lecture des périphériques audio.

onAudioDeviceRouteChanged

onAudioDeviceRouteChanged: (routeType: number) => void
Rappel de changement de route de sortie audio. Le paramètre routeType correspond à une valeur AoqAudioDeviceRouteType (voir section 3.4).

onAudioFileState

onAudioFileState: (state: AoqAudioFileState) => void
Rappel de l'état de lecture des fichiers audio.

onLocalAudioVolumeIndication

onLocalAudioVolumeIndication: (volume: AoqAudioVolume) => void
Rappel d'indication du volume de capture local. Pour l'activer, appelez enableLocalAudioVolumeIndication.

onVideoDeviceStateChanged

onVideoDeviceStateChanged: (state: AoqVideoDeviceState) => void
Rappel des changements d'état des opérations de capture des périphériques vidéo.

onDataMsg

onDataMsg: (data: Uint8Array) => void
Rappel de réception d'un message de données en temps réel. Le paramètre data est un Buffer copié côté natif et peut être conservé en toute sécurité de manière asynchrone. Pour les messages textuels, utilisez Buffer.from(data).toString() afin de convertir les données en chaîne de caractères.

Événements de trame audio

onCapturedAudioFrame:        (frame: AoqAudioFrameEvent) => void  /* raw captured data */
onProcessCapturedAudioFrame: (frame: AoqAudioFrameEvent) => void  /* data after 3A processing */
onPublishAudioFrame:         (frame: AoqAudioFrameEvent) => void  /* publishing data */
onPlaybackAudioFrame:        (frame: AoqAudioFrameEvent) => void  /* playback data */
Vous devez d'abord appeler setAudioFrameObserver(true) puis enableAudioFrameObserver pour activer cette fonctionnalité.

Événements de trame vidéo

onCapturedVideoFrame:  (frame: AoqVideoFrameEvent) => void  /* after capture, before preprocessing */
onPreEncodeVideoFrame: (frame: AoqVideoFrameEvent) => void  /* before encoding, after preprocessing */
onRemoteVideoFrame:    (frame: AoqVideoFrameEvent) => void  /* remote, after decoding and before rendering */
Vous devez d'abord appeler setVideoFrameObserver(true) puis enableVideoFrameObserver pour activer cette fonctionnalité. Les événements de trame sont en lecture seule. Les modifications apportées au buffer dans le rappel ne sont pas répercutées dans le SDK.
Évitez les calculs lourds dans les rappels d'événements : les rappels natifs sont distribués vers le thread principal JS via un thread asynchrone, et les opérations chronophages lors d'événements de trame à haute fréquence provoquent un engorgement.