diff options
Diffstat (limited to 'lib/picoapi.h')
| -rw-r--r-- | lib/picoapi.h | 469 |
1 files changed, 469 insertions, 0 deletions
diff --git a/lib/picoapi.h b/lib/picoapi.h new file mode 100644 index 0000000..0dad702 --- /dev/null +++ b/lib/picoapi.h @@ -0,0 +1,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_*/ |