1 /*

     2 * Copyright (c) 2004-2006 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:     Data type defininitions for TTS

    15 *     %version: 13 %

    16 *

    17 *  Copyright © 2004-2006 Nokia Corporation.

    18 */

    19 

    20 

    21 

    22 

    23 

    24 #ifndef TTSCOMMON_H

    25 #define TTSCOMMON_H

    26 

    27 //  INCLUDES

    28 #include <e32std.h>

    29 #include <e32base.h>

    30 

    31 // CONSTANTS

    32 // Undefined synthesizing language. The default language of TTS processor will be used.

    33 const TLanguage KTtsUndefinedLanguage( ELangOther );

    34 

    35 // Undefined duration of segment. The duration will be defined using other properties.

    36 const TInt32 KTtsUndefinedDuration( -1 );

    37 

    38 // Undefined rate

    39 const TInt KTtsRateUndefined( -1 );

    40 

    41 // Default volume, which is maximum volume (100%). 

    42 const TInt KTtsDefaultVolume( 100 );

    43 

    44 // Max length of voice name

    45 const TInt KVoiceNameMaxLength( 50 );

    46 

    47 // Maximum speaking rate

    48 const TInt KTtsMaxSpeakingRate( 100 ); 

    49 

    50 // 

    51 _LIT( KDefaultVoiceNameMale,   "DefaultMale" );

    52 _LIT( KDefaultVoiceNameFemale, "DefaultFemale" );

    53 

    54 // DATA TYPES

    55 

    56 // Style identifier

    57 typedef TUint32 TTtsStyleID;

    58 

    59 // Voice identifier

    60 typedef TBuf<KVoiceNameMaxLength> TTtsVoice;

    61     

    62 // Preferred quality of TTS output

    63 enum TTtsQuality

    64     {

    65     ETtsQualityLowOnly, // Low quality

    66     ETtsQualityHighOnly, // High quality

    67     ETtsQualityHighPreferred, // High quality preferred, low quality fall back can be used

    68     ETtsQualityLowPreferred, // Low quality preferred

    69     ETtsQualityUndefined // Default quality will be used

    70     };

    71 

    72 // Custom command ids for CTtsUtility::CustomCommand(As|S)ync()

    73 enum TTtsCustomCommandId

    74     {

    75     ETtsCustomCommandSetAudioOutput      = 0, // For setting audio output routing

    76     ETtsCustomCommandSetPluginParameter  = 1, // For setting plugin parameter

    77     };

    78 

    79 // FORWARD DECLARATIONS

    80 class CTtsParsedTextBody;

    81 

    82 // CLASS DECLARATION

    83 

    84 /**

    85 *  Class to encapsulate speaking style

    86 *

    87 *  @lib nssttscommon.lib

    88 *  @since 2.8

    89 */

    90 class TTtsStyle 

    91     {

    92     public: // Constructor and destructor

    93         

    94         /**

    95         * C++ default constructor.

    96         */

    97         IMPORT_C TTtsStyle();

    98                 

    99     public: // Data

   100     

   101         // Synthesizing language

   102         TLanguage iLanguage;

   103 

   104         // Voice identifier

   105         TTtsVoice iVoice;

   106              

   107         // Speaking rate in words-per-minute. See TTtsRate.

   108         TInt iRate;

   109         

   110         // Volume scale in percentages. The range is 0..100.

   111         // Zero means silent and 100 maximum volume. 

   112         TInt iVolume;

   113         

   114         // Sampling rate

   115         TInt iSamplingRate;

   116         

   117         // TTS quality (preferred or exclusive)

   118         TTtsQuality iQuality;

   119         

   120         // Desired time to take to read the segment in microseconds

   121         TTimeIntervalMicroSeconds32 iDuration;

   122         

   123         // Natural languagege processing on/off

   124         TBool iNlp;

   125         

   126     };

   127 

   128 /**

   129 *  Class to store segment information

   130 *

   131 *  @lib nssttscommon.lib

   132 *  @since 2.8

   133 */

   134 class TTtsSegment

   135     {

   136     public: // Constructors and destructor

   137         

   138         /**

   139         * C++ default constructor.

   140         * @since 2.8

   141         * @param aStyleID Indentifier of style.

   142         * @param aText Text for segment

   143         * @param aPhonemeSequence Corresponding phoneme sequence for text

   144         * @param aTrailingSilenceDuration The duration of trailing silence.

   145         */

   146         IMPORT_C TTtsSegment( const TTtsStyleID aStyleID, 

   147             const TDesC& aText = KNullDesC, 

   148             const TDesC8& aPhonemeSequence = KNullDesC8, 

   149             const TTimeIntervalMicroSeconds32& aTrailingSilenceDuration = KTtsUndefinedDuration );

   150                 

   151     public: // New functions

   152         

   153         /**

   154         * Sets duration of trailing silence.

   155         * @since 2.8

   156         * @param aDuration Duration of silence.

   157         * @return None

   158         */

   159         IMPORT_C void SetTrailingSilenceL( const TTimeIntervalMicroSeconds32& aDuration );

   160         

   161         /**

   162         * Sets phoneme sequence pointer. The phoneme sequence cannot be deleted 

   163         * during the life time of this object.

   164         * @since 2.8

   165         * @param aPhonemeSequence Phoneme sequence.

   166         * @return None

   167         */

   168         IMPORT_C void SetPhonemeSequencePtr( const TDesC8& aPhonemeSequence );

   169         

   170         /**

   171         * Returns phoneme sequence pointer of the segment.

   172         * @since 2.8

   173         * @param None

   174         * @return Pointer to phoneme sequence

   175         */

   176         IMPORT_C const TDesC8& PhonemeSequencePtr() const;

   177         

   178         /**

   179         * Sets text pointer. The text cannot be deleted

   180         * during the life time of this object.

   181         * @since 2.8

   182         * @param aText Text.

   183         * @return None

   184         */

   185         IMPORT_C void SetTextPtr( const TDesC& aText );

   186         

   187         /**

   188         * Returns text pointer of the segment.

   189         * @since 2.8

   190         * @param None

   191         * @return Pointer to text.

   192         */

   193         IMPORT_C const TDesC& TextPtr() const;

   194         

   195         /**

   196         * Gets duration of trailing silence.

   197         * @since 2.8

   198         * @param None

   199         * @return Duration of silence.

   200         */

   201         IMPORT_C const TTimeIntervalMicroSeconds32& TrailingSilence() const;

   202         

   203         /**

   204         * Sets style for segment. The style cannot be deleted 

   205         * during this object life time.

   206         * @since 2.8

   207         * @param aStyleID The identifier of the style.

   208         * @return None

   209         */

   210         IMPORT_C void SetStyleID( TTtsStyleID aStyleID );

   211         

   212         /**

   213         * Returns identifier of used style.

   214         * @since 2.8

   215         * @param None

   216         * @return Identifier of style.

   217         */

   218         IMPORT_C TTtsStyleID StyleID() const;

   219 

   220         /**

   221         * Sets style object for segment.

   222         *

   223         * @since 3.1

   224         * @param aStyle Style reference.

   225         */

   226         IMPORT_C void SetStyle( TTtsStyle& aStyle );

   227         

   228         /**

   229         * Returns style object.

   230         *

   231         * @since 3.1

   232         * @return Reference to style.

   233         */

   234         IMPORT_C TTtsStyle& StyleL();

   235 

   236         /**

   237         * Resets previously set style and segment will use the style ID.

   238         *

   239         * @since 3.1

   240         */

   241         IMPORT_C void ResetStyle();

   242       

   243     private:    // Data

   244     

   245         // Style identifier for segment

   246         TTtsStyleID iStyleID;

   247         

   248         // Pointer to text associated for segment

   249         TPtrC iText;

   250         

   251         // Pointer to phoneme sequence associated for segment

   252         TPtrC8 iPhonemeSequence;

   253         

   254         // Duration of trailing silence

   255         TTimeIntervalMicroSeconds32 iTrailingSilenceDuration;

   256 

   257         // Style assigned directly to segment

   258         TTtsStyle iStyle;

   259 

   260         // On if style is directly assigned to the segment

   261         TBool iIncludesStyle;

   262     };

   263     

   264 /**

   265 *  Class to define functions for TTS segment stream. 

   266 *  Using the class, a client can implement similar classes to CParsedText.

   267 *

   268 *  @lib nssttscommon.lib

   269 *  @since 2.8

   270 */

   271 class MTtsSegmentStream

   272     {

   273     public: // New functions

   274         

   275         /**

   276         * Returns used phoneme notation of the stream.

   277         * @since 2.8

   278         * @return Descriptor of used phoneme notation.

   279         */

   280         virtual TDesC& MTtsPhonemeNotation() = 0;

   281         

   282         /**

   283         * Returns the next segment in the stream.

   284         * @since 2.8

   285         * @param aSegment The requested segment.

   286         * @return System wide error code. KErrNone if success. 

   287         *         KErrUnderflow if there is no available segment.

   288         */

   289         virtual TInt MTtsReceiveSegment( TTtsSegment& aSegment ) = 0;

   290         

   291         /**

   292         * Notifies that the segment has been processed and it can be released.

   293         * @since 2.8

   294         * @param aSegment The processed segment.

   295         */

   296         virtual void MTtsSegmentDone( TTtsSegment& aSegment ) = 0;

   297         

   298     };

   299 

   300 /**

   301 *  Class to store parsed text for TTS.

   302 *

   303 *  @lib nssttscommon.lib

   304 *  @since 2.8

   305 */

   306 class CTtsParsedText : public CBase

   307     {

   308     public: // Constructors and destructor

   309         

   310         /**

   311         * Two-phased constructor.

   312         * @since 2.8

   313         * @param aText Text to be parsed.

   314         * @param aPhonemeSequence Corresponding phoneme sequence. 

   315         *        If the sequence is not given, it will be determined automatically.

   316         * @param aPhonemeNotation Identifier of phoneme notation. 

   317         *		 If the descriptor is empty, the TTS engine will use default notation.

   318         * @return Created instance of CTtsParsedText

   319         */

   320         IMPORT_C static CTtsParsedText* NewL( const TDesC& aText = KNullDesC, 

   321             const TDesC8& aPhonemeSequence = KNullDesC8, 

   322             const TDesC& aPhonemeNotation = KNullDesC );

   323         

   324         /**

   325         * Destructor.

   326         */

   327         IMPORT_C virtual ~CTtsParsedText();

   328         

   329     public: // New functions

   330         

   331         /**

   332         * Adds new segment and takes its ownership.

   333         * @since 2.8

   334         * @param aSegment A new segment.

   335         * @param aIndex Index where to add segment. If index is equal or larger 

   336         *        than NumberOfSegments(), the segment will be added into end.

   337         */

   338         IMPORT_C void AddSegmentL( const TTtsSegment& aSegment, TInt aIndex = KMaxTInt );

   339         

   340         /**

   341         * Deletes a segment

   342         * @since 2.8

   343         * @param aIndex The index of segment to be deleted. The index must be 0..NumberOfSegments()-1.

   344         */

   345         IMPORT_C void DeleteSegmentL( TInt aIndex );

   346         

   347         /**

   348         * Checks that the internal structure is valid. 

   349         * @since 2.8

   350         * @return ETrue if valid and EFalse if invalid.

   351         */

   352         IMPORT_C TBool IsValid() const;

   353         

   354         /**

   355         * Returns the number of segments.

   356         * @since 2.8

   357         * @return The number of segments

   358         */

   359         IMPORT_C TInt NumberOfSegments() const;

   360         

   361         /**

   362         * Returns phoneme notation definition.

   363         * @since 2.8

   364         * @return Notation descriptor. KNullDesC8 if none.

   365         */

   366         IMPORT_C const TDesC& PhonemeNotation() const;

   367         

   368         /**

   369         * Returns phoneme sequence.

   370         * @since 2.8

   371         * @return Phoneme sequence. KNullDesC8 if none.

   372         */

   373         IMPORT_C const TDesC8& PhonemeSequence() const;

   374         

   375         /**

   376         * Returns segment from given index

   377         * @since 2.8

   378         * @param aIndex The index of segment to be returned. The index must be 0..NumberOfSegments()-1.

   379         * @return Requested segment.

   380         */

   381         IMPORT_C const TTtsSegment& SegmentL( TInt aIndex ) const;

   382         

   383         /**

   384         * Sets a phoneme notation. The descriptor is copied and can be released after the function call.

   385         * @since 2.8

   386         * @param aPhonemeNotation Phoneme notation.

   387         */

   388         IMPORT_C void SetPhonemeNotationL( const TDesC& aPhonemeNotation );

   389         

   390         /**

   391         * Sets a phoneme sequence. The descriptor is copied and can be released after the function call.

   392         * @since 2.8

   393         * @param aPhonemeSequence Phoneme sequence.

   394         */

   395         IMPORT_C void SetPhonemeSequenceL( const TDesC8& aPhonemeSequence );

   396         

   397         /**

   398         * Sets a text. The descriptor is copied and can be released after the function call.

   399         * @since 2.8

   400         * @param aText Text.

   401         */

   402         IMPORT_C void SetTextL( const TDesC& aText );

   403         

   404         /**

   405         * Returns text.

   406         * @since 2.8

   407         * @return Text. KNullDesC8 if none.

   408         */

   409         IMPORT_C const TDesC& Text() const;

   410         

   411     private:

   412         

   413         /**

   414         * C++ default constructor.

   415         */

   416         CTtsParsedText();

   417         

   418         /**

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

   420         */

   421         void ConstructL( const TDesC& aText, 

   422                          const TDesC8& aPhonemeSequence, 

   423                          const TDesC& aPhonemeNotation );

   424         

   425         

   426     private: // Data

   427     

   428         // Implementation for the class

   429         CTtsParsedTextBody* iBody;

   430         

   431         // Reserved pointer for future extension

   432         TAny* iReserved;

   433         

   434     };   

   435 #endif // TTSCOMMON_H

   436     

   437 // End of File