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
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
|
/*
* Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file picoapi.h
*
* SVOX Pico application programming interface
* (SVOX Pico version 1.0 and later)
*
* Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
* All rights reserved.
*
* History:
* - 2009-04-20 -- initial version
*/
/**
* @addtogroup picoapi
*
@b Basic_Concepts
@e SVOX_Pico_System
The SVOX Pico 'system' is the entity that manages data common to all
SVOX Pico engines, e.g. linguistic data needed to do text-to-speech
(TTS) synthesis, license key, etc. All API functions on the Pico
system level take a 'pico_System' handle as the first parameter.
@e SVOX_Pico_Engine
A SVOX Pico 'engine' provides the functions needed to perform actual
synthesis. Currently there can be only one engine instance at a time
(concurrent engines will be possible in the future). All API functions
at the engine level take a 'pico_Engine' handle as the first
parameter.
@e SVOX_Pico_Resource
A SVOX Pico 'resource' denotes all the language- and speaker-dependent
data needed to do TTS synthesis. In the following, the term 'resource'
may be used interchangeably with the term 'lingware'. A resource file
contains a set of knowledge bases for an entire TTS voice or parts of
it.
@b Basic_Usage
In its most basic form, an application must call the following
functions in order to perform TTS synthesis:
- pico_initialize
- pico_loadResource
- pico_createVoiceDefinition
- pico_addResourceToVoiceDefinition
- pico_newEngine
- pico_putTextUtf8
- pico_getData (several times)
- pico_disposeEngine
- pico_releaseVoiceDefinition
- pico_unloadResource
- pico_terminate
It is possible to repeatedly run the above sequence, i.e., the SVOX
Pico system may be initialized and terminated multiple times. This may
be useful in applications that need TTS functionality only from time
to time.
@b Conventions
@e Function_arguments
All arguments that only return values are marked by a leading 'out...'
in their name. All arguments that are used as input and output values
are marked by a leading 'inout...'. All other arguments are read-only
(input) arguments.
@e Error_handling
All API functions return a status code which is one of the status
constants defined in picodefs.h. In case of an error, a more detailed
description of the status can be retrieved by calling function
'pico_getSystemStatusMessage' (or 'pico_getEngineStatusMessage'
if the error happened on the SVOX Pico engine level).
Unlike errors, warnings do not prevent an API function from performing
its function, but output might not be as intended. Functions
'pico_getNrSystemWarnings' and 'pico_getNrEngineWarnings' respectively
can be used to determine whether an API function caused any
warnings. Details about warnings can be retrieved by calling
'pico_getSystemWarning' and 'pico_getEngineWarning' respectively.
*/
#ifndef PICOAPI_H_
#define PICOAPI_H_
#include "picodefs.h"
#ifdef __cplusplus
extern "C" {
#endif
#if 0
}
#endif
#ifdef _WIN32
# define PICO_EXPORT __declspec( dllexport )
#else
# define PICO_EXPORT extern
#endif
#define PICO_FUNC PICO_EXPORT pico_Status
/* ********************************************************************/
/* PICO data types */
/* ********************************************************************/
/* Handle types (opaque) for Pico system, resource, engine ************/
typedef struct pico_system *pico_System;
typedef struct pico_resource *pico_Resource;
typedef struct pico_engine *pico_Engine;
/* Signed/unsigned integer data types *********************************/
#define PICO_INT16_MAX 32767
#define PICO_UINT16_MAX 0xffff
#define PICO_INT32_MAX 2147483647
#define PICO_UINT32_MAX 0xffffffff
#include <limits.h>
#if (SHRT_MAX == PICO_INT16_MAX)
typedef short pico_Int16;
#else
#error "platform not supported"
#endif
#if (USHRT_MAX == PICO_UINT16_MAX)
typedef unsigned short pico_Uint16;
#else
#error "platform not supported"
#endif
#if (INT_MAX == PICO_INT32_MAX)
typedef int pico_Int32;
#else
#error "platform not supported"
#endif
#if (UINT_MAX == PICO_UINT32_MAX)
typedef unsigned int pico_Uint32;
#else
#error "platform not supported"
#endif
/* Char data type *****************************************************/
typedef unsigned char pico_Char;
/* String type to be used when ASCII string values are returned *******/
#define PICO_RETSTRINGSIZE 200 /* maximum length of returned strings */
typedef char pico_Retstring[PICO_RETSTRINGSIZE];
/* ********************************************************************/
/* System-level API functions */
/* ********************************************************************/
/* System initialization and termination functions ********************/
/**
Initializes the Pico system and returns its handle in 'outSystem'.
'memory' and 'size' define the location and maximum size of memory
in number of bytes that the Pico system will use. The minimum size
required depends on the number of engines and configurations of
lingware to be used. No additional memory will be allocated by the
Pico system. This function must be called before any other API
function is called. It may only be called once (e.g. at application
startup), unless a call to 'pico_terminate'.
*/
PICO_FUNC pico_initialize(
void *memory,
const pico_Uint32 size,
pico_System *outSystem
);
/**
Terminates the Pico system. Lingware resources still being loaded
are unloaded automatically. The memory area provided to Pico in
'pico_initialize' is released. The system handle becomes
invalid. It is not allowed to call this function as long as Pico
engine instances are existing. No API function may be called after
this function, except for 'pico_initialize', which reinitializes
the system.
*/
PICO_FUNC pico_terminate(
pico_System *system
);
/* System status and error/warning message retrieval ******************/
/**
Returns in 'outMessage' a description of the system status or of an
error that occurred with the most recently called system-level API
function.
*/
PICO_FUNC pico_getSystemStatusMessage(
pico_System system,
pico_Status errCode,
pico_Retstring outMessage
);
/**
Returns in 'outNrOfWarnings' the number of warnings that occurred
with the most recently called system-level API function.
*/
PICO_FUNC pico_getNrSystemWarnings(
pico_System system,
pico_Int32 *outNrOfWarnings
);
/**
Returns in 'outMessage' a description of a warning that occurred
with the most recently called system-level API function.
'warningIndex' must be in the range 0..N-1 where N is the number of
warnings returned by 'pico_getNrSystemWarnings'. 'outCode' returns
the warning as an integer code (cf. PICO_WARN_*).
*/
PICO_FUNC pico_getSystemWarning(
pico_System system,
const pico_Int32 warningIndex,
pico_Status *outCode,
pico_Retstring outMessage
);
/* Resource loading and unloading functions ***************************/
/**
Loads a resource file into the Pico system. The number of resource
files loaded in parallel is limited by PICO_MAX_NUM_RESOURCES.
Loading of a resource file may be done at any time (even in
parallel to a running engine doing TTS synthesis), but with the
general restriction that functions taking a system handle as their
first argument must be called in a mutually exclusive fashion. The
loaded resource will be available only to engines started after the
resource is fully loaded, i.e., not to engines currently
running.
*/
PICO_FUNC pico_loadResource(
pico_System system,
const pico_Char *resourceFileName,
pico_Resource *outResource
);
/**
Unloads a resource file from the Pico system. If no engine uses the
resource file, the resource is removed immediately and its
associated internal memory is released, otherwise
PICO_EXC_RESOURCE_BUSY is returned.
*/
PICO_FUNC pico_unloadResource(
pico_System system,
pico_Resource *inoutResource
);
/* *** Resource inspection functions *******************************/
/**
Gets the unique resource name of a loaded resource
*/
PICO_FUNC pico_getResourceName(
pico_System system,
pico_Resource resource,
pico_Retstring outName);
/* Voice definition ***************************************************/
/**
Creates a voice definition. Resources must be added to the created
voice with 'pico_addResourceToVoiceDefinition' before using the
voice in 'pico_newEngine'. It is an error to create a voice
definition with a previously defined voice name. In that case use
'pico_releaseVoiceName' first.
*/
PICO_FUNC pico_createVoiceDefinition(
pico_System system,
const pico_Char *voiceName
);
/**
Adds a mapping pair ('voiceName', 'resourceName') to the voice
definition. Multiple mapping pairs can added to a voice defintion.
When calling 'pico_newEngine' with 'voiceName', the corresponding
resources from the mappings will be used with that engine. */
PICO_FUNC pico_addResourceToVoiceDefinition(
pico_System system,
const pico_Char *voiceName,
const pico_Char *resourceName
);
/**
Releases the voice definition 'voiceName'.
*/
PICO_FUNC pico_releaseVoiceDefinition(
pico_System system,
const pico_Char *voiceName
);
/* Engine creation and deletion functions *****************************/
/**
Creates and initializes a new Pico engine instance and returns its
handle in 'outEngine'. Only one instance per system is currently
possible.
*/
PICO_FUNC pico_newEngine(
pico_System system,
const pico_Char *voiceName,
pico_Engine *outEngine
);
/**
Disposes a Pico engine and releases all memory it occupied. The
engine handle becomes invalid.
*/
PICO_FUNC pico_disposeEngine(
pico_System system,
pico_Engine *inoutEngine
);
/* ********************************************************************/
/* Engine-level API functions */
/* ********************************************************************/
/**
Puts text 'text' encoded in UTF8 into the Pico text input buffer.
'textSize' is the maximum size in number of bytes accessible in
'text'. The input text may also contain text-input commands to
change, for example, speed or pitch of the resulting speech
output. The number of bytes actually copied to the Pico text input
buffer is returned in 'outBytesPut'. Sentence ends are
automatically detected. '\0' characters may be embedded in 'text'
to finish text input or separate independently to be synthesized
text parts from each other. Repeatedly calling 'pico_getData' will
result in the content of the text input buffer to be synthesized
(up to the last sentence end or '\0' character detected). To empty
the internal buffers without finishing synthesis, use the function
'pico_resetEngine'.
*/
PICO_FUNC pico_putTextUtf8(
pico_Engine engine,
const pico_Char *text,
const pico_Int16 textSize,
pico_Int16 *outBytesPut
);
/**
Gets speech data from the engine. Every time this function is
called, the engine performs, within a short time slot, a small
amount of processing its input text, and then gives control back to
the calling application. Ie. after calling 'pico_putTextUtf8'
(incl. a final embedded '\0'), this function needs to be called
repeatedly till 'outBytesReceived' bytes are returned in
'outBuffer'. The type of data returned in 'outBuffer' (e.g. 8 or 16
bit PCM samples) is returned in 'outDataType' and depends on the
lingware resources. Possible 'outDataType' values are listed in
picodefs.h (PICO_DATA_*).
This function returns PICO_STEP_BUSY while processing input and
producing speech output. Once all data is returned and there is no
more input text available in the Pico text input buffer,
PICO_STEP_IDLE is returned. All other function return values
indicate a system error.
*/
PICO_FUNC pico_getData(
pico_Engine engine,
void *outBuffer,
const pico_Int16 bufferSize,
pico_Int16 *outBytesReceived,
pico_Int16 *outDataType
);
/**
Resets the engine and clears all engine-internal buffers, in
particular text input and signal data output buffers.
*/
PICO_FUNC pico_resetEngine(
pico_Engine engine
);
/* Engine status and error/warning message retrieval ******************/
/**
Returns in 'outMessage' a description of the engine status or of an
error that occurred with the most recently called engine-level API
function.
*/
PICO_FUNC pico_getEngineStatusMessage(
pico_Engine engine,
pico_Status errCode,
pico_Retstring outMessage
);
/**
Returns in 'outNrOfWarnings' the number of warnings that occurred
with the most recently called engine-level API function.
*/
PICO_FUNC pico_getNrEngineWarnings(
pico_Engine engine,
pico_Int32 *outNrOfWarnings
);
/**
Returns in 'outMessage' a description of a warning that occurred
with the most recently called engine-level API function.
'warningIndex' must be in the range 0..N-1 where N is the number of
warnings returned by 'pico_getNrEngineWarnings'. 'outCode' returns
the warning as an integer code (cf. PICO_WARN_*).
*/
PICO_FUNC pico_getEngineWarning(
pico_Engine engine,
const pico_Int32 warningIndex,
pico_Status *outCode,
pico_Retstring outMessage
);
#ifdef __cplusplus
}
#endif
#endif /*PICOAPI_H_*/
|