Skip to main content

Paraformer HarmonyOS SDK

Gunakan SDK HarmonyOS pengenalan ucapan waktu nyata Paraformer untuk mengubah ucapan menjadi teks.

Alibaba Cloud Model Studio menyediakan domain workspace khusus untuk wilayah Tiongkok Utara 2 (Beijing), yang meningkatkan kinerja dan stabilitas permintaan inferensi. Kami menyarankan untuk bermigrasi dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
Ganti {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

  1. 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 neonui dan tambahkan ke dependensi proyek Anda. Untuk integrasi C++, gunakan native/libs dan native/include dalam 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

  1. Inisialisasi SDK.
  2. Atur parameter sesuai kebutuhan: gunakan parameter parameters dari antarmuka initialize untuk mengonfigurasi parameter koneksi dan kontrol, dan gunakan antarmuka setParams untuk mengonfigurasi parameter efek pengenalan ucapan.
  3. Panggil startDialog untuk memulai pengenalan.
  4. Dalam callback onNuiAudioStateChanged, mulailah perangkat perekaman berdasarkan status audio.
  5. Dalam callback onNuiNeedAudioData, sediakan data audio rekaman secara terus-menerus.
  6. Dalam callback onNuiEventCallback, dengarkan peristiwa dan peroleh hasil pengenalan ucapan.
  7. Panggil stopDialog untuk menghentikan pengenalan, dan dengarkan peristiwa EVENT_TRANSCRIBER_COMPLETE untuk mengonfirmasi bahwa pengenalan telah berakhir.
  8. 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:
{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
  • Deskripsi parameter
ParameterTipeWajibDeskripsi
urlstringYaAlamat layanan, tetap wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Saat memanggil, ganti {WorkspaceId} dengan ID Workspace aktual Anda.
apikeystringYaKunci API. Kami menyarankan menggunakan kunci API sementara yang berumur pendek dan lebih aman untuk mengurangi risiko kebocoran kunci jangka panjang.
service_modestringYaMode operasi. Untuk pengenalan ucapan waktu nyata, ini ditetapkan tetap pada "1".
device_idstringYaString 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_pathstringTidakJalur 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_wavstringTidakMenentukan 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_sizenumberTidakJumlah 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_levelnumberTidakTingkat 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:
{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}
  • Deskripsi parameter
Parameter tingkat pertamaTipeWajibDeskripsi
service_typeintYaJenis layanan ucapan. Untuk pengenalan ucapan waktu nyata, ini ditetapkan tetap pada 4.
nls_configobjectYaObjek konfigurasi pengenalan ucapan inti, yang berisi parameter kunci seperti pemilihan model dan kontrol performa pengenalan.
nls_config.modelstringYaModel pengenalan ucapan.
nls_config.sr_formatstringYa

Format audio yang akan dikenali. Format audio yang didukung: pcm, wav, opus.

  • opus: harus dikodekan PCM; SDK akan mengodekannya menjadi format OPUS secara internal;
  • wav/pcm: harus dikodekan PCM.
nls_config.sample_rateintYaLaju 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_enabledbooleanTidakMenentukan apakah akan memfilter kata pengisi seperti "um" dan "ah". Nilai default: false.
nls_config.language_hintsarray[string]TidakKode 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_enabledbooleanTidakMenentukan 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_silenceintTidakAmbang 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_enabledbooleanTidakMenentukan 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_enabledbooleanTidakMenentukan 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.heartbeatbooleanTidakMenentukan 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_enabledbooleanTidakMenentukan 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_idstringTidakID 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
public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number
  • Deskripsi parameter
ParameterTipeDeskripsi
callbackINativeNuiCallbackImplementasi antarmuka callback peristiwa dan data.
parametersstringString JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Parameter koneksi dan kontrol.
levelnumberMengontrol tingkat pencetakan log SDK itu sendiri. Nilainya adalah enumerasi Constants.LogLevel.
save_logbooleanMenentukan 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
public setParams(params: string): number
  • Deskripsi parameter
ParameterTipeDeskripsi
paramsstringParameter performa pengenalan ucapan.
  • Nilai kembalian

startDialog

Memulai pengenalan.
  • Tanda tangan metode
public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number
  • Deskripsi parameter
ParameterTipeDeskripsi
vad_modeConstants.VadModeMode VAD. Ini ditetapkan tetap pada Constants.VadMode.TYPE_P2T.
dialog_paramsstringSaat 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
public stopDialog(): number
  • Nilai kembalian

cancelDialog

Segera mengakhiri pengenalan. Setelah antarmuka ini dipanggil, tugas berakhir seketika tanpa menunggu server mengembalikan hasil pengenalan akhir.
  • Tanda tangan metode
public cancelDialog(): number
  • 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
public release(): number
  • Nilai kembalian

GetVersion

Mendapatkan informasi versi SDK saat ini.
  • Tanda tangan metode
public GetVersion(): string
  • Nilai kembalian
Informasi versi SDK saat ini.

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
onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;
  • Deskripsi parameter
ParameterTipeDeskripsi
eventConstants.NuiEventPeristiwa callback.
resultCodenumberHanya valid saat event EVENT_ASR_ERROR terjadi.
asrResultAsrResultHasil pengenalan ucapan.
kwsResultKwsResultFitur bangun suara. Anda tidak perlu menggunakan parameter ini.
arg2numberParameter yang dipesan.

onNuiAudioStateChanged

Dengarkan perubahan status audio untuk menentukan kapan harus memulai, menjeda, atau menghentikan perekaman.
  • Tanda tangan metode
onNuiAudioStateChanged: (state: Constants.AudioState) => void
  • Deskripsi status AudioState
StatusDeskripsi
STATE_OPENInteraksi dimulai. Anda dapat membuka perangkat perekaman untuk mulai merekam.
STATE_PAUSEInteraksi dijeda. Anda dapat menjeda perekaman.
STATE_CLOSEInteraksi dihentikan. Anda dapat menutup perangkat perekaman sepenuhnya.

onNuiAudioRMSChanged

Dengarkan perubahan volume perekaman, yang dapat ditampilkan di UI.
  • Tanda tangan metode
onNuiAudioRMSChanged: (val: number) => number
  • Deskripsi parameter
ParameterTipeDeskripsi
valnumberVolume 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
onNuiNeedAudioData: (buffer: ArrayBuffer) => number
  • Deskripsi parameter
ParameterTipeDeskripsi
bufferArrayBufferData audio yang akan diisi. SDK memperoleh jumlah byte yang diharapkan untuk dibaca berdasarkan buffer.byteLength.
  • Nilai kembalian
Jumlah byte aktual yang diisi. Nilai kembalian <=0 menunjukkan kesalahan atau tidak ada data.

onNuiLogTrackCallback

Dengarkan log jejak SDK untuk pemecahan masalah dan debugging.
onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

Constants.NuiEvent

Di HarmonyOS SDK, tipe event didefinisikan oleh enumerasi Constants.NuiEvent. Berikut mencantumkan event yang berkaitan dengan pengenalan ucapan waktu nyata:
PeristiwaDeskripsi
EVENT_TRANSCRIBER_STARTEDTugas berhasil dimulai.
EVENT_VAD_STARTEvent ini dipicu segera setelah tugas dimulai. Hal ini tidak menandakan bahwa awal ucapan telah terdeteksi.
EVENT_VAD_ENDAkhir suara manusia terdeteksi.
EVENT_ASR_PARTIAL_RESULTHasil pengenalan ucapan sementara.
EVENT_ASR_RESULTHasil pengenalan ucapan lengkap.
EVENT_ASR_ERRORTerjadi kesalahan selama pengenalan ucapan.
EVENT_MIC_ERRORPeristiwa ini dipicu ketika tidak ada data audio yang diterima selama 2 detik berturut-turut.
EVENT_SENTENCE_STARTAwal kalimat terdeteksi.
EVENT_SENTENCE_ENDAkhir kalimat terdeteksi; hasil pengenalan lengkap dikembalikan pada titik ini.
EVENT_TRANSCRIBER_COMPLETEPengenalan ucapan berakhir.

Tipe tambahan

Constants.LogLevel

Enumerasi nilai untuk parameter level:
NilaiDeskripsi
LOG_LEVEL_VERBOSELog paling terperinci.
LOG_LEVEL_DEBUGLog debug.
LOG_LEVEL_INFOLog informasional (default).
LOG_LEVEL_WARNINGLog peringatan.
LOG_LEVEL_ERRORLog kesalahan.
LOG_LEVEL_NONEMenonaktifkan 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 callback onNuiNeedAudioData.
  • Event status: capturer.on('stateChange', (state: audio.AudioState) => void). STATE_RUNNING menandakan bahwa perekaman telah dimulai, dan STATE_STOPPED menandakan bahwa perekaman telah berhenti.
  • Kontrol: start() memulai, stop() menghentikan, dan release() 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:
{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}