Skip to main content

Menggunakan AOQ dengan qwen-audio-3.1-asr-flash-streaming untuk input suara

Tutorial ini menjelaskan penggunaan AOQ SDK dengan qwen-audio-3.1-asr-flash-streaming untuk mengimplementasikan input suara.

Gambaran solusi

Pada interaksi input suara yang umum, pengguna mengeklik tombol input suara lalu langsung berbicara. Hasil pengenalan ditampilkan di kolom input secara real time. Poin utama implementasi klien adalah sebagai berikut:
  1. Langsung merekam: Mulai merekam audio dan menyimpan data PCM dalam buffer segera setelah tombol diklik, sambil meminta kredensial dan membuat koneksi secara asinkron. Karena pembuatan koneksi memerlukan waktu dan pengguna mungkin sudah berbicara, simpan audio terlebih dahulu lalu kirimkan.
  2. Mengejar dengan kecepatan ganda: Setelah koneksi berhasil dan peristiwa kesiapan model diterima, kirim audio dalam buffer dengan kecepatan ganda. Setelah mengejar data terkini, beralih ke pengiriman real time.
  3. Mengirim audio melalui kanal Data: qwen-audio-3.1-asr-flash-streaming menggunakan protokol Inference (run-task / finish-task). Skenario ini memerlukan penyimpanan audio sebelum pengiriman dengan kecepatan ganda, sehingga sendDataMsg digunakan untuk mengirim audio sebagai pesan JSON. Server AOQ mendukung format pesan audio JSON ini dan otomatis menguraikannya menjadi data biner untuk diteruskan ke model.
  4. Hasil sementara dan final: Model terus mengembalikan hasil pengenalan. Tampilkan hasil sementara (sentence_end: false) secara real time dan tambahkan hasil final (sentence_end: true) ke kolom input.

Persiapan

Prasyarat

  1. Aktifkan Alibaba Cloud Model Studio dan dapatkan API key sesuai Mendapatkan dan mengonfigurasi API key. Simpan API key hanya di AppServer. Jangan memasukkannya ke kode klien atau melakukan commit ke repositori kode.
  2. Gunakan {WorkspaceId}.cn-beijing.maas.aliyuncs.com untuk China (Beijing) atau {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com untuk Singapura sebagai {endpoint}. Ganti placeholder dengan ID workspace sebenarnya, dan gunakan API key untuk wilayah dan workspace yang sesuai.
  3. Dapatkan AOQ Client SDK terbaru dari Unduhan SDK.
  4. Siapkan AppServer dengan mengikuti langkah autentikasi AOQ untuk Qwen-Audio-ASR-Streaming. Sebelum setiap koneksi baru, klien harus memperoleh kredensial koneksi baru dari AppServer.

Mengimpor SDK

Unduh AOQ Client SDK terbaru dari Unduhan SDK, lalu impor SDK untuk platform pengembangan yang digunakan. Contoh kode klien berikut menggunakan Android. Platform lain menggunakan desain antarmuka dan alur peristiwa yang sama.
  • Android
  • iOS
  • HarmonyOS
  • Linux (Python)
  1. Tempatkan libPluginOpus.so dari plugin Opus di app/src/main/jniLibs/armeabi-v7a/ dan app/src/main/jniLibs/arm64-v8a/ sesuai ABI. Tempatkan AoqClientSdk-release.aar di app/libs, lalu konfigurasikan dependensi dan ABI yang didukung di app/build.gradle:
    android {
        defaultConfig {
            minSdk 21
            ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' }
        }
    }
    
    dependencies {
        implementation fileTree(dir: 'libs', include: ['*.aar'])
    }
    
  2. Deklarasikan izin berikut di 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" />
    
  3. Minta izin RECORD_AUDIO saat runtime sebelum menggunakan mikrofon.

Mendapatkan token melalui AppServer

AppServer memanggil API alokasi Model Studio dan mengembalikan Token, SID, endpoint Relay, serta informasi lain yang diperlukan SDK untuk membuat koneksi ke klien.
curl -X POST \
  "https://{endpoint}/api/v1/webrtc/inference?model=qwen-audio-3.1-asr-flash-streaming" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  -H "x-dashscope-rtc-transport: moq" \
  -d "{\"clientIp\": \"${CLIENT_REAL_IP}\"}"
Field responsField SDK
aoqTokenForClientAoqConnectConfig.token
sidAoqConnectConfig.sid
clientRelayCertFingerprintAoqConnectConfig.certFingerprint
clientRelayEndpointsAoqConnectConfig.relayEndpoints
extraInfo.workspaceIdHashAoqConnectConfig.workspaceIdHash

Implementasi klien

Urutan implementasi klien input suara
Langkah berikut menggunakan Android dan disusun sesuai urutan implementasi. Platform lain menggunakan desain antarmuka dan alur peristiwa yang sama.

1. Membuat engine dan mendaftarkan callback

Buat instans AoqClientEngine serta daftarkan callback status koneksi dan pesan Data. Kirim run-task setelah koneksi berhasil. Callback pesan Data menangani peristiwa server.
// Create the engine
AoqClientEngine.AoqCreateConfig create = new AoqClientEngine.AoqCreateConfig();
create.workDir = getCacheDir().getAbsolutePath();
engine = AoqClientEngine.createEngine(this, create, new AoqClientListener() {
    @Override
    public void onConnectionStatusChange(
            @NonNull AoqClientEngine.AoqConnectionStatus state) {
        if (state == AoqClientEngine.AoqConnectionStatus.AoqConnectionStatusConnected) {
            // Connected: send run-task (see step 4)
        }
    }

    @Override
    public void onDataMsg(@NonNull AoqClientEngine.AoqDataMsg msg) {
        // Parse server events (see step 5)
    }

    @Override
    public void onError(int code, String message) {
        // Handle errors
    }
});

2. Mengonfigurasi encoding audio dan memulai perekaman

Konfigurasikan encoding PCM (16 kHz, mono), daftarkan callback perekaman dengan setAudioFrameObserver untuk memperoleh PCM, lalu panggil enableSendMediaStream(Audio, false) untuk menonaktifkan pengiriman media audio (audio dikirim melalui kanal Data). Terakhir, panggil startAudioCapture() untuk mulai merekam. Contoh ini menggunakan perekaman bawaan AOQ SDK dan memperoleh PCM melalui onCapturedAudioFrame. Anda juga dapat menggunakan perekaman sendiri, misalnya AudioRecord di Android. Masukkan PCM ke antrean buffer; logika pengiriman selanjutnya tetap sama.
  • Cara A: Perekaman bawaan SDK
  • Cara B: Perekaman sendiri
Contoh kode memanggil startAudioCapture, memperoleh PCM melalui onCapturedAudioFrame, lalu menyalinnya ke buffer aplikasi. Daftarkan callback perekaman mentah AoqAudioSourceCaptured untuk menyimpan audio sebelum koneksi terbentuk.
int SAMPLE_RATE = 16000;

// Configure PCM encoding
AoqClientEngine.AoqAudioCodecConfig codec = new AoqClientEngine.AoqAudioCodecConfig();
codec.codecType = AoqClientEngine.AoqEncoderType.AoqEncoderTypeAudioPCM;
codec.sampleRate = SAMPLE_RATE;
codec.channel = 1;
codec.bitrate = 256000;
engine.setAudioEncoderConfig(codec);

// Register the capture callback
engine.setAudioFrameObserver(new AoqClientListener.AoqAudioFrameListener() {
    @Override
    public void onCapturedAudioFrame(
            @NonNull AoqClientEngine.AoqAudioFrameData frame) {
        if (frame.dataPtr != null && frame.dataSize > 0) {
            // Buffer PCM data in the queue (see step 5)
            pcmQueue.offer(frame.dataPtr, frame.dataSize);
        }
        Arrays.fill(frame.dataPtr, (byte) 0);  // Clear the buffer to prevent outgoing audio media
    }
});

AoqClientEngine.AoqAudioObserverConfig observer = new AoqClientEngine.AoqAudioObserverConfig();
observer.sampleRate = SAMPLE_RATE;
observer.channels = 1;
observer.mode = AoqClientEngine.AoqAudioObserverMode.AoqAudioObserverModeReadWrite;
engine.enableAudioFrameObserver(true,
        AoqClientEngine.AoqAudioSource.AoqAudioSourceCaptured, observer);

// Disable outgoing audio media (send audio over the Data channel)
engine.enableSendMediaStream(AoqClientEngine.AoqTrackType.AoqTrackTypeAudio, false);

// Start capture immediately, without waiting for the connection
engine.startAudioCapture(new AoqClientEngine.AoqAudioCaptureConfig());
Pilih salah satu cara agar tidak menjalankan dua perekam sekaligus. Untuk perekaman sendiri, aplikasi bertanggung jawab atas konversi format, konfirmasi penghentian, dan pelepasan perangkat audio.

3. Mengonfigurasi kredensial dan track, lalu menghubungkan

Isi AoqConnectConfig dengan kredensial dari AppServer. Publikasikan track Audio + Data dan berlangganan track Data. Deklarasi track Audio diperlukan untuk koneksi, tetapi pengiriman media audio dinonaktifkan. Audio sebenarnya dikirim melalui kanal Data.
Track Audio harus dipublikasikan: Model ASR memerlukan deklarasi track Audio saat menghubungkan; jika tidak, koneksi gagal. Data audio dikirim melalui kanal Data sebagai input_audio_buffer.append, bukan kanal media audio. Panggil enableSendMediaStream(Audio, false) sebelum menghubungkan agar SDK tidak otomatis mengirim audio yang direkam.
// Build the connection configuration after obtaining credentials from AppServer
AoqClientEngine.AoqConnectConfig config = new AoqClientEngine.AoqConnectConfig();
config.token = aoqTokenForClient;
config.sid = sid;
config.certFingerprint = clientRelayCertFingerprint;
config.workspaceIdHash = workspaceIdHash;
// Parse relayEndpoints from the response and add them to the configuration

// Publish Audio + Data tracks
AoqClientEngine.AoqTrackParam audioTrack = new AoqClientEngine.AoqTrackParam();
audioTrack.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
config.publishTracks.add(audioTrack);

AoqClientEngine.AoqTrackParam dataTrack = new AoqClientEngine.AoqTrackParam();
dataTrack.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
config.publishTracks.add(dataTrack);

// Subscribe to the Data track
AoqClientEngine.AoqTrackParam subData = new AoqClientEngine.AoqTrackParam();
subData.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
config.subscribeTracks.add(subData);

// Establish the connection
engine.connect(config);

4. Mengirim run-task untuk memulai pengenalan

Setelah koneksi berhasil, buat task_id baru untuk setiap putaran input suara, misalnya dengan UUID.randomUUID().toString(). Pada callback koneksi berhasil, kirim JSON berikut menggunakan sendDataMsg. Kirim run-task hanya sekali setiap putaran. Struktur peristiwa run-task adalah sebagai berikut. ID tugas merupakan contoh; ganti dengan ID yang baru dibuat untuk putaran saat ini. Detail peristiwa tersedia dalam Peristiwa klien.
{
  "header": {
    "action": "run-task",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3",
    "streaming": "duplex"
  },
  "payload": {
    "task_group": "audio",
    "task": "asr",
    "function": "recognition",
    "model": "qwen-audio-3.1-asr-flash-streaming",
    "parameters": {
      "format": "pcm",
      "sample_rate": 16000
    },
    "input": {}
  }
}
Pesan kontrol dan audio dikirim melalui antarmuka sendDataMsg yang sama:
String taskId = UUID.randomUUID().toString();
JSONObject root = new JSONObject()
        .put("header", new JSONObject()
                .put("action", "run-task")
                .put("task_id", taskId)
                .put("streaming", "duplex"))
        .put("payload", new JSONObject()
                .put("task_group", "audio")
                .put("task", "asr")
                .put("function", "recognition")
                .put("model", "qwen-audio-3.1-asr-flash-streaming")
                .put("parameters", new JSONObject()
                        .put("format", "pcm")
                        .put("sample_rate", 16000))
                .put("input", new JSONObject()));

AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
msg.data = root.toString().getBytes(StandardCharsets.UTF_8);
engine.sendDataMsg(msg);

5. Mengirim audio buffer dengan kecepatan ganda setelah task-started

Uraikan JSON di onDataMsg. Ubah status pengiriman menjadi siap hanya setelah menerima peristiwa berikut untuk tugas saat ini.
{
  "header": {
    "event": "task-started",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3"
  },
  "payload": {}
}
Contoh di atas memuat field utama peristiwa. Baca field respons lain sesuai kebutuhan. Lihat Peristiwa server. Biasanya buffer sudah berisi audio yang direkam selama permintaan kredensial, pembuatan koneksi AOQ, dan peluncuran tugas model. Periksa kesesuaian task_id pada respons dengan ID tugas saat ini; task-started duplikat tidak boleh memulai loop pengiriman kedua. Format pesan audio: Protokol Inference qwen-audio-3.1-asr-flash-streaming (Peristiwa klien) hanya mendefinisikan dua peristiwa kontrol: run-task dan finish-task. Audio sendiri bukan dikirim sebagai peristiwa JSON. Namun, pengiriman melalui kanal Data AOQ memerlukan pesan JSON. Karena itu, AOQ membungkus audio dalam peristiwa input_audio_buffer.append pada lapisan SDK:
FieldTipeDeskripsi
typestringNilai tetap: input_audio_buffer.append
event_idstringID peristiwa unik untuk korelasi dan deduplikasi
audiostringData audio PCM ber-encoding Base64
Klien mengenkode PCM yang direkam ke Base64, membungkusnya dalam JSON ini, lalu mengirimnya melalui sendDataMsg. Server AOQ menguraikan field audio menjadi PCM biner dan meneruskannya ke model ASR sesuai protokol model. Klien tidak perlu menangani pembungkusan frame biner. Pastikan format PCM (sample rate, jumlah kanal, dan kedalaman bit) sesuai dengan format dan sample_rate dalam run-task.
{
    "type": "input_audio_buffer.append",
    "event_id": "event_550e8400-e29b-41d4-a716-446655440000",
    "audio": "AQID//+AgAAEAACAAAAA..."
}
Mengirim data audio: Ambil PCM dari antrean buffer, bungkus sebagai JSON input_audio_buffer.append, lalu kirim melalui sendDataMsg:
byte[] pcm = pcmQueue.poll(640);  // Read one PCM frame

if (pcm != null) {
    JSONObject event = new JSONObject()
            .put("type", "input_audio_buffer.append")
            .put("event_id", "event_" + UUID.randomUUID())
            .put("audio", Base64.encodeToString(pcm, Base64.NO_WRAP));

    AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
    msg.data = event.toString().getBytes(StandardCharsets.UTF_8);
    engine.sendDataMsg(msg);
}
Menangani peristiwa server: Uraikan peristiwa server di callback onDataMsg. Mulai mengirim audio saat task-started, dan uraikan hasil pengenalan saat result-generated. Lihat Peristiwa server.
JSONObject root = new JSONObject(new String(msg.data, StandardCharsets.UTF_8));
String event = root.optJSONObject("header").optString("event");

if ("task-started".equals(event)) {
    // Model ready: send buffered audio at double speed, then stream in real time
} else if ("result-generated".equals(event)) {
    // Parse recognition results (see step 6)
    JSONObject sentence = root.optJSONObject("payload")
            .optJSONObject("output").optJSONObject("sentence");
    if (sentence != null && !sentence.optBoolean("heartbeat")) {
        String text = sentence.optString("text", "");
        boolean isFinal = sentence.optBoolean("sentence_end");
        // Display recognition results
    }
} else if ("task-finished".equals(event)) {
    // Task finished
} else if ("task-failed".equals(event)) {
    // Task failed
}

6. Menangani dan menampilkan hasil pengenalan

Peristiwa result-generated membawa kalimat yang dikenali beserta field seperti text dan sentence_end. Tampilkan hasil sementara secara real time dan tambahkan hasil final ke kolom input. Definisi tersedia dalam Peristiwa server.
private void handleRecognitionResult(JSONObject root) {
    JSONObject payload = root.optJSONObject("payload");
    JSONObject output = payload == null ? null : payload.optJSONObject("output");
    JSONObject sentence = output == null ? null : output.optJSONObject("sentence");
    if (sentence == null || sentence.optBoolean("heartbeat")) return;

    String text = sentence.optString("text", "");
    if (text.isEmpty()) return;
    boolean isFinal = sentence.optBoolean("sentence_end");

    // Display interim results in real time; append final results
    listener.onResult(text, isFinal);
}

7. Mengirim finish-task untuk mengakhiri pengenalan

Ketika pengguna mengakhiri input, panggil engine.stopAudioCapture() terlebih dahulu untuk menghentikan perekaman. Tunggu sampai sisa PCM dalam buffer terkirim, lalu kirim finish-task untuk memberi tahu server bahwa semua audio sudah dikirim. Lihat Peristiwa klien untuk definisinya.
task_id harus sama dengan nilai pada run-task untuk putaran saat ini.
Struktur peristiwa finish-task adalah sebagai berikut:
{
    "header": {
        "action": "finish-task",
        "task_id": "UUID",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}
Kirim melalui sendDataMsg:
engine.stopAudioCapture();  // Stop capture

// Wait for the buffer to drain, then send finish-task
JSONObject root = new JSONObject()
        .put("header", new JSONObject()
                .put("action", "finish-task")
                .put("task_id", taskId)
                .put("streaming", "duplex"))
        .put("payload", new JSONObject()
                .put("input", new JSONObject()));

AoqClientEngine.AoqDataMsg msg = new AoqClientEngine.AoqDataMsg();
msg.data = root.toString().getBytes(StandardCharsets.UTF_8);
engine.sendDataMsg(msg);
Ketika model selesai, peristiwa utama yang dikembalikan adalah:
{
  "header": {
    "event": "task-finished",
    "task_id": "9fb212ea-6f83-4aef-9b8e-1bdd71f1d4d3"
  },
  "payload": {}
}

8. Memutuskan koneksi dan menghancurkan engine

Setelah menerima task-finished, lepaskan sumber daya dengan cara berikut jika koneksi tidak perlu digunakan kembali. Lepaskan sumber daya juga saat terjadi kesalahan atau timeout.
engine.stopAudioCapture();
engine.setAudioFrameObserver(null);
engine.disconnect();
AoqClientEngine.destroy();
engine = null;

Catatan penggunaan

  1. Tunggu task-started sebelum mengirim audio; jika tidak, data akan dibuang.
  2. Kirim finish-task hanya setelah buffer kosong (queue.size() == 0) agar model memproses segmen audio terakhir.
  3. Jangan langsung memutuskan koneksi setelah task-finished. Koneksi yang sama dapat digunakan kembali untuk tugas baru dengan task_id baru.
  4. Abaikan paket heartbeat (heartbeat: true) dalam result-generated; jangan anggap sebagai hasil pengenalan.

Skenario umum

Beberapa putaran pengenalan dalam satu koneksi

Koneksi tetap tersedia setelah task-finished. Klien dapat mengirim run-task lagi dengan task_id baru untuk memulai putaran berikutnya tanpa membuat ulang koneksi. Cara ini cocok untuk input suara berkelanjutan dan mengurangi latensi koneksi berulang.
// After the first round finishes (task-finished received)
// Send run-task with a new task_id to start the second round
taskId = UUID.randomUUID().toString();
sendRunTask();

Perekaman audio sendiri

Contoh ini menggunakan perekaman bawaan AOQ SDK (startAudioCapture + onCapturedAudioFrame), tetapi Anda juga dapat membuat perekaman sendiri. Masukkan PCM (16 kHz, mono, 16-bit) ke PcmQueue. Logika pengiriman buffer untuk mengejar data terkini dan pengiriman selanjutnya tetap sama.

Dokumentasi terkait