Alibaba Cloud Model Studio:SDK HarmonyOS sintesis ucapan Sambert

Panduan ini menjelaskan cara menggunakan SDK HarmonyOS sintesis ucapan Sambert untuk mengubah teks menjadi ucapan yang berkualitas tinggi dan ekspresif.

Panduan pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Sintesis ucapan - Sambert.

Pengalaman online****: Tidak didukung.

Ganti {WorkspaceId} dengan ID workspace aktual Anda. Domain yang ada tetap tersedia.

NativeNui

SDK ini didasarkan pada arsitektur NativeNui dan menggunakan callback untuk memproses event sintesis ucapan.

Karakteristik arsitektur****:

• Mode instans****: Buat instans sintesis ucapan dengan menggunakan new NativeNui(Constants.ModeType.MODE_TTS).
• Berbasis callback****: Terima event dan data melalui antarmuka NuiTtsSdkListener.
• Jenis event:
  • NuiSdkTtsEvent: Tugas sintesis dimulai.
  • onTtsDataCallback: Data audio dikembalikan.
  • NuiSdkTtsEvent: Tugas sintesis berakhir.
  • NuiSdkTtsEvent: Terjadi kesalahan sintesis.

Prosedur

1. tts_initialize - Inisialisasi SDK dan konfigurasikan antarmuka callback serta parameter koneksi.
2. setParamTts - Konfigurasikan parameter efek sintesis ucapan seperti model, suara, dan volume.
3. startTts - Mulai tugas sintesis ucapan.
4. onTtsDataCallback - Terima data audio.
5. tts_release - Lepaskan sumber daya SDK.

Metode Sambert

tts_initialize

Menginisialisasi instans SDK sintesis ucapan. Buat instans dengan menggunakan new NativeNui(Constants.ModeType.MODE_TTS). Setiap instans sesuai dengan satu saluran sintesis ucapan. Jangan menginisialisasi instans yang sama lagi sebelum Anda memanggil tts_release. Untuk memproses beberapa tugas secara bersamaan, buat beberapa instans.

Antarmuka ini memblokir thread pemanggil. Panggil dari thread non-UI.

Tanda tangan metode:

public tts_initialize(callback: NuiTtsSdkListener,
                      ticket: string,
                      level: number,
                      save_log: boolean): number

Deskripsi parameter:****

Parameter	Tipe	Deskripsi
callback	NuiTtsSdkListener	Implementasi antarmuka callback peristiwa dan data.
ticket	string	String JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat deskripsi parameter ticket di bawah ini.
level	number	Mengontrol level log SDK. Nilai yang valid didefinisikan oleh enumerasi Constants.LogLevel.
save_log	boolean	Menentukan apakah akan menyimpan log lokal. Jika parameter ini bernilai true, gunakan debug_path dalam parameter tiket untuk menentukan jalur. Anda juga dapat menggunakan max_log_file_size untuk mengatur ukuran file.

Contoh JSON ticket****:

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id",
    "mode_type": "2"
}

Deskripsi parameter ticket:****

Parameter	Tipe	Wajib	Deskripsi
url	string	Ya	Titik akhir. Nilai ini tetap wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
apikey	string	Ya	Kunci API. Kami menyarankan untuk menggunakan kunci API sementara yang lebih aman dengan masa berlaku singkat guna mengurangi risiko kebocoran kunci jangka panjang.
mode_type	string	Ya	Jenis mode. Nilai ini harus diatur ke string "2", yang menunjukkan mode sintesis ucapan online dan sesuai dengan Constants.TtsModeTypeCloud.
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 mengatur save_log ke true saat memanggil tts_initialize. Dalam hal ini, Anda harus menentukan jalur file log. Jika tidak, kesalahan akan terjadi. Maksimum dua file log dipertahankan secara lokal.
max_log_file_size	number	Tidak	Mengatur ukuran maksimum file log dalam byte. Parameter ini hanya berlaku jika Anda mengatur save_log ke true saat memanggil tts_initialize. Nilai default: 104857600 (100 * 1024 * 1024 byte, atau 100 MiB).

setParamTts

Mengatur parameter efek sintesis ucapan sebagai pasangan kunci-nilai. Panggil metode ini sebelum startTts.

Tanda tangan metode:

public setParamTts(param: string, value: string): number

Deskripsi parameter:****

Parameter	Tipe	Deskripsi
param	string	Nama parameter.
value	string	Nilai parameter.

Parameter yang tersedia****:

Parameter	Tipe	Wajib	Deskripsi
model	string	Ya	Nama model, seperti sambert-zhinan-v1.
format	string	Tidak	Format pengkodean audio. Nilai valid: - pcm - wav - mp3 (default).
volume	string	Tidak	Volume. Nilai default: 50. Rentang valid: [0, 100].
sample_rate	string	Tidak	Laju sampel audio dalam Hz. Nilai yang valid: 8000, 16000, 22050, 24000, dan 48000. Laju sampel default untuk sebagian besar model suara Sambert adalah 48000. Konfigurasikan pemutar untuk menggunakan laju sampel yang sesuai.
rate	string	Tidak	Kecepatan bicara. Nilai default: 1.0. Rentang valid: [0.5, 2.0].
pitch	string	Tidak	Nada. Nilai default: 1.0. Rentang valid: [0.5, 2.0].
word_timestamp_enabled	string	Tidak	Menentukan apakah akan mengaktifkan stempel waktu tingkat kata. Nilai default: false. Parameter ini berlaku untuk semua model Sambert.
phoneme_timestamp_enabled	string	Tidak	Menentukan apakah akan mengaktifkan stempel waktu tingkat fonem. Nilai default: false. Aktifkan word_timestamp_enabled terlebih dahulu.
enable_audio_decoder	string	Tidak	Menentukan apakah akan mengaktifkan dekoder audio bawaan. Nilai default: 0. Nilai yang valid: - 1: diaktifkan. Ketika format adalah mp3, atur parameter ini ke "1" untuk mengaktifkan dekoder SDK bawaan. onTtsDataCallback kemudian mengembalikan data PCM yang telah didekode. - 0: dinonaktifkan.
enable_callback_vol	string	Tidak	Menentukan apakah akan mengaktifkan callback volume. Atur ke "1" untuk mengaktifkan onTtsVolCallback.
apikey	string	Tidak	Memperbarui kunci API sementara selama runtime. Sebelum tugas sintesis dimulai, injeksikan kunci sementara terbaru dengan menggunakan setParamTts('apikey', ...).

getparamTts

Mendapatkan nilai parameter. Metode ini terutama digunakan untuk pemecahan masalah.

Tanda tangan metode:

public getparamTts(param: string): string

Deskripsi parameter:****

Parameter	Tipe	Deskripsi
param	string	Nama parameter. Saat ini, hanya "error_msg" yang didukung.

Nilai kembalian:

Nilai parameter.

startTts

Memulai tugas sintesis ucapan. Hasil sintesis dikembalikan melalui callback.

Tanda tangan metode:

public startTts(priority: string, taskid: string, text: string): number

Deskripsi parameter:****

Parameter	Tipe	Deskripsi
priority	string	Prioritas tugas. Atur parameter ini ke 1.
taskid	string	ID tugas. Jika string kosong '' diteruskan, SDK akan membuat ID secara otomatis.
text	string	Teks yang akan disintesis.

pauseTts

Menjeda tugas sintesis ucapan saat ini. Setelah tugas dijeda, panggil resumeTts untuk melanjutkannya atau cancelTts untuk membatalkannya. SDK tidak dapat memulai tugas sintesis baru saat tugas sedang dijeda.

Catatan: Operasi ini hanya menjeda pengambilan data dari server. Data audio yang sudah di-buffer di pemutar terus diputar.

Tanda tangan metode:

public pauseTts(): number

resumeTts

Melanjutkan tugas sintesis ucapan yang dijeda.

Tanda tangan metode:

public resumeTts(): number

cancelTts

Membatalkan tugas sintesis.

Catatan: Operasi ini hanya membatalkan pengambilan data dari server. Data audio yang sudah di-buffer di pemutar terus diputar.

Tanda tangan metode:

public cancelTts(taskid: string): number

Deskripsi parameter:****

Parameter	Tipe	Deskripsi
taskid	string	ID tugas yang akan dibatalkan. Jika string kosong '' diteruskan, semua tugas sintesis yang dijeda atau aktif akan dibatalkan.

tts_release

Melepaskan semua sumber daya internal SDK dan menghentikan secara paksa semua tugas sintesis yang aktif. Setelah metode ini dipanggil, instans SDK menjadi tidak tersedia. Untuk menggunakannya kembali, panggil tts_initialize untuk menginisialisasi ulang.

Tanda tangan metode:

public tts_release(): number

NuiTtsSdkListener

Antarmuka callback sintesis ucapan Sambert menerima peristiwa sintesis dan data audio. Dalam SDK HarmonyOS, callback didefinisikan sebagai fungsi panah ArkTS.

onTtsEventCallback

Mendengarkan event mulai, berakhir, pembatalan, jeda, lanjutan, dan kesalahan tugas sintesis ucapan.

Tanda tangan metode:

onTtsEventCallback: (event: NuiSdkTtsEvent, taskid: string, ret_code: number) => void;

Deskripsi parameter:****

Parameter	Tipe	Deskripsi
event	NuiSdkTtsEvent	Peristiwa callback.
taskid	string	ID tugas sintesis ucapan.
ret_code	number	Hanya valid saat event TTS_EVENT_ERROR terjadi.

onTtsDataCallback

Selama sintesis, SDK terus memicu callback ini. Dapatkan data audio dari callback.

Tanda tangan metode:

onTtsDataCallback: (info: string, info_len: number, buffer: ArrayBuffer | null) => void;

Deskripsi parameter:****

Parameter	Tipe	Deskripsi
info	string	Hasil stempel waktu berformat JSON. Parameter ini berlaku ketika word_timestamp_enabled diatur ke "1".
info_len	number	Panjang data dari field info. Anda dapat mengabaikan parameter ini.
buffer	ArrayBuffer | null	Data audio untuk segmen saat ini. Parameter ini mungkin null. Periksa apakah ada null dalam callback.

onTtsVolCallback

Setelah enable_callback_vol diaktifkan, callback ini mengembalikan volume data sintesis yang baru saja diterima oleh SDK. Ini bukan volume yang sedang diputar saat ini.

Tanda tangan metode:

onTtsVolCallback: (vol: number) => void;

Deskripsi parameter:****

Parameter	Tipe	Deskripsi
vol	number	Volume data sintesis.

NuiSdkTtsEvent

Enumerasi jenis event sintesis ucapan Sambert.

Peristiwa	Deskripsi
TTS_EVENT_START	Tugas sintesis dimulai. Data audio akan segera dikembalikan.
TTS_EVENT_END	Tugas sintesis berakhir secara normal. Semua data audio telah dikembalikan melalui callback.
TTS_EVENT_CANCEL	Tugas sintesis dibatalkan.
TTS_EVENT_PAUSE	Tugas sintesis dijeda.
TTS_EVENT_RESUME	Tugas sintesis dilanjutkan.
TTS_EVENT_ERROR	Terjadi kesalahan selama sintesis. Panggil getparamTts("error_msg") untuk mendapatkan detailnya. { "header": { "task_id": "xxxxxxxxx", "event": "task-failed", "error_code": "InvalidParameter", "error_message": "Please ensure input text is valid.", "attributes": {} }, "payload": {} }

Tipe tambahan

Constants.LogLevel

Nilai enumerasi untuk parameter level adalah sebagai berikut:

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.

Kode sampel

1. Dapatkan kunci API: Dapatkan dan konfigurasikan kunci API. Demi keamanan, kami menyarankan untuk mengonfigurasi kunci API sebagai variabel lingkungan.

   CatatanUntuk memberikan akses sementara ke aplikasi atau pengguna pihak ketiga, atau untuk mengontrol operasi berisiko tinggi secara ketat seperti mengakses atau menghapus data sensitif, gunakan kunci API sementara. Kunci API sementara berlaku selama 60 detik secara default. Dapatkan yang baru setelah kedaluwarsa.

2. Unduh SDK dan jalankan kode sampel:

   • Unduh paket SDK terbaru.
   • Ekstrak paket TAR. Dapatkan SDK format HAR dari direktori neonui dan tambahkan ke dependensi proyek Anda. Untuk integrasi C++, dapatkan pustaka dinamis dan file header dari native/libs dan native/include dalam paket TAR.
   • Buka proyek di DevEco Studio. Kode sampel terletak di DashSambertTtsPage.ets. Ganti kunci API untuk mencoba fitur ini.

Langkah pemanggilan

1. Inisialisasi SDK: Panggil tts_initialize dan teruskan callback NuiTtsSdkListener serta parameter ticket.
2. Konfigurasikan parameter berdasarkan kebutuhan bisnis Anda: Gunakan setParamTts untuk mengonfigurasi parameter efek sintesis ucapan seperti model, format, laju sampel, suara, dan volume. Kami menyarankan untuk mengonfigurasinya segera setelah inisialisasi berhasil.
3. Panggil startTts untuk memulai sintesis ucapan.
4. Dapatkan data audio dari callback onTtsDataCallback. Kami menyarankan pemutaran streaming seperti yang dijelaskan dalam Pemutaran Audio di bawah ini. Untuk menyimpan audio secara lokal, tambahkan data audio ke file yang sama hingga sintesis selesai.
5. Setelah tugas berakhir, panggil tts_release untuk melepaskan sumber daya SDK.

Pemutaran audio

HarmonyOS menggunakan AudioRenderer dari @kit.AudioKit untuk memutar audio yang disintesis. Laju sampel default audio yang disintesis Sambert adalah 48 kHz, jadi konfigurasikan laju sampel pemutar ke 48000.

Sampel produk mengenkapsulasi logika dalam kelas utilitas AudioPlayer.ets. Tentukan laju sampel di konstruktor:

// Play Sambert audio at the default sample rate of 48000. The default for AudioPlayer is 16000.
this.mAudioPlayer = new AudioPlayer(this, 48000);

Pemutar menggunakan callback writeData untuk mengambil data audio dari antrean dan mengembalikan AudioDataCallbackResult.VALID atau AudioDataCallbackResult.INVALID. Ketika onTtsEventCallback menerima TTS_EVENT_END, SDK telah menyelesaikan sintesis dan mengembalikan semua data melalui callback. Tandai antrean pemutaran sebagai selesai agar pemutar berhenti secara otomatis setelah memutar data yang tersisa.