Merge change 3356 into donut

#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.

// 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:

// 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();

    // @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);

    // @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

    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:

    // 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);

    // Synthesize IPA text. When synthesis completes, the engine must call the given callback to notify the TTS API.

    virtual tts_result synthesizeText(const char *text, int8_t *buffer,

            size_t bufferSize, void *userdata);

    // 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