C API

The C API in core/moonshine-c-api.h is the portable ABI that every Moonshine language binding is built on. Python, Swift, Java/Android, JavaScript/WASM, and the C++ wrapper all call into this layer so they share one implementation of speech to text, text to speech, embeddings, and related helpers. Prefer those higher-level bindings for application code; use the C API directly when you are writing a new binding, embedding Moonshine in a C or C++ project, or need the lowest-level control over handles, buffers, and model loading.

All API calls are thread-safe. Work on a single transcriber is serialized, so concurrent calls that share one handle will queue behind each other. Handles are opaque int32_t values: non-negative on success, negative error codes on failure (convert with moonshine_error_to_string()). Pass MOONSHINE_HEADER_VERSION into loaders so newer shared libraries can emulate the header you compiled against. Buffers documented as allocated with malloc must be released with moonshine_free_buffer(), not the process free, so Windows hosts linked against a different CRT stay safe.

• Constants
  • Version
  • Model architectures
  • Error codes
  • Flags
• Data Structures
  • moonshine_option_t
  • transcript_word_t
  • speaker_span_t
  • transcript_line_t
  • transcript_t
  • moonshine_speech_clip_t
  • TTS voice catalog entries
• Utilities
  • moonshine_get_version()
  • moonshine_error_to_string()
  • moonshine_free_buffer()
  • moonshine_transcript_to_string()
• Speech to Text
  • moonshine_load_transcriber_from_files()
  • moonshine_load_transcriber_from_memory_files()
  • moonshine_load_transcriber_from_memory()
  • moonshine_free_transcriber()
  • moonshine_transcriber_set_keyterms()
  • moonshine_transcriber_set_context()
  • moonshine_transcribe_without_streaming()
• Streaming Speech to Text
  • moonshine_create_stream()
  • moonshine_free_stream()
  • moonshine_start_stream()
  • moonshine_stop_stream()
  • moonshine_transcribe_add_audio_to_stream()
  • moonshine_transcribe_stream()
• Embeddings
  • moonshine_create_embedding_model()
  • moonshine_create_embedding_model_from_memory()
  • moonshine_free_embedding_model()
  • moonshine_calculate_embedding()
  • moonshine_free_embedding()
  • moonshine_calculate_embedding_distance()
• Speech Clips
  • moonshine_extract_speech_clip()
• Text to Speech
  • moonshine_create_tts_synthesizer_from_files()
  • moonshine_create_tts_synthesizer_from_memory()
  • moonshine_free_tts_synthesizer()
  • moonshine_text_to_speech()
  • moonshine_phonemes_to_speech()
  • moonshine_get_tts_dependencies()
  • moonshine_get_tts_voices()
• Grapheme to Phonemes
  • moonshine_create_grapheme_to_phonemizer_from_files()
  • moonshine_create_grapheme_to_phonemizer_from_memory()
  • moonshine_free_grapheme_to_phonemizer()
  • moonshine_text_to_phonemes()
  • moonshine_get_g2p_dependencies()
• Model Download Manifests
  • moonshine_get_stt_dependencies()
  • moonshine_get_embedding_dependencies()
  • moonshine_get_diarization_dependencies()
  • moonshine_get_stt_catalog()
  • moonshine_get_embedding_catalog()

Constants

Version

Model architectures

Error codes

Loader functions that return a handle also use negative values as errors; convert any non-success code with moonshine_error_to_string().

Flags

Data Structures

moonshine_option_t

Name/value string pairs passed to loaders and some synthesis calls. See Options for the full catalog of keys.

transcript_word_t

A single word with timing information. Empty / unused unless the word_timestamps option is enabled (identify_speakers turns that on for you). Each entry has the word itself, its start and end times in seconds, and a confidence value.

speaker_span_t

One contiguous span of speech within a line attributed to a single speaker. Only populated when the opt-in identify_speakers option is enabled (which also turns on word timestamps automatically, since they are needed to map spans onto the line text). Spans are ordered by start time and clipped to the line's time range.

Be aware that speaker spans are mutable: streaming diarization re-clusters a sliding window of recent speech (diarization_cluster_window_sec, 120 seconds by default) as more audio arrives, so spans within that window can move, merge, split, or change speaker on any transcription call — even on lines that are already complete. Assignments for audio older than the window are frozen. Watch have_speakers_changed on transcript_line_t (or the LineSpeakersChanged event in higher-level bindings) to catch revisions. Character ranges are UTF-8 byte offsets into the line text; both are zero when the span could not be aligned to words yet.

transcript_line_t

Represents a single "line" or speech segment in a transcript: timing, speaker, text, and state such as whether the speech is ongoing or done. If you're building an application that involves transcription, this structure has all of the information available about each line of speech. Be aware that each line can be updated multiple times with new text and other information as the user keeps speaking.

Memory referenced by a line is owned by the transcriber and remains valid until the next call on that transcriber, or until the transcriber is freed. Audio data is 16 kHz float PCM in [-1.0, 1.0] — useful for further processing (for example to drive a visual indicator or to feed into a specialized model after the line is complete).

Higher-level bindings map changes on these lines into events (LineStarted, LineUpdated, LineTextChanged, LineSpeakersChanged, LineCompleted); see Transcription Event Flow. Prefer those callbacks over polling the dirty flags below, because the library updates the transcript internally as you add audio chunks.

Streaming guarantees: lines are never removed, only added; only the last line may be incomplete; empty text "" means speech was detected but no transcription was produced; line indexes are stable across streaming calls; once is_complete is set, text and timing do not change again (speaker spans for recent audio are the exception when diarization is on — assignments older than diarization_cluster_window_sec are frozen).

transcript_t

An entire transcription of an audio buffer or stream: a list of transcript_line_t values. The transcript is reset whenever a stream is started fresh (or a new one-shot transcription runs), so if you need to retain information from it, make explicit copies. Most applications work through streaming updates and binding-level event callbacks rather than retaining this structure long-term.

moonshine_speech_clip_t

A short window of mostly-speech audio returned by moonshine_extract_speech_clip(), typically used as a ZipVoice cloning reference.

TTS voice catalog entries

moonshine_get_tts_voices() returns JSON rather than a C struct. Each voice row has the shape used by higher-level helpers such as get_tts_voice_catalog() / list_tts_voices():

Voice entry ({"id":"...","state":"..."}):

• id: The voice identifier string (often with a kokoro_ or piper_ prefix to pin the vocoder).
• state: Either "found" (assets present under the resolved asset root) or "missing" (listed in the catalog but not on disk yet).

By availability (the dictionary shape bindings expose from list_tts_voices()):

• present: Sorted list of voice ids that are already available under the asset root used for the query.
• downloadable: Sorted list of catalog voice ids that are not on disk yet but can be fetched (for example when a high-level TextToSpeech().load() downloads assets).

Utilities

Versioning, error strings, transcript debugging, and buffer ownership helpers used across the rest of the API.

moonshine_get_version()

Returns the loaded moonshine library version. This may be different from the header version if a newer shared library is loaded.

int32_t moonshine_get_version(void);

Returns: The loaded library version as an integer (MAJOR * 10000 + MINOR * 100 + PATCH). May differ from MOONSHINE_HEADER_VERSION if a newer shared library is loaded.

moonshine_error_to_string()

Converts an error code number returned from an API call into a human-readable string.

const char *moonshine_error_to_string(
    int32_t error
);

Returns: A human-readable string for the error code.

moonshine_free_buffer()

Frees a buffer that a moonshine_* function returned to the caller as a heap allocation. This covers, for example, out_audio_data from moonshine_text_to_speech() / moonshine_phonemes_to_speech(), the JSON / comma-separated strings from moonshine_get_tts_dependencies() / moonshine_get_g2p_dependencies() / moonshine_get_tts_voices(), and out_phonemes from moonshine_text_to_phonemes().

Always use this instead of the C runtime free directly. On Windows the library and its host (e.g. a Python binding) can be linked against different C runtimes with independent heaps, so freeing a library-allocated pointer with the host's free corrupts the heap. Routing the free back through the library guarantees the allocation and deallocation happen in the same runtime. Safe to call on NULL.

void moonshine_free_buffer(
    void *ptr
);

Returns: Nothing.

moonshine_transcript_to_string()

Converts a transcript_t struct into a human-readable string for debugging purposes. The string is owned by the library, and is valid until the next call to moonshine_transcript_to_string().

const char *moonshine_transcript_to_string(
    const struct transcript_t *transcript
);

Returns: A human-readable string describing the transcript. The string is owned by the library and stays valid until the next call to moonshine_transcript_to_string().

Speech to Text

Load a transcriber from files or memory, run one-shot transcription, set key terms, and release resources.

moonshine_load_transcriber_from_files()

Loads models from the file system, using path as the root directory. A non-streaming model directory is expected to contain:

• encoder_model.ort
• decoder_model_merged.ort
• tokenizer.bin

The .ort files are quantized-activation ONNX models converted to ORT format with the onnxruntime tools. The simplest way to obtain them is to run python scripts/download-moonshine-model.py --model-type base --model-language en. The source weights are on the Hugging Face Model Hub, and the download and conversion script is scripts/convert-moonshine-model.sh in this repository. tokenizer.bin holds the token-to-character mapping in a compact binary format; scripts/json-to-bin-vocab.py converts a common tokenizer.json into one.

The options parameter is a list of moonshine_option_t entries. See Options → Speech to Text (and shared options) for every recognized key.

int32_t moonshine_load_transcriber_from_files(
    const char *path,
    uint32_t model_arch,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    int32_t moonshine_version
);

Returns: A non-negative handle identifying the transcriber in subsequent calls, or a negative error code on failure. Convert the code with moonshine_error_to_string().

moonshine_load_transcriber_from_memory_files()

Loads a transcriber from a set of in-memory model assets keyed by their canonical filename. This is the in-memory counterpart that reaches full parity with moonshine_load_transcriber_from_files(): unlike moonshine_load_transcriber_from_memory() (which only accepts a fixed encoder/decoder/tokenizer/spelling set and rejects streaming models), this entry point accepts whatever files the chosen architecture needs, resolved by name.

filenames[i] is the canonical filename as it would appear on disk under a model directory. Recognized keys depend on model_arch:

• Non-streaming (TINY, BASE): encoder_model.ort, decoder_model_merged.ort, and tokenizer.bin are all required, plus the optional word-timestamp decoder decoder_with_attention.ort (or the two-pass alignment_model.ort) when the word_timestamps option is set.
• Streaming (*_STREAMING): frontend.ort, encoder.ort, adapter.ort, cross_kv.ort, decoder_kv.ort, streaming_config.json, and tokenizer.bin are all required, plus the optional decoder_kv_with_attention.ort when word_timestamps is set.
• Either kind also accepts spelling_cnn.ort, and the two diarization models segmentation.ort and embedding.ort, which are required when the identify_speakers option is set. Fetch those two with moonshine_get_diarization_dependencies().

Unrecognized keys are rejected with MOONSHINE_ERROR_INVALID_ARGUMENT, and missing required keys cause the load to fail. The recognized set is the union of the names above across every architecture, plus spelling_cnn_meta.json, so passing an asset this architecture or option set has no use for is fine — handing over a whole downloaded model directory works. A misspelled name is reported against the key you passed rather than surfacing later as a missing-asset failure.

When memory[i] is non-NULL and memory_sizes[i] > 0, that buffer is used as the asset bytes. The library does not copy the model buffers (the ONNX Runtime sessions read them directly), so the buffers must outlive the transcriber, exactly as for moonshine_load_transcriber_from_memory(). When memory[i] is NULL or memory_sizes[i] is zero, filenames[i] is also used as a filesystem path (relative to the current working directory unless absolute), so callers can mix in-memory and on-disk assets.

All other parameters behave as in the other transcriber loaders.

int32_t moonshine_load_transcriber_from_memory_files(
    const char **filenames,
    const uint8_t **memory,
    const uint64_t *memory_sizes,
    uint64_t file_count,
    uint32_t model_arch,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    int32_t moonshine_version
);

Returns: A non-negative transcriber handle on success, or a negative error code on failure — MOONSHINE_ERROR_INVALID_ARGUMENT when a filename key is not recognized.

moonshine_load_transcriber_from_memory()

DEPRECATED Use moonshine_load_transcriber_from_memory_files() instead. This function is deprecated and will be removed in a future version.

Callers that pass a moonshine_version of MOONSHINE_FROM_MEMORY_REMOVED_VERSION or newer are refused: the call logs an explanation and returns MOONSHINE_ERROR_INVALID_ARGUMENT without loading anything. Only clients built against an earlier header, which pass that earlier version here, can still use it.

Loads models from memory. The encoder_model_data, decoder_model_data and tokenizer_data parameters are the data arrays for the models in binary format, and are expected to be in the same format as the files disk.

spelling_model_data and spelling_model_data_size are an optional in-memory .ort payload for the alphanumeric spelling-CNN. Pass NULL and 0 if you don't want spelling fusion. When provided, the buffer must outlive the transcriber (it is not copied) and the transcriber will run spelling fusion whenever MOONSHINE_FLAG_SPELLING_MODE is passed to moonshine_transcribe_stream() or moonshine_transcribe_without_streaming().

All of the other parameters are the same as for moonshine_load_transcriber_from_files().

int32_t moonshine_load_transcriber_from_memory(
    const uint8_t *encoder_model_data,
    size_t encoder_model_data_size,
    const uint8_t *decoder_model_data,
    size_t decoder_model_data_size,
    const uint8_t *tokenizer_data,
    size_t tokenizer_data_size,
    const uint8_t *spelling_model_data,
    size_t spelling_model_data_size,
    uint32_t model_arch,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    int32_t moonshine_version
);

Returns: A non-negative transcriber handle on success, or a negative error code on failure — including MOONSHINE_ERROR_INVALID_ARGUMENT when moonshine_version is MOONSHINE_FROM_MEMORY_REMOVED_VERSION or newer.

moonshine_free_transcriber()

Releases all resources used by the transcriber. Subsequent transcriber creation calls may reuse this transcriber's ID, so ensure you remove all references to it in your client code after freeing it.

void moonshine_free_transcriber(
    int32_t transcriber_handle
);

Returns: Nothing.

moonshine_transcriber_set_keyterms()

Replaces the contextual-biasing key terms on an existing transcriber, so a caller can follow whatever context the user is in - the contact list on screen, the vocabulary of the document being dictated into - without reloading the model. keyterms is a comma-separated list using the same syntax as the keyterms load option; pass NULL or an empty string to turn biasing off.

Safe to call between transcribe calls on a live stream. Takes effect on the next transcribe call: it does not retroactively change text already emitted.

int32_t moonshine_transcriber_set_keyterms(
    int32_t transcriber_handle,
    const char *keyterms
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code if the handle is invalid or the loaded model is not a streaming architecture (only those decode through a path that can apply the bias).

moonshine_transcriber_set_context()

Picks the key terms out of a passage of free-form text and biases towards them, replacing any previous list. Where moonshine_transcriber_set_keyterms() wants a list, this wants context: hand over the document on screen, the agenda for the meeting, the last few messages in the thread, and the unusual words in it are found for you.

A word is judged unusual by how the model's own tokenizer spells it. That vocabulary is ordered by frequency, so an everyday word has a token to itself while jargon and proper nouns have to be built out of several subwords, and needing more than one is the signal used here. It follows the language of the loaded model, and the capitalization in the passage is what gets asked for in the transcript.

Safe to call between transcribe calls on a live stream. Takes effect on the next transcribe call: it does not retroactively change text already emitted.

int32_t moonshine_transcriber_set_context(
    int32_t transcriber_handle,
    const char *context,
    int32_t max_terms
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code if the handle is invalid or the loaded model is not a streaming architecture (only those decode through a path that can apply the bias).

moonshine_transcribe_without_streaming()

Given an array of PCM audio data, identifies sections of speech and transcribes them into text. This is the call to use if you're analyzing audio from a file or other static source where you have all the audio data at once. If you are transcribing audio from a live microphone or other real-time source, you should use the streaming API instead, since it offers lower latency for those use cases.

int32_t moonshine_transcribe_without_streaming(
    int32_t transcriber_handle,
    float *audio_data,
    uint64_t audio_length,
    int32_t sample_rate,
    uint32_t flags,
    struct transcript_t **out_transcript
);

Returns: Zero on success, or a non-zero error code on failure. Convert the code with moonshine_error_to_string().

Streaming Speech to Text

Create streams on a transcriber, feed live audio, and pull incremental transcripts with lower latency than one-shot transcription.

Streaming reuses work on earlier audio so results can update as new samples arrive. A single transcriber can own multiple streams. Feed audio with moonshine_transcribe_add_audio_to_stream() as often as your capture thread needs; call moonshine_transcribe_stream() on your own schedule for UI updates.

int32_t transcriber_handle = moonshine_load_transcriber_from_files(
    "path/to/models", MOONSHINE_MODEL_ARCH_BASE, NULL, 0,
    MOONSHINE_HEADER_VERSION);
int32_t stream_handle = moonshine_create_stream(transcriber_handle, 0);
moonshine_start_stream(transcriber_handle, stream_handle);

float *latest_audio_data;
size_t latest_audio_data_length;
while (get_audio_from_microphone(&latest_audio_data, &latest_audio_data_length)) {
  moonshine_transcribe_add_audio_to_stream(
      transcriber_handle, stream_handle, latest_audio_data,
      latest_audio_data_length, microphone_sample_rate, 0);
  transcript_t *partial_transcript = NULL;
  moonshine_transcribe_stream(
      transcriber_handle, stream_handle, 0, &partial_transcript);
  print_transcript(partial_transcript);
}
moonshine_stop_stream(transcriber_handle, stream_handle);

transcript_t *final_transcript = NULL;
moonshine_transcribe_stream(
    transcriber_handle, stream_handle, 0, &final_transcript);
print_transcript(final_transcript);

moonshine_free_stream(transcriber_handle, stream_handle);
moonshine_free_transcriber(transcriber_handle);

Returned transcripts are lists of lines with text, audio, timestamps, and flags such as is_updated. Use those flags as dirty markers for minimal UI updates. Updated lines appear at the end of the list; once is_complete is set, text and timing do not change again.

The exception is speaker information: when identify_speakers is enabled, speaker spans for recent audio can be revised on later moonshine_transcribe_stream() calls. Watch have_speakers_changed for those revisions.

moonshine_create_stream()

Creates a stream on an existing transcriber. The returned handle identifies the stream in subsequent calls.

int32_t moonshine_create_stream(
    int32_t transcriber_handle,
    uint32_t flags
);

Returns: A non-negative stream handle on success, or a negative error code on failure. Convert the code with moonshine_error_to_string().

moonshine_free_stream()

Releases the resources used by a stream. Subsequent stream creation calls may reuse this stream's ID, so ensure you remove all references to it in your client code after freeing it.

int32_t moonshine_free_stream(
    int32_t transcriber_handle,
    int32_t stream_handle
);

Returns: Zero on success, or a non-zero error code on failure.

moonshine_start_stream()

Starts a stream. Call this before any calls to moonshine_transcribe_stream(). Start and stop exist because the audio input can be discontinuous — when the user mutes their microphone, for example — so there needs to be a way to start fresh after a break.

int32_t moonshine_start_stream(
    int32_t transcriber_handle,
    int32_t stream_handle
);

Returns: Zero on success, or a non-zero error code on failure. Convert the code with moonshine_error_to_string().

moonshine_stop_stream()

Stops a stream.

int32_t moonshine_stop_stream(
    int32_t transcriber_handle,
    int32_t stream_handle
);

Returns: Zero on success, or a non-zero error code on failure. Convert the code with moonshine_error_to_string().

moonshine_transcribe_add_audio_to_stream()

Call this when new audio data becomes available from your microphone or other audio source. This function will add the audio data to the stream's buffer, but it will not transcribe it or do any other processing, so this should be safe to call frequently even from time-critical threads. The size of the input audio doesn't have any impact on performance, so you should call this with whatever the natural chunk size is for your audio source. It is up to you to call moonshine_transcribe_stream() when you want an updated transcript, the frequency of which should be determined by your application's latency and compute budgets.

int32_t moonshine_transcribe_add_audio_to_stream(
    int32_t transcriber_handle,
    int32_t stream_handle,
    const float *new_audio_data,
    uint64_t audio_length,
    int32_t sample_rate,
    uint32_t flags
);

Returns: Zero on success, or a non-zero error code on failure. Convert the code with moonshine_error_to_string().

moonshine_transcribe_stream()

Analyzes all the audio data in the stream and returns an updated transcript of all the speech segments found. By default this function will only perform full analysis on the audio data if there has been more than 200ms of new samples since the last complete analysis. This is to ensure that too-frequent calls to this function don't result in poor performance. This can be overridden by setting the MOONSHINE_FLAG_FORCE_UPDATE flag.

int32_t moonshine_transcribe_stream(
    int32_t transcriber_handle,
    int32_t stream_handle,
    uint32_t flags,
    struct transcript_t **out_transcript
);

Returns: Zero on success, or a non-zero error code on failure. Convert the code with moonshine_error_to_string().

Embeddings

Load a text embedding model, embed sentences, compare vectors, and free results.

moonshine_create_embedding_model()

Creates an embedding model from files on disk.

model_variant specifies which model variant to load: "fp32", "fp16", "q8", "q4", or "q4f16". Pass NULL to use the default "q4" variant.

int32_t moonshine_create_embedding_model(
    const char *model_path,
    uint32_t model_arch,
    const char *model_variant
);

Returns: A non-negative embedding model handle on success, or a negative error code on failure. Convert the code with moonshine_error_to_string().

moonshine_create_embedding_model_from_memory()

Creates an embedding model from in-memory model buffers.

This mirrors moonshine_load_transcriber_from_memory_files() and moonshine_create_tts_synthesizer_from_memory(): filenames[i] is the canonical asset filename (as listed by moonshine_get_embedding_dependencies(), e.g. model_q4.ort and tokenizer.bin) and memory[i] / memory_sizes[i] are the corresponding bytes. The embedding model must be a single self-contained all-in-one .ort file (no external-data sidecar); the tokenizer is tokenizer.bin. The library copies the bytes it needs, so the buffers only need to remain valid for the duration of this call.

int32_t moonshine_create_embedding_model_from_memory(
    uint32_t model_arch,
    const char *model_variant,
    const char **filenames,
    uint64_t filenames_count,
    const uint8_t **memory,
    const uint64_t *memory_sizes,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    int32_t moonshine_version
);

Returns: A non-negative embedding model handle on success, or a negative error code on failure.

moonshine_free_embedding_model()

Frees an embedding model and all its resources.

void moonshine_free_embedding_model(
    int32_t embedding_model_handle
);

Returns: Nothing.

moonshine_calculate_embedding()

Calculates the embedding for a given sentence.

On success, *out_embedding is set to a heap-allocated array of floats and *out_embedding_size is set to the number of elements. Release the array with moonshine_free_embedding().

int32_t moonshine_calculate_embedding(
    int32_t embedding_model_handle,
    const char *sentence,
    float **out_embedding,
    uint64_t *out_embedding_size,
    const char *model_name
);

Returns: Zero on success, or a non-zero error code on failure.

moonshine_free_embedding()

Frees an embedding returned by moonshine_calculate_embedding().

void moonshine_free_embedding(
    float *embedding
);

Returns: Nothing.

moonshine_calculate_embedding_distance()

Calculates the cosine similarity between two embedding vectors.

Both embedding_a and embedding_b must have embedding_size elements. The result is written to *out_similarity and is in the range [-1, 1] (1 = identical, 0 = orthogonal, -1 = opposite).

int32_t moonshine_calculate_embedding_distance(
    int32_t embedding_model_handle,
    const float *embedding_a,
    const float *embedding_b,
    uint64_t embedding_size,
    float *out_similarity
);

Returns: Zero on success, or a non-zero error code on failure.

Speech Clips

Extract a short, mostly-speech window from a recording for zero-shot voice cloning.

moonshine_extract_speech_clip()

Finds the best short window of speech in a recording, for use as the reference clip in zero-shot voice cloning.

Extract is VAD-only and stays cheap enough for the capture loop. When ZipVoice is later created without zipvoice_clone_transcript, the owned clone ASR (from g2p_root/clone_asr/ or clone_asr/... memory keys) refines the clip and fills the transcript once — see moonshine_get_tts_dependencies().

The returned clip is always 16 kHz mono regardless of sample_rate.

Recognised options are listed under Speech clip extract.

int32_t moonshine_extract_speech_clip(
    const float *audio_data,
    uint64_t audio_length,
    int32_t sample_rate,
    int32_t tts_synthesizer_handle,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    struct moonshine_speech_clip_t *out_clip
);

Returns: Zero on success, or a non-zero error code on failure. Success does not guarantee a clip: when no window holds at least minimum_speech_seconds of speech, out_clip->is_complete is zero and no audio is returned, so record more and call again.

Text to Speech

Create a synthesizer, list voices and download dependencies, and synthesize from text or IPA phonemes.

moonshine_create_tts_synthesizer_from_files()

Creates a text to speech synthesizer from files on disk. Pass construction options such as voice through the options array; see Options → Text to Speech. ZipVoice cloning details are on that page and under moonshine_create_tts_synthesizer_from_memory().

int32_t moonshine_create_tts_synthesizer_from_files(
    const char *language,
    const char **filenames,
    uint64_t filenames_count,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    int32_t moonshine_version
);

Returns: A non-negative synthesizer handle on success, or a negative error code on failure. Convert the code with moonshine_error_to_string().

moonshine_create_tts_synthesizer_from_memory()

Creates a text to speech synthesizer from memory.

filenames[i] is the canonical MoonshineTTSOptions::files key (e.g. kokoro/model.ort, kokoro/config.json, kokoro/voices/af_heart.kokorovoice, piper/onnx, piper/onnx.json, zipvoice/text_encoder.ort, zipvoice/fm_decoder.ort, zipvoice/vocoder.ort, zipvoice/tokens.txt, zipvoice/model.json). For ZipVoice a caller-supplied reference clip is passed as key zipvoice/clone_audio (raw little-endian float32 mono PCM); set zipvoice_clone_sample_rate and, optionally, zipvoice_clone_transcript. When the transcript is omitted, supply clone_asr/<stt-filename> keys (from the ZipVoice TTS dependency clone_asr group) so the library can refine and auto-transcribe the clip with its owned ASR. When memory[i] is non-NULL and memory_sizes[i] > 0, that buffer is used as the asset bytes; the library does not copy it—keep the buffers valid until moonshine_free_tts_synthesizer(). When memory[i] is NULL or memory_sizes[i] is zero, the key string is also used as a path relative to g2p_options.g2p_root (from options), same as path-only map entries.

Other options are parsed like moonshine_create_tts_synthesizer_from_files().

int32_t moonshine_create_tts_synthesizer_from_memory(
    const char *language,
    const char **filenames,
    const uint64_t filenames_count,
    const uint8_t **memory,
    const uint64_t *memory_sizes,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    int32_t moonshine_version
);

Returns: A non-negative synthesizer handle on success, or a negative error code on failure. Convert the code with moonshine_error_to_string().

moonshine_free_tts_synthesizer()

Releases the resources used by a text to speech synthesizer.

void moonshine_free_tts_synthesizer(
    int32_t tts_synthesizer_handle
);

Returns: Nothing.

moonshine_text_to_speech()

Synthesizes text to speech. options / options_count are optional per-call overrides; currently only speed is honored for the call duration. Pass NULL / 0 to use constructor defaults.

int32_t moonshine_text_to_speech(
    int32_t tts_synthesizer_handle,
    const char *text,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    float **out_audio_data,
    uint64_t *out_audio_data_size,
    int32_t *out_sample_rate
);

Returns: Zero on success, or a non-zero error code on failure.

moonshine_phonemes_to_speech()

Synthesizes speech directly from International Phonetic Alphabet (IPA) phonemes, skipping the grapheme-to-phoneme conversion that moonshine_text_to_speech() performs internally. phonemes should be an IPA string in the same format produced by moonshine_text_to_phonemes() (a grapheme-to-phonemizer created for the matching language). This lets callers inspect or edit the phonemes between the text-to-phonemes and phonemes-to-speech steps (e.g. to fix pronunciation of a name). The phonemes are normalized to the active vocoder's phoneme inventory before synthesis, so passing the raw moonshine_text_to_phonemes() output for the same language yields audio equivalent to moonshine_text_to_speech() on the original text.

options / options_count behave like moonshine_text_to_speech(): only speed is honored for the call; pass NULL / 0 for defaults.

int32_t moonshine_phonemes_to_speech(
    int32_t tts_synthesizer_handle,
    const char *phonemes,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    float **out_audio_data,
    uint64_t *out_audio_data_size,
    int32_t *out_sample_rate
);

Returns: Zero on success, or a non-zero error code on failure.

moonshine_get_tts_dependencies()

Returns merged G2P + TTS vocoder download dependencies as a JSON object with a groups array (same shape as moonshine_get_stt_dependencies()). Each group is { "base_url", "files": [{name,url,size,checksum,checksum_type}] }. languages is comma-separated; empty or NULL means all known languages. options / options_count: same TTS options as synthesizer create (voice, g2p_root, and related).

When voice selects ZipVoice, an additional group with "role":"clone_asr" lists the catalog-default STT for the language (including the attention decoder for word timestamps). Local names are prefixed clone_asr/; urls point at the STT CDN. Bindings should download those files under g2p_root/clone_asr/ (or pass clone_asr/... memory keys on create).

On success, *out_dependencies_json is a NUL-terminated JSON object; release with moonshine_free_buffer().

int32_t moonshine_get_tts_dependencies(
    const char *languages,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    char **out_dependencies_json
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code on failure.

moonshine_get_tts_voices()

Returns known TTS voices for the requested languages with availability state. languages is comma-separated; empty or NULL means all registered catalog languages (same tag set as G2P dependencies) that have a resolved TTS layout. options / options_count: TTS options used for listing (voice selects vocoder catalog; set g2p_root / aliases for accurate found/missing). The voice option does not filter the returned list.

On success, *out_voices_json is a NUL-terminated JSON object mapping each language tag to a JSON array of objects {"id":"<voice>","state":"found"} or {"id":"<voice>","state":"missing"}. Voice ids are prefixed with kokoro_ or piper_. Kokoro uses the upstream Kokoro-82M voice id catalog plus any extra *.kokorovoice in the bundle; Piper lists the language default voice stem plus every voice in the resolved voices directory, in either shipped form (<stem>.ort, or the split <stem>.model.ort plus <stem>.weights.ort pair). found means the asset is on disk or supplied via the in-memory file map like MoonshineTTS. Free with moonshine_free_buffer().

int32_t moonshine_get_tts_voices(
    const char *languages,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    char **out_voices_json
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code on failure.

Grapheme to Phonemes

Create a G2P engine, convert text to IPA, and list G2P asset dependencies.

moonshine_create_grapheme_to_phonemizer_from_files()

Creates a grapheme to phonemizer from files on disk.

Lexicons and bundled ONNX assets are resolved under g2p_root (or the process current working directory when g2p_root / model_root is unset) using the same canonical relative keys as MoonshineG2POptions::files in the C++ API (for example en_us/dict_filtered_heteronyms.tsv, zh_hans/roberta_chinese_base_upos_onnx/meta.json, zh_hans/roberta_chinese_base_upos_onnx/model.model.ort, en_us/g2p-config.json, en_us/oov/model.ort, en_us/oov/onnx-config.json). Japanese and Arabic tok-POS / diacritizer bundles use the same pattern under ja/... and ar_msa/.... Korean rule G2P uses ko/dict.tsv only. Models that ship as a split ORT pair need both <stem>.model.ort and <stem>.weights.ort present.

Every model is ORT-format. Moonshine cannot load a .onnx: the wasm and mobile runtimes are minimal ONNX Runtime builds with no ONNX parser compiled in. Convert one with scripts/convert-models-to-ort.py.

int32_t moonshine_create_grapheme_to_phonemizer_from_files(
    const char *language,
    const char **filenames,
    uint64_t filenames_count,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    int32_t moonshine_version
);

Returns: A non-negative phonemizer handle on success, or a negative error code on failure. Convert the code with moonshine_error_to_string().

moonshine_create_grapheme_to_phonemizer_from_memory()

Creates a grapheme to phonemizer from memory.

filenames[i] is the canonical MoonshineG2POptions::files key. When memory[i] is non-NULL and memory_sizes[i] > 0, that buffer is used as the asset bytes (not copied—keep valid until the phonemizer is freed). When memory[i] is NULL or size zero, the key is also used as a path relative to g2p_root, like path-only map entries.

Register every file the engine needs: language lexicon dict.tsv paths, English g2p-config.json and the OOV model keys under en_us/oov/, and for model bundles the meta.json, vocab.txt, tokenizer_config.json, and model.ort keys under the bundle directory key (or both halves of a split pair). English OOV overrides use oov_onnx_override for the model bytes and oov_onnx_config for the merged JSON config UTF-8 text; those key names predate the move to ORT and are kept for compatibility, but the bytes must be ORT-format.

Every model buffer must be a self-contained ORT model. Moonshine cannot load a .onnx, and there is no support for a sidecar weights file: convert with scripts/convert-models-to-ort.py.

int32_t moonshine_create_grapheme_to_phonemizer_from_memory(
    const char *language,
    const char **filenames,
    const uint64_t filenames_count,
    const uint8_t **memory,
    const uint64_t *memory_sizes,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    int32_t moonshine_version
);

Returns: A non-negative phonemizer handle on success, or a negative error code on failure. Convert the code with moonshine_error_to_string().

moonshine_free_grapheme_to_phonemizer()

Releases the resources used by a grapheme to phonemizer.

void moonshine_free_grapheme_to_phonemizer(
    int32_t grapheme_to_phonemizer_handle
);

Returns: Nothing.

moonshine_text_to_phonemes()

Converts a text into the equivalent International Phonetic Alphabet (IPA) phonemes.

int32_t moonshine_text_to_phonemes(
    int32_t grapheme_to_phonemizer_handle,
    const char *text,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    const char **out_phonemes,
    uint64_t *out_phonemes_count
);

Returns: Zero on success, or a non-zero error code on failure.

moonshine_get_g2p_dependencies()

Returns G2P-only canonical asset keys for one or more languages. languages is comma-separated CLI tags (same as moonshine_create_* language); an empty string (or NULL) means all known languages (union of keys). options / options_count: G2P options. TTS-only keys are ignored. Non-empty in-memory override values add those canonical key names to the list. On success, writes a comma-separated list to *out_dependencies_json and returns MOONSHINE_ERROR_NONE. The buffer is allocated with malloc; release with moonshine_free_buffer(). On failure (e.g. unknown language token), logs and returns a non-zero error code and sets *out_dependencies_json to NULL.

int32_t moonshine_get_g2p_dependencies(
    const char *languages,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    char **out_dependencies_json
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code on failure (for example an unknown language token).

Model Download Manifests

Ask the library which CDN files a model needs, and enumerate published STT and embedding catalogs, without hardcoding layouts in bindings.

moonshine_get_stt_dependencies()

Returns the download manifest for a speech-to-text transcription model as a JSON object. This lets language bindings and applications fetch exactly the files a model needs from the CDN (https://download.moonshine.ai) without hardcoding the file layout, then load the model from the resulting directory with moonshine_load_transcriber_from_files().

options / options_count may match the load-time list; only keys that change the file set are honored — see Download manifests.

On success, writes a NUL-terminated JSON object to *out_dependencies_json and returns MOONSHINE_ERROR_NONE. The shape is: {"groups":[{"base_url":"https://download.moonshine.ai/model/tiny-en/quantized/tiny-en","files":[{"name":"encoder_model.ort","url":"https://download.moonshine.ai/model/tiny-en/quantized/tiny-en/encoder_model.ort","size":12345,"checksum":"abc==","checksum_type":"crc32c"}, ...]}]} Each entry in files is an object with name (canonical filename), url (fully-qualified download URL, i.e. base_url + "/" + name), size (bytes, or null when unknown), checksum (base64 digest, or ""), and checksum_type (e.g. "crc32c", or ""). A model is a single group, plus an optional second group for the spelling model (which uses a different base_url). The buffer is allocated with malloc; release it with moonshine_free_buffer(). On failure (empty/unknown language, or an unknown language+arch pair) returns a non-zero error code and sets *out_dependencies_json to NULL.

int32_t moonshine_get_stt_dependencies(
    const char *language,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    char **out_dependencies_json
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code on failure (an empty or unknown language, or an unknown language and architecture pair).

moonshine_get_embedding_dependencies()

Returns the download manifest for an embedding model as a JSON object with the same shape as moonshine_get_stt_dependencies(). Load the downloaded directory with moonshine_create_embedding_model().

options / options_count accept variant / model_variant. The manifest lists the single all-in-one model file (model_<variant>.ort) and tokenizer.bin.

On success, writes a NUL-terminated JSON object to *out_dependencies_json (single group, same file-object shape as moonshine_get_stt_dependencies()) and returns MOONSHINE_ERROR_NONE; release with moonshine_free_buffer(). On failure (unknown model or variant) returns a non-zero error code and sets *out_dependencies_json to NULL.

int32_t moonshine_get_embedding_dependencies(
    const char *model_name,
    const struct moonshine_option_t *options,
    uint64_t options_count,
    char **out_dependencies_json
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code on failure (an unknown model or variant).

moonshine_get_diarization_dependencies()

Returns the download manifest for the speaker diarization models as a JSON object with the same shape as moonshine_get_stt_dependencies(). Fetch these whenever you intend to pass identify_speakers=true to a transcriber, and point the transcriber at them with the diarization_model_dir option (or supply them as segmentation.ort / embedding.ort entries to moonshine_load_transcriber_from_memory_files()).

There is one set of diarization models and it has no variants, so this takes no arguments beyond the output pointer. The manifest is a single group of two files totalling about 8.2 MB.

These models were compiled into the library before version 26.8; a transcriber built with identify_speakers=true and no diarization models now fails to load rather than falling back. See docs/diarization-models.md.

The buffer is allocated with malloc; release it with moonshine_free_buffer(). Returns MOONSHINE_ERROR_NONE on success.

int32_t moonshine_get_diarization_dependencies(
    char **out_dependencies_json
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code on failure.

moonshine_get_stt_catalog()

Returns the full speech-to-text model catalog as a JSON object, so bindings can build language/model pickers and resolve defaults without their own copy of the tables. The shape is: {"languages":[{"code":"en","english_name":"English","models":[{"model_arch":9,"download_url":"https://...","is_default":true}, ...]}, ...]} The buffer is allocated with malloc; release it with moonshine_free_buffer(). Returns MOONSHINE_ERROR_NONE on success.

int32_t moonshine_get_stt_catalog(
    char **out_catalog_json
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code on failure.

moonshine_get_embedding_catalog()

Returns the full text embedding model catalog as a JSON object. The shape is: {"models":[{"name":"embeddinggemma-300m","english_name":"Embedding Gemma 300M","download_url":"https://...","variants":["q4", ...],"default_variant":"q4"}]} The buffer is allocated with malloc; release it with moonshine_free_buffer(). Returns MOONSHINE_ERROR_NONE on success.

int32_t moonshine_get_embedding_catalog(
    char **out_catalog_json
);

Returns: MOONSHINE_ERROR_NONE on success, or a non-zero error code on failure.