speech

​
This module provides access to the Speech Synthesizer component of OS X.
The speech synthesizer functions and methods provide access to OS X's Text-To-Speech capabilities and facilitates generating speech output both to the currently active audio device and to an AIFF file.
A discussion concerning the embedding of commands into the text to be spoken can be found at https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/SpeechSynthesisProgrammingGuide/FineTuning/FineTuning.html#//apple_ref/doc/uid/TP40004365-CH5-SW6. It is somewhat dated and specific to the older MacinTalk style voices, but still contains some information relevant to the more modern higer quality voices as well in its discussion about embedded commands.
Submodules
​hs.speech.listener​
API Overview
Functions - API calls offered directly by the extension
​attributesForVoice​
​availableVoices​
​defaultVoice​
​isAnyApplicationSpeaking​
Constructors - API calls which return an object, typically one that offers API methods
​new​
Methods - API calls which can only be made on an object returned by a constructor
​continue​
​isPaused​
​isSpeaking​
​modulation​
​pause​
​phonemes​
​phoneticSymbols​
​pitch​
​rate​
​reset​
​setCallback​
​speak​
​speaking​
​speakToFile​
​stop​
​usesFeedbackWindow​
​voice​
​volume​
API Documentation
Functions
​attributesForVoice​
Signature
hs.speech.attributesForVoice(voice) -> table
Type
Function
Description
Returns a table containing a variety of properties describing and defining the specified voice.
Parameters
voice - the name of the voice to look up attributes for
Returns
a table containing key-value pairs which describe the voice specified. These attributes may include (but is not limited to) information about specific characters recognized, sample text, gender, etc.
Notes
All of the names that have been encountered thus far follow this pattern for their full name: com.apple.speech.synthesis.voice.name. You can provide this suffix or not as you prefer when specifying a voice name.
​availableVoices​
Signature
hs.speech.availableVoices([full]) -> array
Type
Function
Description
Returns a list of the currently installed voices for speech synthesis.
Parameters
full - an optional boolean flag indicating whether or not the full internal names should be returned, or if the shorter versions should be returned. Defaults to false.
Returns
an array of the available voice names.
Notes
All of the names that have been encountered thus far follow this pattern for their full name: com.apple.speech.synthesis.voice.name. This prefix is normally suppressed unless you pass in true.
​defaultVoice​
Signature
hs.speech.defaultVoice([full]) -> string
Type
Function
Description
Returns the name of the currently selected default voice for the user. This voice is the voice selected in the System Preferences for Dictation & Speech as the System Voice.
Parameters
full - an optional boolean flag indicating whether or not the full internal name should be returned, or if the shorter version should be returned. Defaults to false.
Returns
the name of the system voice.
Notes
All of the names that have been encountered thus far follow this pattern for their full name: com.apple.speech.synthesis.voice.name. This prefix is normally suppressed unless you pass in true.
​isAnyApplicationSpeaking​
Signature
hs.speech.isAnyApplicationSpeaking() -> boolean
Type
Function
Description
Returns whether or not the system is currently using a speech synthesizer in any application to generate speech.
Parameters
None
Returns
a boolean value indicating whether or not any application is currently generating speech with a synthesizer.
Notes
See also hs.speech:speaking.
Constructors
​new​
Signature
hs.speech.new([voice]) -> synthesizerObject
Type
Constructor
Description
Creates a new speech synthesizer object for use by Hammerspoon.
Parameters
voice - an optional string specifying the voice the synthesizer should use for generating speech. Defaults to the system voice.
Returns
a speech synthesizer object or nil, if the system was unable to create a new synthesizer.
Notes
All of the names that have been encountered thus far follow this pattern for their full name: com.apple.speech.synthesis.voice.name. You can provide this suffix or not as you prefer when specifying a voice name.
You can change the voice later with the hs.speech:voice method.
Methods
​continue​
Signature
hs.speech:continue() -> synthesizerObject
Type
Method
Description
Resumes a paused speech synthesizer.
Parameters
None
Returns
the synthesizer object
​isPaused​
| Signature | hs.speech:isPaused() -> boolean | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns whether or not the synthesizer is currently paused. | | Parameters |
None
| | Returns |
True or false indicating whether or not the synthesizer is currently paused. If there is an error, returns nil.
| | Notes |
If an error occurs retrieving this value, the details will be logged in the system logs which can be viewed with the Console application. You can also have such messages logged to the Hammerspoon console by setting the module's log level to at least Information (This can be done with the following, or similar, command: hs.speech.log.level = 3. See hs.logger for more information)
|
​isSpeaking​
| Signature | hs.speech:isSpeaking() -> boolean | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns whether or not the synthesizer is currently speaking, either to an audio device or to a file. | | Parameters |
None
| | Returns |
True or false indicating whether or not the synthesizer is currently producing speech. If there is an error, returns nil.
| | Notes |
If an error occurs retrieving this value, the details will be logged in the system logs which can be viewed with the Console application. You can also have such messages logged to the Hammerspoon console by setting the module's log level to at least Information (This can be done with the following, or similar, command: hs.speech.log.level = 3. See hs.logger for more information)
|
​modulation​
| Signature | hs.speech:modulation([modulation]) -> synthsizerObject | modulation | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Gets or sets the pitch modulation for the synthesizer's voice. | | Parameters |
modulation - an optional number indicating the pitch modulation for the synthesizer.
| | Returns |
If no parameter is provided, returns the current value; otherwise returns the synthesizer object. Returns nil if an error occurs.
| | Notes |
Pitch modulation is expressed as a floating-point value in the range of 0.000 to 127.000. These values correspond to MIDI note values, where 60.000 is equal to middle C on a piano scale. The most useful speech pitches fall in the range of 40.000 to 55.000. A pitch modulation value of 0.000 corresponds to a monotone in which all speech is generated at the frequency corresponding to the speech pitch. Given a speech pitch value of 46.000, a pitch modulation of 2.000 would mean that the widest possible range of pitches corresponding to the actual frequency of generated text would be 44.000 to 48.000.
|
​pause​
Signature
hs.speech:pause([where]) -> synthesizerObject
Type
Method
Description
Pauses the output of the speech synthesizer.
Parameters
where - an optional string indicating when to pause the audio output (defaults to "immediate"). The string can be one of the following:
"immediate" - pauses output immediately. If in the middle of a word, when speech is resumed, the word will be repeated.
"word" - pauses at the end of the current word.
"sentence" - pauses at the end of the current sentence.
Returns
the synthesizer object
​phonemes​
Signature
hs.speech:phonemes(text) -> string
Type
Method
Description
Returns the phonemes which would be spoken if the text were to be synthesized.
Parameters
text - the text to tokenize into phonemes.
Returns
the text converted into the series of phonemes the synthesizer would use for the provided text if it were to be synthesized.
Notes
This method only returns a phonetic representation of the text if a Macintalk voice has been selected. The more modern higher quality voices do not use a phonetic representation and an empty string will be returned if this method is used.
You can modify the phonetic representation and feed it into hs.speech:speak if you find that the default interpretation is not correct. You will need to set the input mode to Phonetic by prefixing the text with "[[inpt PHON]]".
The specific phonetic symbols recognized by a given voice can be queried by examining the array returned by hs.speech:phoneticSymbols after setting an appropriate voice.
​phoneticSymbols​
| Signature | hs.speech:phoneticSymbols() -> array | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns an array of the phonetic symbols recognized by the synthesizer for the current voice. | | Parameters |
None
| | Returns |
For MacinTalk voices, this method will return an array of the recognized symbols for the currently selected voice. For the modern higher quality voices, or if an error occurs, returns nil.
| | Notes |
Each entry in the array of phonemes returned will contain the following keys:
Symbol - The textual representation of this phoneme when returned by hs.speech:phonemes or that you should use for this sound when crafting a phonetic string yourself.
Opcode - The numeric opcode passed to the callback for the "willSpeakPhoneme" message corresponding to this phoneme.
Example - An example word which contains the sound the phoneme represents
HiliteEnd - The character position in the Example where this phoneme's sound begins
HiliteStart - The character position in the Example where this phoneme's sound ends
|
​pitch​
| Signature | hs.speech:pitch([pitch]) -> synthsizerObject | pitch | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Gets or sets the base pitch for the synthesizer's voice. | | Parameters |
pitch - an optional number indicating the pitch base for the synthesizer.
| | Returns |
If no parameter is provided, returns the current value; otherwise returns the synthesizer object. Returns nil if an error occurs.
| | Notes |
Typical voice frequencies range from around 90 hertz for a low-pitched male voice to perhaps 300 hertz for a high-pitched child’s voice. These frequencies correspond to approximate pitch values in the ranges of 30.000 to 40.000 and 55.000 to 65.000, respectively.
|
​rate​
| Signature | hs.speech:rate([rate]) -> synthesizerObject | rate | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Gets or sets the synthesizers speaking rate (words per minute). | | Parameters |
rate - an optional number indicating the speaking rate for the synthesizer.
| | Returns |
If no parameter is provided, returns the current value; otherwise returns the synthesizer object.
| | Notes |
The range of supported rates is not predefined by the Speech Synthesis framework; but the synthesizer may only respond to a limited range of speech rates. Average human speech occurs at a rate of 180.0 to 220.0 words per minute.
|
​reset​
| Signature | hs.speech:reset() -> synthsizerObject | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Reset a synthesizer back to its default state. | | Parameters |
None
| | Returns |
Returns the synthesizer object. Returns nil if an error occurs.
| | Notes |
This method will reset a synthesizer to its default state, including pitch, modulation, volume, rate, etc.
The changes go into effect immediately, if queried, but will not affect a synthesis in progress.
|
​setCallback​
Signature
hs.speech:setCallback(fn) -> synthesizerObject
Type
Method
Description
Sets or removes a callback function for the synthesizer.
Parameters
fn - a function to set as the callback for this speech synthesizer. If the value provided is nil, any currently existing callback function is removed.
Returns
the synthesizer object
Notes
The callback function should expect between 3 and 5 arguments and should not return anything. The first two arguments will always be the synthesizer object itself and a string indicating the activity which has caused the callback. The value of this string also dictates the remaining arguments as follows:
​speak​
Signature
hs.speech:speak(textToSpeak) -> synthesizerObject
Type
Method
Description
Starts speaking the provided text through the system's current audio device.
Parameters
textToSpeak - the text to speak with the synthesizer.
Returns
the synthesizer object
​speaking​
Signature
hs.speech:speaking() -> boolean
Type
Method
Description
Returns whether or not this synthesizer is currently generating speech.
Parameters
None
Returns
A boolean value indicating whether or not this synthesizer is currently generating speech.
Notes
See also hs.speech.isAnyApplicationSpeaking.
​speakToFile​
Signature
hs.speech:speakToFile(textToSpeak, destination) -> synthesizerObject
Type
Method
Description
Starts speaking the provided text and saves the audio as an AIFF file.
Parameters
textToSpeak - the text to speak with the synthesizer.
destination - the path to the file to create and store the audio data in.
Returns
the synthesizer object
​stop​
Signature
hs.speech:stop([where]) -> synthesizerObject
Type
Method
Description
Stops the output of the speech synthesizer.
Parameters
where - an optional string indicating when to stop the audio output (defaults to "immediate"). The string can be one of the following:
"immediate" - stops output immediately.
"word" - stops at the end of the current word.
"sentence" - stops at the end of the current sentence.
Returns
the synthesizer object
​usesFeedbackWindow​
| Signature | hs.speech:usesFeedbackWindow([flag]) -> synthesizerObject | boolean | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Gets or sets whether or not the synthesizer uses the speech feedback window. | | Parameters |
flag - an optional boolean indicating whether or not the synthesizer should user the speech feedback window or not. Defaults to false.
| | Returns |
If no parameter is provided, returns the current value; otherwise returns the synthesizer object.
| | Notes |
Special Note: I am not sure where the visual feedback actually occurs -- I have not been able to locate a feedback window for synthesis in 10.11; however the method is defined and not marked deprecated, so I include it in the module. If anyone has more information, please file an issue and the documentation will be updated.
|
​voice​
| Signature | hs.speech:voice([full] | [voice]) -> synthesizerObject | voice | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Gets or sets the active voice for a synthesizer. | | Parameters |
full - an optional boolean indicating whether or not you wish the full internal voice name to be returned, or if you want the shorter version. Defaults to false.
voice - an optional string indicating the name of the voice to change the synthesizer to.
| | Returns |
If no parameter is provided (or the parameter is a boolean value), returns the current value; otherwise returns the synthesizer object or nil if the voice could not be changed for some reason.
| | Notes |
All of the names that have been encountered thus far follow this pattern for their full name: com.apple.speech.synthesis.voice.name. You can provide this suffix or not as you prefer when specifying a voice name.
The voice cannot be changed while the synthesizer is currently producing output.
If you change the voice while a synthesizer is paused, the current synthesis will be terminated and the voice will be changed.
|
​volume​
| Signature | hs.speech:volume([volume]) -> synthesizerObject | volume | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Gets or sets the synthesizers speaking volume. | | Parameters |
volume - an optional number between 0.0 and 1.0 indicating the speaking volume for the synthesizer.
| | Returns |
If no parameter is provided, returns the current value; otherwise returns the synthesizer object.
| | Notes |
Volume units lie on a scale that is linear with amplitude or voltage. A doubling of perceived loudness corresponds to a doubling of the volume.
|