/*
* Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Client side header of Speech synthesis server
*
*/
#ifndef SPEECHSYNTHESIS_H
#define SPEECHSYNTHESIS_H
// INCLUDES
#include <e32std.h>
// CONSTANTS
/**
* Maximum length of text-to-speech voice name.
*
* @see TVoiceName
*/
const TInt KMaxNameLength = 64;
/**
* Text-to-speech voice name type definition.
*
* @see TVoice
*/
typedef TBuf<KMaxNameLength> TVoiceName;
// CLASSES
/**
* Class containing basic information of text-to-speech voice.
*/
class TVoice
{
public:
/**
* Language spoken by the voice
*/
TLanguage iLanguage;
/**
* Name of the voice
*/
TVoiceName iVoiceName;
/**
* Sampling rate of the voice
*/
TInt iSamplingRate;
/**
* TVoice constructor
*/
inline TVoice():
iLanguage( ELangNone ),
iSamplingRate( KErrNotFound )
{
// Nothing
}
};
/**
* Speech synthesis client side interface
*
* @code
* // Simple example how to use synthesis server synchronously
* _LIT( KText, "This is a text sample" );
* RSpeechSynthesis s;
* TRequestStatus status;
*
* // Open connection
* s.Open();
*
* // Initialise
* s.InitialiseSynthesis( KText, status );
* User::WaitForRequest( status );
*
* // Start synthesis when initialisation is ready
* s.Synthesise( status );
* User::WaitForRequest( status );
*
* // Close connection
* s.Close();
* @endcode
*
* @code
* // Another example how to use synthesis server synchronously
* _LIT( KText, "Second text sample" );
* RSpeechSynthesis s;
* TRequestStatus status;
*
* // Open connection
* s.Open();
*
* // Set volume to maximum value
* s.SetVolumeL( * s.MaxVolumeL() );
*
* // Set speaking rate to half of maximum value
* s.SetSpeakingRateL( * s.MaxSpeakingRateL() / 2 );
*
* // Set synthesis language but leave voice name open
* TVoice voice;
* voice.iLanguage = User::Language();
* s.SetVoiceL( voice );
*
* // Initialise
* s.InitialiseSynthesis( KText, status );
* User::WaitForRequest( status );
*
* // Ask estimated duration of synthesis.
* // Note: Leaves if current TVoice doesn't support duration
* TTimeIntervalMicroSeconds duration = s.DurationL();
*
* // Start synthesis when initialisation is ready
* s.Synthesise( status );
* User::WaitForRequest( status );
*
* // Close connection
* s.Close();
* @endcode
*/
class RSpeechSynthesis : public RSessionBase
{
public:
/**
* Possible parameter values for SetAudioOutputL()
*
* @see RSpeechSynthesis::SetAudioOutputL()
*/
enum TTtsAudioOutput
{
ETtsOutputDefault = 0, ///< Default
ETtsOutputAll = 1, ///< All output devices are used
ETtsOutputNoOutput = 2, ///< No output
ETtsOutputPrivate = 3, ///< Private output device is used
ETtsOutputPublic = 4 ///< Public output device is used
};
public:
/**
* Constructor
*/
IMPORT_C RSpeechSynthesis();
/**
* Connect to synthesis server
*
* @return KErrNone if successful, otherwise system-wide error code.
*/
IMPORT_C TInt Open();
/**
* Close connection to synthesis server
*/
IMPORT_C void Close();
/**
* Initialise text to be synthesised. If there is synthesis already
* ongoing aStatus will be completed with KErrInUse.
*
*
* @param aText Text to be synthesized. Text has to be valid until
* aStatus is completed because this function is asynchronous
* and the request that it represents may not complete until
* some time after the call to the function has returned.
* It is important, therefore, that this descriptor remain valid,
* or remain in scope, until you have been notified that
* the request is complete.
* @param aStatus Status of priming.
*/
IMPORT_C void InitialiseSynthesis( const TDesC& aText,
TRequestStatus& aStatus );
/**
* Initialise text to be synthesised to the file. If there is synthesis
* already ongoing aStatus will be completed with KErrInUse.
*
* @param aText Text to be synthesized. Text has to be valid until
* aStatus is completed because this function is asynchronous
* and the request that it represents may not complete until
* some time after the call to the function has returned.
* It is important, therefore, that this descriptor remain valid,
* or remain in scope, until you have been notified that
* the request is complete.
* @param aFileName Output is written to this file. File name has to be
* valid until aStatus is completed. Client should have capabilities
* needed for writing location defined in aFileName, otherwise aStatus
* will be completed by KErrPermissionDenied.
* @param aStatus Status of priming
*/
IMPORT_C void InitialiseSynthesis( const TDesC& aText,
const TFileName& aFileName,
TRequestStatus& aStatus );
/**
* @todo Not supported. aStatus will be always completed with KErrNotSupported.
*
* Initialise text to be synthesised to the descriptor. If there is synthesis
* already ongoing aStatus will be completed with KErrInUse.
*
* @param aText Text to be synthesized. Text has to be valid until
* aStatus is completed because this function is asynchronous
* and the request that it represents may not complete until
* some time after the call to the function has returned.
* It is important, therefore, that this descriptor remain valid,
* or remain in scope, until you have been notified that
* the request is complete.
* @param aDataBuffer Reference to a descriptor where output is stored
* after Synthesise() is called. If all the data does not fit
* into aDataBuffer Synthesise can be called several times.
* @param aStatus Status of priming
*/
IMPORT_C void InitialiseSynthesis( const TDesC& aText,
TDes8& aDataBuffer,
TRequestStatus& aStatus );
/**
* Synthesise the text or resume paused synthesis.
* InitialiseSynthesis() has to be called succesfully before call to
* this function will succeed. aStatus is completed with KErrNotReady
* if initialisation has not been done.
*
* @param aStatus Status of synthesis
*
* @see RSpeechSynthesis::InitialiseSynthesis()
* @see RSpeechSynthesis::PauseL()
*/
IMPORT_C void Synthesise( TRequestStatus& aStatus );
/**
* Stop ongoing synthesis. Ongoing synthesis request is completed
* with KErrAbort. Does nothing if there is no synthesis ongoing.
*
* @leave KErrInUse if request is made to stop other client's synthesis.
*/
IMPORT_C void StopL();
/**
* Pause synthesis. Resuming can be done by calling Synthesize().
* Ongoing synthesis request is completed with KErrCancel.
*
* @leave KErrNotSupported if trying to pause synthesis to file.
* @leave KErrNotReady if there is no synthesis ongoing.
*/
IMPORT_C void PauseL();
/**
* Returns estimated duration of synthesis. This function returns valid
* duration only after synthesis is initialised and before synthesis has
* completed.
*
* @return Estimated duration of speech synthesis playback.
*
* @leave KErrNotReady if state is incorrect
* @leave KErrNotSupported if current voice settings doesn't support
* duration information
*/
IMPORT_C TTimeIntervalMicroSeconds DurationL();
/**
* Get supported synthesis languages
*
* @param aLanguages Contains supported languages after function call
*
*/
IMPORT_C void GetLanguagesL( RArray<TLanguage>& aLanguages );
/**
* Get available voices
*
* @param aVoices Contains supported voices in TVoice structure after
* the function call.
* @param aLanguage Defines a language that returned voices can speak.
*
*/
IMPORT_C void GetVoicesL( RArray<TVoice>& aVoices, TLanguage aLanguage );
/**
* Get current voice.
*
* @return Current voice.
*
*/
IMPORT_C TVoice VoiceL();
/**
* Change voice. Change is effective after next InitialiseSynthesis() call
* is made and until new SetVoiceL() call is made or Close() is called.
*
* @param aVoice New voice to be set. aVoice.iLanguage is the only mandatory
* parameter,others can be undefined and server may ignore
* those if invalid values are given.
*
* @leave KErrArgument if aVoice is not valid
*/
IMPORT_C void SetVoiceL( const TVoice& aVoice );
/**
* Returns maximum speaking rate.
*
* @return Maximum speaking rate
*
*/
IMPORT_C TInt MaxSpeakingRateL();
/**
* Returns the current speaking rate value.
*
* @return Current speaking rate
*
*/
IMPORT_C TInt SpeakingRateL();
/**
* Sets the speaking rate. Range is 1..MaxSpeakingRateL(). Setting will
* be effective after next InitialiseSynthesis() call and until new rate
* is set or Close() is called. Note: All voices doesn't support speaking
* rate changes and in that case there is no audible change.
*
* @param aSpeakingRate Rate value
*
* @leave KErrArgument if speaking rate is out of range.
*
* @see MaxSpeakingRateL()
*/
IMPORT_C void SetSpeakingRateL( TInt aSpeakingRate );
/**
* Get maximum volume
*
* @return Maximum volume
*
*/
IMPORT_C TInt MaxVolumeL();
/**
* Get current volume.
*
* @return Volume level between 0 and MaxVolumeL()
*
*/
IMPORT_C TInt VolumeL();
/**
* Change volume. Will be effective until new volume is set or Close()
* is called.
*
* @param aVolume New volume, accepted values are in range from 0 to MaxVolumeL()
*
* @leave KErrArgument if volume value is out of range,
*
* @see MaxVolumeL()
*/
IMPORT_C void SetVolumeL( TInt aVolume );
/**
* Sets the playback priority and preference values. Setting will
* be effective after next InitialiseSynthesis() call and until new priority
* is set or Close() is called. Client needs Nokia VID to use
* this function.
*
* @param aPriority Audio priority
* @param aPreference Audio preference
*
* @leave KErrPermissionDenied if client doesn't have Nokia VID.
*/
IMPORT_C void SetAudioPriorityL( TInt aPriority, TInt aPreference );
/**
* Sets the audio output. Setting will be effective immediately and until
* new value is set or connection closed. Client needs WriteDeviceData
* capability if setting output to ETtsOutputAll
*
* @param aAudioOutput - where the audio is routed.
*
* @leave KErrPermissionDenied if client doesn't have WriteDeviceData when
* setting output to ETtsOutputAll.
*
*/
IMPORT_C void SetAudioOutputL( TTtsAudioOutput aAudioOutput );
/**
* Send custom command to the server. By using this function it is possible
* to make adjustments to the synthesis process.
* Note: Currently there is no supported commands.
*
* @param aCommand A custom command
* @param aValue Parameter value for aCommand
*
* @leave KErrNotSupported aCommand is not supported.
* @leave KErrArgument if aValue is not valid.
*/
IMPORT_C void CustomCommandL( TInt aCommand, TInt aValue );
private:
/**
* Internal function used for handling initialisation.
*/
void DoInitialiseSynthesisL( const TDesC& aText,
const TFileName& aFileName,
TRequestStatus& aStatus );
};
#endif // SPEECHSYNTHESIS_H