Fun-ASR-Realtime iOS SDK - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

Pelajari parameter, antarmuka, callback, dan penggunaan SDK iOS untuk Fun-ASR-Realtime.

Mulai cepat

Dapatkan API key: Dapatkan API key
Unduh SDK dan jalankan kode contoh:
- Unduh paket SDK terbaru.
- Ekstrak paket ZIP dan tambahkan nuisdk.xcframework yang disertakan ke proyek Anda.
- Di Build Phases → Link Binary With Libraries, tambahkan nuisdk.xcframework.
- Di General → Frameworks, Libraries, and Embedded Content, atur nuisdk.xcframework ke Embed & Sign.
- Buka proyek contoh di Xcode. Kode contoh berada di DashFunAsrSpeechTranscriberViewController.m. Ganti API key dengan milik Anda untuk mencoba fitur ini.

Urutan pemanggilan

Inisialisasi SDK.
Atur parameter sesuai kebutuhan: gunakan nui_initialize untuk parameter koneksi dan kontrol, serta nui_set_params untuk parameter kualitas pengenalan.
Panggil nui_dialog_start untuk memulai pengenalan.
Dalam callback onNuiAudioStateChanged, buka perangkat perekaman sesuai status audio.
Pasok data rekaman secara berkelanjutan dalam onNuiNeedAudioData, atau panggil nui_update_audio_data untuk mengirimkannya secara aktif.
Dalam onNuiEventCallback, pantau peristiwa dan ambil hasil pengenalan ucapan.
Panggil nui_dialog_cancel untuk menghentikan pengenalan, lalu pastikan pengenalan selesai melalui peristiwa EVENT_TRANSCRIBER_COMPLETE.
Saat pengenalan tidak lagi diperlukan, panggil nui_release untuk melepaskan sumber daya SDK.

Parameter permintaan

Parameter koneksi dan kontrol

Atur parameter ini dengan meneruskan string JSON ke argumen parameters pada nui_initialize.

Contoh parameter: String JSON berikut adalah contoh dan tidak mencantumkan semua parameter. Tambahkan parameter yang diperlukan saat menulis kode.

{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Deskripsi parameter

Parameter	Tipe	Wajib	Deskripsi
`url`	`String`	Ya	Alamat layanan: `wss://dashscope.aliyuncs.com/api-ws/v1/inference` Tiongkok (Beijing): `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference` Singapura: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference` Ganti `{WorkspaceId}` dengan ID Workspace Anda yang sebenarnya.
`apikey`	`String`	Ya	API key.
`service_mode`	`String`	Ya	Mode operasi. Tetapkan ke `"1"` untuk pengenalan ucapan real-time.
`device_id`	`String`	Ya	String unik yang mengidentifikasi pengguna akhir. Gunakan ID pengguna aplikasi atau pengenal perangkat yang dibuat di klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah.
`audio_update_manually`	`String`	Tidak	Mengaktifkan pengiriman data audio secara aktif atau tidak. Default: `"false"`. Jika diatur ke `"true"` dan versi SDK mendukung pemrosesan audio pada perangkat seperti AEC atau VAD, kemampuan tersebut diaktifkan secara default.
`workspace`	`String`	Tidak	Jalur tempat file sumber daya pada perangkat disimpan. Parameter ini diperlukan ketika `audio_update_manually` diatur ke `"true"` dan kemampuan pemrosesan audio pada perangkat seperti AEC atau VAD diaktifkan.
`debug_path`	`String`	Tidak	Lokasi penyimpanan file log. Berlaku hanya jika `save_log` diatur ke `YES` pada `nui_initialize`. Dalam hal ini, lokasi wajib diatur; jika tidak, terjadi kesalahan. Maksimal dua file log disimpan secara lokal.
`save_wav`	`String`	Tidak	Menyimpan audio debug atau tidak. Audio disimpan di `debug_path`. Default: `"false"`. `"true"` menyimpan file; `"false"` tidak menyimpannya. Berlaku hanya jika `save_log` diatur ke true pada `nui_initialize`. `debug_path` juga wajib diatur.
`max_log_file_size`	`int`	Tidak	Ukuran maksimum file log dalam byte. Berlaku hanya jika `save_log` diatur ke `YES` pada `nui_initialize`. Default: 104857600 (100 × 1024 × 1024 byte, yaitu 100 MiB).
`log_track_level`	`int`	Tidak	Level filter log yang dikembalikan melalui `onNuiLogTrackCallback`. Default: 2. Nilai: 0 (LOG_LEVEL_VERBOSE), 1 (LOG_LEVEL_DEBUG), 2 (LOG_LEVEL_INFO), 3 (LOG_LEVEL_WARNING), 4 (LOG_LEVEL_ERROR), 5 (LOG_LEVEL_NONE, nonaktif). Log dikembalikan hanya jika levelnya lebih besar dari atau sama dengan `log_track_level` dan `level` pada `nui_initialize`. Misalnya, dengan nilai 2 (INFO) dan 3 (WARNING), hanya log WARNING dan di atasnya (nilai ≥ 3) yang dikembalikan.

Parameter kualitas pengenalan

Atur parameter ini dengan meneruskan string JSON ke argumen params pada nui_set_params.

Contoh parameter: String JSON berikut adalah contoh dan tidak mencantumkan semua parameter. Tambahkan parameter yang diperlukan saat menulis kode.

{
    "service_type": 4,
    "nls_config": {
        "model": "fun-asr-realtime",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

Deskripsi parameter

Parameter tingkat atas	Tipe	Wajib	Deskripsi
`service_type`	`int`	Ya	Jenis layanan suara. Tetapkan ke `4` untuk pengenalan ucapan real-time.
`nls_config`	`object`	Ya	Objek konfigurasi utama pengenalan. Mencakup parameter seperti pemilihan model dan kontrol kualitas pengenalan.
`nls_config.model`	`string`	Ya	Nama model.
`nls_config.sr_format`	`string`	Ya	Format audio. Nilai yang valid: `pcm` `opus` PentingJika Anda memberikan data PCM dan mengatur parameter ini ke `opus`, SDK mengenkodenya menjadi Opus secara internal.
`nls_config.sample_rate`	`int`	Ya	Laju sampel dalam Hz. Model 8 kHz hanya mendukung 8000 Hz; model lain mendukung semua laju sampel. Penting8000 Hz tidak didukung saat pemrosesan audio pada perangkat seperti AEC atau VAD diaktifkan.
`nls_config.max_sentence_silence`	`int`	Tidak	Ambang batas keheningan VAD untuk segmentasi, dalam ms. Ketika keheningan setelah segmen ucapan melebihi ambang batas ini, sistem menentukan bahwa kalimat telah berakhir. Nilai default: 1300. Nilai yang valid: [200, 6000].
`nls_config.multi_threshold_mode_enabled`	`boolean`	Tidak	Mengaktifkan mode multi-ambang atau tidak. Jika diaktifkan, segmen VAD tidak menjadi terlalu panjang. Nilai default: false.
`nls_config.heartbeat`	`boolean`	Tidak	Apakah akan mengaktifkan paket heartbeat. Nilai default: false. true: Menjaga koneksi ke server tetap aktif bahkan ketika audio senyap dikirim secara terus-menerus. false (default): Bahkan ketika audio senyap dikirim secara terus-menerus, koneksi akan habis waktunya dan tertutup setelah jangka waktu tertentu. Audio senyap merujuk pada konten dalam file audio atau aliran data yang tidak mengandung sinyal suara. Anda dapat menghasilkan audio senyap dengan beberapa cara, seperti menggunakan perangkat lunak pengeditan audio seperti Audacity atau Adobe Audition, atau menggunakan alat baris perintah seperti FFmpeg.
`nls_config.vocabulary_id`	`string`	Tidak	ID dari daftar hotword yang telah dikompilasi sebelumnya. Hasilkan ID ini terlebih dahulu dengan memanggil API buat daftar hotword. Teruskan ID selama pengenalan untuk menggunakan hotword dalam daftar. Cocok untuk skenario di mana kosakata diketahui dan relatif stabil, dan di mana Anda perlu menggunakan kembali daftar kata yang sama di berbagai permintaan. Untuk detail penggunaan, lihat Hotword yang telah dikompilasi sebelumnya.
`nls_config.language_hints`	`array[string]`	Tidak	Bahasa audio yang akan dikenali. Tidak ada nilai default; jika tidak diatur, model mendeteksi bahasa secara otomatis. Anda dapat menetapkan 1 nilai. Jika lebih, hanya nilai pertama yang berlaku. Click to view the supported language codes fun-asr-realtime: zh: Chinese en: English ja: Japanese ko: Korean vi: Vietnamese th: Thai id: Indonesian ms: Malay tl: Filipino hi: Hindi ar: Arabic fr: French de: German es: Spanish pt: Portuguese ru: Russian it: Italian nl: Dutch sv: Swedish da: Danish fi: Finnish no: Norwegian el: Greek pl: Polish cs: Czech hu: Hungarian ro: Romanian bg: Bulgarian hr: Croatian sk: Slovak fun-asr-realtime-2026-02-28: zh: Chinese en: English ja: Japanese fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28: zh: Chinese
`nls_config.speech_noise_threshold`	`float`	Tidak	Ambang batas untuk membedakan ucapan dari kebisingan, digunakan untuk menyesuaikan sensitivitas Deteksi Aktivitas Suara (VAD). Nilai yang valid: [-1.0, 1.0]. Deskripsi nilai: Semakin dekat nilainya ke -1: Ambang batas kebisingan menurun, sehingga kebisingan lebih mungkin dikenali sebagai ucapan, yang dapat menyebabkan lebih banyak kebisingan ditranskripsikan. Semakin dekat nilainya ke +1: Ambang batas kebisingan meningkat, sehingga ucapan lebih mungkin salah dinilai sebagai kebisingan, yang dapat menyebabkan sebagian ucapan terfilter keluar. Ini adalah parameter konfigurasi tingkat lanjut. Menyesuaikannya dapat memengaruhi hasil pengenalan secara signifikan. Rekomendasi: Uji dan verifikasi hasil secara menyeluruh sebelum menyesuaikan. Sesuaikan dalam kenaikan kecil berdasarkan lingkungan audio aktual (langkah sebesar 0.1 direkomendasikan).
`nls_config.special_word_filter`	`object`	Tidak	Menentukan kata sensitif yang akan diproses selama pengenalan ucapan, dan mendukung pengaturan metode pemrosesan yang berbeda untuk kata sensitif yang berbeda. Untuk detailnya, lihat Penyaringan kata sensitif.
`nls_config.enable_connection_fast_check`	`BOOL`	Tidak	Mengaktifkan pemeriksaan jaringan cepat untuk melaporkan koneksi terputus sesegera mungkin. Default: `NO`.

API utama

NeoNui

nui_initialize

Menginisialisasi instance SDK pengenalan ucapan. SDK bersifat singleton. Jangan menginisialisasinya lagi sebelum memanggil nui_release.

Method signature

-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`parameters`	`char*`	String JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Parameter koneksi dan kontrol.
`level`	`NuiSdkLogLevel`	Tingkat cetak untuk log SDK itu sendiri.
`save_log`	`BOOL`	Apakah akan menyimpan log secara lokal. Jika diatur ke `YES`, tentukan jalur dengan `debug_path` di parameter koneksi dan kontrol, dan secara opsional atur ukuran file dengan `max_log_file_size`.

nui_set_params

Menetapkan parameter kualitas pengenalan dalam format JSON. Panggil sebelum nui_dialog_start.

Method signature

-(NuiResultCode) nui_set_params:(const char *)params;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`params`	`char*`	Parameter kualitas pengenalan.

nui_dialog_start

Memulai pengenalan.

Method signature

-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;

Deskripsi parameter

Parameter Tipe Deskripsi

Parameter	Tipe	Deskripsi
`vad_mode`	`NuiVadMode`	Mode VAD. Tetap pada `MODE_P2T`.
`dialog_params`	`char*`	Jika `apikey` pada parameter koneksi dan kontrol menggunakan API key sementara, perbarui di sini saat kedaluwarsa. Anda juga dapat memberikan konteks untuk meningkatkan akurasi melalui pengayaan konteks. Konten menggunakan format JSON: `{ "apikey": "st-****", "input_context": [ { "role": "user", "content": [ { "text": "xxxxx", "type": "input_text" } ] } ] }`

vad_mode

NuiVadMode

Mode VAD. Tetap pada MODE_P2T.

dialog_params

char*

Jika apikey pada parameter koneksi dan kontrol menggunakan API key sementara, perbarui di sini saat kedaluwarsa. Anda juga dapat memberikan konteks untuk meningkatkan akurasi melalui pengayaan konteks.

Konten menggunakan format JSON:

{
  "apikey": "st-****",
  "input_context": [
    {
      "role": "user",
      "content": [
        {
          "text": "xxxxx",
          "type": "input_text"
        }
      ]
    }
  ]
}

nui_dialog_cancel

Mengakhiri pengenalan atau langsung membatalkan interaksi saat ini.

Method signature

-(NuiResultCode) nui_dialog_cancel:(BOOL)force;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`force`	`BOOL`	Menentukan apakah penghentian dipaksa dan hasil akhir dibuang. `YES`: akhiri segera tanpa menunggu hasil akhir dari server. `NO`: akhiri tugas, tetapi tunggu hasil lengkap.

nui_dialog_action

Mengirimkan tindakan runtime untuk memberi tahu AEC pada perangkat tentang status pemutaran.

Method signature

-(NuiResultCode) nui_dialog_action:(const char *)action_params;

Deskripsi parameter

Parameter Tipe Deskripsi

Parameter	Tipe	Deskripsi
`action_params`	`char*`	String JSON yang berisi tindakan runtime.
`action_params.type`	`String`	Tetapkan ke `"action"`.
`action_params.command`	`String`	`play_start`: Saat AEC pada perangkat digunakan, memberi tahu SDK bahwa pemutar telah mulai memutar audio. `play_over`: Saat AEC pada perangkat digunakan, memberi tahu SDK bahwa pemutar telah selesai memutar audio.

action_params

char*

String JSON yang berisi tindakan runtime.

action_params.type String Tetapkan ke "action".

action_params.command

String

play_start: Saat AEC pada perangkat digunakan, memberi tahu SDK bahwa pemutar telah mulai memutar audio.

play_over: Saat AEC pada perangkat digunakan, memberi tahu SDK bahwa pemutar telah selesai memutar audio.

nui_update_audio_data

Jika audio_update_manually bernilai "true", data rekaman tidak lagi dipasok melalui onNuiNeedAudioData. Gunakan metode ini untuk mengirimkannya secara aktif.

Method signature

-(NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`data`	`const char *`	Data audio yang akan di-push.
`length`	`int`	Panjang data audio, dalam byte.
`first_pack`	`BOOL`	Anda tidak perlu menggunakan parameter ini.

nui_push_reference_data

Jika audio_update_manually bernilai "true" dan AEC pada perangkat diaktifkan, gunakan metode ini untuk mengirim audio yang diputar sebagai sinyal referensi.

Method signature

-(NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`data`	`const char *`	Data audio yang akan di-push.
`length`	`int`	Panjang data audio, dalam byte.
`first_pack`	`BOOL`	Anda tidak perlu menggunakan parameter ini.

nui_release

Melepaskan seluruh sumber daya internal SDK dan menghentikan paksa semua tugas berjalan. Instance tidak dapat digunakan setelah pemanggilan ini. Untuk menggunakannya kembali, inisialisasi ulang dengan nui_initialize.

Method signature

-(NuiResultCode) nui_release;

nui_get_version

Mendapatkan versi SDK saat ini. Metode ini mengembalikan nilai hanya setelah nui_initialize dipanggil.

Method signature

-(const char*) nui_get_version;

Return value

Versi SDK saat ini.

nui_get_all_response

Mendapatkan informasi lengkap callback peristiwa saat ini.

Method signature

-(const char*) nui_get_all_response;

Return value

Informasi lengkap peristiwa dalam bentuk string JSON.

NeoNuiSdkDelegate: listener callback

onNuiEventCallback: menerima peristiwa dan hasil pengenalan ucapan

Method signature

-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`nuiEvent`	`NuiCallbackEvent`	Event callback.
`dialog`	`long`	ID Sesi. Anda tidak perlu menggunakan parameter ini.
`wuw`	`char*`	Voice wake-up. Anda tidak perlu menggunakan parameter ini.
`asr_result`	`char*`	Hasil pengenalan ucapan.
`finish`	`BOOL`	Apakah putaran pengenalan saat ini telah selesai.
`code`	`int`	Hanya valid saat event `EVENT_ASR_ERROR` terjadi.

onNuiAudioStateChanged: memantau status audio

SDK menggunakan callback ini untuk memberi tahu kapan perekaman dimulai atau dihentikan.

Method signature

-(void) onNuiAudioStateChanged:(NuiAudioState)state;

NuiAudioState states

Parameter	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 untuk pengenalan

Setelah pengenalan dimulai, callback ini dipicu terus-menerus. Pasok data audio yang akan dikenali di dalamnya.

Method signature

-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`audioData`	`char*`	Data audio yang akan diberikan.
`len`	`int`	Ukuran data audio yang diberikan, dalam byte.

onNuiAssistEventCallback: menerima data dan informasi tambahan

Menerima peristiwa tambahan dan data terkait dari SDK.

Method signature

-(void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;

Deskripsi parameter

Parameter	Tipe	Deskripsi
`nuiEvent`	`NuiCallbackEvent`	Event callback.
`info`	`char*`	Anda tidak perlu menggunakan parameter ini.
`info_len`	`int`	Anda tidak perlu menggunakan parameter ini.
`buffer`	`char*`	Data tambahan, seperti audio setelah pemrosesan AEC.
`len`	`int`	Panjang data tambahan, dalam byte.

onNuiLogTrackCallback: menerima log pelacakan

Callback ini menerima log internal SDK yang terperinci untuk membantu pelacakan dan debug masalah.

-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent: jenis peristiwa

Peristiwa	Deskripsi
`EVENT_TRANSCRIBER_STARTED`	Tugas berhasil dimulai.
`EVENT_VAD_START`	Dipicu segera setelah tugas dimulai. Ini tidak berarti awal ucapan telah terdeteksi.
`EVENT_VAD_END`	Akhir ucapan terdeteksi.
`EVENT_ASR_PARTIAL_RESULT`	Hasil pengenalan ucapan sementara.
EVENT_ASR_ERROR	Terjadi error selama pengenalan ucapan.
`EVENT_MIC_ERROR`	Dipicu karena tidak ada data audio yang diterima selama 2 detik berturut-turut.
`EVENT_SENTENCE_END`	Akhir kalimat terdeteksi. Hasil pengenalan lengkap untuk kalimat tersebut dikembalikan.
`EVENT_TRANSCRIBER_COMPLETE`	Pengenalan ucapan selesai.
`EVENT_AEC_DATA`	Data audio setelah pemrosesan pembatalan gema akustik (AEC).