File size: 7,066 Bytes
cba22ce
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
/* 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 */