Gunakan SDK HarmonyOS pengenalan ucapan waktu nyata Paraformer untuk mengubah ucapan menjadi teks.
Ganti
Buka proyek di DevEco Studio. Kode sampel terletak di
Berikan string JSON ke parameter
Konfigurasikan dengan memberikan string JSON ke parameter
Menginisialisasi instance SDK pengenalan ucapan. Inisialisasi berulang dilarang sebelum Anda memanggil release.
Antarmuka ini memblokir thread pemanggil, jadi panggil dari thread non-UI.
Menetapkan parameter performa pengenalan ucapan dalam format JSON. Panggil sebelum startDialog.
Memulai pengenalan.
Mengakhiri pengenalan. Setelah antarmuka ini dipanggil, server mengembalikan hasil pengenalan akhir dan mengakhiri tugas.
Segera mengakhiri pengenalan. Setelah antarmuka ini dipanggil, tugas berakhir seketika tanpa menunggu server mengembalikan hasil pengenalan akhir.
Melepaskan semua sumber daya internal SDK. Setelah metode ini dipanggil, instance SDK menjadi tidak tersedia. Untuk menggunakannya kembali, panggil initialize untuk menginisialisasinya ulang.
Mendapatkan informasi versi SDK saat ini.
Mendengarkan peristiwa, status audio, perubahan volume, dan log selama pengenalan ucapan waktu nyata.
Mendengarkan peristiwa pengenalan dan memperoleh hasil pengenalan ucapan.
Dengarkan perubahan status audio untuk menentukan kapan harus memulai, menjeda, atau menghentikan perekaman.
Dengarkan perubahan volume perekaman, yang dapat ditampilkan di UI.
Setelah pengenalan dimulai, callback ini dipicu terus-menerus untuk terus menyediakan data audio yang akan dikenali.
Dengarkan log jejak SDK untuk pemecahan masalah dan debugging.
Di HarmonyOS SDK, tipe event didefinisikan oleh enumerasi
Enumerasi nilai untuk parameter
Berbeda dengan Android yang menggunakan
Untuk menggunakan fitur perekaman, nyatakan izin mikrofon di
{WorkspaceId} dengan ID Workspace aktual Anda. Domain yang ada tetap tersedia.
Panduan pengguna: Untuk pengenalan model dan saran pemilihan, lihat Pengenalan ucapan waktu nyata - Fun-ASR/Paraformer.
Prasyarat
- Dapatkan dan konfigurasikan kunci API. Jangan menanamkan kunci API jangka panjang langsung dalam kode aplikasi seluler. Kami menyarankan server aplikasi Anda membuat kunci API sementara lalu mendistribusikannya ke klien.
Instal SDK
- Unduh paket integrasi SDK terbaru.
- Ekstrak paket TAR. Dapatkan SDK dalam format HAR dari direktori
neonuidan tambahkan ke dependensi proyek Anda. Untuk integrasi C++, gunakannative/libsdannative/includedalam paket TAR untuk mendapatkan pustaka dinamis dan file header.
Mulai cepat
Buka proyek di DevEco Studio. Kode sampel terletak di DashParaformerSpeechTranscriberPage.ets. Ganti kunci API untuk mencoba fitur ini.
Langkah pemanggilan
- Inisialisasi SDK.
- Atur parameter sesuai kebutuhan: gunakan parameter
parametersdari antarmuka initialize untuk mengonfigurasi parameter koneksi dan kontrol, dan gunakan antarmuka setParams untuk mengonfigurasi parameter efek pengenalan ucapan. - Panggil startDialog untuk memulai pengenalan.
- Dalam callback onNuiAudioStateChanged, mulailah perangkat perekaman berdasarkan status audio.
- Dalam callback onNuiNeedAudioData, sediakan data audio rekaman secara terus-menerus.
- Dalam callback onNuiEventCallback, dengarkan peristiwa dan peroleh hasil pengenalan ucapan.
- Panggil stopDialog untuk menghentikan pengenalan, dan dengarkan peristiwa
EVENT_TRANSCRIBER_COMPLETEuntuk mengonfirmasi bahwa pengenalan telah berakhir. - Ketika pengenalan ucapan tidak lagi diperlukan, panggil release untuk melepaskan sumber daya SDK.
Parameter permintaan
Parameter koneksi dan kontrol
Berikan string JSON ke parameter parameters dari antarmuka initialize untuk konfigurasi.
Contoh parameter: Berikut adalah contoh string JSON. Tidak semua parameter tercantum. Tambahkan sesuai kebutuhan selama pengembangan:
- Deskripsi parameter
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
url | string | Ya | Alamat layanan, tetap wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Saat memanggil, ganti {WorkspaceId} dengan ID Workspace aktual Anda. |
apikey | string | Ya | Kunci API. Kami menyarankan menggunakan kunci API sementara yang berumur pendek dan lebih aman untuk mengurangi risiko kebocoran kunci jangka panjang. |
service_mode | string | Ya | Mode operasi. Untuk pengenalan ucapan waktu nyata, ini ditetapkan tetap pada "1". |
device_id | string | Ya | String unik yang mengidentifikasi pengguna akhir. Anda dapat mengaturnya ke ID pengguna dalam aplikasi atau pengenal perangkat unik yang dihasilkan oleh klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah. |
debug_path | string | Tidak | Jalur penyimpanan untuk file log. Parameter ini hanya berlaku jika Anda menetapkan save_log ke true saat memanggil initialize. Dalam hal ini, Anda harus menentukan jalur file log. Jika tidak, kesalahan akan terjadi. Maksimum dua file log dipertahankan secara lokal. |
save_wav | string | Tidak | Menentukan apakah akan menyimpan file audio untuk debugging. File audio disimpan di bawah debug_path. Nilai default: "false". Nilai yang valid: - "true": Ya - "false": Tidak Parameter ini hanya berlaku jika Anda menetapkan save_log ke true saat memanggil antarmuka initialize. Dalam hal ini, debug_path juga harus ditetapkan. |
max_log_file_size | number | Tidak | Jumlah byte maksimum file log. Parameter ini hanya berlaku jika Anda menetapkan save_log ke true saat memanggil antarmuka initialize. Nilai default: 104857600 (100 * 1024 * 1024 byte, yaitu 100MiB). |
log_track_level | number | Tidak | Tingkat filter untuk konten log yang dikirim secara eksternal melalui callback log (onNuiLogTrackCallback). Nilai default: 2. Rentang 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 (menunjukkan fitur ini dinonaktifkan) Catatan: log_track_level dan level (ditetapkan melalui antarmuka initialize) bersama-sama menentukan log yang akhirnya dipanggil kembali. Nilai tingkat sebuah log harus lebih besar dari atau sama dengan log_track_level maupun level agar dipanggil kembali. Misalnya, jika log_track_level adalah 2 (INFO) dan level adalah 3 (WARNING), hanya log pada tingkat WARNING dan di atasnya (nilai >=3) yang akan dipanggil kembali. |
Parameter performa pengenalan ucapan
Konfigurasikan dengan memberikan string JSON ke parameter params dari antarmuka setParams.
Contoh parameter: Berikut adalah contoh string JSON, dengan parameter tidak tercantum seluruhnya. Tambahkan sesuai kebutuhan selama coding:
- Deskripsi parameter
| Parameter tingkat pertama | Tipe | Wajib | Deskripsi |
|---|---|---|---|
service_type | int | Ya | Jenis layanan ucapan. Untuk pengenalan ucapan waktu nyata, ini ditetapkan tetap pada 4. |
nls_config | object | Ya | Objek konfigurasi pengenalan ucapan inti, yang berisi parameter kunci seperti pemilihan model dan kontrol performa pengenalan. |
nls_config.model | string | Ya | Model pengenalan ucapan. |
nls_config.sr_format | string | Ya | Format audio yang akan dikenali. Format audio yang didukung: pcm, wav, opus. |
nls_config.sample_rate | int | Ya | Laju sampel audio yang akan dikenali (dalam Hz). Bervariasi menurut model: - paraformer-realtime-v2 mendukung laju sampel apa pun. - paraformer-realtime-8k-v2 hanya mendukung laju sampel 8000 Hz. |
nls_config.disfluency_removal_enabled | boolean | Tidak | Menentukan apakah akan memfilter kata pengisi seperti "um" dan "ah". Nilai default: false. |
nls_config.language_hints | array[string] | Tidak | Kode bahasa audio yang akan dikenali. Jika bahasa tidak dapat ditentukan sebelumnya, Anda dapat membiarkannya tidak ditetapkan, dan model akan mendeteksi bahasa secara otomatis. Kode bahasa yang didukung: - zh: Tionghoa - en: Inggris - ja: Jepang - yue: Kanton - ko: Korea - de: Jerman - fr: Prancis - ru: Rusia Parameter ini hanya berlaku pada model yang mendukung banyak bahasa |
nls_config.semantic_punctuation_enabled | boolean | Tidak | Menentukan mode segmentasi kalimat. Nilai default: false. Nilai yang valid: - true: Mengaktifkan segmentasi semantik dan menonaktifkan segmentasi VAD. - false: Mengaktifkan segmentasi VAD dan menonaktifkan segmentasi semantik. Segmentasi semantik lebih akurat dan cocok untuk transkripsi rapat. Segmentasi VAD (Voice Activity Detection) memiliki latensi lebih rendah dan cocok untuk interaksi waktu nyata. Parameter ini hanya berlaku untuk model v2 dan yang lebih baru. |
nls_config.max_sentence_silence | int | Tidak | Ambang batas keheningan untuk segmentasi kalimat VAD (Voice Activity Detection), dalam milidetik. Nilai default: 800. Rentang yang valid: [200, 6000]. Ketika keheningan setelah sebuah segmen melebihi ambang batas ini, sistem menentukan bahwa kalimat telah berakhir. Parameter ini hanya berlaku ketika semantic_punctuation_enabled bernilai false dan modelnya adalah v2 atau lebih baru. |
nls_config.multi_threshold_mode_enabled | boolean | Tidak | Menentukan apakah akan mengaktifkan mode pencegahan segmen terlalu panjang. Mode ini mencegah segmen VAD menjadi terlalu panjang. Nilai default: false (dinonaktifkan). Nilai yang valid: - true: mengaktifkan mode - false: menonaktifkan mode. Parameter ini hanya berlaku ketika semantic_punctuation_enabled bernilai false dan modelnya adalah v2 atau lebih baru. |
nls_config.punctuation_prediction_enabled | boolean | Tidak | Menentukan apakah akan menambahkan tanda baca secara otomatis ke hasil pengenalan. Nilai default: true (Ya). Nilai yang valid: - true: Ya - false: Tidak Parameter ini hanya berlaku untuk model v2 dan yang lebih baru. |
nls_config.heartbeat | boolean | Tidak | Menentukan apakah akan mempertahankan koneksi persisten ke server. Nilai default: false. Nilai yang valid: - true: Koneksi tetap aktif sementara audio hening dikirimkan secara terus-menerus. - false: Meskipun audio hening dikirimkan secara terus-menerus, koneksi akan habis waktunya setelah periode tertentu. Waktu habis adalah default sisi server dan tidak dapat dikonfigurasi pada klien. Parameter ini hanya berlaku untuk model v2 dan yang lebih baru. |
nls_config.inverse_text_normalization_enabled | boolean | Tidak | Menentukan apakah akan mengaktifkan normalisasi teks invers (ITN). Saat diaktifkan, angka Tiongkok dikonversi menjadi angka Arab. Nilai default: true (diaktifkan). Nilai yang valid: - true: diaktifkan - false: dinonaktifkan. Parameter ini hanya berlaku untuk model v2 dan yang lebih baru. |
nls_config.vocabulary_id | string | Tidak | ID kosakata kata panas, digunakan untuk meningkatkan akurasi pengenalan kata-kata tertentu. Parameter ini berlaku untuk model v2 dan yang lebih baru. Untuk cara menggunakan kata panas, lihat Kustomisasi Kata Panas. |
Referensi API
NativeNui
initialize
Menginisialisasi instance SDK pengenalan ucapan. Inisialisasi berulang dilarang sebelum Anda memanggil release.
Antarmuka ini memblokir thread pemanggil, jadi panggil dari thread non-UI.
- Tanda tangan metode
- Deskripsi parameter
| Parameter | Tipe | Deskripsi |
|---|---|---|
callback | INativeNuiCallback | Implementasi antarmuka callback peristiwa dan data. |
parameters | string | String JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Parameter koneksi dan kontrol. |
level | number | Mengontrol tingkat pencetakan log SDK itu sendiri. Nilainya adalah enumerasi Constants.LogLevel. |
save_log | boolean | Menentukan apakah akan menyimpan log lokal. Jika nilainya true, Anda harus menentukan jalur melalui debug_path dalam Parameter koneksi dan kontrol, dan Anda dapat mengatur ukuran file melalui max_log_file_size. |
- Nilai kembalian
setParams
Menetapkan parameter performa pengenalan ucapan dalam format JSON. Panggil sebelum startDialog.
- Tanda tangan metode
- Deskripsi parameter
| Parameter | Tipe | Deskripsi |
|---|---|---|
params | string | Parameter performa pengenalan ucapan. |
- Nilai kembalian
startDialog
Memulai pengenalan.
- Tanda tangan metode
- Deskripsi parameter
| Parameter | Tipe | Deskripsi |
|---|---|---|
vad_mode | Constants.VadMode | Mode VAD. Ini ditetapkan tetap pada Constants.VadMode.TYPE_P2T. |
dialog_params | string | Saat kunci API sementara yang berkaitan dengan parameter apikey dari parameter koneksi dan kontrol kedaluwarsa, Anda dapat memperbaruinya di sini. Kontennya dalam format JSON: typescript { "apikey": "st-****" } |
- Nilai kembalian
stopDialog
Mengakhiri pengenalan. Setelah antarmuka ini dipanggil, server mengembalikan hasil pengenalan akhir dan mengakhiri tugas.
- Tanda tangan metode
- Nilai kembalian
cancelDialog
Segera mengakhiri pengenalan. Setelah antarmuka ini dipanggil, tugas berakhir seketika tanpa menunggu server mengembalikan hasil pengenalan akhir.
- Tanda tangan metode
- Nilai kembalian
release
Melepaskan semua sumber daya internal SDK. Setelah metode ini dipanggil, instance SDK menjadi tidak tersedia. Untuk menggunakannya kembali, panggil initialize untuk menginisialisasinya ulang.
- Tanda tangan metode
- Nilai kembalian
GetVersion
Mendapatkan informasi versi SDK saat ini.
- Tanda tangan metode
- Nilai kembalian
INativeNuiCallback
Mendengarkan peristiwa, status audio, perubahan volume, dan log selama pengenalan ucapan waktu nyata.
onNuiEventCallback
Mendengarkan peristiwa pengenalan dan memperoleh hasil pengenalan ucapan.
- Tanda tangan metode
- Deskripsi parameter
| Parameter | Tipe | Deskripsi |
|---|---|---|
event | Constants.NuiEvent | Peristiwa callback. |
resultCode | number | Hanya valid saat event EVENT_ASR_ERROR terjadi. |
asrResult | AsrResult | Hasil pengenalan ucapan. |
kwsResult | KwsResult | Fitur bangun suara. Anda tidak perlu menggunakan parameter ini. |
arg2 | number | Parameter yang dipesan. |
onNuiAudioStateChanged
Dengarkan perubahan status audio untuk menentukan kapan harus memulai, menjeda, atau menghentikan perekaman.
- Tanda tangan metode
- Deskripsi status AudioState
| Status | Deskripsi |
|---|---|
STATE_OPEN | Interaksi dimulai. Anda dapat membuka perangkat perekaman untuk mulai merekam. |
STATE_PAUSE | Interaksi dijeda. Anda dapat menjeda perekaman. |
STATE_CLOSE | Interaksi dihentikan. Anda dapat menutup perangkat perekaman sepenuhnya. |
onNuiAudioRMSChanged
Dengarkan perubahan volume perekaman, yang dapat ditampilkan di UI.
- Tanda tangan metode
- Deskripsi parameter
| Parameter | Tipe | Deskripsi |
|---|---|---|
val | number | Volume data audio yang direkam. Rentang keluaran umumnya adalah [-160, 0]. |
onNuiNeedAudioData
Setelah pengenalan dimulai, callback ini dipicu terus-menerus untuk terus menyediakan data audio yang akan dikenali.
- Tanda tangan metode
- Deskripsi parameter
| Parameter | Tipe | Deskripsi |
|---|---|---|
buffer | ArrayBuffer | Data audio yang akan diisi. SDK memperoleh jumlah byte yang diharapkan untuk dibaca berdasarkan buffer.byteLength. |
- Nilai kembalian
<=0 menunjukkan kesalahan atau tidak ada data.
onNuiLogTrackCallback
Dengarkan log jejak SDK untuk pemecahan masalah dan debugging.
Constants.NuiEvent
Di HarmonyOS SDK, tipe event didefinisikan oleh enumerasi Constants.NuiEvent. Berikut mencantumkan event yang berkaitan dengan pengenalan ucapan waktu nyata:
| Peristiwa | Deskripsi |
|---|---|
EVENT_TRANSCRIBER_STARTED | Tugas berhasil dimulai. |
EVENT_VAD_START | Event ini dipicu segera setelah tugas dimulai. Hal ini tidak menandakan bahwa awal ucapan telah terdeteksi. |
EVENT_VAD_END | Akhir suara manusia terdeteksi. |
EVENT_ASR_PARTIAL_RESULT | Hasil pengenalan ucapan sementara. |
EVENT_ASR_RESULT | Hasil pengenalan ucapan lengkap. |
EVENT_ASR_ERROR | Terjadi kesalahan selama pengenalan ucapan. |
EVENT_MIC_ERROR | Peristiwa ini dipicu ketika tidak ada data audio yang diterima selama 2 detik berturut-turut. |
EVENT_SENTENCE_START | Awal kalimat terdeteksi. |
EVENT_SENTENCE_END | Akhir kalimat terdeteksi; hasil pengenalan lengkap dikembalikan pada titik ini. |
EVENT_TRANSCRIBER_COMPLETE | Pengenalan ucapan berakhir. |
Tipe tambahan
Constants.LogLevel
Enumerasi nilai untuk parameter level:
| Nilai | Deskripsi |
|---|---|
LOG_LEVEL_VERBOSE | Log paling terperinci. |
LOG_LEVEL_DEBUG | Log debug. |
LOG_LEVEL_INFO | Log informasional (default). |
LOG_LEVEL_WARNING | Log peringatan. |
LOG_LEVEL_ERROR | Log kesalahan. |
LOG_LEVEL_NONE | Menonaktifkan pencatatan log. |
Manajemen perangkat audio
Berbeda dengan Android yang menggunakan AudioRecord, HarmonyOS menangkap audio melalui AudioCapturer dari @kit.AudioKit. Sampel untuk produk ini telah membungkusnya ke dalam kelas utilitas AudioRecorder.ets, yang dapat digunakan kembali secara langsung.
- Pembuatan:
audio.createAudioCapturer(capturerOptions)membuat capturer secara asinkron dengan laju sampel tetap sebesar 16 kHz, kedalaman bit 16, dan satu saluran (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW). - Event data:
capturer.on('readData', (buffer: ArrayBuffer) => void)menerima data rekaman secara terus-menerus; data harus terlebih dahulu dibuffer ke dalam antrean dan ditarik sesuai kebutuhan oleh callbackonNuiNeedAudioData. - Event status:
capturer.on('stateChange', (state: audio.AudioState) => void).STATE_RUNNINGmenandakan bahwa perekaman telah dimulai, danSTATE_STOPPEDmenandakan bahwa perekaman telah berhenti. - Kontrol:
start()memulai,stop()menghentikan, danrelease()melepaskan penangkap.
AudioCapturer di HarmonyOS dibuat secara asinkron, dan start() hanya dapat dipanggil setelah pembuatan selesai. Oleh karena itu, jangan membuat dan langsung memulai perekam saat STATE_OPEN — selesaikan pembuatan terlebih dahulu, lalu panggil start() dalam callback STATE_OPEN (sampel membuatnya selama tahap doInit dan memulainya selama tahap onNuiAudioStateChanged). Saat STATE_CLOSE, cukup hentikan perekam dan pertahankan instance untuk digunakan kembali; instance tersebut dilepaskan secara seragam oleh release.Deklarasi izin
Untuk menggunakan fitur perekaman, nyatakan izin mikrofon di module.json5: