CosyVoice HarmonyOS SDK - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

Pelajari tentang integrasi SDK HarmonyOS, parameter, API, callback, dan kode contoh untuk sintesis suara real-time.

NativeNui

HarmonyOS SDK menyediakan text-to-speech streaming melalui NativeNui.

Buat instance text-to-speech streaming dengan memanggil new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS). NativeNui.GetInstance() mengembalikan singleton MODE_DIALOG dan tidak dapat digunakan untuk text-to-speech streaming.
Jangan panggil initialize() dalam mode text-to-speech streaming. Berikan kredensial dan parameter sintesis langsung ke startStreamInputTts(), playStreamInputTts(), atau asyncPlayStreamInputTts().
Terima peristiwa sintesis dan audio melalui INativeStreamInputTtsCallback.
SDK mengembalikan STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED saat tugas dimulai, audio melalui onStreamInputTtsDataCallback, STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE saat tugas berakhir, dan STREAM_INPUT_TTS_EVENT_TASK_FAILED saat sintesis gagal.

import { Constants, INativeStreamInputTtsCallback, NativeNui, StreamInputTtsEvent } from 'neonui';

const nuiInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);

Alur panggilan

CosyVoice mendukung input satu kali dan input streaming.

Input satu kali cocok untuk teks pendek atau skenario yang memerlukan SSML.

Panggil playStreamInputTts atau asyncPlayStreamInputTts untuk memberikan teks lengkap dan memulai sintesis. Yang pertama memblokir hingga sintesis selesai. Yang kedua segera mengembalikan dan mensintesis di latar belakang. Jangan panggil startStreamInputTts terlebih dahulu, dan jangan panggil metode stop setelahnya.
Terima audio di onStreamInputTtsDataCallback.
Sintesis berakhir saat STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE diterima.

Input streaming cocok untuk percakapan waktu nyata atau sintesis inkremental teks panjang. SSML tidak didukung dalam mode ini.

Panggil startStreamInputTts untuk membuka koneksi dan mengonfigurasi callback serta parameter.
Panggil sendStreamInputTts untuk mengirim fragmen teks.
Terima audio di onStreamInputTtsDataCallback.
Setelah semua teks dikirim, panggil stopStreamInputTts.
Sintesis berakhir saat STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE diterima.

Ketika text-to-speech tidak lagi diperlukan, panggil releaseStreamInputTts untuk melepaskan sumber daya.

Baik panjang input teks tunggal maupun panjang kumulatif dari beberapa input dibatasi. Lihat CosyVoice WebSocket API.

startStreamInputTts

Memulai sintesis streaming dua arah, membuka koneksi, dan mendaftarkan callback. Metode ini dapat memblokir. Jangan panggil pada thread UI.

startStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

Parameter	Tipe	Deskripsi
`callback`	`INativeStreamInputTtsCallback`	Callback peristiwa dan audio.
`ticket`	`string`	String JSON yang berisi pengaturan autentikasi, koneksi, dan debugging.
`parameters`	`string`	String JSON yang berisi pengaturan sintesis.
`session_id`	`string`	ID sesi yang ditentukan klien. Berikan string kosong agar server membuatnya.
`log_level`	`number`	Tingkat log SDK. Gunakan `Constants.LogLevel` nilai: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR), atau 5 (NONE).
`save_log`	`boolean`	Apakah akan menyimpan log secara lokal. Jika diatur ke `true`, atur `debug_path` di `ticket`.

Metode ini mengembalikan kode error. Constants.NuiResultCode.SUCCESS (0) menunjukkan keberhasilan.

bidang ticket

{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id"
}

Field	Tipe	Wajib	Deskripsi
`url`	`string`	Ya	Endpoint layanan. Gunakan endpoint publik `wss://dashscope.aliyuncs.com/api-ws/v1/inference` , atau endpoint khusus workspace: `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference` untuk Beijing atau `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference` untuk Singapura. Ganti `{WorkspaceId}` dengan ID workspace.
`apikey`	`string`	Ya	Kunci API. Gunakan kunci API sementara untuk mengurangi risiko paparan kunci berumur panjang.
`device_id`	`string`	Ya	Pengidentifikasi pengguna akhir yang unik, seperti ID pengguna dalam aplikasi atau ID perangkat yang dibuat klien. Ini digunakan terutama untuk pelacakan log dan pemecahan masalah.
`complete_waiting_ms`	`number`	Tidak	Waktu dalam milidetik untuk menunggu peristiwa sintesis selesai setelah `stopStreamInputTts(false)`. Default: `10000`.
`debug_path`	`string`	Tidak	Direktori log. Field ini wajib diisi ketika `save_log` adalah `true`. SDK menyimpan paling banyak dua file log.
`max_log_file_size`	`number`	Tidak	Ukuran maksimum satu file log dalam byte. Default: `104857600` (100 MiB). Field ini hanya berlaku ketika `save_log` adalah `true`.
`log_track_level`	`number`	Tidak	Tingkat filter log pelacakan internal. Default: `2`. Nilai yang valid sama dengan `log_level`. Antarmuka callback HarmonyOS saat ini tidak mengekspos callback log TTS streaming, sehingga log yang difilter hanya ditulis oleh SDK.

bidang parameters

{
  "model": "cosyvoice-v3-plus",
  "voice": "longanyang",
  "format": "mp3",
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1.0,
  "pitch": 1.0,
  "enable_audio_decoder": true
}

Field	Tipe	Wajib	Deskripsi
`model`	`string`	Ya	Nama model. Lihat Model sintesis ucapan.
`voice`	`string`	Ya	Suara. Untuk suara sistem, lihat suara CosyVoice. Anda juga dapat menggunakan suara yang dibuat melalui kloning suara atau Voice Design.
`format`	`string`	Tidak	Format pengkodean audio: `pcm`, `wav`, `mp3` (default), atau `opus`.
`enable_audio_decoder`	`boolean`	Tidak	Apakah akan mengaktifkan decoder SDK. Default: `false`. Untuk MP3 atau Opus, atur ini ke `true` untuk mendekode audio ke PCM sebelum dikembalikan melalui callback data.
`volume`	`number`	Tidak	Volume. Default: `50`. Rentang yang valid: `[0, 100]`.
`sample_rate`	`number`	Tidak	Laju sampel dalam Hz. Nilai yang valid: `8000`, `16000`, `22050` (default), `24000`, `44100`, dan `48000`.
`rate`	`number`	Tidak	Laju ucapan. Default: `1.0`. Rentang yang valid: `[0.5, 2.0]`.
`pitch`	`number`	Tidak	Nada. Default: `1.0`. Rentang yang valid: `[0.5, 2.0]`.
`bit_rate`	`number`	Tidak	Bitrate MP3 atau Opus dalam kbps. Default: `32`. Rentang yang valid: `[6, 510]`.
`enable_ssml`	`boolean`	Tidak	Apakah akan mengaktifkan SSML. Default: `false`. Lihat Batasan SSML.
`word_timestamp_enabled`	`boolean`	Tidak	Apakah akan mengembalikan stempel waktu tingkat kata. Default: `false`. Field ini hanya tersedia untuk output streaming. Ini mendukung suara kloning dari cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2, serta suara sistem yang ditandai sebagai didukung dalam daftar suara CosyVoice. Suara kloning dari model lain tidak didukung. Hasil stempel waktu disertakan dalam `all_response` dari `INativeStreamInputTtsCallback`.
`seed`	`number`	Tidak	Seed acak yang digunakan untuk memvariasikan hasil sintesis. Jika versi model, teks, suara, dan semua parameter lainnya sama, `seed` yang sama akan menghasilkan hasil yang sama. Default: `0`. Rentang yang valid: `[0, 65535]`.
`language_hints`	`string[]`	Tidak	Bahasa sintesis target. Pengaturan ini meningkatkan sintesis dan tidak bergantung pada bahasa audio sampel yang digunakan untuk kloning suara. Untuk mengatur bahasa sumber tugas kloning suara, lihat referensi API Voice Cloning. Versi saat ini hanya menggunakan elemen array pertama, jadi berikan satu nilai. Gunakan field ini ketika pembacaan angka, singkatan, atau simbol tidak sesuai harapan, atau ketika sintesis dalam bahasa yang kurang umum terdengar tidak wajar. Misalnya, ini dapat membuat `"hello, this is 110"` dibaca sebagai “one one zero” dalam bahasa Inggris alih-alih pembacaan bahasa Tiongkok, atau membuat `@` dibaca sebagai “at”. Nilai yang valid Nilai yang didukung: `zh`, `en`, `fr`, `de`, `ja`, `ko`, `ru`, `pt`, `th`, `id`, `vi`, `es`, `it`, `ms`, `fil`, dan `ar`.
`instruction`	`string`	Tidak	Instruksi yang mengontrol dialek, emosi, atau peran. Lihat Kontrol instruksi.
`enable_aigc_tag`	`boolean`	Tidak	Apakah akan menyematkan tag AIGC tak terlihat. Default: `false`. CatatanDidukung oleh cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2.
`aigc_propagator`	`string`	Tidak	`ContentPropagator` dalam tag AIGC. Hanya berlaku ketika `enable_aigc_tag` adalah `true`. Default: UID Alibaba Cloud. Model yang didukung sama dengan untuk `enable_aigc_tag`.
`aigc_propagate_id`	`string`	Tidak	`PropagateID` dalam tag AIGC. Hanya berlaku ketika `enable_aigc_tag` adalah `true`. Default: ID permintaan saat ini. Model yang didukung sama dengan untuk `enable_aigc_tag`.
`hot_fix`	`object`	Tidak	Pengaturan hot-fix teks untuk pengucapan kustom dan penggantian teks. Catatan`cosyvoice-v2` tidak mendukung field ini. Untuk skema, lihat Peristiwa klien.

sendStreamInputTts

sendStreamInputTts(text: string): number

Mengirim fragmen teks setelah startStreamInputTts berhasil. Metode ini tidak mengurai tag SSML. Setelah semua teks dikirim, panggil stopStreamInputTts().

Parameter	Tipe	Deskripsi
`text`	`string`	Teks yang akan disintesis. SSML tidak didukung. Tag SSML dibaca sebagai teks biasa.

Metode ini mengembalikan kode error.

stopStreamInputTts

stopStreamInputTts(flag_async: boolean = true): number

Mengakhiri input streaming.

true (default): Akhiri secara asinkron dan segera kembalikan. Tunggu STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE untuk memastikan bahwa sintesis telah selesai.
false: Blokir hingga semua audio dan peristiwa sintesis selesai diterima. Waktu habis dikendalikan oleh complete_waiting_ms.

Memanggil metode pembatalan setelah penghentian sinkron dapat memblokir. Kami merekomendasikan mode asinkron default.

Parameter	Tipe	Deskripsi
`flag_async`	`boolean`	Apakah akan mengakhiri secara asinkron. Default: `true`. `true` mengembalikan tanpa menunggu respons server. `false` memblokir hingga sintesis selesai.

Metode ini mengembalikan kode error.

cancelStreamInputTts

cancelStreamInputTts(): number

Segera menutup koneksi dan mengakhiri tugas saat ini. Tidak ada lagi callback audio yang diterima setelah panggilan ini. Metode ini mengembalikan kode error.

cancelStreamInputTtsKeepConnection

cancelStreamInputTtsKeepConnection(): number

Mengirim perintah pembatalan tingkat protokol untuk mengakhiri tugas saat ini tetapi tetap menjaga koneksi WebSocket terbuka. Gunakan metode ini ketika putaran sintesis lain harus segera dimulai, untuk menghindari biaya pembukaan ulang koneksi. Metode ini mengembalikan kode error.

playStreamInputTts

playStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  text: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

Sintesis satu kali sinkron. Metode ini menginisialisasi tugas, mengirim teks, menerima semua audio, lalu mengembalikan. Jangan panggil startStreamInputTts terlebih dahulu, dan jangan panggil metode stop setelahnya. SSML diaktifkan secara default. Jika enable_ssml diatur secara eksplisit, nilai tersebut akan diutamakan. Jangan panggil metode ini pada thread UI.

callback, ticket, parameters, session_id, log_level, dan save_log didefinisikan dalam startStreamInputTts. text adalah teks yang akan disintesis dan mendukung SSML. Metode ini mengembalikan kode error.

asyncPlayStreamInputTts

asyncPlayStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  text: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

Sintesis satu kali asinkron. Metode ini segera mengembalikan dan memberikan hasil melalui callback. Jangan panggil startStreamInputTts terlebih dahulu, dan jangan panggil metode stop setelahnya. SSML diaktifkan secara default. Jika enable_ssml diatur secara eksplisit, nilai tersebut akan diutamakan.

releaseStreamInputTts

releaseStreamInputTts(): number

Melepaskan instance TTS streaming dan sumber dayanya. Panggil metode ini ketika halaman dihancurkan atau text-to-speech tidak lagi diperlukan. Metode ini mengembalikan kode error.

INativeStreamInputTtsCallback

export interface INativeStreamInputTtsCallback {
  onStreamInputTtsEventCallback(
    event: StreamInputTtsEvent,
    task_id: string,
    session_id: string,
    ret_code: number,
    error_msg: string,
    timestamp: string,
    all_response: string
  ): void;

  onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;
}

onStreamInputTtsEventCallback

Parameter	Tipe	Deskripsi
`event`	`StreamInputTtsEvent`	Peristiwa sintesis.
`task_id`	`string`	ID tugas sintesis.
`session_id`	`string`	ID sesi. Nilai yang ditentukan klien dikembalikan tanpa perubahan. Jika tidak, server akan membuatnya.
`ret_code`	`number`	Kode error. Hanya valid untuk peristiwa tugas gagal.
`error_msg`	`string`	Pesan error. Hanya valid untuk peristiwa tugas gagal.
`timestamp`	`string`	Hasil stempel waktu.
`all_response`	`string`	Respons server lengkap sebagai string JSON. Uraikan untuk penggunaan, stempel waktu, dan detail error.

onStreamInputTtsDataCallback

onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;

Secara terus-menerus mengembalikan fragmen audio. Perhatikan hal berikut:

Data MP3 dan Opus memerlukan decoder streaming. Sebagai alternatif, atur enable_audio_decoder ke true agar SDK mengembalikan PCM.
Untuk merakit file yang lengkap, tambahkan data callback secara berurutan.
Untuk WAV dan MP3, hanya callback pertama yang berisi header file. Setiap frame Opus adalah halaman Ogg independen dan dapat digabungkan secara berurutan.

StreamInputTtsEvent

Event	Deskripsi
`STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED`	Server telah menerima permintaan dan mulai memproses. Data audio pertama biasanya tiba melalui `onStreamInputTtsDataCallback` segera setelah peristiwa ini.
`STREAM_INPUT_TTS_EVENT_SENTENCE_BEGIN`	Server telah mulai mensintesis sebuah ucapan.
`STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESIS`	Informasi progres sintesis, termasuk informasi penagihan dan stempel waktu.
`STREAM_INPUT_TTS_EVENT_SENTENCE_END`	Server telah menyelesaikan sintesis dari sebuah ucapan.
`STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE`	Server telah mengembalikan semua data audio. `onStreamInputTtsEventCallback` tidak dipanggil setelah peristiwa ini, yang merupakan sinyal akhir-stream yang eksplisit. Peristiwa ini tidak menunjukkan bahwa pemutaran lokal telah selesai.
`STREAM_INPUT_TTS_EVENT_TASK_FAILED`	Sintesis gagal. Ambil `task_id`, `error_code`, dan `error_message` dari `all_response`, atau gunakan `ret_code` dan `error_msg` argumen callback.

Contoh respons tugas gagal:

{
  "header": {
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "event": "task-failed",
    "error_code": "InvalidParameter",
    "error_message": "[tts:]Engine return error code: 418",
    "attributes": {}
  },
  "payload": {}
}

Kode contoh

Dapatkan API key. Jangan melakukan hard-code API key berumur panjang di aplikasi klien. Kami menyarankan agar server aplikasi Anda mendapatkan API key sementara dan mengirimkannya ke klien.
Unduh paket SDK terbaru. Ekstrak paket tersebut, salin entry/libs/neonui.har ke direktori entry/libs aplikasi Anda, dan tambahkan dependensi ke entry/oh-package.json5:

{
  "dependencies": {
    "neonui": "file:libs/neonui.har"
  }
}

Buka proyek contoh dari paket SDK di DevEco Studio. Halaman contohnya adalah entry/src/main/ets/pages/dashscope/DashCosyVoiceStreamTtsPage.ets. Konfigurasikan API key dan jalankan proyek.

Kode berikut menunjukkan alur input streaming inti. Untuk pemutaran audio lengkap, pemilihan parameter, dan manajemen status tugas, lihat DashCosyVoiceStreamTtsPage.ets dalam paket SDK.

import { Constants, INativeStreamInputTtsCallback, NativeNui, StreamInputTtsEvent } from 'neonui';

const callback: INativeStreamInputTtsCallback = {
  onStreamInputTtsEventCallback: (event: StreamInputTtsEvent, taskId: string,
    sessionId: string, retCode: number, errorMsg: string,
    timestamp: string, allResponse: string): void => {
    if (event == StreamInputTtsEvent.STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE) {
      // Synthesis is complete.
    } else if (event == StreamInputTtsEvent.STREAM_INPUT_TTS_EVENT_TASK_FAILED) {
      // Handle the error based on retCode, errorMsg, or allResponse.
    }
  },
  onStreamInputTtsDataCallback: (data: ArrayBuffer | null): void => {
    if (data != null) {
      // Write PCM to AudioRenderer, or append encoded audio data in order.
    }
  }
};

const nuiInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);
const ticket: Record<string, Object> = {
  'url': 'wss://dashscope.aliyuncs.com/api-ws/v1/inference',
  'apikey': 'st-****',
  'device_id': 'my_device_id'
};
const parameters: Record<string, Object> = {
  'model': 'cosyvoice-v3-plus',
  'voice': 'longanyang',
  'format': 'mp3',
  'sample_rate': 24000,
  'enable_audio_decoder': true
};

const result = nuiInstance.startStreamInputTts(
  callback,
  JSON.stringify(ticket),
  JSON.stringify(parameters),
  '',
  Constants.LogLevel.LOG_LEVEL_INFO,
  false
);

if (result == Constants.NuiResultCode.SUCCESS) {
  nuiInstance.sendStreamInputTts('Hello, ');
  nuiInstance.sendStreamInputTts('welcome to real-time speech synthesis.');
  nuiInstance.stopStreamInputTts(true);
}

// Call nuiInstance.releaseStreamInputTts() from the SYNTHESIS_COMPLETE handler.

Untuk input satu kali, panggil langsung playStreamInputTts atau asyncPlayStreamInputTts:

const oneShotInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);
oneShotInstance.asyncPlayStreamInputTts(
  callback,
  JSON.stringify(ticket),
  JSON.stringify(parameters),
  'Hello, welcome to real-time speech synthesis.',
  '',
  Constants.LogLevel.LOG_LEVEL_INFO,
  false
);
// Call oneShotInstance.releaseStreamInputTts() from the SYNTHESIS_COMPLETE handler.

Fitur lanjutan

SSML

Tujuan: Sematkan tag XML dalam teks untuk mengontrol pengucapan, kecepatan bicara, jeda, dan detail sintesis lainnya.

Batasan: Hanya API satu kali playStreamInputTts dan asyncPlayStreamInputTts yang mendukung SSML. API input streaming sendStreamInputTts tidak mendukungnya.

Penggunaan: SDK mengaktifkan SSML secara default untuk playStreamInputTts dan asyncPlayStreamInputTts. Berikan teks SSML di text. Untuk informasi selengkapnya, lihat SSML and LaTeX.

Ekspresi matematika

Tujuan: Membuat model membaca rumus dan ekspresi matematika umum dengan benar.

Penggunaan: Berikan teks yang berisi ekspresi matematis berformat LaTeX di text. Untuk sintaks yang didukung, lihat LaTeX text-to-speech.