Skip to main content
Sambert

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.
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****:

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:****
ParameterTipeDeskripsi
callbackNuiTtsSdkListenerImplementasi antarmuka callback peristiwa dan data.
ticketstringString JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat deskripsi parameter ticket di bawah ini.
levelnumberMengontrol level log SDK. Nilai yang valid didefinisikan oleh enumerasi Constants.LogLevel.
save_logbooleanMenentukan 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:****
ParameterTipeWajibDeskripsi
urlstringYaTitik akhir. Nilai ini tetap wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
apikeystringYaKunci API. Kami menyarankan untuk menggunakan kunci API sementara yang lebih aman dengan masa berlaku singkat guna mengurangi risiko kebocoran kunci jangka panjang.
mode_typestringYaJenis mode. Nilai ini harus diatur ke string "2", yang menunjukkan mode sintesis ucapan online dan sesuai dengan Constants.TtsModeTypeCloud.
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 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_sizenumberTidakMengatur 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:****
ParameterTipeDeskripsi
paramstringNama parameter.
valuestringNilai parameter.
Parameter yang tersedia****:
ParameterTipeWajibDeskripsi
modelstringYaNama model, seperti sambert-zhinan-v1.
formatstringTidakFormat pengkodean audio. Nilai valid: - pcm - wav - mp3 (default).
volumestringTidakVolume. Nilai default: 50. Rentang valid: [0, 100].
sample_ratestringTidakLaju 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.
ratestringTidakKecepatan bicara. Nilai default: 1.0. Rentang valid: [0.5, 2.0].
pitchstringTidakNada. Nilai default: 1.0. Rentang valid: [0.5, 2.0].
word_timestamp_enabledstringTidakMenentukan apakah akan mengaktifkan stempel waktu tingkat kata. Nilai default: false. Parameter ini berlaku untuk semua model Sambert.
phoneme_timestamp_enabledstringTidakMenentukan apakah akan mengaktifkan stempel waktu tingkat fonem. Nilai default: false. Aktifkan word_timestamp_enabled terlebih dahulu.
enable_audio_decoderstringTidakMenentukan 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_volstringTidakMenentukan apakah akan mengaktifkan callback volume. Atur ke "1" untuk mengaktifkan onTtsVolCallback.
apikeystringTidakMemperbarui 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:****
ParameterTipeDeskripsi
paramstringNama 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:****
ParameterTipeDeskripsi
prioritystringPrioritas tugas. Atur parameter ini ke 1.
taskidstringID tugas. Jika string kosong '' diteruskan, SDK akan membuat ID secara otomatis.
textstringTeks 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:****
ParameterTipeDeskripsi
taskidstringID 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:****
ParameterTipeDeskripsi
eventNuiSdkTtsEventPeristiwa callback.
taskidstringID tugas sintesis ucapan.
ret_codenumberHanya 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:****
ParameterTipeDeskripsi
infostringHasil stempel waktu berformat JSON. Parameter ini berlaku ketika word_timestamp_enabled diatur ke "1".
info_lennumberPanjang data dari field info. Anda dapat mengabaikan parameter ini.
bufferArrayBuffer | nullData 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:****
ParameterTipeDeskripsi
volnumberVolume data sintesis.

NuiSdkTtsEvent

Enumerasi jenis event sintesis ucapan Sambert.
PeristiwaDeskripsi
TTS_EVENT_STARTTugas sintesis dimulai. Data audio akan segera dikembalikan.
TTS_EVENT_ENDTugas sintesis berakhir secara normal. Semua data audio telah dikembalikan melalui callback.
TTS_EVENT_CANCELTugas sintesis dibatalkan.
TTS_EVENT_PAUSETugas sintesis dijeda.
TTS_EVENT_RESUMETugas sintesis dilanjutkan.
TTS_EVENT_ERRORTerjadi 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:
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.

Kode sampel

  1. 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.
  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.
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.
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Realtime API
Penyematan Teks
TokenPlan
Model production