inc/FUixSpeechSpeechToText.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 3.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-3.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file    FUixSpeechSpeechToText.h
  20  * @brief   This is the header file for the %SpeechToText class.
  21  *
  22  * This header file contains the declarations of the %SpeechToText class.
  23  */
  24
  25 #ifndef _FUIX_SPEECH_SPEECH_TO_TEXT_H_
  26 #define _FUIX_SPEECH_SPEECH_TO_TEXT_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseDataType.h>
  30 #include <FUixSpeechSpeechToTextTypes.h>
  31 #include <FUixSpeechISpeechToTextEventListener.h>
  32
  33 namespace Tizen { namespace Base
  34 {
  35     class String;
  36     class ByteBuffer;
  37 }}
  38 namespace Tizen { namespace Base { namespace Collection
  39 {
  40     class IList;
  41 }}}
  42 namespace Tizen { namespace Locales
  43 {
  44     class Locale;
  45 }}
  46
  47 namespace Tizen { namespace Uix { namespace Speech
  48 {
  49
  50 class _SpeechToTextImpl;
  51
  52 /**
  53 * @class    SpeechToText
  54 * @brief    This class is used to convert spoken words into text.
  55 *
  56 * @since 2.0
  57 *
  58 * @remarks  @b Header @b %file: @b \#include @b <FUix.h> @n
  59 *           @b Library : @b osp-speech-stt
  60 *
  61 * The %SpeechToText class converts spoken words into text.
  62 * @n
  63 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/uix/speech_to_text.htm">Speech-To-Text</a>.
  64 *
  65 * The following example demonstrates how to use the %SpeechToText class. @n
  66 * In the example, the Start() method is called after invoking the ISpeechToTextEventListener::OnSpeechToTextInitialized() method.
  67 *
  68 * @code
  69 *   //Sample code for SpeechToTextSample.h
  70 *   #include <FUix.h>
  71 *
  72 *   using namespace Tizen::Uix::Speech;
  73 *
  74 *     class SpeechToTextSample : public ISpeechToTextEventListener
  75 *     {
  76 *         public:
  77 *             SpeechToTextSample(void);
  78 *             virtual ~SpeechToTextSample(void);
  79 *
  80 *             bool Initialize(void);
  81 *             bool Start(void);
  82 *
  83 *             virtual void OnSpeechToTextInitialized(void);
  84 *             virtual void OnSpeechToTextStatusChanged(Tizen::Uix::Speech::SpeechToTextStatus status);
  85 *             virtual void OnSpeechToTextErrorOccurred(Tizen::Uix::Speech::SpeechToTextError error);
  86 *             virtual void OnSpeechToTextCompleted(Tizen::Base::String& result);
  87 *
  88 *         private:
  89 *             Tizen::Uix::Speech::SpeechToText* __pStt;
  90 *     };
  91 *
  92 *     //Sample code for SpeechToTextSample.cpp
  93 *     #include "SpeechToTextSample.h"
  94 *
  95 *     SpeechToTextSample::SpeechToTextSample(void)
  96 *         : __pStt(null)
  97 *     {
  98 *     }
  99 *
 100 *     SpeechToTextSample::~SpeechToTextSample(void)
 101 *     {
 102 *     }
 103 *
 104 *     void SpeechToTextSample::OnSpeechToTextInitialized(void)
 105 *     {
 106 *         // ....
 107 *         __pStt->SetLocale(Locale(LANGUAGE_ENG, COUNTRY_US));
 108 *
 109 *         __pStt->SetSilenceDetectionEnabled(true);
 110 *     }
 111 *
 112 *     void SpeechToTextSample::OnSpeechToTextStatusChanged(Tizen::Uix::Speech::SpeechToTextStatus status)
 113 *     {
 114 *         // ....
 115 *     }
 116 *
 117 *     void SpeechToTextSample::OnSpeechToTextErrorOccurred(Tizen::Uix::Speech::SpeechToTextError error)
 118 *     {
 119 *         // ....
 120 *     }
 121 *
 122 *     void SpeechToTextSample::OnSpeechToTextCompleted(Tizen::Base::String& result)
 123 *     {
 124 *         // ....
 125 *     }
 126 *
 127 *     bool SpeechToTextSample::Initialize(void)
 128 *     {
 129 *         result r = E_SUCCESS;
 130 *
 131 *         __pStt = new SpeechToText();
 132 *
 133 *         r = __pStt->Construct(*this);
 134 *         if (IsFailed(r))
 135 *         {
 136 *             AppLog("Error code: %s", GetErrorMessage(r)):
 137 *             return false;
 138 *         }
 139 *
 140 *         r = __pStt->Initialize();
 141 *         if (IsFailed(r))
 142 *         {
 143 *             AppLog("Error code: %s", GetErrorMessage(r)):
 144 *             return false;
 145 *         }
 146 *         return true;
 147 *     }
 148 *
 149 *     void SpeechToTextSample::Start(void)
 150 *     {
 151 *         if (__pStt->GetCurrentStatus() == SPEECH_TO_TEXT_STATUS_READY)
 152 *         {
 153 *             __pStt->Start();
 154 *         }
 155 *     }
 156 * @endcode
 157 */
 158
 159 class _OSP_EXPORT_ SpeechToText
 160     : public Tizen::Base::Object
 161 {
 162 public:
 163     /**
 164      * The object is not fully constructed after this constructor is called. @n
 165      * For full construction, the Construct() method must be called right after calling this constructor.
 166      *
 167      * @since 2.0
 168      */
 169     SpeechToText(void);
 170
 171     /**
 172      * This destructor overrides Tizen::Base::Object::~Object().
 173      *
 174      * @since 2.0
 175      */
 176     virtual ~SpeechToText(void);
 177
 178     /**
 179      * Initializes this instance of %SpeechToText with the specified @c listener.
 180      *
 181      * @since 2.0
 182      *
 183      * @return      An error code
 184      * @param[in]   listener        An instance of ISpeechToTextEventListener
 185      * @exception   E_SUCCESS       The method is successful.
 186      * @exception   E_SYSTEM        A system error has occurred.
 187      * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 188      */
 189     result Construct(ISpeechToTextEventListener& listener);
 190
 191     /**
 192      * Initializes the Speech-To-Text service. @n
 193      * This method is asynchronous. @n
 194      * The ISpeechToTextEventListener::OnSpeechToTextInitialized() is invoked when the service has been initialized.
 195      * @since 2.0
 196      *
 197      * @return      An error code
 198      * @exception   E_SUCCESS           The method is successful.
 199      * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 200      * @remarks     This method must be called after Construct().
 201      */
 202     result Initialize(void);
 203
 204     /**
 205      * Starts recording the speech of a user and converts it to text.
 206      *
 207      * @since 2.0
 208      *
 209      * @return      An error code
 210      * @exception   E_SUCCESS           The method is successful.
 211      * @exception   E_SYSTEM            A system error has occurred.
 212      * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 213      * @exception   E_SERVICE_BUSY      The recorder is busy.
 214      * @exception   E_INVALID_STATE     This instance is not initialized as yet.
 215      * @exception   E_INVALID_OPERATION The current status should be @c SPEECH_TO_TEXT_STATUS_READY.
 216      */
 217     result Start(void);
 218
 219     /**
 220      * Stops the recording and current Speech-To-Text service.
 221      *
 222      * @since 2.0
 223      *
 224      * @return      An error code
 225      * @exception   E_SUCCESS           The method is successful.
 226      * @exception   E_SYSTEM            A system error has occurred.
 227      * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
 228      * @exception   E_INVALID_STATE     This instance is not initialized as yet.
 229      * @exception   E_INVALID_OPERATION The current status should be @c SPEECH_TO_TEXT_STATUS_RECORDING.
 230      */
 231     result Stop(void);
 232
 233     /**
 234      * Cancels the in-progress recognition of the Speech-To-Text service.
 235      *
 236      * @since 2.0
 237      *
 238      * @return      An error code
 239      * @exception   E_SUCCESS           The method is successful.
 240      * @exception   E_SYSTEM            A system error has occurred.
 241      * @exception   E_INVALID_STATE     This instance is not initialized as yet.
 242      * @exception   E_INVALID_OPERATION The current status should be @c SPEECH_TO_TEXT_STATUS_RECORDING or @c SPEECH_TO_TEXT_STATUS_PROCESSING.
 243      */
 244     result Cancel(void);
 245
 246     /**
 247     * Sets the locale for the Speech-To-Text service.
 248     *
 249     * @since 2.0
 250     *
 251     * @return       An error code
 252     * @param[in]    locale                  The locale
 253     * @exception    E_SUCCESS               The method is successful.
 254     * @exception    E_UNSUPPORTED_LOCALE    This locale is not supported.
 255     * @exception    E_INVALID_STATE         This instance is not initialized as yet.
 256     * @see          GetSupportedLocales()
 257     */
 258     result SetLocale(const Tizen::Locales::Locale& locale);
 259
 260     /**
 261      * Gets the current locale.
 262      *
 263      * @since 2.0
 264      *
 265      * @return      A current locale
 266      * @exception   E_SUCCESS       The method is successful.
 267      * @exception   E_INVALID_STATE This instance is not initialized as yet.
 268      * @remarks     The specific error code can be accessed using the GetLastResult() method.
 269      */
 270     Tizen::Locales::Locale GetLocale(void) const;
 271
 272     /**
 273      * Checks whether a locale is supported or not.
 274      *
 275      * @since 2.0
 276      *
 277      * @return      @c true if the locale is available, @n
 278      *              else @c false
 279      * @param[in]   locale          The locale
 280      * @exception   E_SUCCESS       The method is successful.
 281      * @exception   E_INVALID_STATE This instance is not initialized as yet.
 282      * @remarks     The specific error code can be accessed using the GetLastResult() method.
 283      */
 284     bool IsLocaleSupported(const Tizen::Locales::Locale& locale) const;
 285
 286     /**
 287      * Gets the list of supported locales. @n
 288      * Each list's item has a pointer of Tizen::Locales::Locale value.
 289      *
 290      * @since 2.0
 291      *
 292      * @return      A list of locales
 293      * @exception   E_SUCCESS       The method is successful.
 294      * @exception   E_INVALID_STATE This instance is not initialized as yet.
 295      * @remarks     The specific error code can be accessed using the GetLastResult() method.
 296      */
 297     const Tizen::Base::Collection::IList* GetSupportedLocales(void) const;
 298
 299     /**
 300      * Sets the grammar for %SpeechToText.
 301      *
 302      * @since 2.0
 303      *
 304      * @return      An error code
 305      * @param[in]   grammar         A grammar
 306      * @exception   E_SUCCESS       The method is successful.
 307      * @exception   E_INVALID_STATE This instance is not initialized as yet.
 308      */
 309     result SetGrammar(SpeechToTextGrammar grammar);
 310
 311     /**
 312      * Gets the current grammar.
 313      *
 314      * @since 2.0
 315      *
 316      * @return      The current grammar used by recognition
 317      * @exception   E_SUCCESS       The method is successful.
 318      * @exception   E_INVALID_STATE This instance is not initialized as yet.
 319      * @remarks     The specific error code can be accessed using the GetLastResult() method.
 320      */
 321     SpeechToTextGrammar GetGrammar(void) const;
 322
 323     /**
 324      * Sets the silence detection enabled or disabled.
 325      *
 326      * @since 2.0
 327      *
 328      * @return      An error code
 329      * @param[in]   enable  Set to @c true to enable the silence detection, @n
 330      *                      else @c false
 331      * @exception   E_SUCCESS       The method is successful.
 332      * @exception   E_INVALID_STATE This instance is not initialized as yet.
 333      */
 334     result SetSilenceDetectionEnabled(bool enable);
 335
 336     /**
 337      * Checks whether the silence detection feature is enabled.
 338      *
 339      * @since 2.0
 340      *
 341      * @return      @c true if the silence detection is enabled, @n
 342      *              else @c false
 343      * @exception   E_SUCCESS       The method is successful.
 344      * @exception   E_INVALID_STATE This instance is not initialized as yet.
 345      * @remarks     The specific error code can be accessed using the GetLastResult() method.
 346      */
 347     bool IsSilenceDetectionEnabled(void) const;
 348
 349     /**
 350      * Gets the current status.
 351      *
 352      * @since 2.0
 353      *
 354      * @return      current status
 355      * @exception   E_SUCCESS           The method is successful.
 356      * @exception   E_INVALID_STATE     This instance is not initialized as yet.
 357      * @remarks     The specific error code can be accessed using the GetLastResult() method.
 358      */
 359     SpeechToTextStatus GetCurrentStatus(void) const;
 360
 361
 362 private:
 363     /**
 364      * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 365      *
 366      * @since 2.0
 367      */
 368     SpeechToText(const SpeechToText& rhs);
 369
 370     /**
 371      * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 372      *
 373      * @since 2.0
 374      */
 375     SpeechToText& operator =(const SpeechToText& rhs);
 376
 377 private:
 378     _SpeechToTextImpl* __pSpeechToTextImpl;
 379     friend class _SpeechToTextImpl;
 380
 381 }; // SpeechToText
 382
 383 } } } // Tizen::Uix::Speech
 384
 385 #endif