Skip to main content

Utilisation d'AOQ avec qwen3.5-omni-plus-realtime pour les appels en temps réel

Cette rubrique explique comment intégrer le SDK client AOQ sur Android, iOS et HarmonyOS pour mettre en œuvre des appels audio et vidéo à l'aide d'AOQ et de qwen3.5-omni-plus-realtime.

Obtenir le SDK

Pour obtenir le SDK client AOQ et le plug-in audio Opus, consultez la rubrique Téléchargement du SDK. Le codec Opus est fourni sous forme de plug-in distinct. Intégrez-le selon vos besoins.

Importer le SDK

Copiez les fichiers principaux du SDK dans le répertoire des dépendances de votre projet, puis déclarez les autorisations requises dans la configuration de ce dernier.

Android

Placez le fichier AoqClientSdk-release.aar dans le répertoire app/libs/ de votre projet. Répartissez le fichier libPluginOpus.so par ABI dans les dossiers app/libs/armeabi-v7a/ et app/libs/arm64-v8a/. Dans le fichier app/build.gradle :
android {
    defaultConfig {
        minSdk 21
        ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' }
    }
    sourceSets { main { jniLibs.srcDirs = ['libs'] } }
    packagingOptions {
        // Avoid conflicts with same-named .so files in the host project
        pickFirsts += ['lib/*/*.so']
    }
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
}
Déclarez les autorisations dans le fichier AndroidManifest.xml :
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.CAMERA" />
Les autorisations RECORD_AUDIO et CAMERA sont soumises à une demande d'autorisation au moment de l'exécution. Votre application doit appeler la méthode Android ActivityCompat.requestPermissions() lors de l'exécution pour solliciter l'accord de l'utilisateur.

iOS (framework)

  1. Faites glisser les fichiers AoqClientSdk.framework et PluginOpus.framework dans votre projet Xcode. Sous Target > General > Frameworks, Libraries, and Embedded Content, sélectionnez Embed & Sign.
  2. Déclarez les autorisations : dans Xcode, accédez à Target > Info > Custom iOS Target Properties, puis ajoutez les deux descriptions d'utilisation suivantes :

    Key

    Value

    NSMicrophoneUsageDescription

    Pour les appels vocaux en temps réel

    NSCameraUsageDescription

    Pour les appels vidéo en temps réel

  3. Projet Swift : utilisez import AoqClientSdk. Projet Objective-C : utilisez #import <AoqClientSdk/AoqClientSdk.h>.

HarmonyOS (har)

  1. Placez le fichier aoq-client-sdk.har dans le répertoire libs/ de votre projet. Répartissez le fichier libPluginOpus.so par ABI dans les dossiers entry/libs/armeabi-v7a/ et entry/libs/arm64-v8a/. Déclarez ensuite la dépendance dans le fichier entry/oh-package.json5.
  2. Ajoutez les autorisations dans le fichier entry/src/main/module.json5 :
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.MICROPHONE",
        "reason": "$string:perm_mic_reason",
        "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" } },
      { "name": "ohos.permission.CAMERA",
        "reason": "$string:perm_camera_reason",
        "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" } }
    ]
    
  3. Dans EntryAbility, déclenchez la demande d'autorisation au moment de l'exécution via abilityAccessCtrl.createAtManager().requestPermissionsFromUser.

Obtenir un token depuis l'AppServer

Configurez un AppServer selon les Étapes d’authentification AOQ de Qwen-Omni-Realtime. Avant chaque appel, le client demande de nouvelles informations de connexion à AppServer.

Mettre en œuvre les appels audio/vidéo IA

111

Créer le moteur et définir les callbacks

Appelez l'API createEngine pour créer une instance d'AoqClientEngine. iOS :
let config = AoqCreateConfig()
config.workDir = workDir
engine = AoqClientEngine.createEngine(config, delegate: self)
Implémentez le protocole AoqEngineDelegate pour écouter les callbacks tels que onConnectionStatusChange, onDataMsg ou onError. Android :
AoqCreateConfig config = new AoqCreateConfig();
config.workDir = appCtx.getFilesDir().getAbsolutePath();
engine = AoqClientEngine.createEngine(appCtx, config, this);
HarmonyOS :
const config: AoqCreateConfig = { workDir: context.filesDir, extras: '' };
engine = AoqClientEngine.createEngine(config, this, context);

Démarrer la capture et la lecture audio/vidéo

Appelez startAudioCapture et startAudioPlayer pour lancer la capture et la lecture audio locales. Appelez ensuite startVideoCapture pour activer la caméra, puis utilisez setLocalView afin d'associer la cible de rendu du SDK à votre contrôle d'aperçu. Dans les exemples suivants, le SDK lit automatiquement l’audio. Pour vérifier le contenu avant la lecture, définissez isExternal sur true dans la configuration de lecture transmise à startAudioPlayer pour désactiver la lecture automatique du SDK, puis activez le callback des trames audio de lecture. L’application peut copier et mettre en mémoire tampon l’audio PCM reçu dans le callback, puis décider de le lire ou de le supprimer après vérification. Pour la configuration, consultez Lecture audio personnalisée. iOS : Pour un appel sur haut-parleur, définissez isVoipMode sur true pour la capture et la lecture avant de les démarrer afin d’activer l’annulation matérielle de l’écho. Gardez le microphone actif pendant la lecture pour que la détection d’activité vocale (VAD) puisse détecter la prise de parole de l’utilisateur et déclencher une interruption.
// Audio capture
let capCfg = AoqAudioCaptureConfig()
capCfg.channel = 1; capCfg.isExternal = false
capCfg.isVoipMode = true
engine.startAudioCapture(capCfg)

// Audio playback
let playCfg = AoqAudioPlaybackConfig()
playCfg.channel = 1; playCfg.isExternal = false
playCfg.isVoipMode = true
playCfg.isDefaultSpeaker = true
engine.startAudioPlayer(playCfg)

// Video capture
let vidCfg = AoqVideoCaptureConfig()
vidCfg.width = 720; vidCfg.height = 1280; vidCfg.fps = 15
engine.startVideoCapture(vidCfg)

// Set render view for local video preview
let canvas = AoqVideoCanvas()
canvas.view = localPreview
canvas.renderMode = .crop
engine.setLocalView(.video, canvas: canvas)
Android :
// Audio capture
AoqAudioCaptureConfig capCfg = new AoqAudioCaptureConfig();
capCfg.channel = 1; capCfg.isExternal = false;
engine.startAudioCapture(capCfg);

// Audio playback
AoqAudioPlaybackConfig playCfg = new AoqAudioPlaybackConfig();
playCfg.channel = 1; playCfg.isExternal = false;
engine.startAudioPlayer(playCfg);

// Video capture
AoqVideoCaptureConfig vidCfg = new AoqVideoCaptureConfig();
vidCfg.width = 720; vidCfg.height = 1280; vidCfg.fps = 15;
engine.startVideoCapture(vidCfg);

// Set render view for local video preview
AoqVideoCanvas canvas = new AoqVideoCanvas();
canvas.view = localPreview;
canvas.renderMode = AoqRenderMode.AoqRenderModeCrop;
engine.setLocalView(AoqTrackType.AoqTrackTypeVideo, canvas);
HarmonyOS :
// Audio capture
const capCfg: AoqAudioCaptureConfig = { channel: 1, isExternal: false };
engine.startAudioCapture(capCfg);

// Audio playback
const playCfg: AoqAudioPlaybackConfig = { channel: 1, isExternal: false };
engine.startAudioPlayer(playCfg);

// Video capture
const vidCfg: AoqVideoCaptureConfig = { width: 720, height: 1280, fps: 15, isExternal: false };
engine.startVideoCapture(vidCfg);

// Set render view for local video preview
const canvas: AoqVideoCanvas = { view: localCtrl, renderMode: AoqRenderMode.AoqRenderModeCrop };
engine.setLocalView(AoqTrackType.AoqTrackTypeVideo, canvas);

Obtenir les identifiants de connexion

Le client demande les informations de connexion à AppServer.

Configurer les codecs et établir la connexion

Définissez les paramètres des codecs, puis appelez la méthode connect. Remarque : qwen3.5-omni-plus-realtime exige que le client commence à envoyer des données multimédias uniquement après avoir reçu l'événement session.updated du serveur. Pour éviter tout envoi accidentel de flux entre l'appel réussi à connect et la réception de session.updated, appelez enableSendMediaStream(trackType, false) pour chaque piste montante avant d'appeler connect. Pour plus de détails sur les événements WebSocket, reportez-vous à la rubrique Événements client. iOS :
// Audio codec configuration
let encCfg = AoqAudioCodecConfig()
encCfg.codecType = .audioPCM; encCfg.sampleRate = 16000; encCfg.channel = 1
engine.setAudioEncoderConfig(encCfg)
engine.setAudioDecoderConfig(encCfg)

// Disable media sending before connect; enable after receiving session.updated
engine.enableSendMediaStream(.audio, enable: false)
engine.enableSendMediaStream(.video, enable: false)

// Establish connection
let conn = AoqConnectConfig()
conn.token = token; conn.sid = sid; conn.certFingerprint = cert
conn.relayEndpoints = endpoints; conn.workspaceIdHash = workspaceIdHash

let aTrack = AoqTrackParam(); aTrack.trackType = .audio
let vTrack = AoqTrackParam(); vTrack.trackType = .video
let dTrack = AoqTrackParam(); dTrack.trackType = .data
conn.publishTracks   = [aTrack, vTrack, dTrack]
conn.subscribeTracks = [aTrack, dTrack]
engine.connect(conn)
Android :
// Audio codec configuration
AoqAudioCodecConfig encCfg = new AoqAudioCodecConfig();
encCfg.codecType = AoqEncoderType.AoqEncoderTypeAudioPCM;
encCfg.sampleRate = 16000; encCfg.channel = 1;
engine.setAudioEncoderConfig(encCfg);
engine.setAudioDecoderConfig(encCfg);

// Disable media sending before connect; enable after receiving session.updated
engine.enableSendMediaStream(AoqTrackType.AoqTrackTypeAudio, false);
engine.enableSendMediaStream(AoqTrackType.AoqTrackTypeVideo, false);

// Establish connection
AoqConnectConfig conn = new AoqConnectConfig();
conn.token = token; conn.sid = sid; conn.certFingerprint = cert;
conn.relayEndpoints.addAll(endpoints); conn.workspaceIdHash = workspaceIdHash;

AoqTrackParam aTrack = new AoqTrackParam(); aTrack.trackType = AoqTrackType.AoqTrackTypeAudio;
AoqTrackParam vTrack = new AoqTrackParam(); vTrack.trackType = AoqTrackType.AoqTrackTypeVideo;
AoqTrackParam dTrack = new AoqTrackParam(); dTrack.trackType = AoqTrackType.AoqTrackTypeData;
conn.publishTracks.add(aTrack);
conn.publishTracks.add(vTrack);
conn.publishTracks.add(dTrack);
conn.subscribeTracks.add(aTrack);
conn.subscribeTracks.add(dTrack);
engine.connect(conn);
HarmonyOS :
// Audio codec configuration
const encCfg: AoqAudioCodecConfig = {
  codecType: AoqEncoderType.AoqEncoderTypeAudioPCM,
  sampleRate: 16000, channel: 1
};
engine.setAudioEncoderConfig(encCfg);
engine.setAudioDecoderConfig(encCfg);

// Disable media sending before connect; enable after receiving session.updated
engine.enableSendMediaStream(AoqTrackType.AoqTrackTypeAudio, false);
engine.enableSendMediaStream(AoqTrackType.AoqTrackTypeVideo, false);

// Establish connection
const conn: AoqConnectConfig = {
  token, sid, certFingerprint: cert,
  relayEndpoints: endpoints,
  workspaceIdHash,
  publishTracks: [
    { trackType: AoqTrackType.AoqTrackTypeAudio },
    { trackType: AoqTrackType.AoqTrackTypeVideo },
    { trackType: AoqTrackType.AoqTrackTypeData }
  ],
  subscribeTracks: [
    { trackType: AoqTrackType.AoqTrackTypeAudio },
    { trackType: AoqTrackType.AoqTrackTypeData }
  ]
};
engine.connect(conn);
Important : Par défaut, le SDK AOQ commence à envoyer des données multimédias dès la connexion établie. Cet exemple montre comment désactiver cet envoi lors de la connexion à un modèle.

Configurer la session IA

Dans le callback onConnectionStatusChange(Connected), envoyez un message session.update via la méthode sendDataMsg. Ce message contient les paramètres de session tels que les modalités, la voix, les instructions et turn_detection, ce qui finalise la négociation de session. Pour plus de détails sur les événements WebSocket, reportez-vous à la rubrique Événements client. iOS :
func onConnectionStatusChange(_ status: AoqConnectionStatus) {
    if status == .connected { sendSessionUpdate() }
}

private func sendSessionUpdate() {
    let json = """
    {
      // Event ID, generated by the client
      "event_id": "event_ToPZqeobitzUJnt3QqtWg",
      // Event type, always session.update
      "type": "session.update",
      // Session configuration
      "session": {
          // Output modalities: ["text"] (text only) or ["text","audio"] (text and audio)
          "modalities": [
              "text",
              "audio"
          ],
          // Output audio voice
          "voice": "Ethan",
          // Input audio format; currently only "pcm" is supported. Input audio is 16 kHz PCM.
          "input_audio_format": "pcm",
          // Output audio format; currently only "pcm" is supported. Output audio is 24 kHz PCM.
          "output_audio_format": "pcm",
          // System message for setting the model's objective or role.
          "instructions": "You are an AI customer service agent for a five-star hotel. Accurately and helpfully answer customer inquiries about room types, facilities, pricing, and reservation policies. Always respond professionally and helpfully. Do not provide unverified information or information outside the scope of hotel services.",
          // Whether to enable voice activity detection. If enabled, pass a config object and the server will automatically detect voice start and end.
          // Set to null to let the client control when to trigger a model response.
          "turn_detection": {
              // VAD type: server_vad or semantic_vad. Recommended: semantic_vad for qwen3.5-omni-realtime.
              "type": "semantic_vad",
              // VAD detection threshold. Increase in noisy environments; decrease in quiet ones.
              "threshold": 0.5,
              // Duration of silence after which a model response is triggered
              "silence_duration_ms": 800
          }
      }
    }
    """
    let msg = AoqDataMsg()
    msg.data = json.data(using: .utf8)!
    engine.send(msg)
}
Android :
@Override
public void onConnectionStatusChange(AoqConnectionStatus status) {
    if (status == AoqConnectionStatus.AoqConnectionStatusConnected) {
        sendSessionUpdate();
    }
}

private void sendSessionUpdate() {
    String sessionUpdateJson = /* Same session.update JSON as in the Swift example above */;
    AoqDataMsg msg = new AoqDataMsg();
    msg.data = sessionUpdateJson.getBytes(StandardCharsets.UTF_8);
    engine.sendDataMsg(msg);
}
HarmonyOS :
onConnectionStatusChange(status: AoqConnectionStatus): void {
  if (status === AoqConnectionStatus.AoqConnectionStatusConnected) {
    this.sendSessionUpdate();
  }
}

private sendSessionUpdate(): void {
  const sessionUpdateJson = /* Same session.update JSON as in the Swift example above */;
  const msg: AoqDataMsg = { data: new TextEncoder().encode(sessionUpdateJson).buffer };
  this.engine.sendDataMsg(msg);
}

Activer l'envoi multimédia après réception de session.updated

Dans le callback onDataMsg, analysez les messages entrants. Lorsque vous recevez l'événement session.updated du modèle, appelez enableSendMediaStream(trackType, true) pour chaque type de piste précédemment désactivé. Pour plus de détails sur les événements WebSocket, reportez-vous à la rubrique Événements serveur. iOS :
func onDataMsg(_ msg: AoqDataMsg) {
    guard let obj = try? JSONSerialization.jsonObject(with: msg.data) as? [String: Any],
          let type = obj["type"] as? String else { return }
    if type == "session.updated" {
        engine.enableSendMediaStream(.audio, enable: true)
        engine.enableSendMediaStream(.video, enable: true)
    }
}
Android :
@Override
public void onDataMsg(AoqDataMsg msg) {
    if (msg == null || msg.data == null) return;
    try {
        JSONObject obj = new JSONObject(new String(msg.data, StandardCharsets.UTF_8));
        if ("session.updated".equals(obj.optString("type"))) {
            engine.enableSendMediaStream(AoqTrackType.AoqTrackTypeAudio, true);
            engine.enableSendMediaStream(AoqTrackType.AoqTrackTypeVideo, true);
        }
    } catch (JSONException ignored) {}
}
HarmonyOS :
onDataMsg(msg: AoqDataMsg): void {
  if (!msg?.data) return;
  try {
    const text = new TextDecoder('utf-8').decode(new Uint8Array(msg.data));
    const obj = JSON.parse(text) as { type?: string };
    if (obj.type === 'session.updated') {
      this.engine.enableSendMediaStream(AoqTrackType.AoqTrackTypeAudio, true);
      this.engine.enableSendMediaStream(AoqTrackType.AoqTrackTypeVideo, true);
    }
  } catch (_) { /* Not JSON, ignore */ }
}
Important
  1. Ne commencez à envoyer des flux multimédias qu'après la réception de session.updated. L'IA pourrait ne pas être prête à recevoir des données avant cet événement.
  2. Les pistes audio et vidéo ajoutées lors de la connexion (canaux multimédias AOQ) transmettent automatiquement les données au serveur.
    1. Audio : transmis directement via la piste audio. Il n'est pas nécessaire d'envoyer des événements input_audio_buffer.append.
    2. Vidéo : les images sont envoyées via la piste vidéo. Il n'est pas nécessaire d'envoyer des événements input_image_buffer.append.

Se déconnecter et détruire le moteur

engine.disconnect()
AoqClientEngine.destroy()

Scénarios courants

Interruption (Barge-in)

  • Le SDK est étroitement intégré à Alibaba Cloud Model Studio. Les messages d'interruption provenant du modèle coupent le tour de parole précédent dès qu'un nouveau tour commence.
  • Le SDK fournit l'interface interruptAudioPlayer pour interrompre la lecture locale. Appelez cette API lorsque l'utilisateur souhaite arrêter la lecture en cours.
// iOS
engine.interruptAudioPlayer(.audio, fadeMs: 100)

Couper / rétablir le micro

Une fois le micro coupé, le SDK continue de capturer l'audio mais n'envoie que des trames silencieuses. La session n'est pas interrompue.
engine.muteAudioCapture(true);   // Mute microphone (capture continues, but only silent frames are sent)
engine.muteAudioCapture(false);  // Unmute

Basculer entre les caméras avant et arrière

// Pass the desired camera direction enum
engine.switchCamera(AoqCameraDirection.AoqCameraDirectionFront);
engine.switchCamera(AoqCameraDirection.AoqCameraDirectionBack);

Sous-titres d'appel et résultats ASR

Le serveur pousse les résultats ASR et les réponses textuelles de l'IA via des messages de données descendants. Dans votre application, acheminez-les en fonction du champ type présent dans le callback onDataMsg. Pour plus de détails sur les événements WebSocket, reportez-vous à la rubrique Événements serveur.

Remarques importantes

  1. Sémantique singleton : createEngine fonctionne comme un singleton ; des appels répétés renvoient toujours la même instance. Le moteur ne peut être recréé qu'après l'appel de destroy. Pour une utilisation multi-pages, gérez le cycle de vie du moteur au niveau de l'Application ou de l'Ability.
  2. Types de vues pour l'aperçu local :
    • Android : SurfaceView ou TextureView. Les autres types ne sont pas pris en charge.
    • iOS : Toute sous-classe de UIView.
    • HarmonyOS : Consultez la documentation du SDK.
  3. Changements de routage audio : Des événements tels que le branchement ou le retrait d'écouteurs, ou encore la connexion Bluetooth, déclenchent onAudioDeviceRouteChanged. Aucune action n'est généralement requise dans votre application. Toutefois, si votre interface comprend un bouton permettant de basculer entre le haut-parleur et l'écouteur, synchronisez l'état en vous basant sur ce callback.
  4. Poursuite de l'audio en arrière-plan : Pour que l'audio continue lorsque l'appel passe en arrière-plan, le fichier Info.plist doit comporter l'option UIBackgroundModes = audio activée, et AVAudioSession doit être correctement activé au premier plan. Le SDK gère la plupart des cas ; utilisez setAudioSessionRestriction: pour un contrôle plus fin.

Télécharger la démo

image
Téléchargez le code source de l'exemple : iOS : aoqdemo.zip

Documents associés