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

115
include/tts/TtsEngine.h
View File

@@ -16,9 +16,10 @@
#include <media/AudioSystem.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.
// An example of the implementation of this interface can be found in
// to access Text-To-Speech functionality in shared libraries that implement
// speech synthesis and the management of resources associated with the
// synthesis.
// An example of the implementation of this interface can be found in
// FIXME: add path+name to implementation of default TTS engine
// Libraries implementing this interface are used in:
// frameworks/base/tts/jni/android_tts_SpeechSynthesis.cpp
@@ -39,15 +40,21 @@ enum tts_callback_status {
// client, the Android TTS service, that the last requested synthesis has been
// completed. // TODO reword
// The callback for synthesis completed takes:
// [inout] void *& - The userdata pointer set in the original synth call
// [in] uint32_t - Track sampling rate in Hz
// [in] audio_format - The AudioSystem::audio_format enum
// [in] int - The number of channels
// [inout] int8_t *& - A buffer of audio data only valid during the execution of the callback
// [inout] size_t & - The size of the buffer
// [in] tts_synth_status - Status of the synthesis; 0 for done, 1 for more data to be synthesized.
// Returns the status of the consumer of the synthesis. 0 for stop, 1 for continue.
typedef tts_callback_status (synthDoneCB_t)(void *&, uint32_t, AudioSystem::audio_format, int, int8_t *&, size_t&, tts_synth_status);
// @param [inout] void *& - The userdata pointer set in the original
// synth call
// @param [in] uint32_t - Track sampling rate in Hz
// @param [in] audio_format - The AudioSystem::audio_format enum
// @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 tts_callback_status (synthDoneCB_t)(void *&, uint32_t,
AudioSystem::audio_format, int, int8_t *&, size_t&, tts_synth_status);
class TtsEngine;
extern "C" TtsEngine* getTtsEngine();
@@ -74,38 +81,41 @@ public:
// @return TTS_SUCCESS, or TTS_FAILURE
virtual tts_result shutdown();
// Interrupt synthesis and flushes any synthesized data that hasn't been output yet.
// This will block until callbacks underway are completed.
// 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
virtual tts_result stop();
// 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 values are based on the Android conventions for localization as described in
// the Android platform documentation on internationalization. This implies that language
// data is specified in the format xx-rYY, where xx is a two letter 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".
// 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 values are based on the Android
// conventions for localization as described in the Android platform
// documentation on internationalization. This implies that language
// data is specified in the format xx-rYY, where xx is a two letter
// 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 size length of the language value
// @return TTS_SUCCESS, or TTS_FAILURE
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
// loaded if it wasn't loaded previously with loadLanguage().
// Signal the engine to use the specified language. This will force the
// language to be loaded if it wasn't loaded previously with loadLanguage().
// See loadLanguage for the specification of the language.
// @param value pointer to the language value
// @param size length of the language value
// @return TTS_SUCCESS, or TTS_FAILURE
virtual tts_result setLanguage(const char *value, const size_t size);
// Retrieve the currently set language, or an empty "value" if no language has
// been set.
// Retrieve the currently set language, or an empty "value" if no language
// has been set.
// @param[out] value pointer to the retrieved language value
// @param[inout] iosize in: stores the size available to store the language value in *value
// out: stores the size required to hold the language value if
// getLanguage() returned TTS_PROPERTY_SIZE_TOO_SMALL,
// unchanged otherwise.
// @param[inout] iosize in: stores the size available to store the language
// value in *value
// out: stores the size required to hold the language
// value if getLanguage() returned
// TTS_PROPERTY_SIZE_TOO_SMALL, unchanged otherwise.
// @return TTS_SUCCESS, or TTS_PROPERTY_SIZE_TOO_SMALL, or TTS_FAILURE
virtual tts_result getLanguage(char *value, size_t *iosize);
@@ -114,23 +124,31 @@ public:
// @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,
// @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_FAILURE,
// 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
// @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
virtual tts_result getProperty(const char *property, char *value, size_t *iosize);
// @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
virtual tts_result getProperty(const char *property, char *value,
size_t *iosize);
// Synthesize the text.
// When synthesis completes, the engine invokes the callback to notify the TTS framework.
// Note about the format of the input: the text parameter may use the following elements
// 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:
@@ -159,14 +177,25 @@ public:
// 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
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 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
virtual tts_result synthesizeIpa(const char *ipa, int8_t *buffer, size_t bufferSize, void *userdata);
// @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_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