1 /* |
|
2 * Copyright (c) 2006-2007 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: Client side header of Speech synthesis server |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef SPEECHSYNTHESIS_H |
|
20 #define SPEECHSYNTHESIS_H |
|
21 |
|
22 // INCLUDES |
|
23 |
|
24 #include <e32std.h> |
|
25 |
|
26 |
|
27 // CONSTANTS |
|
28 |
|
29 /** |
|
30 * Maximum length of text-to-speech voice name. |
|
31 * |
|
32 * @see TVoiceName |
|
33 */ |
|
34 const TInt KMaxNameLength = 64; |
|
35 |
|
36 /** |
|
37 * Text-to-speech voice name type definition. |
|
38 * |
|
39 * @see TVoice |
|
40 */ |
|
41 typedef TBuf<KMaxNameLength> TVoiceName; |
|
42 |
|
43 |
|
44 // CLASSES |
|
45 |
|
46 /** |
|
47 * Class containing basic information of text-to-speech voice. |
|
48 */ |
|
49 class TVoice |
|
50 { |
|
51 |
|
52 public: |
|
53 |
|
54 /** |
|
55 * Language spoken by the voice |
|
56 */ |
|
57 TLanguage iLanguage; |
|
58 |
|
59 /** |
|
60 * Name of the voice |
|
61 */ |
|
62 TVoiceName iVoiceName; |
|
63 |
|
64 /** |
|
65 * Sampling rate of the voice |
|
66 */ |
|
67 TInt iSamplingRate; |
|
68 |
|
69 /** |
|
70 * TVoice constructor |
|
71 */ |
|
72 inline TVoice(): |
|
73 iLanguage( ELangNone ), |
|
74 iSamplingRate( KErrNotFound ) |
|
75 { |
|
76 // Nothing |
|
77 } |
|
78 }; |
|
79 |
|
80 /** |
|
81 * Speech synthesis client side interface |
|
82 * |
|
83 |
|
84 * @code |
|
85 * // Simple example how to use synthesis server synchronously |
|
86 * _LIT( KText, "This is a text sample" ); |
|
87 * RSpeechSynthesis s; |
|
88 * TRequestStatus status; |
|
89 * |
|
90 * // Open connection |
|
91 * s.Open(); |
|
92 * |
|
93 * // Initialise |
|
94 * s.InitialiseSynthesis( KText, status ); |
|
95 * User::WaitForRequest( status ); |
|
96 * |
|
97 * // Start synthesis when initialisation is ready |
|
98 * s.Synthesise( status ); |
|
99 * User::WaitForRequest( status ); |
|
100 * |
|
101 * // Close connection |
|
102 * s.Close(); |
|
103 * @endcode |
|
104 * |
|
105 * @code |
|
106 * // Another example how to use synthesis server synchronously |
|
107 * _LIT( KText, "Second text sample" ); |
|
108 * RSpeechSynthesis s; |
|
109 * TRequestStatus status; |
|
110 * |
|
111 * // Open connection |
|
112 * s.Open(); |
|
113 * |
|
114 * // Set volume to maximum value |
|
115 * s.SetVolumeL( * s.MaxVolumeL() ); |
|
116 * |
|
117 * // Set speaking rate to half of maximum value |
|
118 * s.SetSpeakingRateL( * s.MaxSpeakingRateL() / 2 ); |
|
119 * |
|
120 * // Set synthesis language but leave voice name open |
|
121 * TVoice voice; |
|
122 * voice.iLanguage = User::Language(); |
|
123 * s.SetVoiceL( voice ); |
|
124 * |
|
125 * // Initialise |
|
126 * s.InitialiseSynthesis( KText, status ); |
|
127 * User::WaitForRequest( status ); |
|
128 * |
|
129 * // Ask estimated duration of synthesis. |
|
130 * // Note: Leaves if current TVoice doesn't support duration |
|
131 * TTimeIntervalMicroSeconds duration = s.DurationL(); |
|
132 * |
|
133 * // Start synthesis when initialisation is ready |
|
134 * s.Synthesise( status ); |
|
135 * User::WaitForRequest( status ); |
|
136 * |
|
137 * // Close connection |
|
138 * s.Close(); |
|
139 * @endcode |
|
140 */ |
|
141 class RSpeechSynthesis : public RSessionBase |
|
142 { |
|
143 |
|
144 public: |
|
145 |
|
146 /** |
|
147 * Possible parameter values for SetAudioOutputL() |
|
148 * |
|
149 * @see RSpeechSynthesis::SetAudioOutputL() |
|
150 */ |
|
151 enum TTtsAudioOutput |
|
152 { |
|
153 ETtsOutputDefault = 0, ///< Default |
|
154 ETtsOutputAll = 1, ///< All output devices are used |
|
155 ETtsOutputNoOutput = 2, ///< No output |
|
156 ETtsOutputPrivate = 3, ///< Private output device is used |
|
157 ETtsOutputPublic = 4 ///< Public output device is used |
|
158 }; |
|
159 |
|
160 public: |
|
161 |
|
162 /** |
|
163 * Constructor |
|
164 */ |
|
165 IMPORT_C RSpeechSynthesis(); |
|
166 |
|
167 /** |
|
168 * Connect to synthesis server |
|
169 * |
|
170 * @return KErrNone if successful, otherwise system-wide error code. |
|
171 */ |
|
172 IMPORT_C TInt Open(); |
|
173 |
|
174 /** |
|
175 * Close connection to synthesis server |
|
176 */ |
|
177 IMPORT_C void Close(); |
|
178 |
|
179 /** |
|
180 * Initialise text to be synthesised. If there is synthesis already |
|
181 * ongoing aStatus will be completed with KErrInUse. |
|
182 * |
|
183 * |
|
184 * @param aText Text to be synthesized. Text has to be valid until |
|
185 * aStatus is completed because this function is asynchronous |
|
186 * and the request that it represents may not complete until |
|
187 * some time after the call to the function has returned. |
|
188 * It is important, therefore, that this descriptor remain valid, |
|
189 * or remain in scope, until you have been notified that |
|
190 * the request is complete. |
|
191 * @param aStatus Status of priming. |
|
192 */ |
|
193 IMPORT_C void InitialiseSynthesis( const TDesC& aText, |
|
194 TRequestStatus& aStatus ); |
|
195 |
|
196 /** |
|
197 * Initialise text to be synthesised to the file. If there is synthesis |
|
198 * already ongoing aStatus will be completed with KErrInUse. |
|
199 * |
|
200 * @param aText Text to be synthesized. Text has to be valid until |
|
201 * aStatus is completed because this function is asynchronous |
|
202 * and the request that it represents may not complete until |
|
203 * some time after the call to the function has returned. |
|
204 * It is important, therefore, that this descriptor remain valid, |
|
205 * or remain in scope, until you have been notified that |
|
206 * the request is complete. |
|
207 * @param aFileName Output is written to this file. File name has to be |
|
208 * valid until aStatus is completed. Client should have capabilities |
|
209 * needed for writing location defined in aFileName, otherwise aStatus |
|
210 * will be completed by KErrPermissionDenied. |
|
211 * @param aStatus Status of priming |
|
212 */ |
|
213 IMPORT_C void InitialiseSynthesis( const TDesC& aText, |
|
214 const TFileName& aFileName, |
|
215 TRequestStatus& aStatus ); |
|
216 |
|
217 /** |
|
218 * @todo Not supported. aStatus will be always completed with KErrNotSupported. |
|
219 * |
|
220 * Initialise text to be synthesised to the descriptor. If there is synthesis |
|
221 * already ongoing aStatus will be completed with KErrInUse. |
|
222 * |
|
223 * @param aText Text to be synthesized. Text has to be valid until |
|
224 * aStatus is completed because this function is asynchronous |
|
225 * and the request that it represents may not complete until |
|
226 * some time after the call to the function has returned. |
|
227 * It is important, therefore, that this descriptor remain valid, |
|
228 * or remain in scope, until you have been notified that |
|
229 * the request is complete. |
|
230 * @param aDataBuffer Reference to a descriptor where output is stored |
|
231 * after Synthesise() is called. If all the data does not fit |
|
232 * into aDataBuffer Synthesise can be called several times. |
|
233 * @param aStatus Status of priming |
|
234 */ |
|
235 IMPORT_C void InitialiseSynthesis( const TDesC& aText, |
|
236 TDes8& aDataBuffer, |
|
237 TRequestStatus& aStatus ); |
|
238 |
|
239 /** |
|
240 * Synthesise the text or resume paused synthesis. |
|
241 * InitialiseSynthesis() has to be called succesfully before call to |
|
242 * this function will succeed. aStatus is completed with KErrNotReady |
|
243 * if initialisation has not been done. |
|
244 * |
|
245 * @param aStatus Status of synthesis |
|
246 * |
|
247 * @see RSpeechSynthesis::InitialiseSynthesis() |
|
248 * @see RSpeechSynthesis::PauseL() |
|
249 */ |
|
250 IMPORT_C void Synthesise( TRequestStatus& aStatus ); |
|
251 |
|
252 /** |
|
253 * Stop ongoing synthesis. Ongoing synthesis request is completed |
|
254 * with KErrAbort. Does nothing if there is no synthesis ongoing. |
|
255 * |
|
256 * @leave KErrInUse if request is made to stop other client's synthesis. |
|
257 */ |
|
258 IMPORT_C void StopL(); |
|
259 |
|
260 /** |
|
261 * Pause synthesis. Resuming can be done by calling Synthesize(). |
|
262 * Ongoing synthesis request is completed with KErrCancel. |
|
263 * |
|
264 * @leave KErrNotSupported if trying to pause synthesis to file. |
|
265 * @leave KErrNotReady if there is no synthesis ongoing. |
|
266 */ |
|
267 IMPORT_C void PauseL(); |
|
268 |
|
269 /** |
|
270 * Returns estimated duration of synthesis. This function returns valid |
|
271 * duration only after synthesis is initialised and before synthesis has |
|
272 * completed. |
|
273 * |
|
274 * @return Estimated duration of speech synthesis playback. |
|
275 * |
|
276 * @leave KErrNotReady if state is incorrect |
|
277 * @leave KErrNotSupported if current voice settings doesn't support |
|
278 * duration information |
|
279 */ |
|
280 IMPORT_C TTimeIntervalMicroSeconds DurationL(); |
|
281 |
|
282 /** |
|
283 * Get supported synthesis languages |
|
284 * |
|
285 * @param aLanguages Contains supported languages after function call |
|
286 * |
|
287 */ |
|
288 IMPORT_C void GetLanguagesL( RArray<TLanguage>& aLanguages ); |
|
289 |
|
290 /** |
|
291 * Get available voices |
|
292 * |
|
293 * @param aVoices Contains supported voices in TVoice structure after |
|
294 * the function call. |
|
295 * @param aLanguage Defines a language that returned voices can speak. |
|
296 * |
|
297 */ |
|
298 IMPORT_C void GetVoicesL( RArray<TVoice>& aVoices, TLanguage aLanguage ); |
|
299 |
|
300 /** |
|
301 * Get current voice. |
|
302 * |
|
303 * @return Current voice. |
|
304 * |
|
305 */ |
|
306 IMPORT_C TVoice VoiceL(); |
|
307 |
|
308 /** |
|
309 * Change voice. Change is effective after next InitialiseSynthesis() call |
|
310 * is made and until new SetVoiceL() call is made or Close() is called. |
|
311 * |
|
312 * @param aVoice New voice to be set. aVoice.iLanguage is the only mandatory |
|
313 * parameter,others can be undefined and server may ignore |
|
314 * those if invalid values are given. |
|
315 * |
|
316 * @leave KErrArgument if aVoice is not valid |
|
317 */ |
|
318 IMPORT_C void SetVoiceL( const TVoice& aVoice ); |
|
319 |
|
320 /** |
|
321 * Returns maximum speaking rate. |
|
322 * |
|
323 * @return Maximum speaking rate |
|
324 * |
|
325 */ |
|
326 IMPORT_C TInt MaxSpeakingRateL(); |
|
327 |
|
328 /** |
|
329 * Returns the current speaking rate value. |
|
330 * |
|
331 * @return Current speaking rate |
|
332 * |
|
333 */ |
|
334 IMPORT_C TInt SpeakingRateL(); |
|
335 |
|
336 /** |
|
337 * Sets the speaking rate. Range is 1..MaxSpeakingRateL(). Setting will |
|
338 * be effective after next InitialiseSynthesis() call and until new rate |
|
339 * is set or Close() is called. Note: All voices doesn't support speaking |
|
340 * rate changes and in that case there is no audible change. |
|
341 * |
|
342 * @param aSpeakingRate Rate value |
|
343 * |
|
344 * @leave KErrArgument if speaking rate is out of range. |
|
345 * |
|
346 * @see MaxSpeakingRateL() |
|
347 */ |
|
348 IMPORT_C void SetSpeakingRateL( TInt aSpeakingRate ); |
|
349 |
|
350 /** |
|
351 * Get maximum volume |
|
352 * |
|
353 * @return Maximum volume |
|
354 * |
|
355 */ |
|
356 IMPORT_C TInt MaxVolumeL(); |
|
357 |
|
358 /** |
|
359 * Get current volume. |
|
360 * |
|
361 * @return Volume level between 0 and MaxVolumeL() |
|
362 * |
|
363 */ |
|
364 IMPORT_C TInt VolumeL(); |
|
365 |
|
366 /** |
|
367 * Change volume. Will be effective until new volume is set or Close() |
|
368 * is called. |
|
369 * |
|
370 * @param aVolume New volume, accepted values are in range from 0 to MaxVolumeL() |
|
371 * |
|
372 * @leave KErrArgument if volume value is out of range, |
|
373 * |
|
374 * @see MaxVolumeL() |
|
375 */ |
|
376 IMPORT_C void SetVolumeL( TInt aVolume ); |
|
377 |
|
378 /** |
|
379 * Sets the playback priority and preference values. Setting will |
|
380 * be effective after next InitialiseSynthesis() call and until new priority |
|
381 * is set or Close() is called. Client needs Nokia VID to use |
|
382 * this function. |
|
383 * |
|
384 * @param aPriority Audio priority |
|
385 * @param aPreference Audio preference |
|
386 * |
|
387 * @leave KErrPermissionDenied if client doesn't have Nokia VID. |
|
388 */ |
|
389 IMPORT_C void SetAudioPriorityL( TInt aPriority, TInt aPreference ); |
|
390 |
|
391 /** |
|
392 * Sets the audio output. Setting will be effective immediately and until |
|
393 * new value is set or connection closed. Client needs WriteDeviceData |
|
394 * capability if setting output to ETtsOutputAll |
|
395 * |
|
396 * @param aAudioOutput - where the audio is routed. |
|
397 * |
|
398 * @leave KErrPermissionDenied if client doesn't have WriteDeviceData when |
|
399 * setting output to ETtsOutputAll. |
|
400 * |
|
401 */ |
|
402 IMPORT_C void SetAudioOutputL( TTtsAudioOutput aAudioOutput ); |
|
403 |
|
404 /** |
|
405 * Send custom command to the server. By using this function it is possible |
|
406 * to make adjustments to the synthesis process. |
|
407 * Note: Currently there is no supported commands. |
|
408 * |
|
409 * @param aCommand A custom command |
|
410 * @param aValue Parameter value for aCommand |
|
411 * |
|
412 * @leave KErrNotSupported aCommand is not supported. |
|
413 * @leave KErrArgument if aValue is not valid. |
|
414 */ |
|
415 IMPORT_C void CustomCommandL( TInt aCommand, TInt aValue ); |
|
416 |
|
417 private: |
|
418 |
|
419 /** |
|
420 * Internal function used for handling initialisation. |
|
421 */ |
|
422 void DoInitialiseSynthesisL( const TDesC& aText, |
|
423 const TFileName& aFileName, |
|
424 TRequestStatus& aStatus ); |
|
425 |
|
426 }; |
|
427 |
|
428 #endif // SPEECHSYNTHESIS_H |
|