Add header declaring the interface for TTS engines to implement.

1 files changed, 167 insertions, 0 deletions

diff --git a/include/tts/TtsEngine.h b/include/tts/TtsEngine.h
new file mode 100644
index 0000000..06f3820
--- /dev/null
+++ b/include/tts/TtsEngine.h
@@ -0,0 +1,167 @@
+/*
+ * 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.
+ */
+#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 
+// 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
+
+namespace android {
+
+// The callback is used by the implementation of this interface to notify its
+// client, the Android TTS service, that the last requested synthesis has been
+// completed.
+// The callback for synthesis completed takes:
+//    void *       - The userdata pointer set in the original synth call
+//    uint32_t     - Track sampling rate in Hz
+//    audio_format - The AudioSystem::audio_format enum
+//    int          - The number of channels
+//    int8_t *     - A buffer of audio data only valid during the execution of the callback
+//    size_t       - The size of the buffer
+// Note about memory management:
+//    The implementation of TtsEngine is responsible for the management of the memory
+//    it allocates to store the synthesized speech. After the execution of the callback
+//    to hand the synthesized data to the client of TtsEngine, the TTS engine is
+//    free to reuse or free the previously allocated memory.
+//    This implies that the implementation of the "synthDoneCB" callback cannot use
+//    the pointer to the buffer of audio samples outside of the callback itself.
+typedef void (synthDoneCB_t)(void *, uint32_t, AudioSystem::audio_format, int, int8_t *, size_t);
+
+class TtsEngine;
+extern "C" TtsEngine* getTtsEngine();
+
+enum tts_result {
+    TTS_SUCCESS                 = 0,
+    TTS_FAILURE                 = -1,
+    TTS_FEATURE_UNSUPPORTED     = -2,
+    TTS_VALUE_INVALID           = -3,
+    TTS_PROPERTY_UNSUPPORTED    = -4,
+    TTS_PROPERTY_SIZE_TOO_SMALL = -5
+};
+
+class TtsEngine
+{
+public:
+    // Initialize the TTS engine and returns whether initialization succeeded.
+    // @param synthDoneCBPtr synthesis callback function pointer
+    // @return TTS_SUCCESS, or TTS_FAILURE
+    virtual tts_result init(synthDoneCB_t synthDoneCBPtr);
+
+    // Shut down the TTS engine and releases all associated resources.
+    // @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.
+    // @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".
+    // @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().
+    // 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.
+    // @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.
+    // @return TTS_SUCCESS, or TTS_PROPERTY_SIZE_TOO_SMALL, or TTS_FAILURE
+    virtual tts_result getLanguage(char *value, size_t *iosize);
+
+    // 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
+    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);
+
+    // 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
+    // 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
+    // @return          TTS_SUCCESS or TTS_FAILURE
+    virtual tts_result synthesizeText(const char *text, void *userdata);
+
+    // Synthesize IPA text. When synthesis completes, the engine must call the given callback to notify the TTS API.
+    // @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, void *userdata);
+};
+
+} // namespace android
+