1 /*

     2 * Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Client side header of Speech synthesis server

    15 *

    16 */

    17 

    18 

    19 #ifndef SPEECHSYNTHESIS_H

    20 #define SPEECHSYNTHESIS_H

    21 

    22 // INCLUDES

    23 

    24 #include <e32std.h>

    25 

    26 

    27 // CONSTANTS

    28 

    29 /**

    30 * Maximum length of text-to-speech voice name. 

    31 * 

    32 * @see TVoiceName

    33 */

    34 const TInt KMaxNameLength = 64;

    35 

    36 /**

    37 * Text-to-speech voice name type definition. 

    38 * 

    39 * @see TVoice

    40 */

    41 typedef TBuf<KMaxNameLength> TVoiceName;

    42 

    43 

    44 // CLASSES

    45 

    46 /**

    47 * Class containing basic information of text-to-speech voice. 

    48 */

    49 class TVoice

    50     {

    51 

    52     public:

    53 

    54         /**

    55         * Language spoken by the voice

    56         */

    57         TLanguage               iLanguage;

    58 

    59         /**

    60         * Name of the voice

    61         */

    62         TVoiceName              iVoiceName;

    63     

    64         /**

    65         * Sampling rate of the voice

    66         */

    67         TInt                    iSamplingRate;

    68 

    69         /**

    70         * TVoice constructor

    71         */

    72         inline TVoice():

    73             iLanguage( ELangNone ),

    74             iSamplingRate( KErrNotFound )

    75             {

    76             // Nothing

    77             }

    78     };

    79 

    80 /**

    81 * Speech synthesis client side interface

    82 *

    83 

    84 * @code

    85 * // Simple example how to use synthesis server synchronously

    86 * _LIT( KText, "This is a text sample" );

    87 * RSpeechSynthesis s;

    88 * TRequestStatus status;

    89 *

    90 * // Open connection

    91 * s.Open();

    92 *

    93 * // Initialise

    94 * s.InitialiseSynthesis( KText, status );

    95 * User::WaitForRequest( status );

    96 *

    97 * // Start synthesis when initialisation is ready

    98 * s.Synthesise( status );

    99 * User::WaitForRequest( status );

   100 *

   101 * // Close connection

   102 * s.Close();

   103 * @endcode

   104 *

   105 * @code

   106 * // Another example how to use synthesis server synchronously

   107 * _LIT( KText, "Second text sample" );

   108 * RSpeechSynthesis s;

   109 * TRequestStatus status;

   110 *

   111 * // Open connection

   112 * s.Open();

   113 *

   114 * // Set volume to maximum value    

   115 * s.SetVolumeL( * s.MaxVolumeL() );

   116 *

   117 * // Set speaking rate to half of maximum value

   118 * s.SetSpeakingRateL( * s.MaxSpeakingRateL() / 2 );

   119 * 

   120 * // Set synthesis language but leave voice name open

   121 * TVoice voice;

   122 * voice.iLanguage = User::Language();

   123 * s.SetVoiceL( voice );

   124 *

   125 * // Initialise

   126 * s.InitialiseSynthesis( KText, status );

   127 * User::WaitForRequest( status );

   128 * 

   129 * // Ask estimated duration of synthesis. 

   130 * // Note: Leaves if current TVoice doesn't support duration

   131 * TTimeIntervalMicroSeconds duration = s.DurationL();

   132 *

   133 * // Start synthesis when initialisation is ready

   134 * s.Synthesise( status );

   135 * User::WaitForRequest( status );

   136 *

   137 * // Close connection

   138 * s.Close();

   139 * @endcode

   140 */

   141 class RSpeechSynthesis : public RSessionBase

   142     {

   143     

   144     public:

   145         

   146         /**

   147         * Possible parameter values for SetAudioOutputL()

   148         * 

   149         * @see RSpeechSynthesis::SetAudioOutputL()

   150         */

   151         enum TTtsAudioOutput

   152         	{

   153         	ETtsOutputDefault = 0,  ///< Default

   154         	ETtsOutputAll = 1,      ///< All output devices are used

   155         	ETtsOutputNoOutput = 2, ///< No output

   156         	ETtsOutputPrivate = 3,  ///< Private output device is used

   157         	ETtsOutputPublic = 4    ///< Public output device is used

   158         	};

   159         

   160     public:

   161         

   162         /**

   163         * Constructor

   164         */

   165         IMPORT_C RSpeechSynthesis();

   166         

   167         /**

   168         * Connect to synthesis server

   169         *

   170         * @return KErrNone if successful, otherwise system-wide error code. 

   171         */

   172         IMPORT_C TInt Open();

   173         

   174         /**

   175         * Close connection to synthesis server

   176         */    

   177         IMPORT_C void Close();

   178         

   179         /**

   180         * Initialise text to be synthesised. If there is synthesis already 

   181         * ongoing aStatus will be completed with KErrInUse. 

   182         * 

   183         *

   184         * @param aText Text to be synthesized. Text has to be valid until 

   185         *        aStatus is completed because this function is asynchronous 

   186         *        and the request that it represents may not complete until 

   187         *        some time after the call to the function has returned. 

   188         *        It is important, therefore, that this descriptor remain valid, 

   189         *        or remain in scope, until you have been notified that 

   190         *        the request is complete.

   191         * @param aStatus Status of priming. 

   192         */

   193         IMPORT_C void InitialiseSynthesis( const TDesC& aText,

   194                                            TRequestStatus& aStatus );

   195         

   196         /**

   197         * Initialise text to be synthesised to the file. If there is synthesis 

   198         * already ongoing aStatus will be completed with KErrInUse. 

   199         *

   200         * @param aText Text to be synthesized. Text has to be valid until 

   201         *        aStatus is completed because this function is asynchronous 

   202         *        and the request that it represents may not complete until 

   203         *        some time after the call to the function has returned. 

   204         *        It is important, therefore, that this descriptor remain valid, 

   205         *        or remain in scope, until you have been notified that 

   206         *        the request is complete.

   207         * @param aFileName Output is written to this file. File name has to be

   208         *        valid until aStatus is completed. Client should have capabilities 

   209         *        needed for writing location defined in aFileName, otherwise aStatus

   210         *        will be completed by KErrPermissionDenied. 

   211         * @param aStatus Status of priming

   212         */

   213         IMPORT_C void InitialiseSynthesis( const TDesC& aText, 

   214                                            const TFileName& aFileName,

   215                                            TRequestStatus& aStatus ); 

   216         

   217         /** 

   218         * @todo Not supported. aStatus will be always completed with KErrNotSupported.

   219         *

   220         * Initialise text to be synthesised to the descriptor. If there is synthesis 

   221         * already ongoing aStatus will be completed with KErrInUse. 

   222         *

   223         * @param aText Text to be synthesized. Text has to be valid until 

   224         *        aStatus is completed because this function is asynchronous 

   225         *        and the request that it represents may not complete until 

   226         *        some time after the call to the function has returned. 

   227         *        It is important, therefore, that this descriptor remain valid, 

   228         *        or remain in scope, until you have been notified that 

   229         *        the request is complete.

   230         * @param aDataBuffer Reference to a descriptor where output is stored

   231         *        after Synthesise() is called. If all the data does not fit 

   232         *        into aDataBuffer Synthesise can be called several times. 

   233         * @param aStatus Status of priming

   234         */

   235         IMPORT_C void InitialiseSynthesis( const TDesC& aText,

   236                                            TDes8& aDataBuffer, 

   237                                            TRequestStatus& aStatus );

   238         

   239         /**

   240         * Synthesise the text or resume paused synthesis. 

   241         * InitialiseSynthesis() has to be called succesfully before call to 

   242         * this function will succeed. aStatus is completed with KErrNotReady 

   243         * if initialisation has not been done. 

   244         *

   245         * @param aStatus Status of synthesis

   246         *

   247         * @see RSpeechSynthesis::InitialiseSynthesis() 

   248         * @see RSpeechSynthesis::PauseL() 

   249         */

   250         IMPORT_C void Synthesise( TRequestStatus& aStatus );     

   251         

   252         /**

   253         * Stop ongoing synthesis. Ongoing synthesis request is completed 

   254         * with KErrAbort. Does nothing if there is no synthesis ongoing. 

   255         *

   256         * @leave KErrInUse if request is made to stop other client's synthesis. 

   257         */

   258         IMPORT_C void StopL();

   259         

   260         /**

   261         * Pause synthesis. Resuming can be done by calling Synthesize(). 

   262         * Ongoing synthesis request is completed with KErrCancel. 

   263         *

   264         * @leave KErrNotSupported if trying to pause synthesis to file. 

   265         * @leave KErrNotReady if there is no synthesis ongoing. 

   266         */

   267         IMPORT_C void PauseL();

   268         

   269         /**

   270         * Returns estimated duration of synthesis. This function returns valid 

   271         * duration only after synthesis is initialised and before synthesis has

   272         * completed. 

   273         *

   274         * @return Estimated duration of speech synthesis playback. 

   275         *

   276         * @leave KErrNotReady if state is incorrect

   277         * @leave KErrNotSupported if current voice settings doesn't support 

   278         *        duration information

   279         */

   280         IMPORT_C TTimeIntervalMicroSeconds DurationL();

   281         

   282         /**

   283         * Get supported synthesis languages

   284         *

   285         * @param aLanguages Contains supported languages after function call

   286         *

   287         */

   288         IMPORT_C void GetLanguagesL( RArray<TLanguage>& aLanguages );

   289         

   290         /**

   291         * Get available voices 

   292         *

   293         * @param aVoices Contains supported voices in TVoice structure after 

   294         *        the function call. 

   295         * @param aLanguage Defines a language that returned voices can speak. 

   296         *

   297         */

   298         IMPORT_C void GetVoicesL( RArray<TVoice>& aVoices, TLanguage aLanguage );

   299         

   300         /**

   301         * Get current voice. 

   302         *

   303         * @return Current voice. 

   304         *

   305         */

   306         IMPORT_C TVoice VoiceL();

   307         

   308         /**

   309         * Change voice. Change is effective after next InitialiseSynthesis() call 

   310         * is made and until new SetVoiceL() call is made or Close() is called. 

   311         *

   312         * @param aVoice New voice to be set. aVoice.iLanguage is the only mandatory 

   313         *        parameter,others can be undefined and server may ignore 

   314         *        those if invalid values are given. 

   315         *

   316         * @leave KErrArgument if aVoice is not valid

   317         */

   318         IMPORT_C void SetVoiceL( const TVoice& aVoice ); 

   319         

   320         /**

   321         * Returns maximum speaking rate.

   322         *

   323         * @return Maximum speaking rate

   324         *

   325         */

   326         IMPORT_C TInt MaxSpeakingRateL(); 

   327         

   328         /**

   329         * Returns the current speaking rate value.

   330         *

   331         * @return Current speaking rate

   332         *

   333         */

   334         IMPORT_C TInt SpeakingRateL(); 

   335         

   336         /**

   337         * Sets the speaking rate. Range is 1..MaxSpeakingRateL(). Setting will 

   338         * be effective after next InitialiseSynthesis() call and until new rate 

   339         * is set or Close() is called. Note: All voices doesn't support speaking 

   340         * rate changes and in that case there is no audible change. 

   341         *

   342         * @param aSpeakingRate Rate value

   343         *

   344         * @leave KErrArgument if speaking rate is out of range. 

   345         *

   346         * @see MaxSpeakingRateL()

   347         */

   348         IMPORT_C void SetSpeakingRateL( TInt aSpeakingRate ); 

   349         

   350         /**

   351         * Get maximum volume

   352         *

   353         * @return Maximum volume

   354         *

   355         */

   356         IMPORT_C TInt MaxVolumeL(); 

   357         

   358         /**

   359         * Get current volume.

   360         *

   361         * @return Volume level between 0 and MaxVolumeL()

   362         *

   363         */

   364         IMPORT_C TInt VolumeL(); 

   365         

   366         /**

   367         * Change volume. Will be effective until new volume is set or Close()

   368         * is called.

   369         *

   370         * @param aVolume New volume, accepted values are in range from 0 to MaxVolumeL()

   371         *

   372         * @leave KErrArgument if volume value is out of range, 

   373         *

   374         * @see MaxVolumeL()

   375         */

   376         IMPORT_C void SetVolumeL( TInt aVolume ); 

   377         

   378         /**

   379         * Sets the playback priority and preference values. Setting will 

   380         * be effective after next InitialiseSynthesis() call and until new priority 

   381         * is set or Close() is called. Client needs Nokia VID to use

   382         * this function. 

   383         *

   384         * @param aPriority Audio priority

   385         * @param aPreference Audio preference

   386         *

   387         * @leave KErrPermissionDenied if client doesn't have Nokia VID. 

   388         */

   389         IMPORT_C void SetAudioPriorityL( TInt aPriority, TInt aPreference ); 

   390         

   391         /**

   392       	* Sets the audio output. Setting will be effective immediately and until

   393       	* new value is set or connection closed. Client needs WriteDeviceData 

   394       	* capability if setting output to ETtsOutputAll

   395         *

   396       	* @param aAudioOutput - where the audio is routed. 

   397       	*

   398       	* @leave KErrPermissionDenied if client doesn't have WriteDeviceData when

   399       	*        setting output to ETtsOutputAll. 

   400         *

   401       	*/

   402         IMPORT_C void SetAudioOutputL( TTtsAudioOutput aAudioOutput );

   403         

   404         /**

   405         * Send custom command to the server. By using this function it is possible 

   406         * to make adjustments to the synthesis process. 

   407         * Note: Currently there is no supported commands. 

   408         *

   409         * @param aCommand A custom command 

   410         * @param aValue Parameter value for aCommand 

   411         * 

   412         * @leave KErrNotSupported aCommand is not supported. 

   413         * @leave KErrArgument if aValue is not valid. 

   414         */

   415         IMPORT_C void CustomCommandL( TInt aCommand, TInt aValue ); 

   416         

   417     private:

   418         

   419         /**

   420         * Internal function used for handling initialisation. 

   421         */

   422         void DoInitialiseSynthesisL( const TDesC& aText, 

   423                                      const TFileName& aFileName, 

   424                                      TRequestStatus& aStatus ); 

   425         

   426     };

   427     

   428 #endif // SPEECHSYNTHESIS_H