srsfenginestub/common/inc/nssttscommon.h
changeset 0 0ce1b5ce9557
equal deleted inserted replaced
-1:000000000000 0:0ce1b5ce9557
       
     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