Panduan pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Sintesis ucapan - Sambert.
Pengalaman online****: Tidak didukung.
Alibaba Cloud Model Studio telah memperkenalkan domain khusus workspace untuk wilayah Tiongkok (Beijing). Domain ini memberikan kinerja unggul dan stabilitas lebih tinggi untuk 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.
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:
Prosedur
- tts_initialize - Inisialisasi SDK dan konfigurasikan antarmuka callback serta parameter koneksi.
- setParamTts - Konfigurasikan parameter efek sintesis ucapan seperti model, suara, dan volume.
- startTts - Mulai tugas sintesis ucapan.
- onTtsDataCallback - Terima data audio.
- 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. |
Implementasi dasar dapat menggunakan ulang buffer. Untuk menyimpannya dalam cache, buat salinan terlebih dahulu, misalnya dengan menggunakan new Uint8Array(buffer.slice(0)).
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": {} } |
Peristiwa TTS_EVENT_END menunjukkan bahwa sintesis TTS telah selesai dan semua data audio telah dikembalikan melalui callback. Peristiwa ini tidak menunjukkan bahwa pemutar telah selesai memutar semua data audio.
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
-
Dapatkan kunci API: Dapatkan dan konfigurasikan kunci API. Demi keamanan, kami menyarankan untuk mengonfigurasi kunci API sebagai variabel lingkungan.
Untuk 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.
-
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
- Inisialisasi SDK: Panggil tts_initialize dan teruskan callback
NuiTtsSdkListener serta parameter ticket.
- 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.
- Panggil
startTts untuk memulai sintesis ucapan.
- 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.
- 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.
Pemutaran MP3****: AudioRenderer hanya mendukung pemutaran PCM. Ketika format diatur ke mp3, atur juga enable_audio_decoder ke "1". Dekoder SDK bawaan mendekode MP3 menjadi PCM dan mengembalikannya melalui onTtsDataCallback. mEncodeType hanya digunakan sebagai ekstensi nama file dari file audio yang dihasilkan dan tidak memengaruhi jenis data callback.