[[tags: egg]]

[[toc:]]

== espeak

Bindings to [[https://github.com/espeak-ng/espeak-ng/|espeak-ng]]'s C library

=== Introduction

Text to speech? Text to phonemes? Phonemes to speech? This library should have
you covered. The goal was to expose espeak-ng's C library through Chicken while
also doing a little more of the work internally to make the API more
user-friendly. Currently, the parts of the library related to callbacks and
events are not supported.

=== Procedures

==== Synthesis
<procedure>(say text #!key sync name language identifier gender age variant rate volume pitch range punctuation capitals wordgap)</procedure>

A high-level speech synthesis addition to the library. {{sync}} is a boolean
that determines if the function should wait for the audio to be spoken before
returning. The parameters {{name}} - {{variant}} get passed directly into
{{make-voice}}, while the rest are set using {{set-parameter!}}. Subsequent
calls use the last settings (unless explicitly changed in the {{say}} call, or
set by {{set-voice-by*}} functions or {{set-parameter!}}):

<enscript highlight="scheme">
(say "This is an example." gender: gender/female rate: 200)
(say "This will sound the same.")
</enscript>

<procedure>(synth text #!key (position 0) (position-type pos/char) (end-position #f) (ssml #f) (phonemes #f) (endpause #f))</procedure>
<procedure>(synth-mark text index-mark #!key (end-position 0) (ssml #f) (phonemes #f) (endpause #f))</procedure>
The basic speech synthesis function.

; {{position}} : The position in the text where speaking starts.
; {{position_type}} : One of {{pos/char}}, {{pos/word}}, or {{pos/sentence}}. It seems {{pos/char}} currently acts like {{pos/word}}, and the other two are 1-indexed.
; {{end_position}} : A character position at which speaking will stop.
; {{ssml}} : elements within {{< >}} are treated as [[https://github.com/espeak-ng/espeak-ng/blob/master/docs/markup.md|espeak SSML]].
; {{phonemes}} : elements within {{[[ ]]}} are treated as [[https://en.wikipedia.org/wiki/Kirshenbaum|Kirshenbaum encoded phonemes]]
; {{endpause}} : wheter to add a sentence pause to the end of the text.

{{synth-mark}} is like {{synth}}, but an SSML {{<mark name="example">}} element
indicates the beginning of speech, with the name passed to {{index-mark}}

<procedure>(key k)</procedure>
<procedure>(char c)</procedure>

Speak the name of the keyboard key (a single-character length string) or
character, respectively. {{key}} will speak a full string if it's longer than
one character.

<procedure>(cancel)</procedure>

Immediately stop synthesis and audio output of the current text. When this
function returns, the audio output is fully stopped and the synthesizer is
ready to synthesize a new message.

<procedure>(playing?)</procedure>

Determines whether audio is playing or not.

<procedure>(synchronize)</procedure>

Returns when all audio data has been spoken.

==== Phonemes

<procedure>(text->phonemes input #!key ipa tie separator)</procedure>

Translates an input string into a string of phonemes. By default, uses
Kirshenbaum (ascii) encoding, but will output UTF8 if {{ipa}} is #t. You can
specify a character to separate the phonemes with using {{separator}}. If
{{tie}} is set, that character is used as a tie within multi-letter phoneme
names.

Examples:
<enscript highlight="scheme">
(text->phonemes "hello") ;; => "h@l'oU"
(text->phonemes "hello" ipa: #t) ;; => "həlˈəʊ"
(text->phonemes "hello" ipa: #t separator: #\-) ;; => "h-ə-l-ˈəʊ"
(text->phonemes "hello my name is" ipa: #t tie: #t separator: #\x35c)
;; => "həlˈə͜ʊ ma͜ɪ nˈe͜ɪm ɪz"
</enscript>

==== Settings
<procedure>(make-voice #!key name language identifier (gender 0) (age 0) (variant 0))</procedure>
<procedure>voice?</procedure>
<procedure>voice-name</procedure>
<procedure>voice-name-set!</procedure>
<procedure>voice-language</procedure>
<procedure>voice-language-set!</procedure>
<procedure>voice-identifier</procedure>
<procedure>voice-identifier-set!</procedure>
<procedure>voice-gender</procedure>
<procedure>voice-gender-set!</procedure>
<procedure>voice-age</procedure>
<procedure>voice-age-set!</procedure>
<procedure>voice-variant</procedure>
<procedure>voice-variant-set!</procedure>

{{make-voice}} returns a voice record that is mostly useful for filtering the
results of {{list-voices}} or passing to {{set-voice-by-properties!}}. Name,
language, and identifier should all be either #f or strings.

<constant>gender/none</constant>
<constant>gender/male</constant>
<constant>gender/female</constant>

Allowed values for {{gender}} parameter of {{make-voice}}.

<procedure>(set-parameter! parameter value #!optional relative)</procedure>

Set the value of a parameter, which can be any of:

; {{param/rate}} : speaking speed in words per minute, 80 - 450. Defaults to 175.
; {{param/volume}} : volume, 0 or more. Defaults to 100. Values greater than that may produce amplitude compression or distortion.
; {{param/pitch}} : base pitch, 0-100. Defaults to 50.
; {{param/range}} : pitch range, 0-100. Defaults to 50.
; {{param/punctuation}} : which punctuation characters to announce: {{punct/none}}, {{punct/some}}, or {{punct/all}}.
; {{param/captials}} : announce capital letters by: {{capitals/none}}, {{capitals/sound-icon}}, {{capitals/spelling}}, 3+ by raising pitch, where the value corresponds to the amount in Hz by which the pitch is raised.
; {{param/wordgap}} : pause between words in units of 10mS at the default speed.

<procedure>(get-parameter! parameter #!optional default)</procedure>

Get the current or default value of a parameter.

<procedure>(set-punctuation-list! str)</procedure>

Specifies a string list of punctuation characters whose names are to be spoken
when the value of the punctuation parameter is set to {{pnuct/some}}.

<procedure>(list-voices #!optional voice)</procedure>
Can be used to list all voices, or filter voices by properties. For example, to
list all spanish voices:

<enscript highlight="scheme">
(list-voices (make-voice language: "es"))
</enscript>

<procedure>(set-voice-by-properties! voice)</procedure>
<procedure>(set-voice-by-name! name)</procedure>
<procedure>(set-voice-by-file! filepath)</procedure>

Can be used to select a voice to be used for synthesis functions by properties. For example:
<enscript highlight="scheme">
;; Set to spanish by name
(set-voice-by-properties! (make-voice name: "Spanish (Spain)"))
;; Set to a spanish voice
(set-voice-by-properties! (make-voice language: "es"))
;; Set to an english voice
(set-voice-by-properties! (make-voice language: "en"))
;; Specify dialect
(set-voice-by-properties! (make-voice language: "en-uk"))
;; Set to gender
(set-voice-by-properties! (make-voice language: gender/female))
;; Combine, female spanish
(set-voice-by-properties! (make-voice gender: gender/female language: "es"))
</enscript>

<procedure>(get-current-voice)</procedure>

Returns the currently set voice.

<procedure>(reset-defaults!)</procedure>

Added in Chicken - resets all parameters and voice to defaults.

==== Other

<procedure>(initialize #!key (output output/playback) (buflength 0) (path #f) (phoneme-events #f) (phoneme-ipa #f) (dont-exit #f))</procedure>

A binding for {{espeak_Initialize}}. Unless you want change {{path}}, you
shouldn't have to call this, as it's implicitly called by the first function
that may need it. The rest of the parameters are currently probably useless
without support for events and callbacks.

<constant>output/playback</constant>
<constant>output/retrieval</constant>
<constant>output/synchronous</constant>
<constant>output/synch-playback</constant>

Allowed values for {{output}} parameter of {{initialize}}

<procedure>(terminate)</procedure>

Last function to be called. Shouldn't be necessary (don't quote me on this).

<procedure>(info)</procedure>

Returns version number string and path to espeak_data.

=== Author

Diego A. Mundo

=== License

GPL-3.0

=== Version History

; 0.1.6 : Minor code quality improvement
; 0.1.1 - 0.1.5 : Various minor bug fixes
; 0.1.0 : Initial version.