eeh-1 / include /eeh.h
ctrltokyo's picture
Ship the Rust engine: Python wheels, CLI, C library, WASM demo
cba22ce verified
Raw History Blame Contribute Delete
7.07 kB
/* eeh C API. Generated by cbindgen from rust/crates/eeh-ffi (generate-header.sh); do not edit. */
#ifndef EEH_H
#define EEH_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
/**
* Result of a call. `EEH_STATUS_OK` is 0.
*/
typedef enum {
/**
* Success.
*/
EEH_STATUS_OK = 0,
/**
* A pointer was null or a string was not UTF-8.
*/
EEH_STATUS_INVALID_ARGUMENT = 1,
/**
* No sentence of the text could be read (eeh only reads Japanese for now).
*/
EEH_STATUS_NOTHING_TO_PRONOUNCE = 2,
/**
* The voice is not one of the model's.
*/
EEH_STATUS_UNKNOWN_VOICE = 3,
/**
* The dictionary is malformed, or the text could not be analysed.
*/
EEH_STATUS_FRONTEND = 4,
/**
* The weights are malformed or an option is out of range.
*/
EEH_STATUS_MODEL = 5,
/**
* Anything else, e.g. a word too long to speak or non-finite audio.
*/
EEH_STATUS_OTHER = 6,
/**
* An internal panic was caught; the call had no effect.
*/
EEH_STATUS_PANIC = 7,
} EehStatus;
/**
* An error: a code and a message. Opaque to C; read it with `eeh_error_code` and `eeh_error_message`.
*/
typedef struct EehError EehError;
/**
* A synthesizer and the voice names as C strings.
*/
typedef struct EehSynthesizer EehSynthesizer;
/**
* Options of a call; `NULL` for all defaults (see `eeh_options_default`).
*/
typedef struct {
/**
* Speaking rate, 0.25 to 4 (1 = as predicted, larger is faster).
*/
float speed;
/**
* Added to log F0 (0.058 is about one semitone).
*/
float pitch_shift;
/**
* Scales the pitch movement, 0 to 3 (1 = as predicted).
*/
float pitch_range;
/**
* Seed of the noise; sentence `i` uses `seed + i`.
*/
uint64_t seed;
/**
* The loudest sample of the audio: louder audio is scaled down to it. Zero or less (or NaN) leaves
* the model's output as it is. In `eeh_speak_each` each sentence is limited on its own.
*/
float peak;
} EehOptions;
/**
* Called by `eeh_speak_each` for each sentence: its text (NUL-terminated UTF-8) and `len` samples at
* `audio`, both valid only during the call. Return `false` to stop.
*/
typedef bool (*EehUtteranceCallback)(const char *text,
const float *audio,
size_t len,
void *user_data);
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* The version of the library, e.g. `"0.1.0"`. Static; never freed.
*/
const char *eeh_version(void);
/**
* Writes the default options (speed 1, no pitch change, seed 0, peak 0.99) to `*options`.
*
* # Safety
* `options` is null or points to writable memory for an `EehOptions`.
*/
void eeh_options_default(EehOptions *options);
/**
* Loads a synthesizer from the bytes of the weights file (safetensors) and of the packed dictionary
* (both are copied or parsed during the call; the buffers may be freed afterwards).
*
* Returns `NULL` on failure, with `*err` set when `err` is not `NULL`. Free the result with
* `eeh_synthesizer_free` and the error with `eeh_error_free`. A synthesizer can be used from
* several threads at once.
*
* # Safety
* Each buffer is `NULL` or has that many readable bytes; `err` is `NULL` or points to a writable `EehError*`.
*/
EehSynthesizer *eeh_synthesizer_new(const uint8_t *weights,
size_t weights_len,
const uint8_t *dictionary,
size_t dictionary_len,
EehError **err);
/**
* Frees a synthesizer. `NULL` is fine. No other call may use it at the same time or after.
*
* # Safety
* `synth` is `NULL` or came from `eeh_synthesizer_new` and is not freed twice.
*/
void eeh_synthesizer_free(EehSynthesizer *synth);
/**
* Sample rate of the audio in Hz; 0 when `synth` is `NULL`.
*
* # Safety
* `synth` is `NULL` or a live synthesizer.
*/
uint32_t eeh_sample_rate(const EehSynthesizer *synth);
/**
* Number of voices of the model; 0 when `synth` is `NULL`.
*
* # Safety
* `synth` is `NULL` or a live synthesizer.
*/
size_t eeh_voice_count(const EehSynthesizer *synth);
/**
* Name of voice `index` (e.g. `"F1"`), valid until the synthesizer is freed; `NULL` when out of range.
*
* # Safety
* `synth` is `NULL` or a live synthesizer.
*/
const char *eeh_voice_name(const EehSynthesizer *synth,
size_t index);
/**
* Speaks `utf8` (NUL-terminated) in `voice` and returns all the audio.
*
* On success `*audio` points to `*len` samples (mono, `eeh_sample_rate` Hz, `float`) that the caller frees with `eeh_audio_free(*audio, *len)`.
* `options` may be `NULL`. Returns `EEH_STATUS_OK` or an error code, with `*err` set when `err` is not
* `NULL` (free it with `eeh_error_free`); `*audio` is `NULL` and `*len` 0 on failure.
*
* # Safety
* `synth` is live; `utf8` and `voice` are NUL-terminated strings; `options` is `NULL` or readable;
* `audio` and `len` are writable; `err` is `NULL` or points to a writable `EehError*`.
*/
EehStatus eeh_speak(const EehSynthesizer *synth,
const char *utf8,
const char *voice,
const EehOptions *options,
float **audio,
size_t *len,
EehError **err);
/**
* Like `eeh_speak`, but hands each sentence to `callback` as soon as it is made (streaming).
*
* The audio is only valid during the callback. The callback returns `false` to stop early (the result is then
* still `EEH_STATUS_OK`). It runs on the calling thread and must not call back into the same
* synthesizer's `eeh_synthesizer_free`.
*
* # Safety
* As `eeh_speak`; `callback` is a valid function and `user_data` whatever it expects.
*/
EehStatus eeh_speak_each(const EehSynthesizer *synth,
const char *utf8,
const char *voice,
const EehOptions *options,
EehUtteranceCallback callback,
void *user_data,
EehError **err);
/**
* Frees audio from `eeh_speak`; `len` is the length it returned. `NULL` is fine.
*
* # Safety
* `audio` is `NULL` or the pointer and `len` the length `eeh_speak` returned, not freed twice.
*/
void eeh_audio_free(float *audio, size_t len);
/**
* The message of an error (NUL-terminated UTF-8), valid until `eeh_error_free`; `""` for `NULL`.
*
* # Safety
* `error` is `NULL` or a live error.
*/
const char *eeh_error_message(const EehError *error);
/**
* The status code of an error; `EEH_STATUS_INVALID_ARGUMENT` for `NULL`.
*
* # Safety
* `error` is `NULL` or a live error.
*/
EehStatus eeh_error_code(const EehError *error);
/**
* Frees an error. `NULL` is fine.
*
* # Safety
* `error` is `NULL` or came from this library and is not freed twice.
*/
void eeh_error_free(EehError *error);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif /* EEH_H */