Skip to content
This repository has been archived by the owner on Jun 9, 2023. It is now read-only.

Latest commit

 

History

History
250 lines (217 loc) · 29.8 KB

hs.speech.md

File metadata and controls

250 lines (217 loc) · 29.8 KB
Raw

docs » hs.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

API Overview

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.
|