This page documents all public symbols declared in include/cosyvoice.h.
The runtime supports concurrent inference through multiple worker slots; context duplication lets separate threads bind to different workers while sharing loaded model resources.
#ifndef COSYVOICE_API
#ifdef COSYVOICE_STATIC
#define COSYVOICE_API
#else
#ifdef _WIN32
#define COSYVOICE_API __declspec(dllimport)
#else
#define COSYVOICE_API __attribute__((visibility("default")))
#endif
#endif
#endifControls symbol import/export visibility for the C API. Define COSYVOICE_STATIC when linking statically to suppress import attributes.
On Windows, the macro expands to __declspec(dllimport) by default. On non-Windows targets, default symbol visibility is used.
typedef enum cosyvoice_kv_cache_type
{
COSYVOICE_KV_CACHE_TYPE_F32,
COSYVOICE_KV_CACHE_TYPE_F16,
COSYVOICE_KV_CACHE_TYPE_Q8_0,
COSYVOICE_KV_CACHE_TYPE_Q5_1,
COSYVOICE_KV_CACHE_TYPE_Q5_0,
COSYVOICE_KV_CACHE_TYPE_Q4_1,
COSYVOICE_KV_CACHE_TYPE_Q4_0,
COSYVOICE_KV_CACHE_TYPE_COUNT
} cosyvoice_kv_cache_type_t, cosyvoice_llm_kv_cache_type_t;The old cosyvoice_llm_kv_cache_type_t and COSYVOICE_LLM_KV_CACHE_TYPE_* constants
are provided as backward-compatibility aliases:
#define COSYVOICE_LLM_KV_CACHE_TYPE_F32 COSYVOICE_KV_CACHE_TYPE_F32
#define COSYVOICE_LLM_KV_CACHE_TYPE_F16 COSYVOICE_KV_CACHE_TYPE_F16
#define COSYVOICE_LLM_KV_CACHE_TYPE_Q8_0 COSYVOICE_KV_CACHE_TYPE_Q8_0
#define COSYVOICE_LLM_KV_CACHE_TYPE_Q5_1 COSYVOICE_KV_CACHE_TYPE_Q5_1
#define COSYVOICE_LLM_KV_CACHE_TYPE_Q5_0 COSYVOICE_KV_CACHE_TYPE_Q5_0
#define COSYVOICE_LLM_KV_CACHE_TYPE_Q4_1 COSYVOICE_KV_CACHE_TYPE_Q4_1
#define COSYVOICE_LLM_KV_CACHE_TYPE_Q4_0 COSYVOICE_KV_CACHE_TYPE_Q4_0
#define COSYVOICE_LLM_KV_CACHE_TYPE_COUNT COSYVOICE_KV_CACHE_TYPE_COUNTSpecifies supported KV-cache storage formats. Used by both the LLM and DiT modules.
COSYVOICE_KV_CACHE_TYPE_F32: 32-bit floating-point cache.COSYVOICE_KV_CACHE_TYPE_F16: 16-bit floating-point cache.COSYVOICE_KV_CACHE_TYPE_Q8_0: GGMLQ8_0quantized cache.COSYVOICE_KV_CACHE_TYPE_Q5_1: GGMLQ5_1quantized cache.COSYVOICE_KV_CACHE_TYPE_Q5_0: GGMLQ5_0quantized cache.COSYVOICE_KV_CACHE_TYPE_Q4_1: GGMLQ4_1quantized cache.COSYVOICE_KV_CACHE_TYPE_Q4_0: GGMLQ4_0quantized cache.COSYVOICE_KV_CACHE_TYPE_COUNT: Sentinel value, not a runtime mode.
The cosyvoice_kv_cache_type_t value can encode separate types for the K and V cache
buffers via bit-packing. This allows using different quantization formats for the K and V
tensors (e.g. K in Q8_0 and V in Q4_0) to trade off quality vs. memory.
| Bits | Field |
|---|---|
| 0–4 | K cache type |
| 5–9 | V cache type |
| 10–14 | Fallback cache type |
| 15–30 | Reserved |
| 31 | Separate-K/V flag |
When bit 31 is 0, the value is a plain cosyvoice_kv_cache_type_t that applies
to both K and V (backward compatible).
#define COSYVOICE_MAKE_SEPARATE_KV_CACHE(k_type, v_type, fallback_type)
#define COSYVOICE_IS_SEPARATE_KV_CACHE(t)
#define COSYVOICE_K_CACHE_TYPE(t)
#define COSYVOICE_V_CACHE_TYPE(t)
#define COSYVOICE_KV_CACHE_FALLBACK(t)COSYVOICE_MAKE_SEPARATE_KV_CACHE(k_type, v_type, fallback_type)— Pack separate K, V and fallback types into a single value.COSYVOICE_IS_SEPARATE_KV_CACHE(t)— Returns non-zero iftis in separate-K/V mode.COSYVOICE_K_CACHE_TYPE(t)— Extracts the K cache type from a packed value.COSYVOICE_V_CACHE_TYPE(t)— Extracts the V cache type from a packed value.COSYVOICE_KV_CACHE_FALLBACK(t)— Extracts the fallback cache type from a packed value.
When the preferred K or V type is not supported by the backend, the fallback type is tried first; if that also fails, auto-fallback applies.
Use the bitfield members of cosyvoice_context_params_t or cosyvoice_context_params_v3_t
directly, or pack a value with COSYVOICE_MAKE_SEPARATE_KV_CACHE and assign it to
llm_kv_cache_type / dit_kv_cache_type:
params.llm_k_cache_type = COSYVOICE_KV_CACHE_TYPE_Q8_0;
params.llm_v_cache_type = COSYVOICE_KV_CACHE_TYPE_Q4_0;
params.llm_kv_cache_separate_buffers = true;or equivalently:
params.llm_kv_cache_type = COSYVOICE_MAKE_SEPARATE_KV_CACHE(
COSYVOICE_KV_CACHE_TYPE_Q8_0,
COSYVOICE_KV_CACHE_TYPE_Q4_0,
COSYVOICE_KV_CACHE_TYPE_Q8_0);typedef enum cosyvoice_inference_buffer_policy
{
COSYVOICE_INFERENCE_BUFFER_POLICY_SHARED,
COSYVOICE_INFERENCE_BUFFER_POLICY_BALANCED,
COSYVOICE_INFERENCE_BUFFER_POLICY_DEDICATED,
COSYVOICE_INFERENCE_BUFFER_POLICY_COUNT
} cosyvoice_inference_buffer_policy_t;Defines memory allocation and reuse behavior for inference buffers.
COSYVOICE_INFERENCE_BUFFER_POLICY_SHARED: Maximizes sharing between KV-cache and token2wav intermediates to reduce memory usage.COSYVOICE_INFERENCE_BUFFER_POLICY_BALANCED: Shares buffers while preserving reusable sequence segments for faster restoration.COSYVOICE_INFERENCE_BUFFER_POLICY_DEDICATED: Allocates separate buffers to prioritize throughput.COSYVOICE_INFERENCE_BUFFER_POLICY_COUNT: Sentinel value.
typedef enum cosyvoice_builtin_sampler_rng_policy
{
COSYVOICE_BUILTIN_SAMPLER_RNG_POLICY_RESET_PER_SESSION,
COSYVOICE_BUILTIN_SAMPLER_RNG_POLICY_CONTINUE_ACROSS_SESSIONS,
COSYVOICE_BUILTIN_SAMPLER_RNG_POLICY_COUNT
} cosyvoice_builtin_sampler_rng_policy_t;Controls how the built-in sampler random state evolves across LLM sessions.
COSYVOICE_BUILTIN_SAMPLER_RNG_POLICY_RESET_PER_SESSION: Resets to configured seed per session for reproducible runs.COSYVOICE_BUILTIN_SAMPLER_RNG_POLICY_CONTINUE_ACROSS_SESSIONS: Keeps advancing RNG state between sessions.COSYVOICE_BUILTIN_SAMPLER_RNG_POLICY_COUNT: Sentinel value.
typedef struct cosyvoice_sampling_params
{
int top_k;
float top_p;
int win_size;
float tau_r;
} cosyvoice_sampling_params_t;Defines nucleus-sampling parameters used by the built-in sampler.
top_k: Limits candidate set size before sampling.top_p: Cumulative probability threshold for nucleus truncation.win_size: Sliding-window length used by repetition-aware logic.tau_r: Repetition control coefficient.
typedef struct cosyvoice_generation_config
{
float temperature;
cosyvoice_sampling_params_t sampling;
float min_token_text_ratio;
float max_token_text_ratio;
} cosyvoice_generation_config_t;Holds runtime generation controls for token sampling and output-length limits.
temperature: Softmax temperature applied to logits.sampling: Built-in sampler configuration.min_token_text_ratio: Lower bound for generated acoustic-token count relative to input text length.max_token_text_ratio: Upper bound for generated acoustic-token count relative to input text length.
typedef struct cosyvoice_llm_token_prob
{
int token_id;
float prob;
} cosyvoice_llm_token_prob_t;Represents one candidate token and its probability, typically passed to custom samplers.
token_id: Vocabulary token identifier.prob: Probability assigned after filtering.
typedef struct cosyvoice_generated_speech
{
float* data;
uint32_t length;
} *cosyvoice_generated_speech_ptr;Pointer to generated waveform metadata and PCM sample buffer.
data: Pointer to 32-bit float PCM samples.length: Number of samples indata.
typedef struct cosyvoice_context* cosyvoice_context_t;Opaque handle to a loaded model context.
typedef struct cosyvoice_prompt_speech* cosyvoice_prompt_speech_t;Opaque handle to prompt-speech features loaded or extracted for inference.
typedef struct cosyvoice_prompt* cosyvoice_prompt_t;Opaque handle to a prepared prompt object bound to a model context.
typedef struct cosyvoice_tts_context* cosyvoice_tts_context_t;Opaque handle to a reusable text-to-speech session context.
typedef int (*cosyvoice_sampler_t)(
cosyvoice_llm_token_prob_t* nucleus_probs,
int k,
float* probs,
uint32_t size,
const cosyvoice_sampling_params_t* sampling_params,
int* accepted_tokens,
uint32_t n_accepted_tokens,
void* sampler_ctx
);Callback used to override token selection from LLM logits.
nucleus_probs: Candidate tokens after nucleus filtering.k: Number of elements innucleus_probs.probs: Full probability distribution buffer.size: Number of entries inprobs.sampling_params: Active sampling configuration.accepted_tokens: Tokens already accepted in current sequence.n_accepted_tokens: Number of accepted tokens.sampler_ctx: User context pointer registered with sampler.
Selected token id.
typedef struct cosyvoice_context_params
{
bool llm_use_flash_attn;
bool flow_use_flash_attn;
union
{
struct
{
cosyvoice_kv_cache_type_t llm_k_cache_type : 5; ///< K cache data type.
cosyvoice_kv_cache_type_t llm_v_cache_type : 5; ///< V cache data type.
cosyvoice_kv_cache_type_t llm_kv_cache_fallback : 5; ///< Fallback type when preferred type unsupported.
cosyvoice_kv_cache_type_t : 16; ///< Reserved.
uint32_t llm_kv_cache_separate_buffers : 1; ///< Allocate separate K & V buffers.
};
cosyvoice_kv_cache_type_t llm_kv_cache_type; ///< Backward-compatible unified type.
};
bool llm_allow_kv_cache_fallback;
cosyvoice_inference_buffer_policy_t inference_buffer_policy;
uint32_t n_batch;
uint32_t n_max_seq;
uint32_t seed;
cosyvoice_builtin_sampler_rng_policy_t builtin_sampler_rng_policy;
cosyvoice_sampler_t sampler;
void* sampler_ctx;
} cosyvoice_context_params_t;Groups context creation options that affect backend behavior, memory planning, and sampler setup.
llm_use_flash_attn: Enables flash attention for the LLM when backend supports it.flow_use_flash_attn: Enables flash attention for Flow module when available.llm_k_cache_type,llm_v_cache_type: Separate data types for K and V cache whenllm_kv_cache_separate_buffersis true.llm_kv_cache_fallback: Fallback type when the preferred K or V type is unsupported by the backend.llm_kv_cache_separate_buffers: If true, allocate separate buffers for K and V caches using the types fromllm_k_cache_typeandllm_v_cache_type. Ignored when the unifiedllm_kv_cache_typedoes not have bit 31 set.llm_kv_cache_type: Requested KV-cache storage type. Can be a plain enum value (unified, applied to both K and V) or a packed value created withCOSYVOICE_MAKE_SEPARATE_KV_CACHEthat encodes separate K, V, and fallback types.llm_allow_kv_cache_fallback: Allows fallback to flash-attention-compatible KV type when unsupported.inference_buffer_policy: Strategy for inference-buffer allocation and reuse.n_batch: Kernel batch size.n_max_seq: Maximum sequence length.seed: RNG seed for built-in sampler and noise generation.builtin_sampler_rng_policy: Built-in sampler RNG evolution policy; ignored whensampleris non-null.sampler: Optional custom sampler; set toNULLto use built-in sampler.sampler_ctx: User pointer passed tosampler.
COSYVOICE_API void cosyvoice_init_backend();Initializes the default backend runtime.
Call before creating contexts when the selected backend requires explicit initialization.
COSYVOICE_API void cosyvoice_init_backend_from_path(const char* dir_path);Initializes backend runtime using resources located in a custom directory.
dir_path: Directory path used during backend initialization.
Loads backend resources from the specified directory and initializes the runtime.
COSYVOICE_API void cosyvoice_init_default_context_params(cosyvoice_context_params_t* params);Fills a context-parameter struct with library defaults.
params: Output parameter block to initialize.
COSYVOICE_API cosyvoice_context_t cosyvoice_load_from_file(const char* filename);Loads a model context from a GGUF file using default context parameters.
filename: Path to the model file.
Loaded context handle on success; NULL on failure.
Uses default backend and thread settings.
Equivalent to calling cosyvoice_load_from_file_ext(filename, ¶ms, NULL, 0, 0) with default-initialized params.
COSYVOICE_API cosyvoice_context_t cosyvoice_load_from_file_with_params(
const char* filename,
const cosyvoice_context_params_t* params
);Loads a model context from file with explicit context parameters.
filename: Path to the model file.params: Context-parameter block to apply.
Loaded context handle on success; NULL on failure.
Equivalent to calling cosyvoice_load_from_file_ext(filename, params, NULL, 0, 0).
typedef struct cosyvoice_context_params_v2
{
cosyvoice_context_params_t base_params;
uint32_t n_workers;
} cosyvoice_context_params_v2_t;Extends cosyvoice_context_params_t with a worker count for concurrent inference.
base_params: Base context parameters.n_workers: Number of worker slots to create.
COSYVOICE_API cosyvoice_context_t cosyvoice_load_from_file_with_params_v2(
const char* filename,
const cosyvoice_context_params_v2_t* params
);Loads a model context with extended parameters, including worker-count configuration.
filename: Path to the model file.params: Extended context-parameter block.
Loaded context handle on success; NULL on failure.
typedef struct cosyvoice_context_params_v3
{
cosyvoice_context_params_v2_t base_params;
union
{
struct
{
#if defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__) || defined(_BYTE_ORDER) && (_BYTE_ORDER == _BIG_ENDIAN) || defined(__BIG_ENDIAN__) && !defined(__LITTLE_ENDIAN__) || defined(__ARMEB__) || defined(__MIPSEB__) || defined(__sparc__)
uint32_t dit_kv_cache_separate_buffers : 1;
cosyvoice_kv_cache_type_t : 16;
cosyvoice_kv_cache_type_t dit_kv_cache_fallback : 5;
cosyvoice_kv_cache_type_t dit_v_cache_type : 5;
cosyvoice_kv_cache_type_t dit_k_cache_type : 5;
#else
cosyvoice_kv_cache_type_t dit_k_cache_type : 5;
cosyvoice_kv_cache_type_t dit_v_cache_type : 5;
cosyvoice_kv_cache_type_t dit_kv_cache_fallback : 5;
cosyvoice_kv_cache_type_t : 16;
uint32_t dit_kv_cache_separate_buffers : 1;
#endif
};
cosyvoice_kv_cache_type_t dit_kv_cache_type;
};
bool dit_allow_kv_cache_fallback;
uint32_t dit_kv_fixed_slots;
uint32_t dit_kv_offloadable_slots;
uint32_t dit_kv_cache_length;
} cosyvoice_context_params_v3_t;
#ifdef __cplusplus
struct cosyvoice_context_params_v3_cpp : cosyvoice_context_params_v2_cpp
{
union
{
struct
{
#if defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__) || defined(_BYTE_ORDER) && (_BYTE_ORDER == _BIG_ENDIAN) || defined(__BIG_ENDIAN__) && !defined(__LITTLE_ENDIAN__) || defined(__ARMEB__) || defined(__MIPSEB__) || defined(__sparc__)
uint32_t dit_kv_cache_separate_buffers : 1;
cosyvoice_kv_cache_type_t : 16;
cosyvoice_kv_cache_type_t dit_kv_cache_fallback : 5;
cosyvoice_kv_cache_type_t dit_v_cache_type : 5;
cosyvoice_kv_cache_type_t dit_k_cache_type : 5;
#else
cosyvoice_kv_cache_type_t dit_k_cache_type : 5;
cosyvoice_kv_cache_type_t dit_v_cache_type : 5;
cosyvoice_kv_cache_type_t dit_kv_cache_fallback : 5;
cosyvoice_kv_cache_type_t : 16;
uint32_t dit_kv_cache_separate_buffers : 1;
#endif
};
cosyvoice_kv_cache_type_t dit_kv_cache_type;
};
bool dit_allow_kv_cache_fallback;
uint32_t dit_kv_fixed_slots;
uint32_t dit_kv_offloadable_slots;
uint32_t dit_kv_cache_length;
};
#endifExtends cosyvoice_context_params_v2_t with DiT (diffusion) KV cache configuration. The DiT module runs multiple diffusion steps during streaming TTS — each step computes self-attention over the full audio sequence. A KV cache can avoid redundant attention recomputation across steps, but the cache is very large (up to sequence_length × n_diffusion_steps key-value pairs).
base_params: V2 base parameters.dit_k_cache_type: Data type of the K cache in the DiT module.dit_v_cache_type: Data type of the V cache in the DiT module.dit_kv_cache_separate_buffers: If true, allocate separate buffers for K and V.dit_kv_cache_fallback: Fallback type when preferred K/V type is unsupported.dit_kv_cache_type: Shorthand — assigns a unified type (no separate K/V).dit_allow_kv_cache_fallback: If true, fall back to a flash-attention-compatible type.dit_kv_fixed_slots: Number of fixed (device memory, never offloaded) DiT KV slots. Each fixed slot holds the KV cache for one diffusion step and gets a dedicated device slot index.dit_kv_offloadable_slots: Number of offloadable (CPU offload) DiT KV slots. All offloadable steps share a single device scratch slot and copy KV to/from one CPU buffer per slot.dit_kv_cache_length: Maximum sequence length for the DiT KV cache. 0 to use default (n_max_seq × 10).
See README.md — Streaming TTS for a user-facing overview. This section documents how the cache is laid out internally.
Slot layout. The device cache allocates n_slots = fixed_slots + (offloadable_slots > 0 ? 1 : 0) physical slots. When offloading is enabled, slot index 0 is a dedicated scratch slot shared by all offloadable steps; fixed steps then occupy slot indices 1..fixed_slots. When offloading is disabled, the fixed slots occupy indices 0..fixed_slots-1.
Step-to-slot scheduling. The diffusion_steps (10) are partitioned in order into n_nocache = 10 − fixed − offloadable uncached steps, then the offloadable steps, then the fixed steps:
- Uncached steps recompute attention every step and touch no KV slot.
- Offloadable steps all compute into slot 0, then copy KV to their own CPU buffer (
offload_slot), and reload it on the next step. One CPU buffer is allocated per offloadable slot. - Fixed steps each write to their dedicated device slot; their KV persists on device so the last fixed step seeds the cache of the next streaming chunk.
Flash Attention path. With flow_use_flash_attn the graph is built once and reused while the view chain slides through slots via slide_kv_slot. The boundary slide from the scratch slot (last offloadable step) into slot 1 hands KV off to the fixed chain; fixed steps never rebind, so their chain position is determined purely by the slide index.
Non-FA path. Each cached step rebuilds a fresh graph. The step config rebinds an explicit slot — offloadable steps bind_slot(0), fixed steps bind_slot(step + slot_offset) — so the fixed steps land on their dedicated slot indices.
Normalization and clamping. At load time a single offloadable slot (offloadable == 1) is converted to a fixed slot (fixed++, offloadable = 0), and both counts are clamped so fixed ≤ 10 and fixed + offloadable ≤ 10. The builder also allocates offloadable CPU-safe KV buffers used to round-trip offloaded state.
Cache length. dit_kv_cache_length caps the max sequence positions retained per slot. When the stream exceeds it, part of the context is discarded — inference continues normally and never crashes, but audio quality may degrade.
COSYVOICE_API cosyvoice_context_t cosyvoice_load_from_file_with_params_v3(
const char* filename,
const cosyvoice_context_params_v3_t* params
);Loads a model context with V3 extended parameters, including DiT KV cache configuration.
filename: Path to the model file.params: V3 context-parameter block.
Loaded context handle on success; NULL on failure.
COSYVOICE_API cosyvoice_context_t cosyvoice_duplicate_context(cosyvoice_context_t ctx);Creates a new context that shares the loaded model resources with the original context.
ctx: Source context.
Duplicated context handle on success; NULL on failure.
The new context starts with the same active worker binding as the source context, then can be rebound independently with cosyvoice_set_worker_no().
COSYVOICE_API uint32_t cosyvoice_get_n_workers(cosyvoice_context_t ctx);Gets the total number of worker slots available in the context.
ctx: Context handle.
Worker-slot count.
COSYVOICE_API uint32_t cosyvoice_get_worker_no(cosyvoice_context_t ctx);Gets the active worker slot number.
ctx: Context handle.
Current worker slot number.
COSYVOICE_API bool cosyvoice_set_worker_no(cosyvoice_context_t ctx, uint32_t worker_no);Sets the active worker slot used by subsequent inference calls.
ctx: Context handle.worker_no: Worker-slot index.
true on success; otherwise false.
Use this on duplicated contexts when two threads need to run inference concurrently while sharing the same loaded model.
COSYVOICE_API void cosyvoice_free(cosyvoice_context_t ctx);Releases a model context and all resources owned by it.
ctx: Context handle to destroy.
COSYVOICE_API void cosyvoice_get_context_params(
cosyvoice_context_t ctx,
cosyvoice_context_params_t* params
);Retrieves effective context parameters currently active in a loaded context.
ctx: Context handle.params: Output structure receiving parameters.
COSYVOICE_API void cosyvoice_get_default_generation_config(
cosyvoice_context_t ctx,
cosyvoice_generation_config_t* config
);Gets the generation configuration loaded from the model file before any worker-specific overrides are applied.
ctx: Context handle.config: Output structure receiving the default configuration.
COSYVOICE_API const char* cosyvoice_get_architecture(cosyvoice_context_t ctx);Returns the architecture identifier of the loaded model.
ctx: Context handle.
Null-terminated UTF-8 architecture string, such as cosyvoice3-2512.
COSYVOICE_API bool cosyvoice_is_backend_uma(cosyvoice_context_t ctx);Queries whether the backend appears to use unified memory architecture (UMA).
ctx: Context handle.
true if the backend memory is detected as UMA; otherwise false.
The result is determined at model load time by probing the backend memory bandwidth. On Apple Silicon (__aarch64__), UMA is assumed by default. On other platforms, the runtime compares backend tensor-set bandwidth against host memcpy bandwidth. When UMA is detected and the requested buffer policy is balanced, the library automatically switches to dedicated to avoid redundant buffer sharing. This query is useful for callers that want to display backend characteristics or make policy decisions based on the memory architecture.
Note: UMA detection is a heuristic based on bandwidth probing. Results may be inaccurate depending on hardware, driver version, and system load at probe time. Treat the result as a rough hint rather than a definitive hardware capability.
COSYVOICE_API void cosyvoice_get_generation_config(
cosyvoice_context_t ctx,
cosyvoice_generation_config_t* config
);Gets current generation configuration.
ctx: Context handle.config: Output structure receiving current configuration.
COSYVOICE_API uint32_t cosyvoice_get_sample_rate(cosyvoice_context_t ctx);Returns output sample rate of the loaded model.
ctx: Context handle.
Sample rate in Hz.
COSYVOICE_API bool cosyvoice_set_generation_config(
cosyvoice_context_t ctx,
const cosyvoice_generation_config_t* config
);Validates and applies generation configuration, overriding model defaults.
ctx: Context handle.config: Configuration to apply.
true when configuration is valid and accepted; otherwise false.
The sample-rate field is not part of this configuration and is not changed by this API.
COSYVOICE_API void cosyvoice_set_sampler(cosyvoice_context_t ctx, cosyvoice_sampler_t sampler, void* sampler_ctx);Registers a custom sampler callback for token selection.
ctx: Context handle.sampler: Callback function; setNULLto restore built-in sampler.sampler_ctx: User context pointer passed to callback.
typedef int (_cdecl * cosyvoice_sampler_ext_t)(
cosyvoice_llm_token_prob_t* nucleus_probs,
int k,
float* probs,
uint32_t size,
const cosyvoice_sampling_params_t* sampling_params,
int* accepted_tokens,
uint32_t n_accepted_tokens,
void* sampler_ctx,
uint32_t worker_no
);Extended sampler callback that receives the worker slot number.
worker_no: Active worker slot index.
COSYVOICE_API void cosyvoice_get_sampler(cosyvoice_context_t ctx, cosyvoice_sampler_t* sampler, void** sampler_ctx);Returns currently configured sampler callback and context pointer.
ctx: Context handle.sampler: Output callback pointer.sampler_ctx: Output user context pointer.
COSYVOICE_API cosyvoice_builtin_sampler_rng_policy_t cosyvoice_get_builtin_sampler_rng_policy(cosyvoice_context_t ctx);Gets RNG policy used by the built-in sampler.
ctx: Context handle.
Current built-in sampler RNG policy.
COSYVOICE_API bool cosyvoice_set_builtin_sampler_rng_policy(cosyvoice_context_t ctx, cosyvoice_builtin_sampler_rng_policy_t policy);Sets built-in sampler RNG policy.
ctx: Context handle.policy: Policy to apply.
true when policy is valid and built-in sampler is active; otherwise false.
COSYVOICE_API bool cosyvoice_set_sampler_seed(cosyvoice_context_t ctx, uint32_t seed);Sets seed used by sampler RNG.
ctx: Context handle.seed: Seed value.
true if built-in sampler is currently active; otherwise false.
The seed applies to the active worker only. The seed value is stored even when a custom sampler is active and takes effect when built-in sampler is re-enabled on that worker.
COSYVOICE_API uint32_t cosyvoice_get_sampler_seed(cosyvoice_context_t ctx);Gets the active worker's built-in sampler seed.
ctx: Context handle.
Current sampler seed for the active worker.
COSYVOICE_API uint32_t cosyvoice_generate_random_seed();Generates a random 32-bit seed.
A deterministic-looking random 32-bit unsigned integer suitable for use with cosyvoice_set_sampler_seed.
COSYVOICE_API cosyvoice_prompt_speech_t cosyvoice_prompt_speech_load_from_file(const char* filename);Loads prompt-speech features from disk.
filename: Prompt-speech file path.
Prompt-speech handle on success; NULL on failure.
COSYVOICE_API cosyvoice_prompt_speech_t cosyvoice_prompt_speech_load(const void* data, size_t size);Loads prompt-speech features from a memory buffer.
data: Pointer to the prompt-speech GGUF data in memory.size: Size of the prompt-speech data in bytes.
Prompt-speech handle on success; NULL on failure.
- The data buffer must contain prompt-speech GGUF data with
feat,embedding,tokens, andtexttensors. - A CRC32 checksum is verified if present in the metadata.
- After loading, the data buffer is no longer needed and can be freed by the caller.
COSYVOICE_API bool cosyvoice_prompt_speech_save_to_file(cosyvoice_prompt_speech_t prompt_speech, const char* filename);Saves a prompt-speech object to disk.
prompt_speech: Prompt-speech handle to save.filename: Output file path.
true on success; otherwise false.
COSYVOICE_API cosyvoice_prompt_t cosyvoice_prompt_init_from_prompt_speech(cosyvoice_context_t ctx, cosyvoice_prompt_speech_t prompt_speech);Builds a prompt object for a model context from prompt-speech features.
ctx: Context handle.prompt_speech: Source prompt-speech handle.
Prompt handle on success; NULL on failure.
COSYVOICE_API void cosyvoice_prompt_speech_free(cosyvoice_prompt_speech_t prompt_speech);Releases a prompt-speech handle.
prompt_speech: Handle to free.
COSYVOICE_API void cosyvoice_prompt_free(cosyvoice_prompt_t prompt);Releases a prompt handle.
prompt: Handle to free.
COSYVOICE_API cosyvoice_tts_context_t cosyvoice_tts_context_new(cosyvoice_context_t ctx, cosyvoice_prompt_t prompt);Creates a reusable TTS session bound to a model context and initial prompt.
ctx: Context handle.prompt: Initial prompt handle.
TTS context handle on success; NULL on failure.
The created session keeps reusable runtime state tied to the specified model context and prompt, so repeated synthesis calls can avoid rebuilding the full session each time.
COSYVOICE_API void cosyvoice_tts_context_free(cosyvoice_tts_context_t ctx);Destroys a TTS session context.
ctx: TTS context handle.
COSYVOICE_API void cosyvoice_tts_context_set_prompt(cosyvoice_tts_context_t ctx, cosyvoice_prompt_t prompt);Updates the prompt used by an existing TTS session.
ctx: TTS context handle.prompt: New prompt handle.
Calling this API resets cached instruction text associated with the session.
COSYVOICE_API bool cosyvoice_tts_context_set_text_normalization_enabled(cosyvoice_tts_context_t ctx, bool enabled);Enables or disables frontend text normalization for a TTS session.
ctx: TTS context handle.enabled:trueto enable text normalization;falseto bypass normalization and tokenize raw input text directly.
true on success, false if normalization is unavailable (for example when compiled without ICU).
Text normalization is enabled by default for newly created TTS contexts.
COSYVOICE_API bool cosyvoice_tts_context_get_text_normalization_enabled(cosyvoice_tts_context_t ctx);Queries whether frontend text normalization is enabled for a TTS session.
ctx: TTS context handle.
true when text normalization is enabled; otherwise false.
COSYVOICE_API bool cosyvoice_tts_context_set_split_text_enabled(cosyvoice_tts_context_t ctx, bool enabled);Enables or disables fragment splitting for a TTS session.
ctx: TTS context handle.enabled:trueto split text into fragments before synthesis;falseto synthesize the full text in one pass.
true on success.
Text splitting is enabled by default for newly created TTS contexts.
COSYVOICE_API bool cosyvoice_tts_context_get_split_text_enabled(cosyvoice_tts_context_t ctx);Queries whether fragment splitting is enabled for a TTS session.
ctx: TTS context handle.
true when text splitting is enabled; otherwise false.
COSYVOICE_API bool cosyvoice_tts_context_set_fast_split_text_enabled(cosyvoice_tts_context_t ctx, bool enabled);Enables or disables fast token-based splitting for a TTS session.
ctx: TTS context handle.enabled:trueto enable fast split;falseto use the slower text reassembly path.
true on success.
Fast split is enabled by default for newly created TTS contexts.
COSYVOICE_API bool cosyvoice_tts_context_get_fast_split_text_enabled(cosyvoice_tts_context_t ctx);Queries whether fast token-based splitting is enabled for a TTS session.
ctx: TTS context handle.
true when fast split is enabled; otherwise false.
COSYVOICE_API bool cosyvoice_tts_context_set_fade_in_enabled(cosyvoice_tts_context_t ctx, bool enabled);Enables or disables the default output fade-in for a TTS session.
ctx: TTS context handle.enabled:trueto apply a 20 ms fade-in to generated output;falseto return raw PCM without fade-in.
true on success.
Fade-in is enabled by default for newly created TTS contexts.
COSYVOICE_API bool cosyvoice_tts_context_get_fade_in_enabled(cosyvoice_tts_context_t ctx);Queries whether output fade-in is enabled for a TTS session.
ctx: TTS context handle.
true when fade-in is enabled; otherwise false.
COSYVOICE_API uint32_t cosyvoice_tts_context_get_flags(cosyvoice_tts_context_t ctx);Gets the current TTS context flag bitmask.
ctx: TTS context handle.
A bitmask composed of COSYVOICE_TTS_FLAG_* values.
COSYVOICE_API uint32_t cosyvoice_tts_context_set_flags(cosyvoice_tts_context_t ctx, uint32_t flags);Sets the TTS context flag bitmask.
ctx: TTS context handle.flags: Requested flag bitmask.
The effective flags after masking unsupported bits.
COSYVOICE_API bool cosyvoice_tts_zero_shot(
cosyvoice_tts_context_t ctx,
const char* text,
float speed,
cosyvoice_generated_speech_ptr result
);Generates speech in zero-shot mode.
ctx: TTS context handle.text: Input text.speed: Speech speed multiplier.result: Output waveform container.
true on success; otherwise false.
Generates speech directly from text using the current session prompt.
COSYVOICE_API bool cosyvoice_tts_instruct(
cosyvoice_tts_context_t ctx,
const char* text,
const char* instruction,
float speed,
cosyvoice_generated_speech_ptr result
);Generates speech in instruct mode using explicit instruction text.
ctx: TTS context handle.text: Input text.instruction: Instruction text guiding style or behavior.speed: Speech speed multiplier.result: Output waveform container.
true on success; otherwise false.
COSYVOICE_API bool cosyvoice_tts_cross_lingual(
cosyvoice_tts_context_t ctx,
const char* text,
float speed,
cosyvoice_generated_speech_ptr result
);Generates speech in cross-lingual mode.
ctx: TTS context handle.text: Input text.speed: Speech speed multiplier.result: Output waveform container.
true on success; otherwise false.
typedef bool (*cosyvoice_tts_audio_callback_t)(const float* audio, uint32_t n_samples, void* user_data);Callback invoked by the streaming TTS API for each generated audio chunk.
audio: PCM samples in 32-bit floating point format, 1 channel.n_samples: Number of samples in this chunk.user_data: Opaque context passed when registering the callback.
true to continue streaming, false to abort synthesis.
COSYVOICE_API bool cosyvoice_tts_zero_shot_stream(
cosyvoice_tts_context_t ctx,
const char* text,
float speed,
cosyvoice_tts_audio_callback_t callback,
void* user_data
);Generates speech with streaming output in zero-shot mode. Audio chunks are delivered incrementally via the callback.
ctx: TTS context handle.text: Input text.speed: Speech speed multiplier.callback: Callback receiving each audio chunk.user_data: Opaque context passed to the callback.
true on success; otherwise false.
COSYVOICE_API bool cosyvoice_tts_instruct_stream(
cosyvoice_tts_context_t ctx,
const char* text,
const char* instruction,
float speed,
cosyvoice_tts_audio_callback_t callback,
void* user_data
);Generates speech with streaming output in instruct mode.
ctx: TTS context handle.text: Input text.instruction: Instruction text guiding style or behavior.speed: Speech speed multiplier.callback: Callback receiving each audio chunk.user_data: Opaque context passed to the callback.
true on success; otherwise false.
COSYVOICE_API bool cosyvoice_tts_cross_lingual_stream(
cosyvoice_tts_context_t ctx,
const char* text,
float speed,
cosyvoice_tts_audio_callback_t callback,
void* user_data
);Generates speech with streaming output in cross-lingual mode.
ctx: TTS context handle.text: Input text.speed: Speech speed multiplier.callback: Callback receiving each audio chunk.user_data: Opaque context passed to the callback.
true on success; otherwise false.
COSYVOICE_API bool cosyvoice_save_wav(const char* filename, const float* data, uint32_t data_len, uint32_t sample_rate);Writes floating-point PCM samples to a WAV file.
filename: Output WAV path.data: Input PCM sample buffer.data_len: Number of samples.sample_rate: Sample rate in Hz.
true on success; otherwise false.
Outputs mono 32-bit float WAV PCM data.
typedef struct cosyvoice_memory_usage
{
size_t parameters;
size_t kv_cache;
size_t token2wav;
size_t buffers;
size_t cpu_buffers;
size_t offloaded_kv_cache;
size_t random_noise;
} cosyvoice_memory_usage_t;Reports memory usage components for a loaded context.
parameters: Memory for model parameters on main device.kv_cache: Memory used by KV cache on main device.token2wav: Memory used by token2wav intermediates on main device.buffers: Internal buffer memory on main device.cpu_buffers: Host-side buffer memory.offloaded_kv_cache: KV-cache memory offloaded to CPU.random_noise: CPU memory used by random-noise buffers.
COSYVOICE_API void cosyvoice_get_memory_usage(cosyvoice_context_t ctx, cosyvoice_memory_usage_t* usage);Retrieves a snapshot of current memory usage for the context.
ctx: Context handle.usage: Output structure receiving usage values.
COSYVOICE_API void cosyvoice_get_total_memory_usage(cosyvoice_context_t ctx, cosyvoice_memory_usage_t* usage);Retrieves a snapshot of total memory usage across all workers in the context.
ctx: Context handle.usage: Output structure receiving usage values.
COSYVOICE_API void cosyvoice_empty_buffer_cache(cosyvoice_context_t ctx);Releases reusable inference buffers cached inside the context.
ctx: Context handle.
COSYVOICE_API void cosyvoice_request_stop(cosyvoice_context_t ctx);Requests the current worker's job to stop and waits for cancellation. Cleans up internal context state before returning. Must be called from a separate thread — calling from a stream callback will deadlock.
ctx: Context handle.
COSYVOICE_API bool cosyvoice_is_stop_requested(cosyvoice_context_t ctx);Checks if a stop was requested for the current worker. Returns immediately. Does NOT clear the stop flag.
ctx: Context handle.
true if a stop was requested; false otherwise.