CosyVoice iOS SDK - Alibaba Cloud Model Studio

NeoNui

Sorotan arsitektur:

Pola singleton: dapatkan instance global melalui [StreamInputTts get_instance].
Berbasis callback: menerima event dan data audio melalui protokol StreamInputTtsDelegate.
Konfigurasi JSON: teruskan parameter sebagai string JSON.

Alur pemanggilan

CosyVoice mendukung dua mode pemanggilan: input satu kali dan input streaming. One-shot input: paling cocok untuk sintesis teks pendek atau ketika Anda memerlukan markup SSML.

playStreamInputTts() atau asyncPlayStreamInputTts() — Kirim teks lengkap dan mulai sintesis. Yang pertama bersifat sinkron dan kembali setelah sintesis selesai; yang kedua bersifat asinkron dan langsung kembali setelah memulai sintesis.
onStreamInputTtsDataCallback() — Menerima data audio.
TTS_EVENT_SYNTHESIS_COMPLETE — Sintesis selesai.

Streaming input: paling cocok untuk percakapan waktu nyata atau skenario "speak-while-synthesizing" bentuk panjang. Mode ini tidak mendukung markup SSML.

startStreamInputTts() — Inisialisasi SDK dan atur delegasi callback serta parameter koneksi.
sendStreamInputTts() — Terus-menerus mengirim fragmen teks untuk disintesis.
onStreamInputTtsDataCallback() — Menerima data audio.
stopStreamInputTts() atau asyncStopStreamInputTts() — Kirim permintaan akhir sintesis. Yang pertama bersifat sinkron dan kembali setelah sintesis selesai; yang kedua bersifat asinkron dan langsung kembali setelah mengirim permintaan.
TTS_EVENT_SYNTHESIS_COMPLETE — Sintesis selesai.

startStreamInputTts

Memulai tugas sintesis suara streaming dan membuka koneksi ke server. Signature metode

- (int) startStreamInputTts:(const char *)ticket parameters:(const char *)parameters sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

Parameter

Parameter	Tipe	Deskripsi
`ticket`	`char*`	String JSON yang menyimpan pengaturan autentikasi, koneksi, dan debugging.
`parameters`	`char*`	String JSON yang menyimpan pengaturan efek sintesis suara.
`sessionId`	`char*`	ID sesi yang ditentukan klien. Jika diabaikan, server akan membuatnya.
`logLevel`	NuiSdkLogLevel	Level cetak untuk log internal SDK.
`saveLog`	`BOOL`	Apakah akan menyimpan log secara lokal. Jika diatur ke `YES`, Anda harus menentukan path dengan `debug_path` dan dapat membatasi ukuran file dengan `max_log_file_size`.

Nilai kembalian Mengembalikan kode kesalahan. Contoh JSON ticket: Contoh berikut tidak mencantumkan setiap bidang. Tambahkan bidang lainnya sesuai kebutuhan kode Anda:

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

bidang ticket

Bidang	Tipe	Wajib	Deskripsi
`url`	`string`	Ya	Alamat layanan: `wss://dashscope.aliyuncs.com/api-ws/v1/inference` Tiongkok (Beijing): `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference` Singapura: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference` Ganti `{WorkspaceId}` dengan ID Workspace Anda yang sebenarnya.
`apikey`	`string`	Ya	API key. Untuk membatasi paparan jika key berumur panjang bocor, gunakan API key berumur pendek sebagai gantinya.
`device_id`	`string`	Ya	Pengidentifikasi unik untuk pengguna akhir. Atur ini ke ID pengguna dalam aplikasi atau pengidentifikasi perangkat yang dibuat klien. ID ini digunakan untuk pelacakan log dan pemecahan masalah.
`complete_waiting_ms`	`int`	Tidak	Timeout, dalam milidetik, untuk menunggu event sintesis selesai (`TTS_EVENT_SYNTHESIS_COMPLETE`) setelah Anda memanggil `stopStreamInputTts`.Default: 10000.
`debug_path`	`string`	Tidak	Jalur lokal tempat file log disimpan.Bidang ini hanya berlaku ketika `saveLog` diatur ke `YES` di `startStreamInputTts`, `playStreamInputTts`, atau `asyncPlayStreamInputTts`. Dalam kasus tersebut, Anda harus mengatur path ini; jika tidak, error akan dikembalikan.Maksimal dua file log disimpan secara lokal.
`max_log_file_size`	`int`	Tidak	Ukuran maksimum file log, dalam byte.Bidang ini hanya berlaku ketika `saveLog` diatur ke `YES` di `startStreamInputTts`, `playStreamInputTts`, atau `asyncPlayStreamInputTts`.Default: 104857600 (100 × 1024 × 1024 byte, yaitu 100 MiB).
`log_track_level`	`int`	Tidak	Level filter untuk log yang dikirim melalui callback log (`onStreamInputTtsLogTrackCallback`).Default: 2.Nilai yang valid: 0: LOG_LEVEL_VERBOSE 1: LOG_LEVEL_DEBUG 2: LOG_LEVEL_INFO 3: LOG_LEVEL_WARNING 4: LOG_LEVEL_ERROR 5: LOG_LEVEL_NONE (menonaktifkan callback) Catatan: `log_track_level` dan `logLevel` (diatur melalui `startStreamInputTts`, `playStreamInputTts`, atau `asyncPlayStreamInputTts`) bersama-sama menentukan log mana yang mencapai callback. Log memicu callback hanya ketika levelnya berada pada atau di atas kedua ambang batas. Misalnya, jika `log_track_level` adalah 2 (INFO) dan `logLevel` adalah 3 (WARNING), hanya log pada WARNING atau lebih tinggi (level >= 3) yang dikirimkan.

Contoh JSON parameters: Contoh berikut tidak mencantumkan setiap bidang. Tambahkan bidang lainnya sesuai kebutuhan kode Anda:

{
  "model": "cosyvoice-v3-plus",
  "voice": "longanyang",
  "format": "mp3",
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1,
  "pitch": 1,
  "language_hints": ["zh"],
  "enable_ssml": false
}

bidang parameters

Bidang	Tipe	Wajib	Deskripsi
`model`	`string`	Ya	Nama model.
`voice`	`string`	Ya	Suara yang digunakan untuk sintesis suara. Suara sistem: Lihat CosyVoice Daftar suara Suara kloning: Suara kustom yang dibuat melalui kloning suara Suara kustom: Suara kustom yang dibuat melalui desain suara
`format`	`string`	Tidak	Format pengkodean audio.Nilai yang valid: pcm wav mp3 (default) opus cosyvoice-v1 tidak mendukung format opus.
`enable_audio_decoder`	`BOOL`	Tidak	Apakah akan mengaktifkan decoder internal SDK. Default: `NO`.Parameter ini hanya berlaku ketika format pengodean audio adalah opus atau mp3. Saat diaktifkan, SDK mendekode data audio opus atau mp3 menjadi data PCM sebelum mengembalikannya.
`volume`	`int`	Tidak	Tingkat volume.Nilai default: 50.Nilai yang valid: [0, 100].
`sample_rate`	`int`	Tidak	Tingkat sampel audio dalam Hz.Nilai yang valid: 8000, 16000, 22050 (default), 24000, 44100, 48000.
`rate`	`float`	Tidak	Kecepatan bicara.Nilai default: 1.0.Nilai yang valid: [0.5, 2.0].
`pitch`	`float`	Tidak	Pitch.Nilai default: 1.0.Nilai yang valid: [0.5, 2.0].
`bit_rate`	`int`	Tidak	Bit rate audio dalam kbps. Saat format audio adalah mp3 atau opus, gunakan `bit_rate` untuk menyesuaikan bit rate.Nilai default: 32.Nilai yang valid: [6, 510]. cosyvoice-v1 tidak mendukung parameter ini.
`enable_ssml`	`boolean`	Tidak	Apakah akan mengaktifkan SSML.Default: false. true: diaktifkan. false: dinonaktifkan. Untuk batasan penggunaan SSML (model, suara, dan API yang didukung), lihat Batasan.
`word_timestamp_enabled`	`boolean`	Tidak	Menentukan apakah akan mengaktifkan stempel waktu tingkat kata.Nilai default: false.Hanya tersedia dalam mode output streaming. Suara yang didukung: 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 CosyVoice Voice list. Suara kloning dari model lain tidak mendukung fitur ini. Stempel waktu dikembalikan dalam `all_response` dari `onStreamInputTtsEventCallback`.
`seed`	`int`	Tidak	Seed acak untuk mengontrol variasi dalam output sintesis. Ketika versi model, teks, suara, dan parameter lainnya tidak berubah, menggunakan seed yang sama akan menghasilkan hasil yang identik.Nilai default: 0.Nilai yang valid: [0, 65535]. cosyvoice-v1 tidak mendukung parameter ini.
`language_hints`	`array[string]`	Tidak	Parameter ini adalah array, tetapi versi saat ini hanya memproses elemen pertama. Berikan satu nilai. Parameter ini menentukan bahasa target untuk sintesis ucapan. Ini tidak terkait dengan bahasa sampel audio yang digunakan dalam kloning suara. Untuk mengatur bahasa sumber untuk tugas kloning, lihat referensi API kloning suara. Menentukan bahasa target untuk sintesis ucapan guna meningkatkan kualitas output. cosyvoice-v1 tidak mendukung fitur ini. Ketika pengucapan angka, ekspansi singkatan, pembacaan simbol, atau sintesis bahasa minoritas tidak sesuai harapan, gunakan parameter ini. Misalnya: Pengucapan angka yang tidak terduga: "hello, this is 110" dibaca sebagai "hello, this is one zero" alih-alih pengucapan bahasa Mandarin yang diharapkan Pengucapan simbol yang tidak akurat: "@" dibaca sebagai padanan bahasa Mandarin, bukan "at" Kualitas sintesis bahasa minor yang buruk dengan hasil yang tidak wajar Nilai yang valid zh: Tiongkok en: Inggris fr: Prancis de: Jerman ja: Jepang ko: Korea ru: Rusia pt: Portugis th: Thai id: Indonesia vi: Vietnam es: Spanyol it: Italia ms: Malaysia fil: Filipina ar: Arab
`instruction`	`string`	Tidak	Mengontrol karakteristik sintesis seperti dialek, emosi, atau gaya bicara.Untuk detail penggunaan, lihat Kontrol instruksi.
`enable_aigc_tag`	`boolean`	Tidak	Menentukan apakah akan menyematkan watermark AIGC dalam audio yang dihasilkan. Jika diatur ke true, watermark disematkan dalam file audio dengan format yang didukung (wav/mp3/opus).Nilai default: false. Hanya cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.
`aigc_propagator`	`string`	Tidak	Mengatur field `ContentPropagator` dalam watermark AIGC, yang mengidentifikasi penyebar konten. Hanya berlaku jika `enable_aigc_tag` adalah `true`.Nilai default: UID Alibaba Cloud. Hanya cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.
`aigc_propagate_id`	`string`	Tidak	Mengatur field `PropagateID` dalam watermark AIGC, yang secara unik mengidentifikasi tindakan penyebaran tertentu. Hanya berlaku jika `enable_aigc_tag` adalah `true`.Nilai default: ID permintaan dari permintaan sintesis suara saat ini. Hanya cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.
`hot_fix`	`object`	Tidak	Konfigurasi hot-fix teks untuk menyesuaikan pengucapan kata-kata tertentu atau mengganti teks sebelum sintesis. cosyvoice-v2, cosyvoice-v1 tidak mendukung fitur ini. Field: pronunciation: Menentukan anotasi pinyin untuk kata-kata yang pengucapan defaultnya perlu dikoreksi. replace: Mengganti kata-kata tertentu sebelum sintesis. Teks pengganti digunakan sebagai input sintesis aktual. Contoh: `"hot_fix": { "pronunciation": [ {"天气": "tian1 qi4"} ], "replace": [ {"今天": "金天"} ] }`
`enable_markdown_filter`	`BOOL`	Tidak	Hanya suara kloning dari cosyvoice-v3-flash yang mendukung fitur ini. Apakah akan memfilter markup Markdown dari teks input sebelum sintesis sehingga markup tidak diucapkan dengan keras.Default: `NO`.Nilai yang valid: `YES`: Aktifkan pemfilteran Markdown. `NO`: Nonaktifkan pemfilteran Markdown.

sendStreamInputTts

Mengirim teks yang akan disintesis. Gunakan metode ini bersama dengan startStreamInputTts. Setelah Anda memanggil startStreamInputTts, gunakan metode ini untuk mendorong teks secara terus-menerus. Setelah semua teks dikirim, panggil stopStreamInputTts atau asyncStopStreamInputTts untuk memberi sinyal akhir input. Signature metode

- (int) sendStreamInputTts:(const char *)text;

Parameter

Parameter	Tipe	Deskripsi
`text`	`char*`	Teks yang akan disintesis. SSML tidak didukung. Tag SSML dalam input dibaca sebagai teks biasa alih-alih diuraikan.