source: project/wiki/eggref/5/espeak @ 39440

Last change on this file since 39440 was 39440, checked in by dieggsy, 3 months ago

Initial documentation

File size: 7.9 KB
Line 
1[[tags: egg]]
2
3[[toc:]]
4
5== espeak
6
7Bindings to [[https://github.com/espeak-ng/espeak-ng/|espeak-ng]]'s C library
8
9=== Introduction
10
11Text to speech? Text to phonemes? Phonemes to speech? This library should have
12you covered. The goal was to expose espeak-ng's C library through Chicken while
13also doing a little more of the work internally to make the API more
14user-friendly. Currently, the parts of the library related to callbacks and
15events are not supported.
16
17=== Procedures
18
19==== Synthesis
20<procedure>(say text #!key sync name language identifier gender age variant rate volume pitch range punctuation capitals wordgap)</procedure>
21
22A high-level speech synthesis addition to the library. {{sync}} is a boolean
23that determines if the function should wait for the audio to be spoken before
24returning. The parameters {{name}} - {{variant}} get passed directly into
25{{make-voice}}, while the rest are set using {{set-parameter!}}. Subsequent
26calls use the last settings (unless explicitly changed in the {{say}} call, or
27set by {{set-voice-by*}} functions or {{set-parameter!}}):
28
29<enscript highlight="scheme">
30(say "This is an example." gender: gender/female rate: 200)
31(say "This will sound the same.")
32</enscript>
33
34<procedure>(synth text #!key (position 0) (position-type pos/char) (end-position #f) (ssml #f) (phonemes #f) (endpause #f))</procedure>
35<procedure>(synth-mark text index-mark #!key (end-position 0) (ssml #f) (phonemes #f) (endpause #f))</procedure>
36The basic speech synthesis function.
37
38; {{position}} : The position in the text where speaking starts.
39; {{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.
40; {{end_position}} : A character position at which speaking will stop.
41; {{ssml}} : elements within {{< >}} are treated as [[https://github.com/espeak-ng/espeak-ng/blob/master/docs/markup.md|espeak SSML]].
42; {{phonemes}} : elements within {{[[ ]]}} are treated as [[https://en.wikipedia.org/wiki/Kirshenbaum|Kirshenbaum encoded phonemes]]
43; {{endpause}} : wheter to add a sentence pause to the end of the text.
44
45{{synth-mark}} is like {{synth}}, but an SSML {{<mark name="example">}} element
46indicates the beginning of speech, with the name passed to {{index-mark}}
47
48<procedure>(key k)</procedure>
49<procedure>(char c)</procedure>
50
51Speak the name of the keyboard key (a single-character length string) or
52character, respectively. {{key}} will speak a full string if it's longer than
53one character.
54
55<procedure>(cancel)</procedure>
56
57Immediately stop synthesis and audio output of the current text. When this
58function returns, the audio output is fully stopped and the synthesizer is
59ready to synthesize a new message.
60
61<procedure>(playing?)</procedure>
62
63Determines whether audio is playing or not.
64
65<procedure>(synchronize)</procedure>
66
67Returns when all audio data has been spoken.
68
69==== Phonemes
70
71<procedure>(text->phonemes input #!key ipa tie separator)</procedure>
72
73Translates an input string into a string of phonemes. By default, uses
74Kirshenbaum (ascii) encoding, but will output UTF8 if {{ipa}} is #t. You can
75specify a character to separate the phonemes with using {{separator}}. If
76{{tie}} is set, that character is used as a tie within multi-letter phoneme
77names.
78
79Examples:
80<enscript highlight="scheme">
81(text->phonemes "hello") ;; => "h@l'oU"
82(text->phonemes "hello" ipa: #t) ;; => "həlˈəʊ"
83(text->phonemes "hello" ipa: #t separator: #\-) ;; => "h-ə-l-ˈəʊ"
84(text->phonemes "hello my name is" ipa: #t tie: #t separator: #\x35c)
85;; => "həlˈə͜ʊ ma͜ɪ nˈe͜ɪm ɪz"
86</enscript>
87
88==== Settings
89<procedure>(make-voice #!key name language identifier (gender 0) (age 0) (variant 0))</procedure>
90<procedure>voice?</procedure>
91<procedure>voice-name</procedure>
92<procedure>voice-name-set!</procedure>
93<procedure>voice-language</procedure>
94<procedure>voice-language-set!</procedure>
95<procedure>voice-identifier</procedure>
96<procedure>voice-identifier-set!</procedure>
97<procedure>voice-gender</procedure>
98<procedure>voice-gender-set!</procedure>
99<procedure>voice-age</procedure>
100<procedure>voice-age-set!</procedure>
101<procedure>voice-variant</procedure>
102<procedure>voice-variant-set!</procedure>
103
104{{make-voice}} returns a voice record that is mostly useful for filtering the
105results of {{list-voices}} or passing to {{set-voice-by-properties!}}. Name,
106language, and identifier should all be either #f or strings.
107
108<constant>gender/none</constant>
109<constant>gender/male</constant>
110<constant>gender/female</constant>
111
112Allowed values for {{gender}} parameter of {{make-voice}}.
113
114<procedure>(set-parameter! parameter value #!optional relative)</procedure>
115
116Set the value of a parameter, which can be any of:
117
118; {{param/rate}} : speaking speed in words per minute, 80 - 450. Defaults to 175.
119; {{param/volume}} : volume, 0 or more. Defaults to 100. Values greater than that may produce amplitude compression or distortion.
120; {{param/pitch}} : base pitch, 0-100. Defaults to 50.
121; {{param/range}} : pitch range, 0-100. Defaults to 50.
122; {{param/punctuation}} : which punctuation characters to announce: {{punct/none}}, {{punct/some}}, or {{punct/all}}.
123; {{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.
124; {{param/wordgap}} : pause between words in units of 10mS at the default speed.
125
126<procedure>(get-parameter! parameter #!optional default)</procedure>
127
128Get the current or default value of a parameter.
129
130<procedure>(set-punctuation-list! str)</procedure>
131
132Specifies a string list of punctuation characters whose names are to be spoken
133when the value of the punctuation parameter is set to {{pnuct/some}}.
134
135<procedure>(list-voices #!optional voice)</procedure>
136Can be used to list all voices, or filter voices by properties. For example, to
137list all spanish voices:
138
139<enscript highlight="scheme">
140(list-voices (make-voice language: "es"))
141</enscript>
142
143<procedure>(set-voice-by-properties! voice)</procedure>
144<procedure>(set-voice-by-name! name)</procedure>
145<procedure>(set-voice-by-file! filepath)</procedure>
146
147Can be used to select a voice to be used for synthesis functions by properties. For example:
148<enscript highlight="scheme">
149;; Set to spanish by name
150(set-voice-by-properties! (make-voice name: "Spanish (Spain)"))
151;; Set to a spanish voice
152(set-voice-by-properties! (make-voice language: "es"))
153;; Set to an english voice
154(set-voice-by-properties! (make-voice language: "en"))
155;; Specify dialect
156(set-voice-by-properties! (make-voice language: "en-uk"))
157;; Set to gender
158(set-voice-by-properties! (make-voice language: gender/female))
159;; Combine, female spanish
160(set-voice-by-properties! (make-voice gender: gender/female language: "es"))
161</enscript>
162
163<procedure>(get-current-voice)</procedure>
164
165Returns the currently set voice.
166
167<procedure>(reset-defaults!)</procedure>
168
169Added in Chicken - resets all parameters and voice to defaults.
170
171==== Other
172
173<procedure>(initialize #!key (output output/playback) (buflength 0) (path #f) (phoneme-events #f) (phoneme-ipa #f) (dont-exit #f))</procedure>
174
175A binding for {{espeak_Initialize}}. Unless you want change {{path}}, you
176shouldn't have to call this, as it's implicitly called by the first function
177that may need it. The rest of the parameters are currently probably useless
178without support for events and callbacks.
179
180<constant>output/playback</constant>
181<constant>output/retrieval</constant>
182<constant>output/synchronous</constant>
183<constant>output/synch-playback</constant>
184
185Allowed values for {{output}} parameter of {{initialize}}
186
187<procedure>(terminate)</procedure>
188
189Last function to be called. Shouldn't be necessary (don't quote me on this).
190
191<procedure>(info)</procedure>
192
193Returns version number string and path to espeak_data.
194
195=== Author
196
197Diego A. Mundo
198
199=== License
200
201GPL-3.0
202
203=== Version History
204
205; 0.1.1 - 0.1.5 : Various minor bug fixes
206; 0.1.0 : Initial version.
Note: See TracBrowser for help on using the repository browser.