This page documents all public symbols declared in include/cosyvoice-lowlevel.h.
typedef struct cosyvoice_tokenization_result* cosyvoice_tokenization_result_t;Opaque handle to a tokenization-result container.
typedef struct cosyvoice_tokenizer_context* cosyvoice_tokenizer_context_t;Opaque handle to a tokenizer context.
typedef enum cosyvoice_inference_mode
{
COSYVOICE_INFERENCE_MODE_NULL = -1,
COSYVOICE_INFERENCE_MODE_ZERO_SHOT,
COSYVOICE_INFERENCE_MODE_INSTRUCT,
COSYVOICE_INFERENCE_MODE_CROSS_LINGUAL,
COSYVOICE_INFERENCE_MODE_COUNT
} cosyvoice_inference_mode_t;Prompt-update mode used by low-level prompt APIs.
COSYVOICE_INFERENCE_MODE_NULL: No update; useful when duplicating prompts.COSYVOICE_INFERENCE_MODE_ZERO_SHOT: Zero-shot generation.COSYVOICE_INFERENCE_MODE_INSTRUCT: Instruction-following generation.COSYVOICE_INFERENCE_MODE_CROSS_LINGUAL: Cross-lingual generation that ignores prompt instruction text.COSYVOICE_INFERENCE_MODE_COUNT: Sentinel value.
typedef enum cosyvoice_noise_callback_stage
{
COSYVOICE_NOISE_CALLBACK_STAGE_BEFORE_FLOW,
COSYVOICE_NOISE_CALLBACK_STAGE_AFTER_FLOW,
COSYVOICE_NOISE_CALLBACK_STAGE_BEFORE_HIFT,
COSYVOICE_NOISE_CALLBACK_STAGE_AFTER_HIFT
} cosyvoice_noise_callback_stage_t;Indicates which Flow/HiFT stage triggered the noise callback.
COSYVOICE_NOISE_CALLBACK_STAGE_BEFORE_FLOW: Called before Flow; callback must provide noise buffer.COSYVOICE_NOISE_CALLBACK_STAGE_AFTER_FLOW: Called after Flow; return value ignored.COSYVOICE_NOISE_CALLBACK_STAGE_BEFORE_HIFT: Called before HiFT; callback must provide noise buffer.COSYVOICE_NOISE_CALLBACK_STAGE_AFTER_HIFT: Called after HiFT; return value ignored.
typedef float* (*cosyvoice_noise_callback_t)(
cosyvoice_noise_callback_stage_t stage,
uint32_t length,
float* noise,
void* ctx
);Callback for observing or overriding random-noise buffers.
stage: Callback stage.length: Required number of float samples.noise: Null forBEFORE_*; previous buffer forAFTER_*.ctx: User context.
Buffer to use for BEFORE_* calls; ignored for AFTER_* calls.
COSYVOICE_API void cosyvoice_log_callback_default(enum ggml_log_level level, const char* text, void* user_data);Default GGML log callback used by runtime.
level: GGML log level.text: Log message.user_data: Caller-provided context.
No return value.
COSYVOICE_API cosyvoice_context_t cosyvoice_load_from_file_ext(
const char* filename,
const cosyvoice_context_params_t* params,
ggml_backend_t backend,
uint32_t n_threads,
uint32_t params_version
);Loads model context with explicit backend and threading parameters.
filename: Model path.params: Context parameters. Whenparams_versionselects an extended layout, pass a pointer to the embeddedbase_paramsmember (it is the first member, so the struct address works too).backend: Optional backend handle. If non-null, ownership is transferred to the created context.n_threads: CPU thread count; set0to use hardware concurrency when available.params_version: Context-parameters version.COSYVOICE_CONTEXT_PARAMS_VERSION(0) —cosyvoice_context_params_t;COSYVOICE_CONTEXT_PARAMS_V2_VERSION(1) —cosyvoice_context_params_v2_t;COSYVOICE_CONTEXT_PARAMS_V3_VERSION(2) —cosyvoice_context_params_v3_t.
Context handle on success; NULL on failure.
- This API is available in both shared and static GGML builds.
backend == NULLmeans auto-select backend.- If
backend != NULL, ownership is transferred to the created context and released bycosyvoice_free(). - In C++, a template overload of this function (4 arguments, no
params_version) deduces the version from the static type ofparams— it acceptscosyvoice_context_params_t,..._v2_t,..._v3_t, and the flat C++ variants..._v2_cpp/..._v3_cpp.
COSYVOICE_API cosyvoice_context_t cosyvoice_load_ext(
const void* data,
size_t size,
const cosyvoice_context_params_t* params,
ggml_backend_t backend,
uint32_t n_threads,
uint32_t params_version
);Loads a model context from a memory buffer with explicit backend, threading, and context parameters.
data: Pointer to the model GGUF data in memory.size: Size of the model data in bytes.params: Context parameters.backend: Optional backend handle. If non-null, ownership is transferred to the created context.n_threads: CPU thread count; set0to use hardware concurrency when available.params_version: Context parameters version.COSYVOICE_CONTEXT_PARAMS_VERSION(0) forcosyvoice_context_params_t,COSYVOICE_CONTEXT_PARAMS_V2_VERSION(1) forcosyvoice_context_params_v2_t,COSYVOICE_CONTEXT_PARAMS_V3_VERSION(2) forcosyvoice_context_params_v3_t(pass the embedded base pointer).
Context handle on success; NULL on failure.
backend == NULLselects the default backend.- If
backend != NULL, backend ownership is transferred to the created context and released bycosyvoice_free(). - After loading, the data buffer is no longer needed and can be freed by the caller.
- When
n_threadsis0, the library uses hardware concurrency divided by the number of workers.
COSYVOICE_API enum ggml_status cosyvoice_get_last_status(cosyvoice_context_t ctx);Gets status code from the most recent backend operation.
ctx: Context handle.
enum ggml_status value.
COSYVOICE_API const ggml_tensor* cosyvoice_get_word_token_embed_weight(cosyvoice_context_t ctx);Returns word-token embedding tensor.
ctx: Context handle.
Read-only tensor pointer.
COSYVOICE_API const ggml_tensor* cosyvoice_get_speech_token_embed_weight(cosyvoice_context_t ctx);Returns speech-token embedding tensor.
ctx: Context handle.
Read-only tensor pointer.
COSYVOICE_API bool cosyvoice_llm_prefill(
cosyvoice_context_t ctx,
enum ggml_type type,
const void* data,
uint32_t n_tokens
);Prefills LLM with a sequence of token embeddings.
ctx: Context handle.type: Input element type.data: Embedding buffer.n_tokens: Token count.
true on success; otherwise false.
Does not compute next-token logits.
COSYVOICE_API bool cosyvoice_llm_decode(
cosyvoice_context_t ctx,
enum ggml_type type,
const void* data
);Runs one decode step and updates internal logits.
ctx: Context handle.type: Input element type.data: Embedding vector.
true on success; otherwise false.
This function only advances decode state. Call cosyvoice_llm_prepare_probs() before cosyvoice_llm_sample_token().
COSYVOICE_API void cosyvoice_llm_prepare_probs(cosyvoice_context_t ctx, bool allow_stop_tokens);Prepares sampling probabilities from the latest decode output.
ctx: Context handle.allow_stop_tokens: Iffalse, stop tokens are masked to zero probability.
No return value.
Call this after each successful cosyvoice_llm_decode() and before cosyvoice_llm_sample_token().
COSYVOICE_API uint32_t cosyvoice_llm_get_kv_cache_len(cosyvoice_context_t ctx);Gets current KV-cache token length.
ctx: Context handle.
Current KV length.
COSYVOICE_API bool cosyvoice_llm_set_kv_cache_len(cosyvoice_context_t ctx, uint32_t len);Trims current KV-cache length.
ctx: Context handle.len: Target length.
true on success; otherwise false.
len must be less than or equal to the current length.
COSYVOICE_API void cosyvoice_llm_offload_kv_cache(cosyvoice_context_t ctx);Offloads the LLM KV cache from device memory to CPU memory.
ctx: Context handle.
COSYVOICE_API void cosyvoice_llm_load_kv_cache(cosyvoice_context_t ctx);Loads the LLM KV cache from CPU memory back to the backend device.
ctx: Context handle.
COSYVOICE_API int cosyvoice_llm_sample_token(cosyvoice_context_t ctx);Samples next token from current logits.
ctx: Context handle.
Sampled token id.
COSYVOICE_API bool cosyvoice_llm_is_stop_token(cosyvoice_context_t ctx, int token_id);Checks whether token id is a stop token.
ctx: Context handle.token_id: Token id.
true if stop token; otherwise false.
COSYVOICE_API void cosyvoice_llm_accept_token(cosyvoice_context_t ctx, int token_id);Accepts token into generated sequence.
ctx: Context handle.token_id: Token id.
No return value.
COSYVOICE_API void cosyvoice_llm_clear_accepted_tokens(cosyvoice_context_t ctx);Clears accepted-token history.
ctx: Context handle.
No return value.
COSYVOICE_API uint32_t cosyvoice_llm_get_n_accepted_tokens(cosyvoice_context_t ctx);Gets number of accepted tokens.
ctx: Context handle.
Accepted-token count.
COSYVOICE_API const int* cosyvoice_llm_get_accepted_tokens(cosyvoice_context_t ctx);Gets pointer to accepted-token buffer.
ctx: Context handle.
Read-only pointer to token id array.
COSYVOICE_API bool cosyvoice_llm_job(
cosyvoice_context_t ctx,
const int* text,
uint32_t text_len,
cosyvoice_prompt_t prompt
);Runs low-level LLM generation for tokenized text and prompt.
ctx: Context handle.text: Text token ids.text_len: Number of tokens intext.prompt: Prompt handle.
true on success; otherwise false.
COSYVOICE_API bool cosyvoice_llm_job_ext(
cosyvoice_context_t ctx,
const int* text,
uint32_t text_len,
cosyvoice_prompt_t prompt,
uint32_t max_new_tokens,
bool* final
);Runs low-level LLM generation with additional options.
ctx: Context handle.text: Text token ids.text_len: Number of tokens intext.prompt: Prompt handle.max_new_tokens: Maximum number of new tokens to generate. If 0, no new tokens are generated.final: Output parameter indicating whether the generation is complete (true) or more tokens can be generated (false).
true on success; otherwise false.
COSYVOICE_API bool cosyvoice_token2wav(
cosyvoice_context_t ctx,
const int* token_ids,
uint32_t n_tokens,
float speed,
cosyvoice_prompt_t prompt,
cosyvoice_generated_speech_ptr generated_speech
);Converts speech tokens to waveform.
ctx: Context handle.token_ids: Speech token ids.n_tokens: Number of speech tokens.speed: Speech speed multiplier.prompt: Prompt handle.generated_speech: Output waveform container.
true on success; otherwise false.
COSYVOICE_API bool cosyvoice_token2wav_ext(
cosyvoice_context_t ctx,
const int* token_ids,
uint32_t n_tokens,
float speed,
cosyvoice_prompt_t prompt,
bool streaming,
bool finalize,
cosyvoice_generated_speech_ptr result
);Converts speech tokens to waveform with additional options.
ctx: Context handle.token_ids: Speech token ids.n_tokens: Number of speech tokens.speed: Speech speed multiplier.prompt: Prompt handle.streaming: If true, convert incrementally (partial chunks).finalize: If true, flush and finalize the output.result: Output waveform container.
true on success; otherwise false.
COSYVOICE_API bool cosyvoice_tts(
cosyvoice_context_t ctx,
const int* text,
uint32_t text_len,
float speed,
cosyvoice_prompt_t prompt,
cosyvoice_generated_speech_ptr result
);Runs full low-level text-to-speech pipeline.
ctx: Context handle.text: Text token ids.text_len: Number of text tokens.speed: Speech speed multiplier.prompt: Prompt handle.result: Output waveform container.
true on success; otherwise false.
Runs LLM generation and waveform conversion as a single convenience pipeline.
COSYVOICE_API bool cosyvoice_tts_stream(
cosyvoice_context_t ctx,
const int* text,
uint32_t text_len,
float speed,
cosyvoice_prompt_t prompt,
cosyvoice_tts_audio_callback_t callback,
void* user_data
);Runs full low-level text-to-speech pipeline with streaming output. Audio chunks are delivered incrementally via the callback.
ctx: Context handle.text: Text token ids.text_len: Number of text tokens.speed: Speech speed multiplier.prompt: Prompt handle.callback: Callback receiving each audio chunk.user_data: Opaque context passed to the callback.
true on success; otherwise false.
COSYVOICE_API cosyvoice_tokenizer_context_t cosyvoice_get_tokenizer(cosyvoice_context_t ctx);Borrows tokenizer owned by model context.
ctx: Context handle.
Tokenizer handle owned by context.
This handle is borrowed from the model context.
COSYVOICE_API cosyvoice_tokenizer_context_t cosyvoice_tokenizer_load_from_file(const char* filename);Loads standalone tokenizer from file.
filename: Model/tokenizer file path.
Tokenizer handle on success; NULL on failure.
COSYVOICE_API cosyvoice_tokenizer_context_t cosyvoice_tokenizer_load(const void* data, size_t size);Loads standalone tokenizer from a memory buffer.
data: Pointer to model GGUF data in memory.size: Size of the data buffer in bytes.
Tokenizer handle on success; NULL on failure.
- The data buffer can be freed after loading.
COSYVOICE_API void cosyvoice_tokenizer_free(cosyvoice_tokenizer_context_t ctx);Frees standalone tokenizer context.
ctx: Tokenizer handle.
No return value.
Use this only for standalone tokenizers created by cosyvoice_tokenizer_load_from_file or cosyvoice_tokenizer_load.
COSYVOICE_API cosyvoice_tokenization_result_t cosyvoice_tokenization_result_create();Creates empty tokenization-result container.
Result handle on success; NULL on failure.
COSYVOICE_API void cosyvoice_tokenization_result_free(cosyvoice_tokenization_result_t result);Frees tokenization-result container.
result: Result handle.
No return value.
COSYVOICE_API int* cosyvoice_tokenization_result_get_tokens(cosyvoice_tokenization_result_t result);Gets mutable token buffer.
result: Result handle.
Pointer to token id array.
COSYVOICE_API uint32_t cosyvoice_tokenization_result_get_n_tokens(cosyvoice_tokenization_result_t result);Gets number of tokens in a tokenization result.
result: Result handle.
Token count.
COSYVOICE_API uint32_t cosyvoice_tokenize(
cosyvoice_tokenizer_context_t ctx,
const char* text,
cosyvoice_tokenization_result_t result,
bool parse_special
);Tokenizes null-terminated UTF-8 string.
ctx: Tokenizer handle.text: Input UTF-8 string.result: Output result container.parse_special: Whether to parse special tokens.
Number of tokens written.
COSYVOICE_API uint32_t cosyvoice_tokenize_ext(
cosyvoice_tokenizer_context_t ctx,
const char* text,
uint32_t text_len,
cosyvoice_tokenization_result_t result,
bool parse_special
);Tokenizes UTF-8 text with explicit byte length.
ctx: Tokenizer handle.text: Input UTF-8 data.text_len: Byte length oftext.result: Output result container.parse_special: Whether to parse special tokens.
Number of tokens written.
COSYVOICE_API void cosyvoice_set_noise_callback(cosyvoice_context_t ctx, cosyvoice_noise_callback_t callback, void* callback_ctx);Registers callback for noise-buffer observation/override.
ctx: Context handle.callback: Callback function.callback_ctx: Callback context pointer.
No return value.
COSYVOICE_API void cosyvoice_get_noise_callback(cosyvoice_context_t ctx, cosyvoice_noise_callback_t* callback, void** callback_ctx);Gets currently registered noise callback and context.
ctx: Context handle.callback: Output callback pointer.callback_ctx: Output context pointer.
No return value.
COSYVOICE_API uint32_t cosyvoice_get_chunk_tokens(cosyvoice_context_t ctx);Gets the number of tokens processed in each chunk during streaming inference.
ctx: Context handle.
Current chunk token count.
COSYVOICE_API uint32_t cosyvoice_get_hift_rand_ini_len(cosyvoice_context_t ctx);Gets required length of HiFT initialization noise buffer.
ctx: Context handle.
Required sample count.
COSYVOICE_API void cosyvoice_set_chunk_tokens(cosyvoice_context_t ctx, uint32_t n_tokens);Sets the number of tokens processed in each chunk during streaming inference.
ctx: Context handle.n_tokens: Number of tokens per chunk. Smaller values reduce first-chunk latency but increase overhead; larger values reduce RTF but increase first-chunk latency.
COSYVOICE_API void cosyvoice_set_hift_rand_ini(cosyvoice_context_t ctx, const float* data);Overrides HiFT initialization noise buffer.
ctx: Context handle.data: Noise buffer pointer.
No return value.
COSYVOICE_API uint32_t cosyvoice_prompt_speech_get_crc32(cosyvoice_prompt_speech_t prompt_speech);Computes CRC32 for prompt-speech object.
prompt_speech: Prompt-speech handle.
CRC32 value.
COSYVOICE_API uint32_t cosyvoice_prompt_get_crc32(cosyvoice_prompt_t prompt);Computes CRC32 for prompt object.
prompt: Prompt handle.
CRC32 value.
COSYVOICE_API const char* cosyvoice_get_instruction_prefix(cosyvoice_context_t ctx);Gets instruction prefix expected by current model.
ctx: Context handle.
Null-terminated UTF-8 prefix string.
COSYVOICE_API cosyvoice_prompt_t cosyvoice_prompt_set(
cosyvoice_context_t ctx,
cosyvoice_prompt_t prompt,
cosyvoice_inference_mode_t mode,
const char* instruction,
#ifdef __cplusplus
uint32_t instruction_length = 0xFFFFFFFFU,
bool inplace = true
#else
uint32_t instruction_length,
bool inplace
#endif
);Sets prompt mode and instruction text using raw text input.
ctx: Context handle.prompt: Prompt handle to update.mode: Inference mode.instruction: Instruction text.instruction_length: Instruction length in bytes.inplace: Whether to modify input prompt in place.
Updated prompt handle.
Instruction prefix is not prepended automatically.
COSYVOICE_API cosyvoice_prompt_t cosyvoice_prompt_set_ext(
cosyvoice_context_t ctx,
cosyvoice_prompt_t prompt,
cosyvoice_inference_mode_t mode,
const int* instruction,
uint32_t instruction_length,
bool inplace
);Sets prompt mode and instruction content from tokenized input.
ctx: Context handle.prompt: Prompt handle to update.mode: Inference mode.instruction: Tokenized instruction ids.instruction_length: Number of instruction tokens.inplace: Whether to update existing prompt.
Updated prompt handle.
This API does not prepend instruction prefix and does not append <|endofprompt|> automatically.