speech-dispatcher: Output Module Functions
5.2.6 Output Module Functions
-----------------------------
-- Output Module Functions: void module_speak_sync (char *data, size_t
bytes, EMessageType msgtype)
This is the function where the actual speech output is produced.
It is called every time Speech Dispatcher decides to send a message
to synthesis. The data of length BYTES are passed in a NULL
terminated string DATA. The argument MSGTYPE defines what type of
message it is (different types should be handled differently, if
the synthesizer supports it).
Each output module should take care of setting the output device to
the parameters from msg_settings (defined in module_utils.h) (See
SPDMsgSettings in 'module_utils.h'). However, it is not an error
if some of these values are ignored. At least rate, pitch and
language should be set correctly.
Speed and pitch are values between -100 and 100 included. 0 is the
default value that represents normal speech flow. So -100 is the
slowest (or lowest) and +100 is the fastest (or highest) speech.
The language parameter is given as a null-terminated string
containing the name of the language according to RFC 1766 (en, cs,
fr, en-US, ...). If the requested language is not supported by
this synthesizer, it's ok to abort and return 0, because that's an
error in user settings.
An easy way to set the parameters is using the UPDATE_PARAMETER()
and UPDATE_STRING_PARAMETER() macros. ⇒Module Utils Functions
and Macros.
Example from festival:
UPDATE_STRING_PARAMETER(language, festival_set_language);
UPDATE_PARAMETER(voice, festival_set_voice);
UPDATE_PARAMETER(rate, festival_set_rate);
UPDATE_PARAMETER(pitch, festival_set_pitch);
UPDATE_PARAMETER(punctuation_mode, festival_set_punctuation_mode);
UPDATE_PARAMETER(cap_let_recogn, festival_set_cap_let_recogn);
Once this function has checked that everything is OK, it must call
'module_speak_ok()' to let the server know that the speak was
accepted. From then on, the server may send stop requests, so
reseting the stop state must be done before calling this. On
errors, 'module_speak_error()' has to be called instead.
When actual synthesis starts, 'module_speak_begin()' must be called
to let the server know of this. On synthesis termination,
'module_speak_end()' should be called (or 'module_speak_pause()',
'module_speak_stopped()' if the synthesis was interrupted through
'module_pause()' or 'module_stop()').
This function should return only when it is finished with
synthesizing. It should however call 'module_process(STDIN_FILENO,
0)' periodically so as to promptly process messages coming from the
server, notably speech stopping requests.
-- Output Module Functions: int module_speak (char *data, size_t bytes,
EMessageType msgtype)
This is the same as 'module_speak_sync', except that it proceeds
asynchronously, it can be used when the synthesis works
asynchronously.
Instead of calling 'module_speak_ok()' or 'module_speak_error()',
this function should return 0 if it fails and 1 if the delivery to
the synthesizer is successful. It should return immediately,
because otherwise, it would block stopping, priority handling and
other important things in Speech Dispatcher.
If there is a need to stay longer, it can call
'module_process(STDIN_FILENO, 0)' to process messages coming from
the server, but in that case 'module_speak_sync' could as well be
used.
Note: if the synthesis creates separate threads, you have to set
them to ignore all signals. The simplest way to do this is to use
'spd_pthread_create()' (which is defined in module_utils.c) instead
of 'pthread_create()'.
-- Output module function: int module_stop (void)
This function should stop the synthesis of the currently spoken
message immediately and throw away the rest of the message.
This function should return immediately. Speech Dispatcher will
not send another command until module_report_event_stop() is
called. Note that you cannot call module_report_event_stop() from
within the call to module_stop(). The best thing to do is emit the
stop event from another thread.
It should return 0 on success, -1 otherwise.
-- Output module function: size_t module_pause (void)
This function should stop speaking on the synthesizer (or sending
data to soundcard) just after sending an '__spd_' index mark so
that Speech Dispatcher knows the position of stop.
The pause can wait for a short time until such index mark is
reached. However, if it's not possible to determine the exact
position, this function should have the same effect as
'module_stop'.
This function should return immediately. Speech Dispatcher will
not send another command until module_report_event_pause() is
called. Note that you cannot call module_report_event_pause() from
within the call to module_pause(). The best thing to do is emit
the pause event from another thread.
For some software synthesizers, the desired effect can be archieved
in this way: When 'module_speak()' is called, you execute a
separate process and pass it the requested message. This process
cuts the message into sentences and then runs in a loop and sends
the pieces to synthesis. If a signal arrives from
'module_pause()', you set a flag and stop the loop at the point
where next piece of text would be synthesized.
It's not an error if this function is called when the device is not
speaking. In this case, it should return 0.
Note there is no module_resume() function. The semantics of
'module_pause()' is the same as 'module_stop()' except that your
module should stop after reaching a '__spd_' index mark. Just like
'module_stop()', it should discard the rest of the message after
pausing. On the next 'module_speak()' call, Speech Dispatcher will
resend the rest of the message after the index mark.
Info Catalog
speech-dispatcher: The Skeleton of an Output Module
speech-dispatcher: Output Modules
speech-dispatcher: Module Utils Functions and Macros