Skip to main content
Qwen-Audio-Realtime

SDK Android percakapan suara real-time Qwen-Audio-3.0-Realtime

Gunakan Android SDK untuk Qwen-Audio-3.0-Realtime guna membangun percakapan suara waktu nyata dengan input audio dan output audio atau teks.

Panduan pengguna: Untuk pengenalan model dan saran pemilihan, lihat Percakapan suara real-time.

Mulai cepat

  1. Dapatkan dan konfigurasikan API key.
  2. Unduh SDK dan jalankan kode contoh:
    • Unduh paket SDK terbaru.
    • Ekstrak paket ZIP. Dapatkan SDK AAR dari app/libs dan tambahkan ke dependensi proyek Anda. Untuk integrasi C++ Android, gunakan android_libs dan android_include dalam paket ZIP untuk mendapatkan pustaka dinamis dan file header.
    • Buka proyek di Android Studio. Kode contoh ada di DashQwenAudioChatActivity.java. Ganti API key untuk mencoba fitur ini.

Prosedur pemanggilan

  1. Inisialisasi SDK.
  2. Atur parameter untuk kasus penggunaan Anda. Gunakan argumen parameters dari initialize untuk mengatur parameter koneksi dan kontrol, dan gunakan setParams untuk mengatur parameter percakapan suara.
  3. Panggil startDialog untuk memulai percakapan.
  4. Di onNuiAudioStateChanged, mulai perangkat perekaman berdasarkan status audio.
  5. Sediakan data perekaman secara terus-menerus di onNuiNeedAudioData, atau panggil updateAudio untuk mendorong data perekaman secara aktif.
  6. Terima secara terus-menerus audio yang dikembalikan oleh model di onNuiAssistEventCallback.
  7. Dengarkan event dan dapatkan informasi event di onNuiEventCallback.
  8. Panggil stopDialog untuk menghentikan percakapan, dan dengarkan EVENT_TRANSCRIBER_COMPLETE untuk mengonfirmasi bahwa percakapan telah berakhir.
  9. Saat fitur percakapan tidak lagi diperlukan, panggil release untuk melepaskan sumber daya SDK.

Parameter permintaan

Parameter koneksi dan kontrol

Berikan string JSON pada argumen parameters dari initialize. Contoh: String JSON berikut tidak mencantumkan setiap parameter. Tambahkan parameter sesuai kebutuhan untuk kasus penggunaan Anda.
{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}
Parameter
ParameterTipeWajibDeskripsi
urlStringYaEndpoint layanan:
  • wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Tiongkok (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Ganti {WorkspaceId} dengan ID Workspace.
apikeyStringYaAPI key.
service_modeStringYaMode runtime. Atur parameter ini ke "1" untuk percakapan suara real-time.
device_idStringYaString unik yang mengidentifikasi pengguna akhir. Anda dapat menggunakan ID pengguna dalam aplikasi atau pengidentifikasi perangkat yang dibuat klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah.
audio_update_manuallyStringTidakApakah akan mendorong data audio secara aktif. Default: "false". Jika diatur ke "true" dan SDK mendukung kemampuan audio on-device seperti AEC dan VAD, kemampuan tersebut diaktifkan secara default.
workspaceStringTidakJalur penyimpanan untuk file sumber daya on-device. Parameter ini wajib diisi jika audio_update_manually adalah "true" dan kemampuan audio on-device seperti AEC atau VAD diaktifkan.
debug_pathStringTidakJalur penyimpanan file log. Parameter ini hanya berlaku jika save_log adalah true di initialize. Dalam hal ini, jalur wajib diisi. SDK menyimpan paling banyak dua file log secara lokal.
save_wavStringTidakApakah akan menyimpan audio debug di bawah debug_path. Default: "false". Nilai yang valid adalah "true" dan "false". Parameter ini hanya berlaku jika save_log adalah true, dan debug_path juga harus diatur.
max_log_file_sizeintTidakUkuran file log maksimum dalam byte. Parameter ini hanya berlaku jika save_log adalah true. Default: 104857600 (100 × 1024 × 1024 byte, atau 100 MiB).
log_track_levelintTidakTingkat filter untuk log yang dikirim melalui onNuiLogTrackCallback. Default: 2. Nilai yang valid: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR), dan 5 (NONE). Log hanya dikembalikan jika tingkatnya lebih besar dari atau sama dengan log_track_level dan level yang diteruskan ke initialize. Misalnya, jika log_track_level adalah 2 (INFO) dan level adalah 3 (WARNING), hanya log WARNING dan tingkat lebih tinggi (nilai lebih besar dari atau sama dengan 3) yang dikembalikan.
aec_paramsobjectTidakKonfigurasi AEC on-device tingkat lanjut. Objek ini hanya berlaku jika audio_update_manually adalah "true".
aec_params.enable_aecbooleanTidakApakah akan mengaktifkan AEC on-device. Jika audio_update_manually adalah "true" dan SDK mendukung AEC on-device, AEC diaktifkan secara default.
aec_params.save_audiobooleanTidakApakah akan menyimpan audio yang diproses oleh modul AEC on-device. Jika save_wav adalah "true" dan debug_path diatur, fitur ini diaktifkan secara default dan audio disimpan di bawah debug_path.
aec_params.enable_aec_data_callbackbooleanTidakApakah akan mengembalikan audio yang diproses AEC melalui EVENT_AEC_DATA di onNuiAssistEventCallback. Default: false.
vad_paramsobjectTidakKonfigurasi VAD on-device tingkat lanjut. Objek ini hanya berlaku jika audio_update_manually adalah "true".
vad_params.enable_vadbooleanTidakApakah akan mengaktifkan VAD on-device. Jika audio_update_manually adalah "true" dan SDK mendukung VAD on-device, VAD diaktifkan secara default.
vad_params.save_audiobooleanTidakApakah akan menyimpan audio yang diproses oleh modul VAD on-device. Jika save_wav adalah "true" dan debug_path diatur, fitur ini diaktifkan secara default dan audio disimpan di bawah debug_path.

Parameter percakapan suara

Berikan string JSON pada argumen params dari setParams. Contoh: String JSON berikut tidak mencantumkan setiap parameter. Tambahkan parameter sesuai kebutuhan untuk kasus penggunaan Anda.
{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}
Parameter
Parameter tingkat atasTipeWajibDeskripsi
service_typeintYaTipe layanan suara. Atur parameter ini ke 4 untuk percakapan suara real-time.
nls_configobjectYaKonfigurasi inti percakapan suara, termasuk pemilihan model dan perilaku percakapan.
nls_config.modelstringYaNama model. Mendukung seri model qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.
nls_config.sr_formatstringYaFormat audio input. Hanya pcm yang didukung. Format defaultnya adalah PCM mono 16 kHz, 16-bit.
nls_config.modalitiesstringTidakString yang berisi array modalitas output. Nilai yang valid:
  • ["text"]: hanya mengembalikan teks.
  • ["audio", "text"] (default): mengembalikan audio dan teks.
nls_config.voicestringTidakSuara TTS. Defaultnya adalah longanqian_v3.1 untuk 3.1 Plus dan longanqian untuk 3.0 Plus/Flash. Parameter ini hanya dapat diatur pada session.update pertama; nilai berikutnya akan diabaikan. Suara sistem: longanqian, longanlingxin, longanlingxi, longanxiaoxin, dan longanlufeng. Anda juga dapat menentukan voice_id kloning yang dibuat melalui API kloning suara. Lihat Konfigurasi suara.3.1 Plus juga mendukung longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1, cally_v3.1.
nls_config.enable_speech_emotionbooleanTidakApakah akan mengaktifkan ekspresi emosional yang ditingkatkan. Saat diaktifkan, suara respons memiliki variasi emosional yang lebih kentara. Default: true. Nilai yang valid: true dan false.
nls_config.instructionsstringTidakInstruksi sistem yang menentukan peran model, gaya respons, dan preferensi perilaku untuk seluruh sesi.
nls_config.max_history_turnsintTidakJumlah maksimum giliran tanya-jawab historis yang diizinkan dalam satu permintaan. Nilai yang valid: 1 hingga 50. Default: 20.
nls_config.toolsstringTidakString yang berisi array definisi alat Function Calling. Setelah Anda mengonfigurasi parameter ini, model memutuskan apakah akan memanggil alat berdasarkan input pengguna. Setiap definisi menggunakan type (wajib dan ditetapkan ke function) dan objek function yang berisi name (wajib), description (opsional), dan parameters (opsional). Jika fungsi tidak memiliki argumen, abaikan parameters.
Contoh:
[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Queries weather information for a specified city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  }
]
nls_config.turn_detectionstringTidakString yang berisi objek JSON untuk deteksi giliran. Jika diabaikan, sesi menggunakan mode push-to-talk, di mana audio dikirim dan inferensi dipicu secara manual. Jika diatur, mode percakapan dupleks diaktifkan.
nls_config.turn_detection.typestringTidakTipe VAD. server_vad (default) mendeteksi batasan ucapan dari fitur akustik dan secara otomatis memicu inferensi. smart_turn menggabungkan sinyal akustik dan semantik; suara tanpa konten semantik, seperti suara pengisi, tidak memulai giliran atau mengganggu pemutaran model.
nls_config.turn_detection.thresholdfloatTidakSensitivitas VAD. Parameter ini hanya berlaku untuk server_vad dan tidak berpengaruh pada smart_turn. Nilai yang lebih rendah membuat VAD lebih sensitif terhadap suara pelan dan kebisingan latar belakang; nilai yang lebih tinggi memerlukan ucapan yang lebih jelas dan lebih keras. Rentang yang valid: [-1.0, 1.0]. Default: 0.5.
nls_config.turn_detection.silence_duration_msintTidakDurasi hening minimum setelah ucapan, dalam milidetik, sebelum respons model dipicu. Parameter ini hanya berlaku untuk server_vad dan tidak berpengaruh pada smart_turn. Nilai yang lebih rendah mengurangi latensi tetapi dapat terpicu pada jeda singkat. Rentang yang valid: [200, 6000]. Default: 800. Direkomendasikan untuk percakapan: 400 hingga 800.
nls_config.turn_detection.voiceprint_audio_urlsstringTidakString yang berisi array URL audio prarekaman yang dapat diakses publik untuk pembicara target. Parameter ini hanya berlaku untuk smart_turn. Dalam percakapan dupleks, ini membantu model fokus pada pembicara target dan mengabaikan pembicara lain serta kebisingan latar belakang. Mendukung hingga lima URL. Audio harus berupa PCM atau WAV 16 kHz.

API Utama

NativeNui

initialize

Menginisialisasi instance SDK percakapan suara. SDK adalah singleton. Jangan menginisialisasinya lebih dari sekali sebelum Anda memanggil release. Metode ini memblokir, jadi panggil pada thread non-UI. Signature metode
public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
Parameter

Parameter

Tipe

Deskripsi

callback

INativeNuiCallback

Implementasi antarmuka callback event dan data.

parameters

String

String JSON yang berisi parameter autentikasi, koneksi, dan debug. Lihat Parameter koneksi dan kontrol.

level

Constants.LogLevel

Mengontrol tingkat pencetakan log SDK itu sendiri.

save_log

boolean

Apakah akan menyimpan log lokal. Jika diatur ke true, tentukan jalur melalui debug_path dalam Parameter koneksi dan kontrol, dan secara opsional atur ukuran file melalui max_log_file_size.

setParams

Mengatur Parameter percakapan suara dalam format JSON. Panggil metode ini sebelum startDialog. Signature metode
public synchronized int setParams(String params)
Parameter

Parameter

Tipe

Deskripsi

params

String

Parameter percakapan suara.

startDialog

Memulai percakapan. Signature metode
public synchronized int startDialog(VadMode vad_mode, String dialog_params)
Parameter
ParameterTipeDeskripsi
vad_modeVadModeMode VAD. Tetap pada VadMode.TYPE_P2T.
dialog_paramsStringJika apikey dalam parameter koneksi dan kontrol adalah API key sementara, perbarui di sini setelah kedaluwarsa.
Format JSON:
{
  "apikey": "st-****"
}

stopDialog

Mengakhiri percakapan. Setelah Anda memanggil metode ini, server akan mengembalikan hasil percakapan akhir dan mengakhiri tugas. Signature metode
public synchronized int stopDialog();

cancelDialog

Mengakhiri percakapan segera. Setelah Anda memanggil metode ini, tugas langsung berakhir tanpa menunggu server mengembalikan hasil percakapan akhir. Signature metode
public synchronized int cancelDialog();

updateAction

Mengirimkan perintah tindakan percakapan selama interaksi untuk memperbarui perilaku runtime seperti konteks percakapan. Signature metode
public synchronized int updateAction(String params);
Parameter
ParameterTipeDeskripsi
paramsStringString JSON yang digunakan untuk memperbarui perilaku runtime seperti konteks percakapan.
params.typeStringAtur ke "action".
params.commandStringPerintah runtime. Nilai yang valid:
  • function_call: memperbarui permintaan function call.
  • play_start: ketika AEC pada perangkat digunakan, memberi tahu SDK bahwa pemutaran audio telah dimulai.
  • play_over: ketika AEC pada perangkat digunakan, memberi tahu SDK bahwa pemutaran audio telah berakhir.
params.contextStringPembaruan permintaan function call. Digunakan ketika command adalah "function_call".
params.context.typeStringTipe event. Parameter ini wajib diisi jika command adalah "function_call". conversation.item.create menyisipkan item percakapan untuk konteks historis, teks tambahan, atau hasil alat. Setelah mengirim conversation.item.create, gunakan response.create untuk memicu inferensi lain.
params.context.itemobjectWajib ketika params.context.type adalah conversation.item.create. Item percakapan yang akan dibuat.
params.context.responseobjectOpsional jika params.context.type adalah response.create. Menimpa default sesi untuk inferensi ini. Jika diabaikan, konfigurasi sesi saat ini akan digunakan.
Parameter context.item:
ParameterTipeDeskripsi
idStringID item percakapan unik opsional. Jika diabaikan, server akan membuatnya. Error akan dikembalikan jika ID yang ditentukan sudah ada.
typeStringTipe item wajib. Nilai yang valid:
  • message: pesan reguler.
  • function_call: permintaan pemanggilan fungsi. Tipe ini biasanya dibuat oleh server. Klien juga dapat menggunakannya untuk menambahkan konteks historis.
  • function_call_output: hasil eksekusi alat. Setelah menerima function_call, klien menjalankan alat dan menggunakan tipe ini untuk menulis kembali hasilnya.
roleStringWajib untuk message. Nilai yang valid: system, user, dan assistant.
contentarrayWajib untuk message. Setiap item berisi type dan bidang data terkait. system mendukung input_text dengan text; user mendukung input_text dengan text dan input_audio dengan audio yang dienkode Base64; assistant mendukung output_text dengan text.
call_idStringWajib untuk function_call dan function_call_output. ID unik yang mengaitkan permintaan pemanggilan fungsi dengan hasilnya.
nameStringWajib untuk function_call. Nama fungsi yang akan dipanggil.
argumentsStringWajib untuk function_call. Argumen fungsi sebagai string JSON.
outputStringWajib untuk function_call_output. Hasil eksekusi tool sebagai string JSON.
Parameter context.response:
ParameterTipeDeskripsi
modalitiesarrayModalitas output. ["text"] hanya mengembalikan teks. ["audio", "text"] (default) mengembalikan audio dan teks.
voicestringMenimpa suara TTS untuk inferensi ini.
Contoh:
{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"Hangzhou\",\"condition\":\"sunny\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": ["text", "audio"]
    },
    "type": "response.create"
  }
}

updateAudio

Saat audio_update_manually diatur ke "true", panggil metode ini untuk mendorong data perekaman secara aktif alih-alih menyediakan data melalui onNuiNeedAudioData. Signature metode
public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);
Parameter

Parameter

Tipe

Deskripsi

data

byte[]

Data audio yang akan di-push.

len

int

Jumlah byte data audio yang akan di-push.

first_pack

boolean

Abaikan parameter ini.

updateRefAudio

Saat audio_update_manually diatur ke "true" dan AEC on-device diaktifkan, panggil metode ini untuk mendorong audio yang diputar oleh pemutar sebagai sinyal referensi. Signature metode
public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);
Parameter

Parameter

Tipe

Deskripsi

data

byte[]

Data audio yang akan di-push.

len

int

Jumlah byte data audio yang akan di-push.

first_pack

boolean

Abaikan parameter ini.

release

Melepaskan semua sumber daya internal SDK. Setelah Anda memanggil metode ini, instance SDK menjadi tidak tersedia. Untuk menggunakannya lagi, Anda harus menginisialisasi ulang dengan memanggil initialize. Signature metode
public synchronized int release();

GetVersion

Mendapatkan informasi versi SDK saat ini. Signature metode
public synchronized String GetVersion();
Nilai kembalian Informasi versi SDK saat ini.

INativeNuiCallback: callback listener

onNuiEventCallback: mendengarkan informasi event

Signature metode
void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);
Parameter

Parameter

Tipe

Deskripsi

event

NuiEvent

Event callback.

resultCode

int

Hanya valid saat event EVENT_ASR_ERROR terjadi.

arg2

int

Parameter yang dicadangkan.

asrResult

AsrResult

Hasil pengenalan ucapan.

kwsResult

KwsResult

Fitur voice wake-up. Anda tidak perlu menggunakan parameter ini.

onNuiAudioStateChanged: mendengarkan status audio

SDK menggunakan callback ini untuk memberi tahu Anda kapan harus memulai atau menghentikan perekaman. Signature metode
void onNuiAudioStateChanged(AudioState state);
Status AudioState

Status

Deskripsi

STATE_OPEN

Interaksi telah dimulai. Anda dapat membuka perangkat perekaman dan memulai perekaman.

STATE_PAUSE

Interaksi telah berhenti. Anda dapat menghentikan perekaman.

STATE_CLOSE

Instans SDK telah dilepaskan. Anda dapat menutup perangkat perekaman sepenuhnya.

onNuiNeedAudioData: memasok data audio

Setelah percakapan dimulai, callback ini dipicu secara terus-menerus. Sediakan data audio di callback ini. Anda tidak perlu menggunakan callback ini saat audio_update_manually diatur ke "true". Signature metode
int onNuiNeedAudioData(byte[] buffer, int len);
Parameter

Parameter

Tipe

Deskripsi

buffer

byte[]

Data audio yang akan diisi.

len

int

Jumlah byte data audio yang akan diisi.

Nilai kembalian Jumlah byte yang sebenarnya diisi.

onNuiAssistEventCallback: menerima event dan data tambahan

Callback ini menerima event tambahan dan data terkait dari SDK. Signature metode
void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);
Parameter

Parameter

Tipe

Deskripsi

event

int

Event NuiEvent.

info

String

Abaikan parameter ini.

info_len

int

Abaikan parameter ini.

data

byte[]

Data tambahan, seperti audio TTS yang dikembalikan oleh model.

onNuiLogTrackCallback: mendengarkan log trace

Callback ini menerima log internal terperinci dari SDK untuk membantu pemecahan masalah dan debugging.
default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

NuiEvent: tipe event

EventDeskripsi
EVENT_TRANSCRIBER_STARTEDTugas berhasil dimulai.
EVENT_VAD_STARTDipicu segera setelah tugas dimulai. Ini tidak berarti bahwa awal ucapan telah terdeteksi.
EVENT_VAD_ENDAkhir ucapan terdeteksi.
EVENT_ASR_PARTIAL_RESULTHasil pengenalan ucapan sementara.
EVENT_ASR_ERRORTerjadi kesalahan selama percakapan suara.
EVENT_MIC_ERRORDipicu ketika tidak ada data audio yang diterima selama dua detik berturut-turut.
EVENT_SENTENCE_ENDAkhir kalimat terdeteksi dan hasil pengenalan lengkap dikembalikan.
EVENT_TRANSCRIBER_COMPLETEPercakapan suara berakhir.
EVENT_AUDIO_TRANSCRIPTIONEvent transkripsi teks inkremental untuk output audio. Segmen transkripsi dikembalikan dalam mode streaming.
EVENT_AUDIO_TRANSCRIPTION_COMPLETEDTranskrip untuk output audio telah selesai.
EVENT_OTHER_RESULTInformasi event lainnya, seperti hasil Function Calling.
EVENT_ASR_TTS_STARTModel mulai mengembalikan audio TTS.
EVENT_ASR_TTS_DATAAudio TTS yang dikembalikan oleh model.
EVENT_ASR_TTS_COMPLETEModel selesai mengembalikan audio TTS.
EVENT_AEC_DATAData audio yang diproses oleh AEC.
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Realtime API
Penyematan Teks
TokenPlan
Model production