Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge change 3356 into donut

Browse Source 
* changes:
  Cleaning up comments in interface for TTS engines.
This commit is contained in:
Android (Google) Code Review
2009-06-05 15:55:24 -07:00
parent 4e0b13c9a9 6270d6100e
commit e3523054de
1 changed files with 72 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
include/tts/TtsEngine.h
View File

@@ -16,8 +16,9 @@
#include <media/AudioSystem.h> #include <media/AudioSystem.h>
// This header defines the interface used by the Android platform // This header defines the interface used by the Android platform
// to access Text-To-Speech functionality in shared libraries that implement speech // to access Text-To-Speech functionality in shared libraries that implement
// synthesis and the management of resources associated with the synthesis. // speech synthesis and the management of resources associated with the
// synthesis.
// An example of the implementation of this interface can be found in // An example of the implementation of this interface can be found in
// FIXME: add path+name to implementation of default TTS engine // FIXME: add path+name to implementation of default TTS engine
// Libraries implementing this interface are used in: // Libraries implementing this interface are used in:
@@ -39,15 +40,21 @@ enum tts_callback_status {
// client, the Android TTS service, that the last requested synthesis has been // client, the Android TTS service, that the last requested synthesis has been
// completed. // TODO reword // completed. // TODO reword
// The callback for synthesis completed takes: // The callback for synthesis completed takes:
// [inout] void *& - The userdata pointer set in the original synth call // @param [inout] void *& - The userdata pointer set in the original
// [in] uint32_t - Track sampling rate in Hz // synth call
// [in] audio_format - The AudioSystem::audio_format enum // @param [in] uint32_t - Track sampling rate in Hz
// [in] int - The number of channels // @param [in] audio_format - The AudioSystem::audio_format enum
// [inout] int8_t *& - A buffer of audio data only valid during the execution of the callback // @param [in] int - The number of channels
// [inout] size_t & - The size of the buffer // @param [inout] int8_t *& - A buffer of audio data only valid during the
// [in] tts_synth_status - Status of the synthesis; 0 for done, 1 for more data to be synthesized. // execution of the callback
// Returns the status of the consumer of the synthesis. 0 for stop, 1 for continue. // @param [inout] size_t & - The size of the buffer
typedef tts_callback_status (synthDoneCB_t)(void *&, uint32_t, AudioSystem::audio_format, int, int8_t *&, size_t&, tts_synth_status); // @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 tts_callback_status (synthDoneCB_t)(void *&, uint32_t,
AudioSystem::audio_format, int, int8_t *&, size_t&, tts_synth_status);
class TtsEngine; class TtsEngine;
extern "C" TtsEngine* getTtsEngine(); extern "C" TtsEngine* getTtsEngine();
@@ -74,38 +81,41 @@ public:
// @return TTS_SUCCESS, or TTS_FAILURE // @return TTS_SUCCESS, or TTS_FAILURE
virtual tts_result shutdown(); virtual tts_result shutdown();
// Interrupt synthesis and flushes any synthesized data that hasn't been output yet. // Interrupt synthesis and flushes any synthesized data that hasn't been
// This will block until callbacks underway are completed. // output yet. This will block until callbacks underway are completed.
// @return TTS_SUCCESS, or TTS_FAILURE // @return TTS_SUCCESS, or TTS_FAILURE
virtual tts_result stop(); virtual tts_result stop();
// Load the resources associated with the specified language. The loaded language will // Load the resources associated with the specified language. The loaded
// only be used once a call to setLanguage() with the same language value is issued. // language will only be used once a call to setLanguage() with the same
// Language values are based on the Android conventions for localization as described in // language value is issued. Language values are based on the Android
// the Android platform documentation on internationalization. This implies that language // conventions for localization as described in the Android platform
// data is specified in the format xx-rYY, where xx is a two letter ISO 639-1 language code // documentation on internationalization. This implies that language
// in lowercase and rYY is a two letter ISO 3166-1-alpha-2 language code in uppercase // data is specified in the format xx-rYY, where xx is a two letter
// preceded by a lowercase "r". // ISO 639-1 language code in lowercase and rYY is a two letter
// ISO 3166-1-alpha-2 language code in uppercase preceded by a
// lowercase "r".
// @param value pointer to the language value // @param value pointer to the language value
// @param size length of the language value // @param size length of the language value
// @return TTS_SUCCESS, or TTS_FAILURE // @return TTS_SUCCESS, or TTS_FAILURE
virtual tts_result loadLanguage(const char *value, const size_t size); virtual tts_result loadLanguage(const char *value, const size_t size);
// Signal the engine to use the specified language. This will force the language to be // Signal the engine to use the specified language. This will force the
// loaded if it wasn't loaded previously with loadLanguage(). // language to be loaded if it wasn't loaded previously with loadLanguage().
// See loadLanguage for the specification of the language. // See loadLanguage for the specification of the language.
// @param value pointer to the language value // @param value pointer to the language value
// @param size length of the language value // @param size length of the language value
// @return TTS_SUCCESS, or TTS_FAILURE // @return TTS_SUCCESS, or TTS_FAILURE
virtual tts_result setLanguage(const char *value, const size_t size); virtual tts_result setLanguage(const char *value, const size_t size);
// Retrieve the currently set language, or an empty "value" if no language has // Retrieve the currently set language, or an empty "value" if no language
// been set. // has been set.
// @param[out] value pointer to the retrieved language value // @param[out] value pointer to the retrieved language value
// @param[inout] iosize in: stores the size available to store the language value in *value // @param[inout] iosize in: stores the size available to store the language
// out: stores the size required to hold the language value if // value in *value
// getLanguage() returned TTS_PROPERTY_SIZE_TOO_SMALL, // out: stores the size required to hold the language
// unchanged otherwise. // value if getLanguage() returned
// TTS_PROPERTY_SIZE_TOO_SMALL, unchanged otherwise.
// @return TTS_SUCCESS, or TTS_PROPERTY_SIZE_TOO_SMALL, or TTS_FAILURE // @return TTS_SUCCESS, or TTS_PROPERTY_SIZE_TOO_SMALL, or TTS_FAILURE
virtual tts_result getLanguage(char *value, size_t *iosize); virtual tts_result getLanguage(char *value, size_t *iosize);
@@ -116,21 +126,29 @@ public:
// @param size maximum size required to store this type of property // @param size maximum size required to store this type of property
// @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_FAILURE, // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_FAILURE,
// or TTS_VALUE_INVALID // or TTS_VALUE_INVALID
virtual tts_result setProperty(const char *property, const char *value, const size_t size); virtual tts_result setProperty(const char *property, const char *value,
const size_t size);
// Retrieve a property from the TTS engine // Retrieve a property from the TTS engine
// @param property pointer to the property name // @param property pointer to the property name
// @param[out] value pointer to the retrieved language value // @param[out] value pointer to the retrieved language value
// @param[inout] iosize in: stores the size available to store the property value // @param[inout] iosize in: stores the size available to store the
// out: stores the size required to hold the language value if // property value.
// getLanguage() returned TTS_PROPERTY_SIZE_TOO_SMALL, // out: stores the size required to hold the language
// unchanged otherwise. // value if getLanguage() returned
// @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_PROPERTY_SIZE_TOO_SMALL // TTS_PROPERTY_SIZE_TOO_SMALL, unchanged otherwise
virtual tts_result getProperty(const char *property, char *value, size_t *iosize); // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS,
// or TTS_PROPERTY_SIZE_TOO_SMALL
virtual tts_result getProperty(const char *property, char *value,
size_t *iosize);
// Synthesize the text. // Synthesize the text.
// When synthesis completes, the engine invokes the callback to notify the TTS framework. // As the synthesis is performed, the engine invokes the callback to notify
// Note about the format of the input: the text parameter may use the following elements // 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: // and their respective attributes as defined in the SSML 1.0 specification:
// * lang // * lang
// * say-as: // * say-as:
@@ -159,14 +177,25 @@ public:
// Text is coded in UTF-8. // Text is coded in UTF-8.
// @param text the UTF-8 text to synthesize // @param text the UTF-8 text to synthesize
// @param userdata pointer to be returned when the call is invoked // @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 // @return TTS_SUCCESS or TTS_FAILURE
virtual tts_result synthesizeText(const char *text, int8_t *buffer, size_t bufferSize, void *userdata); virtual tts_result synthesizeText(const char *text, int8_t *buffer,
size_t bufferSize, void *userdata);
// Synthesize IPA text. When synthesis completes, the engine must call the given callback to notify the TTS API. // Synthesize IPA 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 IPA data.
// @param ipa the IPA data to synthesize // @param ipa the IPA data to synthesize
// @param userdata pointer to be returned when the call is invoked // @param userdata pointer to be returned when the call is invoked
// @return TTS_FEATURE_UNSUPPORTED if IPA is not supported, otherwise TTS_SUCCESS or TTS_FAILURE // @param buffer the location where the synthesized data must be written
virtual tts_result synthesizeIpa(const char *ipa, int8_t *buffer, size_t bufferSize, void *userdata); // @param bufferSize the number of bytes that can be written in buffer
// @return TTS_FEATURE_UNSUPPORTED if IPA is not supported,
// otherwise TTS_SUCCESS or TTS_FAILURE
virtual tts_result synthesizeIpa(const char *ipa, int8_t *buffer,
size_t bufferSize, void *userdata);
}; };
} // namespace android } // namespace android