Collapse all Symbian^3 Application Developer Library

RSpeechSynthesis Class Reference

class RSpeechSynthesis : public RSessionBase

Speech synthesis client side interface

        // 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();

        // 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();

Inherits from

RSpeechSynthesis
- RSessionBase
  - RHandleBase

Public Member Functions
	RSpeechSynthesis ()
IMPORT_C void	Close ()
IMPORT_C void	CustomCommandL ( TInt , TInt )
IMPORT_C TTimeIntervalMicroSeconds	DurationL ()
IMPORT_C void	GetLanguagesL ( RArray < TLanguage > &)
IMPORT_C void	GetVoicesL ( RArray < TVoice > &, TLanguage )
IMPORT_C void	InitialiseSynthesis (const TDesC &, TRequestStatus &)
IMPORT_C void	InitialiseSynthesis (const TDesC &, const TFileName &, TRequestStatus &)
IMPORT_C void	InitialiseSynthesis (const TDesC &, TDes8 &, TRequestStatus &)
IMPORT_C TInt	MaxSpeakingRateL ()
IMPORT_C TInt	MaxVolumeL ()
IMPORT_C TInt	Open ()
IMPORT_C void	PauseL ()
IMPORT_C void	SetAudioOutputL ( TTtsAudioOutput )
IMPORT_C void	SetAudioPriorityL ( TInt , TInt )
IMPORT_C void	SetSpeakingRateL ( TInt )
IMPORT_C void	SetVoiceL (const TVoice &)
IMPORT_C void	SetVolumeL ( TInt )
IMPORT_C TInt	SpeakingRateL ()
IMPORT_C void	StopL ()
IMPORT_C void	Synthesise ( TRequestStatus &)
IMPORT_C TVoice	VoiceL ()
IMPORT_C TInt	VolumeL ()

Private Member Functions
void	DoInitialiseSynthesisL (const TDesC &, const TFileName &, TRequestStatus &)

Inherited Functions
	RHandleBase::Attributes()const
	RHandleBase::BTraceId()const
	RHandleBase::DoExtendedClose()
	RHandleBase::Duplicate(const RThread &,TOwnerType)
	RHandleBase::FullName()const
	RHandleBase::FullName(TDes &)const
	RHandleBase::Handle()const
	RHandleBase::HandleInfo(THandleInfo *)
	RHandleBase::Name()const
	RHandleBase::NotifyDestruction(TRequestStatus &)
	RHandleBase::Open(const TFindHandleBase &,TOwnerType)
	RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
	RHandleBase::RHandleBase()
	RHandleBase::RHandleBase(TInt)
	RHandleBase::SetHandle(TInt)
	RHandleBase::SetHandleNC(TInt)
	RSessionBase::CreateSession(RServer2,const TVersion &)
	RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
	RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy ,TRequestStatus )
	RSessionBase::CreateSession(const TDesC &,const TVersion &)
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy ,TRequestStatus )
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
	RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
	RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
	RSessionBase::Open(TInt,TOwnerType)
	RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
	RSessionBase::Send(TInt)const
	RSessionBase::Send(TInt,const TIpcArgs &)const
	RSessionBase::SendReceive(TInt)const
	RSessionBase::SendReceive(TInt,TRequestStatus &)const
	RSessionBase::SendReceive(TInt,const TIpcArgs &)const
	RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
	RSessionBase::SetReturnedHandle(TInt)
	RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
	RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
	RSessionBase::ShareAuto()
	RSessionBase::ShareProtected()

Public Member Enumerations
enum	TTtsAudioOutput { ETtsOutputDefault = 0, ETtsOutputAll = 1, ETtsOutputNoOutput = 2, ETtsOutputPrivate = 3, ETtsOutputPublic = 4 }

Inherited Enumerations
	RHandleBase:TAttributes
	RSessionBase:TAttachMode

Inherited Attributes
	RHandleBase::iHandle

Constructor & Destructor Documentation

RSpeechSynthesis()

IMPORT_C

RSpeechSynthesis

(

)

Constructor

Member Functions Documentation

Close()

IMPORT_C void

(

)

Close connection to synthesis server

CustomCommandL(TInt, TInt)

IMPORT_C void	CustomCommandL	(	TInt	aCommand,
			TInt	aValue
		)

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.

leave: KErrNotSupported aCommand is not supported.

leave: KErrArgument if aValue is not valid.

Parameters

TInt aCommand	A custom command
TInt aValue	Parameter value for aCommand

DoInitialiseSynthesisL(const TDesC &, const TFileName &, TRequestStatus &)

void	DoInitialiseSynthesisL	(	const TDesC &	aText,
			const TFileName &	aFileName,
			TRequestStatus &	aStatus
		)	[private]

Internal function used for handling initialisation.

Parameters

const TDesC & aText
const TFileName & aFileName
TRequestStatus & aStatus

DurationL()

IMPORT_C TTimeIntervalMicroSeconds

DurationL

(

)

Returns estimated duration of synthesis. This function returns valid duration only after synthesis is initialised and before synthesis has completed.

leave: KErrNotReady if state is incorrect

leave: KErrNotSupported if current voice settings doesn't support duration information

GetLanguagesL(RArray< TLanguage > &)

IMPORT_C void

GetLanguagesL

(

RArray < TLanguage > &

aLanguages

)

Get supported synthesis languages

Parameters

RArray < TLanguage > & aLanguages

Contains supported languages after function call

GetVoicesL(RArray< TVoice > &, TLanguage)

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

Get available voices

Parameters

RArray < TVoice > & aVoices	Contains supported voices in TVoice structure after the function call.
TLanguage aLanguage	Defines a language that returned voices can speak.

InitialiseSynthesis(const TDesC &, TRequestStatus &)

IMPORT_C void	InitialiseSynthesis	(	const TDesC &	aText,
			TRequestStatus &	aStatus
		)

Initialise text to be synthesised. If there is synthesis already ongoing aStatus will be completed with KErrInUse.

Parameters

const TDesC & 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.
TRequestStatus & aStatus	Status of priming.

InitialiseSynthesis(const TDesC &, const TFileName &, TRequestStatus &)

IMPORT_C void	InitialiseSynthesis	(	const TDesC &	aText,
			const TFileName &	aFileName,
			TRequestStatus &	aStatus
		)

Initialise text to be synthesised to the file. If there is synthesis already ongoing aStatus will be completed with KErrInUse.

Parameters

const TDesC & 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.
const TFileName & 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.
TRequestStatus & aStatus	Status of priming

InitialiseSynthesis(const TDesC &, TDes8 &, TRequestStatus &)

IMPORT_C void	InitialiseSynthesis	(	const TDesC &	aText,
			TDes8 &	aDataBuffer,
			TRequestStatus &	aStatus
		)

TodoNot 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.

Parameters

const TDesC & 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.
TDes8 & 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.
TRequestStatus & aStatus	Status of priming

MaxSpeakingRateL()

IMPORT_C TInt

MaxSpeakingRateL

(

)

Returns maximum speaking rate.

MaxVolumeL()

IMPORT_C TInt

MaxVolumeL

(

)

Get maximum volume

Open()

IMPORT_C TInt

Open

(

)

Connect to synthesis server

PauseL()

IMPORT_C void

PauseL

(

)

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.

SetAudioOutputL(TTtsAudioOutput)

IMPORT_C void

SetAudioOutputL

(

TTtsAudioOutput

aAudioOutput

)

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

leave: KErrPermissionDenied if client doesn't have WriteDeviceData when setting output to ETtsOutputAll.

Parameters

TTtsAudioOutput aAudioOutput

- where the audio is routed.

SetAudioPriorityL(TInt, TInt)

IMPORT_C void	SetAudioPriorityL	(	TInt	aPriority,
			TInt	aPreference
		)

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.

leave: KErrPermissionDenied if client doesn't have Nokia VID.

Parameters

TInt aPriority	Audio priority
TInt aPreference	Audio preference

SetSpeakingRateL(TInt)

IMPORT_C void

SetSpeakingRateL

(

TInt

aSpeakingRate

)

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.

leave: KErrArgument if speaking rate is out of range.

MaxSpeakingRateL()

Parameters

TInt aSpeakingRate

Rate value

SetVoiceL(const TVoice &)

IMPORT_C void

SetVoiceL

(

const TVoice &

aVoice

)

Change voice. Change is effective after next InitialiseSynthesis() call is made and until new SetVoiceL() call is made or Close() is called.

leave: KErrArgument if aVoice is not valid

Parameters

const TVoice & 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.

SetVolumeL(TInt)

IMPORT_C void

SetVolumeL

(

TInt

aVolume

)

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

leave: KErrArgument if volume value is out of range,

MaxVolumeL()

Parameters

TInt aVolume

New volume, accepted values are in range from 0 to MaxVolumeL()

SpeakingRateL()

IMPORT_C TInt

SpeakingRateL

(

)

Returns the current speaking rate value.

StopL()

IMPORT_C void

StopL

(

)

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.

Synthesise(TRequestStatus &)

IMPORT_C void

Synthesise

(

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.

RSpeechSynthesis::InitialiseSynthesis() RSpeechSynthesis::PauseL()

Parameters

TRequestStatus & aStatus

Status of synthesis

VoiceL()

IMPORT_C TVoice

VoiceL

(

)

Get current voice.

VolumeL()

IMPORT_C TInt

VolumeL

(

)

Get current volume.

Member Enumerations Documentation

Enum TTtsAudioOutput

Possible parameter values for SetAudioOutputL()

RSpeechSynthesis::SetAudioOutputL()

Enumerators

ETtsOutputDefault = 0
ETtsOutputAll = 1
ETtsOutputNoOutput = 2
ETtsOutputPrivate = 3
ETtsOutputPublic = 4