1 /*

     2 * Copyright (c) 2004 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:  DevTTS interface for Text-to-Speech

    15 *

    16 */

    17 

    18 

    19 #ifndef DEVTTS_H

    20 #define DEVTTS_H

    21 

    22 //  INCLUDES

    23 #include <e32base.h>

    24 #include <e32def.h>

    25 // TTSCommon include

    26 #include <nssttscommon.h>

    27 

    28 // CONSTANTS

    29 const TInt KDevTTSBalanceRight = 100;

    30 const TInt KDevTTSBalanceRightMiddle = 50;

    31 const TInt KDevTTSBalanceMiddle = 0;

    32 const TInt KDevTTSBalanceLeftMiddle = -50;

    33 const TInt KDevTTSBalanceLeft = -100;

    34 

    35 // DATA TYPES

    36 enum TDevTTSEvent

    37     {

    38     EDevTTSEventComplete

    39     };

    40 

    41 enum TDevTTSOutputMode

    42     {

    43     EDevTTSSoundDeviceMode = 0,

    44     EDevTTSClientMode

    45     };

    46 

    47 enum TDevTTSAudioPreference

    48     {

    49     EDevTTSPriorityPreferenceNone = 0,

    50     EDevTTSPriorityPreferenceTime, 

    51     EDevTTSPriorityPreferenceQuality,

    52     EDevTTSPriorityPreferenceTimeAndQuality 

    53     };

    54 

    55 // FORWARD DECLARATIONS

    56 class CTTSAlgorithmManager;

    57 

    58 // CLASS DECLARATIONS

    59 

    60 /**

    61 *  MDevTTSObserver

    62 *

    63 *  Interface for a set of DevTTS callback functions.

    64 *

    65 *  This mixin class is intended to be inherited by the DevTTS client. Functions

    66 *  of this class get called when DevTTS specific events occur.

    67 *

    68 *  @lib nssdevtts.lib

    69 *  @since 2.8

    70 */

    71 class MDevTTSObserver

    72     {

    73     

    74     public:  // New functions

    75         

    76         /**

    77         * Invoked by DevTTS when it needs a configuration data package.

    78         *

    79         * @since 2.8

    80         * @param "TUint32 aPackageType" Packege type identifier

    81         * @param "TUint32 aPackageID" Package identifier

    82         * @param "TUint32 aStartPosition" Start position in bytes from beginning of data

    83         * @param "TUint32 aEndPosition" End index in bytes. If the position is bigger 

    84         *         than the size of data package, the end part will be returned.

    85         *

    86         * @return Pointer to created data buffer. NULL if failure. User must 

    87         *         take care of the buffer deletion after usage.

    88         */

    89         virtual HBufC8* MdtoConfigurationData( TUint32 aPackageType, 

    90                                                TUint32 aPackageID, 

    91                                                TUint32 aStartPosition, 

    92                                                TUint32 aEndPosition ) = 0;

    93         

    94         /**

    95         * Called by DevTTS when an event occured. EDevTTSEventComplete is the only

    96         * event that can happen currently.

    97         *

    98         * @since 2.8

    99         * @param "TDevTTSEvent aEvent"

   100         *         Event code

   101         * @param "TInt aStatus"

   102         *         Error code. KErrNone if success, one of the system level

   103         *         error codes otherwise.

   104         */

   105         virtual void MdtoEvent( TDevTTSEvent aEvent, TInt aStatus ) = 0;

   106         

   107         /**

   108         * Called by DevTTS device when output mode is EDevTTSClientMode and a 

   109         * new audio buffer has been filled by the synthesizer. 

   110         *

   111         * @since 2.8

   112         * @param "TDesC8& aBuffer"

   113         *         Synthesized audio buffer.

   114         */

   115         virtual void MdtoProcessBuffer( const TDesC8& aBuffer ) = 0;

   116     };

   117 

   118 /**

   119 *  CDevTTS is the interface towards DevTTS module. Actual implementation is

   120 *  not included in this class.

   121 *

   122 *  @lib nssdevtts.lib

   123 *  @since 2.8

   124 */

   125 class CDevTTS : public CBase

   126     {

   127     public:  // Constructors and destructor

   128         

   129         /**

   130         * Two-phased constructor.

   131         */

   132         IMPORT_C static CDevTTS* NewL( MDevTTSObserver& aObserver/*, CConsoleBase* console*/ );

   133         

   134         /**

   135         * Destructor.

   136         */

   137         IMPORT_C ~CDevTTS();

   138         

   139     public: // New functions

   140         

   141         /**

   142         * Adds a new style to the collection. If equal style exists already,

   143         * new style is not added.

   144         * Will leave if an error occurs. Likely errors are: KErrNoMemory,

   145         * not enough memory to add new style. KErrNotSupported, the style 

   146         * is not supported. KErrArgument, the style contains an imposible 

   147         * value.

   148         *

   149         * @since 2.8

   150         * @param "TTtsStyle& aStyle"

   151         *        Reference to the style which will be added to the style 

   152         *        collection.

   153         *

   154         * @return Identifier of added style.

   155         */

   156         IMPORT_C TTtsStyleID AddStyleL( const TTtsStyle& aStyle );

   157         

   158         /**

   159         * Returns the current balance setting.

   160         *

   161         * @since 2.8

   162         * @return Balance value.

   163         */

   164         IMPORT_C TInt Balance();

   165 

   166         /**

   167         * Notifies that the buffer has been processed. The 

   168         * method is used if output mode of synthesizing is 

   169         * EDevTTSClientMode.

   170         *

   171         * @since 2.8

   172         * @param "TDesC8& aBuffer"

   173         *        The buffer which has been processed.

   174         */

   175         IMPORT_C void BufferProcessed( const TDesC8& aBuffer );

   176         

   177         /**

   178         * Request a pointer to the custom interface. Currently not in use.

   179         * 

   180         * @since 2.8

   181         * @param "TUid aInterfaceID"

   182         *        Custom interface identifier.

   183         *

   184         * @return Pointer to custom interface. NULL if interface is not 

   185         *         found or initiation failures.

   186         */

   187         IMPORT_C TAny* CustomInterface( TUid aInterfaceID );

   188         

   189         /**

   190         * Deletes style.

   191         * 

   192         * @since 2.8

   193         * @param "TTtsStyleID aStyleID" Identifier of style to be deleted.

   194         */

   195         IMPORT_C void DeleteStyleL( TTtsStyleID aStyleID );

   196 

   197         /**

   198         * Gives current position of synthesizing. The method will leave if an 

   199         * error occurs. Likely errors are: KErrNotReady, no synthesizing is 

   200         * ongoing.

   201         * 

   202         * @since 2.8

   203         * @param "TTimeIntervalMicroSeconds& aTime"

   204         *        Time of the synthesizing position

   205         */

   206         IMPORT_C void GetPositionL( TTimeIntervalMicroSeconds& aTime ) const;

   207         

   208         /**

   209         * Gives current position of synthesizing. The method will leave if an 

   210         * error occurs. Likely errors are: KErrNotReady, no synthesizing is 

   211         * ongoing.

   212         * 

   213         * @since 2.8

   214         * @param "TTtsSegment& aSegment"

   215         *        Current segment which is synthesized, out parameter

   216         * @param "TInt& aWordIndex"

   217         *        Index of the current word, starting from the begining of 

   218         *        current segment

   219         */

   220         IMPORT_C void GetPositionL( TTtsSegment& aSegment, TInt& aWordIndex ) const;

   221         

   222         /**

   223         * Tells if language is supported by the TTS engine or not.

   224         * 

   225         * @since 2.8

   226         * @param "TLanguage aLanguage"

   227         *        Language code

   228         *

   229         * @return ETrue if supported, EFalse otherwise

   230         */

   231         IMPORT_C TBool IsLanguageSupported( TLanguage aLanguage ) const;

   232         

   233         /**

   234         * Returns maximum volume value.

   235         * 

   236         * @since 2.8

   237         * @return Maximum volume.

   238         */

   239         IMPORT_C TInt MaxVolume();

   240 

   241         /**

   242         * Gives number of styles.

   243         * 

   244         * @since 2.8

   245         * @return Number of styles.

   246         */

   247         IMPORT_C TUint16 NumberOfStyles() const;

   248         

   249         /**

   250         * Pauses synthesis process.

   251         * @since 2.8

   252         */

   253         IMPORT_C void Pause();

   254         

   255         /**

   256         * Prepares for synthesis. The method will leave if an 

   257         * error occurs. Likely errors are: KErrInUse, synthesizing is 

   258         * currently ongoing. KErrNoMemory, not enough memory to start 

   259         * synthesis. KErrNotSupport, requested function is not supported.

   260         * 

   261         * @since 2.8

   262         * @param "MTtsSegmentStream& aStream"

   263         *        Stream to be synthesized.

   264         */

   265         IMPORT_C void PrimeSynthesisL( MTtsSegmentStream& aStream );

   266         

   267         /**

   268         * Prepares for synthesis. The method will leave if an 

   269         * error occurs. Likely errors are: KErrInUse, synthesizing is 

   270         * currently ongoing. KErrNoMemory, not enough memory to start 

   271         * synthesis. KErrNotSupport, requested function is not supported.

   272         * 

   273         * @since 2.8

   274         * @param "CTtsParsedText& aText"

   275         *        Text containing multiple segments to be synthesized.

   276         */

   277         IMPORT_C void PrimeSynthesisL( CTtsParsedText& aText );

   278         

   279         /**

   280         * Sets the priority for audio playback if in EDevTTSSoundDeviceMode.

   281         * 

   282         * @since 2.8

   283         * @param "TInt aPriority"

   284         *        Priority value.

   285         * @param "TDevTTSAudioPreference aPref"'

   286         *        Preference setting. Quality, time or both.

   287         */

   288         IMPORT_C void SetAudioPriority( TInt aPriority, TDevTTSAudioPreference aPref );

   289         

   290         /**

   291         * Sets the audio output routing

   292         * 

   293         * @since 3.2

   294         * @param "TInt aAudioOutput"

   295         *        New output.

   296         */

   297         IMPORT_C void SetAudioOutputL( TInt aAudioOutput );

   298         

   299         /**

   300         * Sets the playback device balance. Affects only when DevTTS is in 

   301         * EDevTTSSoundDeviceMode. Illegal values are neglected.

   302         * 

   303         * @since 2.8

   304         * @param "TInt aBalance" Balance to be set. 

   305         */

   306         IMPORT_C void SetBalance( TInt aBalance );

   307        

   308         /**

   309         * Sets new position for synthesizing. The method will leave if an 

   310         * error occurs. Likely errors are: KErrNotReady, no synthesizing is 

   311         * ongoing. KErrArgument, position cannot be set.

   312         * 

   313         * @since 2.8

   314         * @param "TTimeIntervalMicroSeconds& aTime"

   315         *        Time of the synthesizing postion.

   316         */

   317         IMPORT_C void SetPositionL( const TTimeIntervalMicroSeconds& aTime );

   318         

   319         /**

   320         * Sets new position for synthesizing. The method will leave if an 

   321         * error occurs. Likely errors are: KErrNotReady, no synthesizing is 

   322         * ongoing. KErrArgument, position cannot be set.

   323         * 

   324         * @since 2.8

   325         * @param "TTtsSegment& aSegment"

   326         *        The segment being synthesized.

   327         * @param "TInt aWordIndex"

   328         *        The index of word being synthesized.

   329         */

   330         IMPORT_C void SetPositionL( const TTtsSegment& aSegment, TInt aWordIndex );

   331         

   332         /**

   333         * Sets the playback device volume. Affects only when DevTTS is in 

   334         * EDevTTSSoundDeviceMode. Range is from 0..MaxVolume(). Illegal values 

   335         * are neglected.

   336         * 

   337         * @since 2.8

   338         * @param "TInt aVolume" Volume setting.

   339         */

   340         IMPORT_C void SetVolume( TInt aVolume );

   341 

   342         /**

   343         * Sets the volume ramp duration. Start and end volumes must be set with

   344         * SetVolume() function.

   345         * 

   346         * @since 2.8

   347         * @param "TTimeIntervalMicroSeconds& aRampDuration" 

   348         *        Ramp duration in microseconds.

   349         */

   350         IMPORT_C void SetVolumeRamp( const TTimeIntervalMicroSeconds& aRampDuration );

   351 

   352         /**

   353         * Stops synthesizing and releases resources of synthesizing. 

   354         * The method does nothing if already stopped.

   355         * @since 2.8

   356         */

   357         IMPORT_C void Stop();

   358         

   359         /**

   360         * Receives style information. The method will leave if an error 

   361         * occurs. Likely errors are: KErrNotFound, style identifier not 

   362         * found. 

   363         * 

   364         * @since 2.8

   365         * @param "TTtsStyle& aStyle"

   366         *        Reference to style object where to assign the requested style.

   367         * @param "TTtsStyleID aStyleID"

   368         *        Style identifier.

   369         */

   370         IMPORT_C TTtsStyle& StyleL( TTtsStyleID aStyleID ) const;

   371         

   372         /**

   373         * Receives style information. The method will leave if an error 

   374         * occurs. Likely errors are: KErrArgument, index is out of bounds.

   375         * 

   376         * @since 2.8

   377         * @param "TTtsStyle& aStyle"

   378         *        Reference to style object where to assign the requested style.

   379         * @param "TUint16 aIndex"

   380         *        Index to style: 0..NumberOfStyles().

   381         */

   382         IMPORT_C TTtsStyle& StyleL( TUint16 aIndex ) const;

   383         

   384         /**

   385         * Starts synthesizing the text. The method is asynchronous, as soon

   386         * as the request has been placed, function call will return. 

   387         * MDevTTSObserver::MdtoEvent will be called when synthesizing finishes.

   388         * The method will leave if an error occurs. Likely errors are: 

   389         * KErrNoMemory, not enough memory. 

   390         * KErrInUse, synthesizing is currently ongoing

   391         * 

   392         * @since 2.8

   393         * @param "TDevTTSOutputMode aOutputMode"

   394         *        Either use a sound device (EDevTTSSoundDeviceMode) or client 

   395         *        using callback (EDevTTSClientMode)

   396         */

   397         IMPORT_C void SynthesizeL( TDevTTSOutputMode aOutputMode );

   398         

   399         /**

   400         * Returns current playback volume.

   401         * 

   402         * @since 2.8

   403         * @return Volume setting.

   404         */       

   405         IMPORT_C TInt Volume();

   406 

   407         /** 

   408         * Calls language identification for a given text.

   409         *

   410         * @since 3.0M

   411         * @param "CTtsParsedText& aText" Text

   412         * @param "TInt aNumberOfGuesses" Maximum number of guesses that will be provided

   413         * @param "RArray<TLanguage>& aLanguages" Output parameter which will contain the languages

   414         * @param "RArray<TInt>& aScores" Scores

   415         */

   416         IMPORT_C void LanguageIdentificationL( CTtsParsedText& aText, 

   417                                                TInt aNumberOfGuesses, 

   418                                                RArray<TLanguage>& aLanguages,

   419                                                RArray<TInt>& aScores );

   420 

   421         /**

   422         * Calls Natural Language Processing (NLP) to normalize text.

   423         *

   424         * @since 3.0M

   425         * @param "CTtsParsedText& aText" Text which will be normalized

   426         */

   427         IMPORT_C void NormalizeTextL( CTtsParsedText& aText );

   428 

   429         /**

   430         * Calls Natural Language Processing (NLP) to normalize and segment text.

   431         *

   432         * @since 3.0M

   433         * @param "CTtsParsedText& aText" Text which will be normalized

   434         */

   435         IMPORT_C void NormalizeAndSegmentTextL( CTtsParsedText& aText );

   436 

   437     public: // Functions from base classes

   438         

   439     protected:  // New functions

   440         

   441     protected:  // Functions from base classes

   442         

   443     private:

   444         

   445         /**

   446         * C++ default constructor.

   447         */

   448         CDevTTS();

   449         

   450         /**

   451         * By default Symbian 2nd phase constructor is private.

   452         */

   453         void ConstructL( MDevTTSObserver& aObserver/*, CConsoleBase* console*/ );

   454         

   455         /**

   456         * Prohibit copy constructor

   457         */

   458         CDevTTS( const CDevTTS& );

   459         

   460         /** 

   461         * Prohibit assignment operator

   462         */

   463         CDevTTS& operator=( const CDevTTS& );

   464         

   465     public:     // Data

   466         

   467     protected:  // Data

   468         

   469     private:    // Data

   470         

   471         // Pointer to the implementation class

   472         CTTSAlgorithmManager* iImpl;

   473         

   474         // Reserved pointer for future extension

   475         TAny* iReserved;

   476         

   477     public:     // Friend classes

   478         

   479     protected:  // Friend classes

   480         

   481     private:    // Friend classes

   482         

   483     };

   484     

   485 #endif // DEVTTS_H   

   486     

   487 // End of File