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:
- 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.
- 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.
- 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
sendDataMsgdigunakan untuk mengirim audio sebagai pesan JSON. Server AOQ mendukung format pesan audio JSON ini dan otomatis menguraikannya menjadi data biner untuk diteruskan ke model. - 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
- 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.
- Gunakan
{WorkspaceId}.cn-beijing.maas.aliyuncs.comuntuk China (Beijing) atau{WorkspaceId}.ap-southeast-1.maas.aliyuncs.comuntuk Singapura sebagai{endpoint}. Ganti placeholder dengan ID workspace sebenarnya, dan gunakan API key untuk wilayah dan workspace yang sesuai. - Dapatkan AOQ Client SDK terbaru dari Unduhan SDK.
- 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)
-
Tempatkan
libPluginOpus.sodari plugin Opus diapp/src/main/jniLibs/armeabi-v7a/danapp/src/main/jniLibs/arm64-v8a/sesuai ABI. TempatkanAoqClientSdk-release.aardiapp/libs, lalu konfigurasikan dependensi dan ABI yang didukung diapp/build.gradle: -
Deklarasikan izin berikut di
AndroidManifest.xml: -
Minta izin
RECORD_AUDIOsaat 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.
| Field respons | Field SDK |
|---|---|
aoqTokenForClient | AoqConnectConfig.token |
sid | AoqConnectConfig.sid |
clientRelayCertFingerprint | AoqConnectConfig.certFingerprint |
clientRelayEndpoints | AoqConnectConfig.relayEndpoints |
extraInfo.workspaceIdHash | AoqConnectConfig.workspaceIdHash |
Implementasi klien

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.
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.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.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.
sendDataMsg yang sama:
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.
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:
| Field | Tipe | Deskripsi |
|---|---|---|
type | string | Nilai tetap: input_audio_buffer.append |
event_id | string | ID peristiwa unik untuk korelasi dan deduplikasi |
audio | string | Data audio PCM ber-encoding Base64 |
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.
input_audio_buffer.append, lalu kirim melalui sendDataMsg:
onDataMsg. Mulai mengirim audio saat task-started, dan uraikan hasil pengenalan saat result-generated. Lihat Peristiwa server.
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.
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.sendDataMsg:
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.
Catatan penggunaan
- Tunggu
task-startedsebelum mengirim audio; jika tidak, data akan dibuang. - Kirim
finish-taskhanya setelah buffer kosong (queue.size() == 0) agar model memproses segmen audio terakhir. - Jangan langsung memutuskan koneksi setelah
task-finished. Koneksi yang sama dapat digunakan kembali untuk tugas baru dengantask_idbaru. - Abaikan paket heartbeat (
heartbeat: true) dalamresult-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.
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.