| /* |
| * Copyright (C) 2009 Google Inc. |
| * |
| * 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. |
| */ |
| #ifndef ANDROID_TTS_H |
| #define ANDROID_TTS_H |
| |
| // This header defines the interface used by the Android platform |
| // to access Text-To-Speech functionality in shared libraries that implement |
| // speech synthesis and the management of resources associated with the |
| // synthesis. |
| |
| // The shared library must contain a function named "android_getTtsEngine" |
| // that returns an 'android_tts_engine_t' instance. |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #include <stdint.h> |
| |
| #define ANDROID_TTS_ENGINE_PROPERTY_CONFIG "engineConfig" |
| #define ANDROID_TTS_ENGINE_PROPERTY_PITCH "pitch" |
| #define ANDROID_TTS_ENGINE_PROPERTY_RATE "rate" |
| #define ANDROID_TTS_ENGINE_PROPERTY_VOLUME "volume" |
| |
| typedef enum { |
| ANDROID_TTS_SUCCESS = 0, |
| ANDROID_TTS_FAILURE = -1, |
| ANDROID_TTS_FEATURE_UNSUPPORTED = -2, |
| ANDROID_TTS_VALUE_INVALID = -3, |
| ANDROID_TTS_PROPERTY_UNSUPPORTED = -4, |
| ANDROID_TTS_PROPERTY_SIZE_TOO_SMALL = -5, |
| ANDROID_TTS_MISSING_RESOURCES = -6 |
| } android_tts_result_t; |
| |
| typedef enum { |
| ANDROID_TTS_LANG_COUNTRY_VAR_AVAILABLE = 2, |
| ANDROID_TTS_LANG_COUNTRY_AVAILABLE = 1, |
| ANDROID_TTS_LANG_AVAILABLE = 0, |
| ANDROID_TTS_LANG_MISSING_DATA = -1, |
| ANDROID_TTS_LANG_NOT_SUPPORTED = -2 |
| } android_tts_support_result_t; |
| |
| typedef enum { |
| ANDROID_TTS_SYNTH_DONE = 0, |
| ANDROID_TTS_SYNTH_PENDING = 1 |
| } android_tts_synth_status_t; |
| |
| typedef enum { |
| ANDROID_TTS_CALLBACK_HALT = 0, |
| ANDROID_TTS_CALLBACK_CONTINUE = 1 |
| } android_tts_callback_status_t; |
| |
| // Supported audio formats |
| typedef enum { |
| ANDROID_TTS_AUDIO_FORMAT_INVALID = -1, |
| ANDROID_TTS_AUDIO_FORMAT_DEFAULT = 0, |
| ANDROID_TTS_AUDIO_FORMAT_PCM_16_BIT = 1, |
| ANDROID_TTS_AUDIO_FORMAT_PCM_8_BIT = 2, |
| } android_tts_audio_format_t; |
| |
| |
| /* An android_tts_engine_t object can be anything, but must have, |
| * as its first field, a pointer to a table of functions. |
| * |
| * See the full definition of struct android_tts_engine_t_funcs_t |
| * below for details. |
| */ |
| typedef struct android_tts_engine_funcs_t android_tts_engine_funcs_t; |
| |
| typedef struct { |
| android_tts_engine_funcs_t *funcs; |
| } android_tts_engine_t; |
| |
| /* This function must be located in the TTS Engine shared library |
| * and must return the address of an android_tts_engine_t library. |
| */ |
| extern android_tts_engine_t *android_getTtsEngine(); |
| |
| /* Including the old version for legacy support (Froyo compatibility). |
| * This should return the same thing as android_getTtsEngine. |
| */ |
| android_tts_engine_t *getTtsEngine(); |
| |
| // A callback type used to notify the framework of new synthetized |
| // audio samples, status will be SYNTH_DONE for the last sample of |
| // the last request, of SYNTH_PENDING otherwise. |
| // |
| // This is passed by the framework to the engine through the |
| // 'engine_init' function (see below). |
| // |
| // The callback for synthesis completed takes: |
| // @param [inout] void *& - The userdata pointer set in the original |
| // synth call |
| // @param [in] uint32_t - Track sampling rate in Hz |
| // @param [in] uint32_t - The audio format |
| // @param [in] int - The number of channels |
| // @param [inout] int8_t *& - A buffer of audio data only valid during the |
| // execution of the callback |
| // @param [inout] size_t & - The size of the buffer |
| // @param [in] tts_synth_status - indicate whether the synthesis is done, or |
| // if more data is to be synthesized. |
| // @return TTS_CALLBACK_HALT to indicate the synthesis must stop, |
| // TTS_CALLBACK_CONTINUE to indicate the synthesis must continue if |
| // there is more data to produce. |
| typedef android_tts_callback_status_t (*android_tts_synth_cb_t) |
| (void **pUserData, |
| uint32_t trackSamplingHz, |
| android_tts_audio_format_t audioFormat, |
| int channelCount, |
| int8_t **pAudioBuffer, |
| size_t *pBufferSize, |
| android_tts_synth_status_t status); |
| |
| |
| // The table of function pointers that the android_tts_engine_t must point to. |
| // Note that each of these functions will take a handle to the engine itself |
| // as their first parameter. |
| // |
| |
| struct android_tts_engine_funcs_t { |
| // reserved fields, ignored by the framework |
| // they must be placed here to ensure binary compatibility |
| // of legacy binary plugins. |
| void *reserved[2]; |
| |
| // Initialize the TTS engine and returns whether initialization succeeded. |
| // @param synthDoneCBPtr synthesis callback function pointer |
| // @return TTS_SUCCESS, or TTS_FAILURE |
| android_tts_result_t (*init) |
| (void *engine, |
| android_tts_synth_cb_t synthDonePtr, |
| const char *engineConfig); |
| |
| // Shut down the TTS engine and releases all associated resources. |
| // @return TTS_SUCCESS, or TTS_FAILURE |
| android_tts_result_t (*shutdown) |
| (void *engine); |
| |
| // Interrupt synthesis and flushes any synthesized data that hasn't been |
| // output yet. This will block until callbacks underway are completed. |
| // @return TTS_SUCCESS, or TTS_FAILURE |
| android_tts_result_t (*stop) |
| (void *engine); |
| |
| // Returns the level of support for the language, country and variant. |
| // @return TTS_LANG_COUNTRY_VAR_AVAILABLE if the language, country and variant are supported, |
| // and the corresponding resources are correctly installed |
| // TTS_LANG_COUNTRY_AVAILABLE if the language and country are supported and the |
| // corresponding resources are correctly installed, but there is no match for |
| // the specified variant |
| // TTS_LANG_AVAILABLE if the language is supported and the |
| // corresponding resources are correctly installed, but there is no match for |
| // the specified country and variant |
| // TTS_LANG_MISSING_DATA if the required resources to provide any level of support |
| // for the language are not correctly installed |
| // TTS_LANG_NOT_SUPPORTED if the language is not supported by the TTS engine. |
| android_tts_support_result_t (*isLanguageAvailable) |
| (void *engine, |
| const char *lang, |
| const char *country, |
| const char *variant); |
| |
| // Load the resources associated with the specified language. The loaded |
| // language will only be used once a call to setLanguage() with the same |
| // language value is issued. Language and country values are coded according to the ISO three |
| // letter codes for languages and countries, as can be retrieved from a java.util.Locale |
| // instance. The variant value is encoded as the variant string retrieved from a |
| // java.util.Locale instance built with that variant data. |
| // @param lang pointer to the ISO three letter code for the language |
| // @param country pointer to the ISO three letter code for the country |
| // @param variant pointer to the variant code |
| // @return TTS_SUCCESS, or TTS_FAILURE |
| android_tts_result_t (*loadLanguage) |
| (void *engine, |
| const char *lang, |
| const char *country, |
| const char *variant); |
| |
| // Load the resources associated with the specified language, country and Locale variant. |
| // The loaded language will only be used once a call to setLanguageFromLocale() with the same |
| // language value is issued. Language and country values are coded according to the ISO three |
| // letter codes for languages and countries, as can be retrieved from a java.util.Locale |
| // instance. The variant value is encoded as the variant string retrieved from a |
| // java.util.Locale instance built with that variant data. |
| // @param lang pointer to the ISO three letter code for the language |
| // @param country pointer to the ISO three letter code for the country |
| // @param variant pointer to the variant code |
| // @return TTS_SUCCESS, or TTS_FAILURE |
| android_tts_result_t (*setLanguage) |
| (void *engine, |
| const char *lang, |
| const char *country, |
| const char *variant); |
| |
| // Retrieve the currently set language, country and variant, or empty strings if none of |
| // parameters have been set. Language and country are represented by their 3-letter ISO code |
| // @param[out] pointer to the retrieved 3-letter code language value |
| // @param[out] pointer to the retrieved 3-letter code country value |
| // @param[out] pointer to the retrieved variant value |
| // @return TTS_SUCCESS, or TTS_FAILURE |
| android_tts_result_t (*getLanguage) |
| (void *engine, |
| char *language, |
| char *country, |
| char *variant); |
| |
| // Notifies the engine what audio parameters should be used for the synthesis. |
| // This is meant to be used as a hint, the engine implementation will set the output values |
| // to those of the synthesis format, based on a given hint. |
| // @param[inout] encoding in: the desired audio sample format |
| // out: the format used by the TTS engine |
| // @param[inout] rate in: the desired audio sample rate |
| // out: the sample rate used by the TTS engine |
| // @param[inout] channels in: the desired number of audio channels |
| // out: the number of channels used by the TTS engine |
| // @return TTS_SUCCESS, or TTS_FAILURE |
| android_tts_result_t (*setAudioFormat) |
| (void *engine, |
| android_tts_audio_format_t* pEncoding, |
| uint32_t* pRate, |
| int* pChannels); |
| |
| // Set a property for the the TTS engine |
| // "size" is the maximum size of "value" for properties "property" |
| // @param property pointer to the property name |
| // @param value pointer to the property value |
| // @param size maximum size required to store this type of property |
| // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_FAILURE, |
| // or TTS_VALUE_INVALID |
| android_tts_result_t (*setProperty) |
| (void *engine, |
| const char *property, |
| const char *value, |
| const size_t size); |
| |
| // Retrieve a property from the TTS engine |
| // @param property pointer to the property name |
| // @param[out] value pointer to the retrieved language value |
| // @param[inout] iosize in: stores the size available to store the |
| // property value. |
| // out: stores the size required to hold the language |
| // value if getLanguage() returned |
| // TTS_PROPERTY_SIZE_TOO_SMALL, unchanged otherwise |
| // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, |
| // or TTS_PROPERTY_SIZE_TOO_SMALL |
| android_tts_result_t (*getProperty) |
| (void *engine, |
| const char *property, |
| char *value, |
| size_t *iosize); |
| |
| // Synthesize the text. |
| // As the synthesis is performed, the engine invokes the callback to notify |
| // the TTS framework that it has filled the given buffer, and indicates how |
| // many bytes it wrote. The callback is called repeatedly until the engine |
| // has generated all the audio data corresponding to the text. |
| // Note about the format of the input: the text parameter may use the |
| // following elements |
| // and their respective attributes as defined in the SSML 1.0 specification: |
| // * lang |
| // * say-as: |
| // o interpret-as |
| // * phoneme |
| // * voice: |
| // o gender, |
| // o age, |
| // o variant, |
| // o name |
| // * emphasis |
| // * break: |
| // o strength, |
| // o time |
| // * prosody: |
| // o pitch, |
| // o contour, |
| // o range, |
| // o rate, |
| // o duration, |
| // o volume |
| // * mark |
| // Differences between this text format and SSML are: |
| // * full SSML documents are not supported |
| // * namespaces are not supported |
| // Text is coded in UTF-8. |
| // @param text the UTF-8 text to synthesize |
| // @param userdata pointer to be returned when the call is invoked |
| // @param buffer the location where the synthesized data must be written |
| // @param bufferSize the number of bytes that can be written in buffer |
| // @return TTS_SUCCESS or TTS_FAILURE |
| android_tts_result_t (*synthesizeText) |
| (void *engine, |
| const char *text, |
| int8_t *buffer, |
| size_t bufferSize, |
| void *userdata); |
| }; |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* ANDROID_TTS_H */ |
