Skip to main content

Qwen-Audio-Realtime Flutter SDK

Integrate Qwen-Audio-Realtime with the Flutter SDK. See the Dart call sequence, request parameters, and events.

Qwen-Audio-Realtime takes live audio and returns model responses. Configure the session to receive response text and audio.

Prerequisites

  • Set up Flutter development for your target platform. The example app requires Dart 3.4 or later, below 4.0.
  • Get an API key. Choose a service endpoint in the same region as the API key. If you use a workspace-specific domain, also get your workspace ID.
Do not hardcode a long-lived API key in a mobile app. For models that accept temporary API keys, have your application server generate a temporary API key and send it to the client.

Install the SDK

Open Mobile speech SDK selection and download, select Flutter, and download and extract the package. Copy the extracted SDK directory to packages/aliyun_neonui in your Flutter project and add the local dependency to pubspec.yaml.
dependencies:
  aliyun_neonui:
    path: packages/aliyun_neonui
Run flutter pub get, then import the SDK in your Dart file.
import 'package:aliyun_neonui/neonui.dart';

Quick start

Run the example app

  1. Connect your target device. Run these commands from the extracted SDK directory.
    cd example
    flutter pub get
    flutter run
    
  2. In the example app, open 百炼(DashScope) from the home screen. Select a service endpoint and enter your API Key. If you use a workspace-specific domain, enter your WorkspaceId as well.
  3. Open Qwen-Audio 实时语音对话 and run the example. Allow microphone access when running an audio capture example.
The complete example is in example/lib/pages/dashscope/dash_qwen_audio_chat_page.dart in the SDK package.

Models in the included example

  • qwen-audio-3.1-realtime-plus
  • qwen-audio-3.0-realtime-plus
  • qwen-audio-3.0-realtime-flash

Call procedure

Call these methods on the instance returned by NativeNui(). Use the connection JSON and task JSON under Request parameters as initJson and sessionJson. Check the result of each call before continuing.
  1. Subscribe to eventStream and ttsAudioStream before calling these methods.
  2. Set the connection and task parameters, then start the session.
    await nui.nuiInitialize(params: initJson);
    await nui.dialogSetParams(sessionJson);
    await nui.dialogStart(vadMode: VadMode.p2t.code, dialogParams: sessionJson);
    
  3. Once the session starts, capture audio and send PCM chunks with sendAudio. The included recording example captures 16 kHz, 16-bit, mono PCM. On iOS, start the microphone before starting the audio player. If the player is already running, restart it after the microphone starts so the response audio can play.
  4. Stop capturing audio and call dialogStop. After handling the last events, call nuiRelease and cancel your subscriptions.

Request parameters

The following example uses a model from the package. For additional settings, see example/lib/dashscope_params.dart in the package. For additional parameter details, see Android SDK, iOS SDK, HarmonyOS SDK. Replace YOUR_WS_HOST with the WebSocket host for your region, YOUR_DEVICE_ID with a device identifier, and YOUR_API_KEY with an API key for that region.

Connection parameters

Pass the example JSON as a string to the Dart method.
{
  "device_id": "YOUR_DEVICE_ID",
  "url": "wss://YOUR_WS_HOST/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus",
  "service_mode": "1",
  "audio_update_manually": "false"
}

Task parameters

Pass the example JSON as a string to the Dart method.
{
  "apikey": "YOUR_API_KEY",
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm",
    "modalities": "[\"text\",\"audio\"]",
    "voice": "longanqian_v3.1",
    "turn_detection": "{\"type\":\"server_vad\",\"threshold\":0.5,\"silence_duration_ms\":800}"
  },
  "service_type": 4
}
Use the same model ID in the URL query parameter model and in nls_config.model. For this Dart SDK, modalities and turn_detection are JSON strings.

API reference

Methods

For methods returning Future<int>, result code 0 indicates success. The return type of sendAudio is Future<Object?>.
Method signaturePurpose
Future<int> nuiInitialize({required String params, int logLevel = 0, bool saveLog = false})Initialize the SDK with connection parameters as a JSON string.
Future<int> dialogSetParams(String params)Set the JSON parameters for the current session.
Future<int> dialogStart({required int vadMode, String dialogParams = "{}"})Start the session. vadMode selects the segmentation mode, and dialogParams accepts a JSON string with per-session parameters.
Future<Object?> sendAudio(Uint8List data)Send a chunk of PCM audio.
Future<int> dialogStop()End the current capture session and keep the connection open.
Future<int> dialogCancel()Cancel the current session or synthesis task.
Future<int> nuiRelease()Release SDK resources.
Future<int> dialogAction(String actionParams)Send a tool-call result to the session.

Events and audio streams

Read events from eventStream. For events delivered as Dart maps, read the event name from event and use resultCode to inspect task errors. The ttsAudioStream stream emits audio chunks for the app to play.
EventPurpose
EVENT_ASR_PARTIAL_RESULTPartial recognition result
EVENT_SENTENCE_ENDFinal recognition result for the current sentence
EVENT_AUDIO_TRANSCRIPTION_COMPLETEDTranscription of the spoken response complete
EVENT_ASR_TTS_STARTSynthesis or response audio started
EVENT_ASR_TTS_COMPLETETask or current audio output complete
EVENT_ASR_ERRORTask failed