pangdudu-swiftly 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.rdoc ADDED
@@ -0,0 +1,57 @@
1
+ == swiftly
2
+
3
+ Hi everybody!
4
+
5
+ I always wanted my ruby apps to tell me when something is wrong. :)
6
+
7
+ This is inspired by the gem flite4r I found after lunch. After looking around a
8
+ bit I found http://www.cepstral.com, which makes some pretty decent unit selection
9
+ based text to speech stuff.
10
+
11
+ They have some demo voices, but most of their voices cost around 29$. I couldn't
12
+ find any "free" TTS unit selection corpora, so if you know one, text me. :)
13
+
14
+ Oki, it's still pretty basic. It essentially just offers one method:
15
+
16
+ speak "something"
17
+
18
+ That's all I need right now, it will be pretty easy to bloat the whole thing with
19
+ all the stuff cepstrals swift can also do: SSML input, pitch, speed, other voices, etc ...
20
+
21
+ If you want to do that, feel free, fork or text me and I'll add you to the maintainors.
22
+
23
+ This is also the first time i've written a C extension for ruby (which is easy, so try it),
24
+ so if know a prettier way to do what Swiftly.c does, text me.
25
+
26
+ INSTALL:
27
+
28
+ Before this will work, you'll need to install a cepstral (5.1) voice and the
29
+ swift-app and sdk.
30
+
31
+ It's pretty easy, just go here: http://www.cepstral.com/downloads/
32
+ download a voice (comes with the swift-app and sdk) and install it.
33
+
34
+ then go to lib (that's where my code is) and run: ruby extconf.rb && make
35
+
36
+ Tada!
37
+
38
+ I'll build a gem later or so, lazy...
39
+
40
+ Example code:
41
+
42
+ require 'swiftly'
43
+ include Swiftly
44
+
45
+ class String
46
+ def to_speech
47
+ speak self
48
+ end
49
+ end
50
+
51
+ "Test. Test.".to_speech
52
+
53
+
54
+ Have fun!
55
+
56
+ ,nick
57
+
@@ -0,0 +1,1040 @@
1
+ /* swift.h: Swift API for text-to-speech
2
+ *
3
+ * Copyright (c) 2002-2006 Cepstral LLC. All rights reserved.
4
+ *
5
+ * Redistribution of this file, in whole or in part, with or without
6
+ * modification, is not allowed without express written permission of
7
+ * the copyright holder.
8
+ */
9
+
10
+ #ifndef _SWIFT_H_
11
+ #define _SWIFT_H_
12
+
13
+ #ifdef __cplusplus
14
+ extern "C" {
15
+ #endif /* __cplusplus */
16
+
17
+ /**
18
+ * \file swift.h
19
+ * Main include file for Swift text-to-speech engine.
20
+ **/
21
+
22
+ #include "swift_exports.h"
23
+ #include "swift_defs.h"
24
+ #include "swift_params.h"
25
+
26
+ /* swift_version strings exposed through SWIFT_API */
27
+ /** Contains the name of the Swift engine, as a string. */
28
+ SWIFT_API extern const char *swift_engine_name;
29
+ /** Contains the version of the Swift library, as a string. */
30
+ SWIFT_API extern const char *swift_version;
31
+ /** Contains the date of the Swift library, as a string. */
32
+ SWIFT_API extern const char *swift_date;
33
+ /** Contains the platform for which the Swift library was built,
34
+ * as a string. */
35
+ SWIFT_API extern const char *swift_platform;
36
+
37
+ /**
38
+ * Open an instance of the Swift TTS engine.
39
+ *
40
+ * @param params A swift_params object with engine initialization parameters.
41
+ * <br>Parameters recognized are:
42
+ * - config/voice-path (string): A colon (most platforms) or semicolon
43
+ * (Windows) delimited list of directories to be searched for voices.
44
+ * - config/default-voice (string): The name of the default voice to
45
+ * use for text-to-speech.
46
+ * - NOTE: The engine retains ownership of this object, so you should not
47
+ * call swift_params_delete() on it.
48
+ * @return a new engine if successful, NULL for failure.
49
+ **/
50
+ SWIFT_API
51
+ swift_engine * SWIFT_CALLCONV swift_engine_open(swift_params *params);
52
+
53
+ /**
54
+ * Close and delete a Swift TTS engine.
55
+ *
56
+ * @param engine A swift_engine object
57
+ * @return SWIFT_SUCCESS if successful, SWIFT_ENGINE_INUSE if engine
58
+ * still has open ports associated with it
59
+ **/
60
+ SWIFT_API
61
+ swift_result_t SWIFT_CALLCONV swift_engine_close(swift_engine *engine);
62
+
63
+ /**
64
+ * Set the voice retention policy for the engine. Voice settings and
65
+ * parameters will be allocated as the voice is loaded. The retention
66
+ * policy dictates when this information will be released, allowing for
67
+ * the adjustment of voice-load overhead.
68
+ *
69
+ * NOTE: This function currently has no effect. The engine uses a retention
70
+ * policy of SWIFT_VOICE_RETAIN_FOREVER regardless of the actual setting.
71
+ *
72
+ * @param engine A swift_engine object
73
+ * @param policy A voice retention (i.e.: garbage collection policy). May
74
+ * be one of:
75
+ * - SWIFT_VOICE_RETAIN_FOREVER: retain voice information for the
76
+ * lifetime of the engine.
77
+ * - SWIFT_VOICE_RETAIN_PORT_USAGE: retain voice information for the
78
+ * lifetime of the ports using it.
79
+ * - SWIFT_VOICE_RETAIN_NONE: retain voice information only as long as
80
+ * the voice is in use.
81
+ * @return void
82
+ **/
83
+ SWIFT_API
84
+ void SWIFT_CALLCONV
85
+ swift_engine_set_voice_retention_policy(swift_engine *engine,
86
+ swift_voice_retention_policy_t policy);
87
+
88
+ /**
89
+ * Get the voice retention policy for the engine.
90
+ *
91
+ * @param engine A swift_engine object
92
+ * @return The voice retention (i.e.: garbage collection policy). May be
93
+ * one of:
94
+ * - SWIFT_VOICE_RETAIN_FOREVER: retain voice information for the
95
+ * lifetime of the engine.
96
+ * - SWIFT_VOICE_RETAIN_PORT_USAGE: retain voice information for the
97
+ * lifetime of the ports using it.
98
+ * - SWIFT_VOICE_RETAIN_NONE: retain voice information only as long as
99
+ * the voice is in use.
100
+ **/
101
+ SWIFT_API
102
+ swift_voice_retention_policy_t SWIFT_CALLCONV
103
+ swift_engine_get_voice_retention_policy(swift_engine *engine);
104
+
105
+ /**
106
+ * Open a new TTS port.
107
+ *
108
+ * @param engine An instance of a swift engine from swift_engine_open
109
+ * @param params A swift_params object with port initialization
110
+ * parameters and port-wide synthesis parameters.
111
+ * - NOTE: The port retains ownership of this object, so you should not
112
+ * call swift_params_delete() on it.
113
+ * @return The new port, or NULL for failure.
114
+ **/
115
+ SWIFT_API
116
+ swift_port * SWIFT_CALLCONV swift_port_open(swift_engine *engine,
117
+ swift_params *params);
118
+
119
+ /**
120
+ * Release resources of a TTS port. This is meant to be used when doing
121
+ * asynchronous processing. If called when SWIFT_EVENT_END is true, the concurrency
122
+ * license is released in the thread - thus relieving the main thread (which is
123
+ * calling swift_port_open) to allocate a port.
124
+ *
125
+ * Using this call eliminates the need for having a timeout of swift_port_open or
126
+ * the license server from cleaning dormant licenses.
127
+ *
128
+ * @param port The swift_port to close.
129
+ * @return SWIFT_SUCCESS on successful close, or one of several
130
+ * swift_result_t values.
131
+ **/
132
+ SWIFT_API
133
+ swift_result_t SWIFT_CALLCONV
134
+ swift_port_done_on_thread(swift_port *port);
135
+
136
+ /**
137
+ * Close a TTS port and dispose of its resources.
138
+ *
139
+ * @param port The swift_port to close.
140
+ * @return SWIFT_SUCCESS on successful close, or one of several
141
+ * swift_result_t values.
142
+ **/
143
+ SWIFT_API
144
+ swift_result_t SWIFT_CALLCONV swift_port_close(swift_port *port);
145
+
146
+ /**
147
+ * User-Defined callback function type (for audio, events, errors, etc).
148
+ * Pointer to this function is passed to swift_port_set_callback().
149
+ *
150
+ * @param event The event object this callback is being called for.
151
+ * @param type The type of this event.
152
+ * @param udata The user data pointer passed to swift_port_set_callback().
153
+ * @return Your callback should return SWIFT_SUCCESS (or 0), unless
154
+ * you wish to halt synthesis immediately, in which case
155
+ * you should return SWIFT_INTERRUPTED.
156
+ **/
157
+ typedef swift_result_t (*swift_callback_t)(swift_event *event,
158
+ swift_event_t type,
159
+ void *udata);
160
+
161
+ /**
162
+ * Set a callback for a port. This allows a user-defined function to
163
+ * handle swift_events as they are sent by the engine.
164
+ *
165
+ * @param port The port for which this callback is to be set.
166
+ * @param callback The callback function to set up, or NULL to remove
167
+ * an existing callback function.
168
+ * @param mask A bitmask of events you wish this function to be called
169
+ * for (see enum swift_event_t).
170
+ * @param udata User Data - pointer to anything you want to pass to the
171
+ * callback function.
172
+ * @return The previous callback function, or NULL if none.
173
+ **/
174
+ SWIFT_API
175
+ swift_callback_t SWIFT_CALLCONV
176
+ swift_port_set_callback(swift_port *port, swift_callback_t callback,
177
+ unsigned int mask, void *udata);
178
+
179
+ /**
180
+ * Get the string name of the given event type.
181
+ *
182
+ * @param type The event type of which to get the string name.
183
+ * @return The string name of the event, or NULL if no such event.
184
+ **/
185
+ SWIFT_API
186
+ const char * SWIFT_CALLCONV swift_event_type_get_name(swift_event_t type);
187
+
188
+ /**
189
+ * Get the event type for the given string name.
190
+ *
191
+ * @param name The string event name for which to get the type.
192
+ * @return The swift_event_t corresponding to the name, or 0 if none.
193
+ **/
194
+ SWIFT_API
195
+ swift_event_t SWIFT_CALLCONV swift_event_name_get_type(const char *name);
196
+
197
+ /**
198
+ * Get the swift_port and swift_background_t thread ID from which an event
199
+ * was generated.
200
+ *
201
+ * @param event The event for which to get the information.
202
+ * @param port Output - the swift_port from which the event was generated.
203
+ * @param async Output - the swift_background_t thread ID from wich the event
204
+ * was generated.
205
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if event is NULL
206
+ **/
207
+ SWIFT_API
208
+ swift_result_t SWIFT_CALLCONV
209
+ swift_event_get_context(swift_event *event, swift_port **port,
210
+ swift_background_t *async);
211
+
212
+ /**
213
+ * Get the timepoints for an event of type sentence, phrase, word, token,
214
+ * syllable, or phoneme.
215
+ *
216
+ * @param event The event for which to get the information.
217
+ * @param start Output - The starting time of the event with relation to
218
+ * the start of synthesis.
219
+ * @param len Output - The length of the event
220
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if event is NULL
221
+ **/
222
+ SWIFT_API
223
+ swift_result_t SWIFT_CALLCONV swift_event_get_times(swift_event *event,
224
+ float *start, float *len);
225
+
226
+ /**
227
+ * Get the text positions for an event of type sentence, phrase, word, or
228
+ * token.
229
+ *
230
+ * @param event The event for which to get the information.
231
+ * @param start Output - The starting position in the synthesis input text
232
+ * corresponding to the event.
233
+ * @param len Output - The length in characters of the text corresponding
234
+ * to the event.
235
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if event is NULL,
236
+ * or SWIFT_WRONG_EVENT if event type isn't
237
+ * SWIFT_EVENT_[SENTENCE/PHRASE/TOKEN/WORDBOOKMARK].
238
+ **/
239
+ SWIFT_API
240
+ swift_result_t SWIFT_CALLCONV swift_event_get_textpos(swift_event *event,
241
+ int *start, int *len);
242
+
243
+ /**
244
+ * Get the text string associated with an event of type sentence, phrase,
245
+ * word, or phoneme.
246
+ *
247
+ * @param event The event for which to get the information.
248
+ * @param text Output - pointer to the text associated with the event.
249
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
250
+ **/
251
+ SWIFT_API
252
+ swift_result_t SWIFT_CALLCONV swift_event_get_text(swift_event *event,
253
+ char **text);
254
+
255
+ /**
256
+ * Get the audio buffer for an audio event.
257
+ *
258
+ * @param event The event for which to get the audio buffer.
259
+ * @param buf Output - The buffer that will receive the waveform.
260
+ * @param nbytes Output - The number of bytes copied into the buffer.
261
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
262
+ **/
263
+ SWIFT_API
264
+ swift_result_t SWIFT_CALLCONV swift_event_get_audio(swift_event *event,
265
+ void **buf, int *nbytes);
266
+
267
+ /**
268
+ * Get the swift_waveform structure for an audio event.
269
+ *
270
+ * @param event The event for which to get the audio buffer.
271
+ * @param wave Input/Output - A pointer to a wave structure.
272
+ * @param concatenate Boolean - If true, audio will be concatenated onto the
273
+ * wave structure passed in. If false, the synthesized
274
+ * audio will overwrite any audio that may already be in
275
+ * the wave structure.
276
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
277
+ **/
278
+ SWIFT_API
279
+ swift_result_t SWIFT_CALLCONV swift_event_get_wave(swift_event *event,
280
+ swift_waveform **wave,
281
+ int concatenate);
282
+
283
+ /**
284
+ * Get the error code and string message for an error event.
285
+ *
286
+ * @param event The error event for which to get the error information.
287
+ * @param rv Output - The error code of the error event.
288
+ * @param errmsg Output - The string message for the error event.
289
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if event is
290
+ * NULL, or SWIFT_WRONG_EVENT if event type is not
291
+ * SWIFT_EVENT_ERROR.
292
+ **/
293
+ SWIFT_API
294
+ swift_result_t SWIFT_CALLCONV swift_event_get_error(swift_event *event,
295
+ swift_result_t *rv,
296
+ const char **errmsg);
297
+
298
+ /**
299
+ * Set a port parameter.
300
+ *
301
+ * @param port The port being modified.
302
+ * @param name The name of the parameter.
303
+ * @param val The value (as a swift_val) of the parameter.
304
+ * @param async The background job in which to set this parameter.
305
+ * @return SWIFT_SUCCESS if successful, SWIFT_INVALID_PARAM if
306
+ * no such parameter exists.
307
+ *
308
+ * This function sets a synthesis parameter in a port, and optionally
309
+ * sets it in some or all of that port's running background jobs. The
310
+ * parameter and value described by NAME and VAL must be valid,
311
+ * i.e. NAME must specify a parameter that exists, and VAL must be a
312
+ * proper value for that parameter. swift_param_validate() is used to
313
+ * check this, against swift_param_descriptors.
314
+ **/
315
+ SWIFT_API
316
+ swift_result_t SWIFT_CALLCONV swift_port_set_param(swift_port *port,
317
+ const char *name,
318
+ swift_val *val,
319
+ swift_background_t async);
320
+ /**
321
+ * Set a list of parameters in a port.
322
+ *
323
+ * @param port The port on which to set the parameters list.
324
+ * @param params The list of parameters to set on the port.
325
+ * @param async The background job, if any, to set this paramters
326
+ * list in.
327
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
328
+ **/
329
+ SWIFT_API
330
+ swift_result_t SWIFT_CALLCONV swift_port_set_params(swift_port *port,
331
+ swift_params *params,
332
+ swift_background_t async);
333
+
334
+ /** Set an integer or boolean parameter in a port. */
335
+ #define swift_port_set_param_int(p,n,i,a) \
336
+ swift_port_set_param(p,n,swift_val_int((int)(i)),a)
337
+
338
+ /** Set a floating-point parameter in a port. */
339
+ #define swift_port_set_param_float(p,n,f,a) \
340
+ swift_port_set_param(p,n,swift_val_float((float)(f)),a)
341
+
342
+ /** Set a string parameter in a port. */
343
+ #define swift_port_set_param_string(p,n,s,a) \
344
+ swift_port_set_param(p,n,swift_val_string((const char *)(s)),a)
345
+
346
+ /**
347
+ * Get a pointer to the first (default) voice matching params.
348
+ *
349
+ * @param port The port on which to search for voices.
350
+ * @param search_criteria A semicolon-separated list of attribute=value
351
+ * pairs required from the voice, or NULL to return
352
+ * the default voice.
353
+ * @param order_criteria A semicolon-separated list of attribute=value
354
+ * pairs used to set a loose sorting order on the
355
+ * list of those that match match the seach_criteria.
356
+ * Voices matching the order_criteria are placed at
357
+ * the top of the list.
358
+ * @return A descriptor for the voice, or NULL if not found.
359
+ *
360
+ * The search_criteria and order_criteria arguments are strings containing
361
+ * one or more expressions which are to be tested against the voice's
362
+ * attributes. These expressions are of the form ATTR=VALUE,
363
+ * ATTR<VALUE, or ATTR>VALUE. For example, to search for female
364
+ * voices only, you would call swift_port_find_first_voice(port,
365
+ * "speaker/gender=female", NULL).
366
+ *
367
+ * The order_criteria argument controls the ordering of the voices returned.
368
+ *
369
+ * Currently available attributes to use for search_criteria and order_criteria
370
+ * are:
371
+ * - name
372
+ * - path
373
+ * - version
374
+ * - sample-rate
375
+ * - license/key
376
+ * - language/tag
377
+ * - language/name
378
+ * - language/version
379
+ * - lexicon/name
380
+ * - lexicon/version
381
+ * - speaker/name
382
+ * - speaker/gender
383
+ * - speaker/age
384
+ *
385
+ * Negation of an expression is allowed, simply prepend a '!'.
386
+ * Disjunctions and conjunctions are also allowed, using '|' and '&'
387
+ * respectively. So to find voices for either US or UK English, you
388
+ * could call swift_port_find_first_voice(port,
389
+ * "language/tag=en-US|language/tag=en-UK");
390
+ **/
391
+ SWIFT_API
392
+ swift_voice * SWIFT_CALLCONV
393
+ swift_port_find_first_voice(swift_port *port, const char *search_criteria,
394
+ const char *order_criteria);
395
+
396
+ /**
397
+ * Get the next voice in the list of voices matching the attributes
398
+ * passed to swift_find_first_voice().
399
+ *
400
+ * @param port The port on which to find the next voice.
401
+ * @return The next matching voice, or NULL if the end of the list is
402
+ * reached.
403
+ **/
404
+ SWIFT_API
405
+ swift_voice * SWIFT_CALLCONV swift_port_find_next_voice(swift_port *port);
406
+
407
+ /** Rewind the voice pointer to the first voice returned by
408
+ * swift_port_find_find_first_voice().
409
+ *
410
+ * @param port The port on which to rewind the voice list.
411
+ * @return The first voice in the list returned by
412
+ * swift_port_find_first_voice().
413
+ **/
414
+ SWIFT_API
415
+ swift_voice * SWIFT_CALLCONV swift_port_rewind_voices(swift_port *port);
416
+
417
+ /**
418
+ * Load a voice and set it as the port's current voice.
419
+ *
420
+ * @param port The port on which to set the voice.
421
+ * @param voice The voice to load and set as the port's current voice.
422
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
423
+ **/
424
+ SWIFT_API
425
+ swift_result_t SWIFT_CALLCONV swift_port_set_voice(swift_port *port,
426
+ swift_voice *voice);
427
+
428
+ /**
429
+ * Load the voice referenced by name and set it as the port's current
430
+ * voice.
431
+ *
432
+ * @param port The port on which to set the voice.
433
+ * @param name The name of the voice to load and set on the port.
434
+ * @return The voice if it was successfully loaded, else NULL.
435
+ **/
436
+ SWIFT_API
437
+ swift_voice * SWIFT_CALLCONV swift_port_set_voice_by_name(swift_port *port,
438
+ const char *name);
439
+
440
+ /**
441
+ * Load a voice from a directory and set it as the port's current voice.
442
+ *
443
+ * @param port The port on which to set the voice.
444
+ * @param dir The directory from which to load the voice.
445
+ * @return The voice if it was successfully loaded, else NULL.
446
+ **/
447
+ SWIFT_API
448
+ swift_voice * SWIFT_CALLCONV swift_port_set_voice_from_dir(swift_port *port,
449
+ const char *dir);
450
+
451
+ /**
452
+ * Get a pointer to the current voice.
453
+ *
454
+ * @param port The port from which to get the current voice.
455
+ * @return The current voice from the port. This could be NULL
456
+ * if no voice was ever set for the port.
457
+ **/
458
+ SWIFT_API
459
+ swift_voice * SWIFT_CALLCONV swift_port_get_current_voice(swift_port *port);
460
+
461
+ /**
462
+ * Get an attribute from a voice.
463
+ *
464
+ * @param voice The voice from which to get the attribute.
465
+ * @param attr The name of the attribute to get from the voice.
466
+ * @return The value of the requested param, or NULL.
467
+ *
468
+ * Currently available attributes are:
469
+ * - id
470
+ * - name
471
+ * - path
472
+ * - version
473
+ * - buildstamp
474
+ * - sample-rate
475
+ * - license/key
476
+ * - language/tag
477
+ * - language/name
478
+ * - language/version
479
+ * - lexicon/name
480
+ * - lexicon/version
481
+ * - speaker/name
482
+ * - speaker/gender
483
+ * - speaker/age
484
+ **/
485
+ SWIFT_API
486
+ const char * SWIFT_CALLCONV swift_voice_get_attribute(swift_voice *voice,
487
+ const char *attr);
488
+
489
+ /**
490
+ * Get all attributes from a voice.
491
+ * @param voice The voice to get attributes for.
492
+ * @param out_params Output - A swift_params in which to store the
493
+ * attributes.
494
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if voice
495
+ * or out_params is NULL
496
+ *
497
+ * After getting the attributes, you can use swift_params_dump() to
498
+ * print them out or swift_params_foreach() to iterate over them.
499
+ **/
500
+ SWIFT_API
501
+ swift_result_t SWIFT_CALLCONV
502
+ swift_voice_get_attributes(swift_voice *voice, swift_params *out_params);
503
+
504
+ /**
505
+ * Load custom lexicon entries into a voice from a file.
506
+ *
507
+ * @param voice The voice for which to load the lexicon.
508
+ * @param file The file from which to load the lexicon.
509
+ * @return SWIFT_SUCCESS, or SWIFT_FILE_ERROR if file could not be opened.
510
+ *
511
+ * When synthesizing text, the search order for lexicon entries is:
512
+ * <br>1. Lexicons loaded with this API call, most recent first.
513
+ * <br>2. A lexicon.txt file in the voice directory
514
+ * <br>3. The built-in lexicon
515
+ **/
516
+ SWIFT_API
517
+ swift_result_t SWIFT_CALLCONV swift_voice_load_lexicon(swift_voice *voice,
518
+ const char *file);
519
+
520
+ /**
521
+ * Returns the string encoding of the current active voice on the port.
522
+ *
523
+ * @param port The port from which to get the language encoding.
524
+ * @return The port's active voice's text encoding, or NULL if that
525
+ * can't be attained.
526
+ **/
527
+ SWIFT_API
528
+ const char * SWIFT_CALLCONV swift_port_language_encoding(swift_port *port);
529
+
530
+ /**
531
+ * Load a special effects output chain into a port from a file.
532
+ *
533
+ * @param port The port onto which to load the sfx chain.
534
+ * @param file The file to from which to load, or NULL to remove the
535
+ * current sfx chain without loading a new one.
536
+ * @return SWIFT_SUCCESS, or SWIFT_FILE_ERROR if file could not be opened.
537
+ *
538
+ **/
539
+ SWIFT_API
540
+ swift_result_t SWIFT_CALLCONV swift_port_load_sfx(swift_port *port,
541
+ const char *file);
542
+
543
+ /**
544
+ * Query the status of a background job.
545
+ *
546
+ * @param port The port to query for background job status.
547
+ * @param async The background job to look for. Can one of:
548
+ * - A swift_background_t thread ID
549
+ * - SWIFT_ASYNC_ANY to get the status of any job
550
+ * - SWIFT_ASYNC_CURRENT to get the status of the currently running job
551
+ * @return One of:
552
+ * - SWIFT_STATUS_UNKNOWN if the job specified doesn't exist
553
+ * - SWIFT_STATUS_DONE if it has completed
554
+ * - SWIFT_STATUS_RUNNING if it is currently running
555
+ * - SWIFT_STATUS_QUEUED if it is scheduled to run in the future.
556
+ **/
557
+ SWIFT_API
558
+ swift_status_t SWIFT_CALLCONV swift_port_status(swift_port *port,
559
+ swift_background_t async);
560
+
561
+ /**
562
+ * Wait for a background job (and any jobs ahead of it) to complete.
563
+ *
564
+ * @param port The port on which to wait for background jobs.
565
+ * @param async The background job to wait for. Can be one of:
566
+ * - A swift_background_t thread ID
567
+ * - SWIFT_ASYNC_ANY to wait for the completion of any job
568
+ * - SWIFT_ASYNC_CURRENT to wait for the completion of the currently
569
+ * running job
570
+ * @return SWIFT_SUCCESS
571
+ **/
572
+ SWIFT_API
573
+ swift_result_t SWIFT_CALLCONV swift_port_wait(swift_port *port,
574
+ swift_background_t async);
575
+
576
+ /**
577
+ * Stop and cancel a background job, waiting for any jobs ahead of it
578
+ * on the port to complete, and cancelling any jobs after it.
579
+ *
580
+ * @param port The port to on which to stop background jobs.
581
+ * @param async The background job to stop. Can be one of:
582
+ * - A swift_background_t thread ID
583
+ * - SWIFT_ASYNC_ANY to stop any job
584
+ * - SWIFT_ASYNC_CURRENT to stop the currently running job
585
+ * @param place The event (e.g. word, sentence, syllable) to wait for
586
+ * before halting. Use SWIFT_EVENT_NOW for immediate halt.
587
+ * - NOTE: This parameter is currently ignored. Halting always occurs
588
+ * immediately.
589
+ * - NOTE: No swift_events will be sent to your swift_callback_t function
590
+ * for the given background job after swift_port_stop is called.
591
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if port or its
592
+ * thread handler is NULL.
593
+ **/
594
+ SWIFT_API
595
+ swift_result_t SWIFT_CALLCONV swift_port_stop(swift_port *port,
596
+ swift_background_t async,
597
+ swift_event_t place);
598
+
599
+ /**
600
+ * Pause a background job. If the job you want to pause hasn't started yet
601
+ * and is in the queue, then any jobs ahead of it complete first.
602
+ *
603
+ * @param port The port on which to pause a background job.
604
+ * @param async The background job to pause. Can be one of:
605
+ * - A swift_background_t thread ID
606
+ * - SWIFT_ASYNC_ANY for any job
607
+ * - SWIFT_ASYNC_CURRENT for the currently running job
608
+ * @param place The event (e.g. word, sentence, syllable) to wait for
609
+ * before halting. Use SWIFT_EVENT_NOW for immediate pause.
610
+ * - NOTE: This parameter is currently ignored. Halting always occurs
611
+ * immediately.
612
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
613
+ **/
614
+ SWIFT_API
615
+ swift_result_t SWIFT_CALLCONV swift_port_pause(swift_port *port,
616
+ swift_background_t async,
617
+ swift_event_t place);
618
+
619
+ /**
620
+ * Synthesize text on the given port.
621
+ *
622
+ * @param port The port on which to perform synthesis.
623
+ * @param text Text to synthesize.
624
+ * @param nbytes Length, in bytes, of text. If 0, this paramter is ignored.
625
+ * @param encoding Character encoding of the input text. If NULL, the default
626
+ * encoding is assumed.
627
+ * @param async Output - Thread ID of the background job on which to run
628
+ * this synthesis call.<br>If NULL, synthesis occurs
629
+ * synchronously, thus blocking until complete.
630
+ * @param params The parameters to be used for this synthesis call. Can
631
+ * be NULL.
632
+ * - NOTE: The utterance retains ownership of this object, so you should not call
633
+ * swift_params_delete() on it.
634
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
635
+ *
636
+ * - NOTE: If a voice was not explicitely set on the port via
637
+ * swift_port_set_voice(), swift_port_set_voice_by_name(), or
638
+ * swift_port_set_voice_from_dir(), then this call implicitely loads
639
+ * the default voice and sets it as the port's current voice.
640
+ *
641
+ **/
642
+ SWIFT_API
643
+ swift_result_t SWIFT_CALLCONV swift_port_speak_text(swift_port *port,
644
+ const void *text,
645
+ int nbytes,
646
+ const char *encoding,
647
+ swift_background_t *async,
648
+ swift_params *params);
649
+
650
+ /**
651
+ * Synthesize text from a file on the given port.
652
+ *
653
+ * @param port The port on which to perform synthesis.
654
+ * @param path The path to the file from which to synthesize the text.
655
+ * @param encoding Character encoding of the input text. If NULL, the default
656
+ * encoding is assumed.
657
+ * @param async Output - Thread ID of the background job on which to run
658
+ * this synthesis call.<br>If NULL, synthesis occurs
659
+ * synchronously, thus blocking until complete.
660
+ * @param params The parameters to be used for this synthesis call. Can
661
+ * be NULL.
662
+ * - NOTE: The utterance retains ownership of this object, so you should not call
663
+ * swift_params_delete() on it.
664
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
665
+ *
666
+ * - NOTE: If a voice was not explicitely set on the port via
667
+ * swift_port_set_voice(), swift_port_set_voice_by_name(), or
668
+ * swift_port_set_voice_from_dir(), then this call implicitely loads
669
+ * the default voice and sets it as the port's current voice.
670
+ **/
671
+ /* FIXME: Windows has wide character filenames */
672
+ SWIFT_API
673
+ swift_result_t SWIFT_CALLCONV swift_port_speak_file(swift_port *port,
674
+ const char *path,
675
+ const char *encoding,
676
+ swift_background_t *async,
677
+ swift_params *params);
678
+
679
+ /**
680
+ * Get Performance Statistics for the most recently completed synthesis call
681
+ * on the given port.
682
+ *
683
+ * This information is written to the swift_port at the end of each synthesis
684
+ * call. As such, the information is volatile; It only lasts until the next
685
+ * synthesis call is completed. If you are using this function, make sure that
686
+ * you call it after a synthesis call has completed, but before the next
687
+ * synthesis call has completed to ensure you are getting reliable data.
688
+ *
689
+ * @param port The port for which to get performance statistics.
690
+ * @param uttcount Output - Number of utterances synthesized during the
691
+ * most recently completed synthesis call.
692
+ * @param avg_startup_time Output - Average time to begin speaking each
693
+ * utterance during the most recently completed
694
+ * synthesis call.
695
+ * @param audiotime Output - Total length in seconds of audio generated
696
+ * during the most recently completed synthesis call.
697
+ * @param realtime Output - Total length in seconds required to
698
+ * complete the most recently completed synthesis call.
699
+ * @param speed_ratio Output - Ratio of audio time to real time. Shows
700
+ * how much faster synthesis was completed compared to
701
+ * the amount of audio generated.
702
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if port
703
+ * is NULL.
704
+ **/
705
+ SWIFT_API
706
+ swift_result_t SWIFT_CALLCONV swift_port_get_perfstats(swift_port *port,
707
+ int *uttcount,
708
+ float *avg_startup_time,
709
+ float *audiotime,
710
+ float *realtime,
711
+ float *speed_ratio);
712
+
713
+ /**
714
+ * Synthesize text string or text from a file, and return the corresponding
715
+ * phonemes and event time information.
716
+ *
717
+ * @param port The port on which to perform the synthesis.
718
+ * @param text The text to synthesize, or the path to the file from which
719
+ * to synthesize the text.
720
+ * @param nbytes Length, in bytes, of text. If 0, this paramter is ignored.
721
+ * @param encoding Character encoding of the input text. If NULL, the default
722
+ * encoding is assumed.
723
+ * @param is_file Boolean - Set this to true if text is the path to a file.
724
+ * @param params The parameters to be used for this synthesis call. Can
725
+ * be NULL.
726
+ * - NOTE: The utterance retains ownership of this object, so you should not call
727
+ * swift_params_delete() on it.
728
+ * @return A string containing a list of the phonemes and event time
729
+ * information for the synthesized speech.
730
+ *
731
+ * - NOTE: If a voice was not explicitely set on the port via
732
+ * swift_port_set_voice(), swift_port_set_voice_by_name(), or
733
+ * swift_port_set_voice_from_dir(), then this call implicitely loads
734
+ * the default voice and sets it as the port's current voice.
735
+ *
736
+ * - NOTE: This function DOES NOT WORK as of Swift v3.1.0.
737
+ **/
738
+ SWIFT_API
739
+ const char * SWIFT_CALLCONV swift_port_get_phones(swift_port *port,
740
+ const void *text,
741
+ int nbytes,
742
+ const char *encoding,
743
+ int is_file,
744
+ swift_params *params);
745
+
746
+ /**
747
+ * Synthesize text string or text from file to a swift_waveform.
748
+ *
749
+ * @param port The port on which to perform the synthesis.
750
+ * @param text The text to synthesize, or the path to the file from which
751
+ * to synthesize the text.
752
+ * @param nbytes Length, in bytes, of text. If 0, this paramter is ignored.
753
+ * @param encoding Character encoding of the input text. If NULL, the default
754
+ * encoding is assumed.
755
+ * @param is_file Boolean - Set this to true if text is the path to a file.
756
+ * @param params The parameters to be used for this synthesis call. Can
757
+ * be NULL.
758
+ * - NOTE: The utterance retains ownership of this object, so you should not call
759
+ * swift_params_delete() on it.
760
+ * @return Pointer to the swift_waveform containing the synthesized
761
+ * speech. The caller owns the pointer, so must explicitly call
762
+ * swift_waveform_close() on the wave.
763
+ *
764
+ * - NOTE: If a voice was not explicitely set on the port via
765
+ * swift_port_set_voice(), swift_port_set_voice_by_name(), or
766
+ * swift_port_set_voice_from_dir(), then this call implicitely loads
767
+ * the default voice and sets it as the port's current voice.
768
+ **/
769
+ SWIFT_API
770
+ swift_waveform * SWIFT_CALLCONV swift_port_get_wave(swift_port *port,
771
+ const void *text,
772
+ int nbytes,
773
+ const char *encoding,
774
+ int is_file,
775
+ swift_params *params);
776
+
777
+ /**
778
+ * Play a swift_waveform through a port.
779
+ *
780
+ * @param port The port on which to play the waveform.
781
+ * @param wav The waveform to play on the port.
782
+ * @param async Output - Thread ID of the background job on which to run this
783
+ * synthesis call.<br>If NULL, synthesis occurs synchronously,
784
+ * thus blocking until complete.
785
+ * @param params The parameters to be used for this synthesis call. Can
786
+ * be NULL.
787
+ * - NOTE: The utterance retains ownership of this object, so you should not call
788
+ * swift_params_delete() on it.
789
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
790
+ **/
791
+ SWIFT_API
792
+ swift_result_t SWIFT_CALLCONV swift_port_play_wave(swift_port *port,
793
+ const swift_waveform *wav,
794
+ swift_background_t *async,
795
+ swift_params *params);
796
+
797
+ /**
798
+ * Create a new, empty waveform object.
799
+ *
800
+ * @return A new, empty waveform object.
801
+ **/
802
+ SWIFT_API
803
+ swift_waveform * SWIFT_CALLCONV swift_waveform_new(void);
804
+
805
+ /**
806
+ * Load a swift_waveform object from an audio file.
807
+ *
808
+ * @param filename The path to the audio file to open.
809
+ * @param format The format of the audio file (see note below).
810
+ * @param encoding The encoding of the file. One of "pcm16", "pcm8",
811
+ * "ulaw", "alaw". This is only used if the format is
812
+ * "raw", "le", or "be", and can be NULL otherwise.
813
+ * @param sample_rate The sampling rate of the audio data. This is only used
814
+ * if the format is "raw", "le", or "be", and will be
815
+ * ignored otherwise.
816
+ * @param num_channels The number of interleaved channels in the audio data.
817
+ * This is only used if the formate is "raw", "le", or
818
+ * "be", and will be ignored otherwise.
819
+ * @return The swift_wavform object that has been populated with
820
+ * data from the audio file.
821
+ *
822
+ * NOTE: The format argument is one of:
823
+ * - riff: Microsoft RIFF (WAV) file
824
+ * - snd: Sun/NeXT .au (SND) format.
825
+ * - raw: unheadered audio data, native byte order
826
+ * - le: unheadered audio data, little-endian
827
+ * - be: unheadered audio data, big-endian
828
+ * - NULL: the filename's extension will determine the format.
829
+ **/
830
+ SWIFT_API
831
+ swift_waveform * SWIFT_CALLCONV swift_waveform_open(const char *filename,
832
+ const char *format,
833
+ const char *encoding,
834
+ int sample_rate,
835
+ int num_channels);
836
+
837
+ /**
838
+ * Print detailed information about a swift_waveform.
839
+ *
840
+ * @param wave The swift_waveform about which to print detailed information.
841
+ * @return Void
842
+ **/
843
+ SWIFT_API
844
+ void SWIFT_CALLCONV swift_waveform_print(swift_waveform *wave);
845
+
846
+ /**
847
+ * Close a swift_waveform and deallocate associated memory and resources.
848
+ *
849
+ * @param wave The swift_waveform to close.
850
+ * @return SWIFT_SUCCESS
851
+ **/
852
+ SWIFT_API
853
+ swift_result_t SWIFT_CALLCONV swift_waveform_close(swift_waveform *wave);
854
+
855
+ /**
856
+ * Save a swift_waveform to an audio file.
857
+ *
858
+ * @param wave The swift_waveform to save to the file.
859
+ * @param filename The path to the file in which to save the swift_waveform data.
860
+ * @param format The format of the swift_waveform (see note below).
861
+ * @return SWIFT_SUCCESS, or one of several swift_result_t values.
862
+ *
863
+ * NOTE: The format argument is one of:
864
+ * - riff: Microsoft RIFF (WAV) file
865
+ * - snd: Sun/NeXT .au (SND) format.
866
+ * - raw: unheadered audio data, native byte order
867
+ * - le: unheadered audio data, little-endian (LSB first)
868
+ * - be: unheadered audio data, big-endian (MSB first)
869
+ * - NOTE: that not all encoding types may be supported by all formats.
870
+ * For instance, SND doesn't support A-Law.
871
+ **/
872
+ SWIFT_API
873
+ swift_result_t SWIFT_CALLCONV swift_waveform_save(const swift_waveform *wave,
874
+ const char *filename,
875
+ const char *format);
876
+
877
+ /**
878
+ * Get the sample rate of a swift_waveform.
879
+ *
880
+ * @param wave The swift_waveform from which to get the sample rate.
881
+ * @return The sample rate of the waveform.
882
+ **/
883
+ SWIFT_API
884
+ int SWIFT_CALLCONV swift_waveform_get_sps(const swift_waveform *wave);
885
+
886
+ /**
887
+ * Get the encoding type for a swift_waveform.
888
+ *
889
+ * @param wave The swift_waveform from which to get the encoding type.
890
+ * @return The encoding type, one of:
891
+ * - "pcm16" - 16-bit signed linear PCM
892
+ * - "pcm8" - 8-bit unsigned linear PCM
893
+ * - "ulaw" - �-Law (8-bit by definition)
894
+ * - "alaw" - A-Law (8-bit by definition)
895
+ **/
896
+ SWIFT_API
897
+ const char * SWIFT_CALLCONV
898
+ swift_waveform_get_encoding(const swift_waveform *wave);
899
+
900
+ /**
901
+ * Resample a swift_waveform.
902
+ *
903
+ * @param wave The swift_waveform to resample.
904
+ * @param new_sps The sample rate to apply to the swift_waveform.
905
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if wave is
906
+ * NULL.
907
+ **/
908
+ SWIFT_API
909
+ swift_result_t SWIFT_CALLCONV swift_waveform_resample(swift_waveform *wave,
910
+ int new_sps);
911
+
912
+ /**
913
+ * Convert a swift_waveform to a different encoding type.
914
+ *
915
+ * @param wave The swift_waveform to convert
916
+ * @param encoding One of:
917
+ * - "pcm16" - 16-bit signed linear PCM
918
+ * - "pcm8" - 8-bit unsigned linear PCM
919
+ * - "ulaw" - �-Law (8-bit by definition)
920
+ * - "alaw" - A-Law (8-bit by definition)
921
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if wave or
922
+ * encoding is NULL.
923
+ **/
924
+ SWIFT_API
925
+ swift_result_t SWIFT_CALLCONV swift_waveform_convert(swift_waveform *wave,
926
+ const char *encoding);
927
+
928
+ /**
929
+ * Get the raw sample data and byte-per-sample information about the data
930
+ * from a swift_waveform.
931
+ *
932
+ * @param wave The swift_waveform from which to get the sample
933
+ * data and byte-per-sample information.
934
+ * @param samples Output - Buffer to receive the raw sample data.
935
+ * @param nsamples Output - Number of samples copied into the buffer.
936
+ * @param bytes_per_sample Output - number of bytes-per-sample.
937
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if wave
938
+ * is NULL.
939
+ **/
940
+ SWIFT_API
941
+ swift_result_t SWIFT_CALLCONV
942
+ swift_waveform_get_samples(const swift_waveform *wave, const void **samples,
943
+ int *nsamples, int *bytes_per_sample);
944
+
945
+ /**
946
+ * Create a new swift_waveform and populate it with audio data from a buffer
947
+ * of raw samples.
948
+ *
949
+ * @param samples Buffer holding the raw data - must be pcm16 data.
950
+ * @param nsamples Number of samples.
951
+ * @param frequency Frequency (sample rate) of data in the buffer.
952
+ * @param channels Number of channels.
953
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_POINTER if wave is NULL.
954
+ *
955
+ * NOTE: If the samples and nsamples parameters are set to NULL and 0
956
+ * respectively, this will create an empty swift_waveform.
957
+ **/
958
+ SWIFT_API
959
+ swift_waveform * SWIFT_CALLCONV
960
+ swift_waveform_set_samples(const unsigned short *samples, const int nsamples,
961
+ const int frequency, const int channels);
962
+
963
+ /**
964
+ * Set the number of channels for the given swift_waveform.
965
+ *
966
+ * @param wave The swift_waveform for which to set channels.
967
+ * @param channels Number of channels. Must be 1 or 2.
968
+ * @return SWIFT_SUCCESS, or SWIFT_INVALID_PARAM.
969
+ **/
970
+ SWIFT_API
971
+ swift_result_t SWIFT_CALLCONV swift_waveform_set_channels(swift_waveform *wave,
972
+ int channels);
973
+
974
+
975
+ /**
976
+ * Append waveSrc swift_waveform to waveDst swift_waveform.
977
+ *
978
+ * @param waveDst The swift_waveform onto which to append waveSrc.
979
+ * @param waveSrc The swift_waveform to append to waveDst.
980
+ * @return SWIFT_SUCCESS, or SWIFT_UNKNOWN_ERROR.
981
+ **/
982
+ SWIFT_API
983
+ swift_result_t SWIFT_CALLCONV swift_waveform_concat(swift_waveform *waveDst,
984
+ swift_waveform *waveSrc);
985
+
986
+ /**
987
+ * Return a string description of an error code.
988
+ *
989
+ * @param t The error code from which to retreive the string description.
990
+ * @return The string description of the error code.
991
+ **/
992
+ SWIFT_API
993
+ const char * SWIFT_CALLCONV swift_strerror(swift_result_t t);
994
+
995
+ /**
996
+ * Place a newly-allocated, comma-seperated list of all values for a given
997
+ * parameter and given XML swift configuration file into the 'values'
998
+ * output parameter.
999
+ *
1000
+ * @param file The path to the config file.
1001
+ * @param element The name of the parameter for which values should be
1002
+ * returned.
1003
+ * @param data Output - The newly-allocated, comma-seperated list of values.
1004
+ * @return SWIFT_FILE_ERROR or SWIFT_SUCCESS.
1005
+ **/
1006
+ SWIFT_API
1007
+ swift_result_t SWIFT_CALLCONV
1008
+ swift_conffile_get_element_data(const char *file,
1009
+ const char *element,
1010
+ char **data);
1011
+
1012
+ /**
1013
+ * Retrieve the maximum number of concurrent synthesis calls allowed.
1014
+ *
1015
+ * @param engine An active swift_engine structure. Pass in the pointer
1016
+ * to the engine through which your swift_ports are open.
1017
+ * @param max_tokens Output - the maximum number of concurrent synthesis
1018
+ * calls that can be made on this system. A value of -1
1019
+ * indicates that the system is running with an Unlimited
1020
+ * Concurrency License.
1021
+ * @param tokens_in_use Output - the number of sysnthesis calls currently in
1022
+ * operation on this system at the time this call is made.
1023
+ * If max_tokens is 1 and tokens_in_use is -1, then the
1024
+ * system is running in Single Token Mode, in which the
1025
+ * license server is not used.
1026
+ * @return SWIFT_SUCCESS on success, or SWIFT_NETWORK_ERROR if
1027
+ * communication to the license server cannot be made. If
1028
+ * communication fails, max_tokens is set to 1 and
1029
+ * tokens_in_use is set to -1, meaning "unknown."
1030
+ **/
1031
+ SWIFT_API
1032
+ swift_result_t SWIFT_CALLCONV
1033
+ swift_license_get_concurrency_info(swift_engine *engine, int *max_tokens,
1034
+ int *tokens_in_use);
1035
+
1036
+ #ifdef __cplusplus
1037
+ };
1038
+ #endif /* __cplusplus */
1039
+
1040
+ #endif /* _SWIFT_H_ */