Awesome
<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->Contents
- voices — TTS CLI for macOS
- Examples
- Installation
- Usage
- macOS Service for switching between default voices
- macOS Service for speaking selected text with a specific voice
- License
- Changelog
voices — TTS CLI for macOS
[IMPORTANT: PARTIALLY BROKEN AS OF macOS Sonoma (14): many installed voices aren't recognized, and the default voice isn't listed with -l
]
voices
is a macOS CLI for changing the default TTS (text-to-speech) voice and for printing information about and/or speaking text with multiple voices.
voices
complements the standard say
utility by:
- providing a way to change the default voice
- operating on active voices - those selected for active use - rather than all installed voices
- filtering voices by language
- speaking text with multiple voices.
- On a related note: For a simple
say
wrapper that supports text with embedded instructions to change the voice mid-text (e.g.,[[voice alex]]
), assuming you have Powershell installed, see this comment.
- On a related note: For a simple
Caveats:
-
As of macOS 10.12 (Sierra), there is no documented programmatic way to change the default voice. Thus, this utility makes use of undocumented system internals, which, unfortunately, means that future compatibility of this feature is uncertain. Feedback welcome.
-
voices
currently only fully supports voices provided by Apple. Support for third-party voices such as InfoVox iVox is limited to speaking with them, and the macOS Services documented below will not work with them. -
Additionally, as of macOS 10.15, Siri voices are not supported, due to lack of API support (see this Stack Overflow question).
See the examples below, concise usage information further below, or read the manual.
Additionally, two macOS Services are offered:
- a service for switching between two or more default voices - see below.
- a service for speaking selected text with a specific voice - see below
Note: If you have Alfred with its Power Pack, consider workflow speak.awf as a superior alternative.
Examples
# List all active voices; add -a to list all installed ones.
voices -l
# Print information about the default voice and speak its demo text.
voices -d -k
# Print information about voice 'Alex'.
voices alex
# Make 'Alex' the new default voice, print information about it, and
# speak text that announces the change.
voices -k'The new default voice is Alex.' -d alex
# List languages for which at least one voice is active.
voices -L
# List active French voices.
voices -l fr
# Print information about all active voices and speak
# their respective demo text.
voices -l -k
# Print information about all active Spanish voices and speak their
# respective demo text.
voices -k -l es
# Say "hello", first with voice Alex, then with Jill, suppressing printed
# output.
voices -k"hello" -q alex jill
Installation
Supported platforms
- macOS
Verified to work from OS X 10.8 (Mountain Lion) up to macOS 10.12 (Sierra).
The change-the-default-voice feature makes use of undocumented system internals, so its future compatiblity is uncertain. Do let me know if you find the feature broken in a future macOS version.
Installation from the npm registry
<sup>Note: Even if you don't use Node.js, its package manager, npm
, works across platforms and is easy to install; try curl -L http://git.io/n-install | bash
</sup>
With Node.js installed, install the package as follows:
[sudo] npm install voices -g
Note:
- Whether you need
sudo
depends on how you installed Node.js / io.js and whether you've changed permissions later; if you get anEACCES
error, try again withsudo
. - The
-g
ensures global installation and is needed to putvoices
in your system's$PATH
.
Manual installation
- Download the CLI as
voices
. - Make it executable with
chmod +x voices
. - Move it or symlink it to a folder in your
$PATH
, such as/usr/local/bin
.
Usage
Find concise usage information below; for complete documentation, read the
manual online, or, once installed, run man voices
(voices --man
if installed manually).
$ voices --help
Get or set or speak with the DEFAULT VOICE:
voices [<options>] [-d [<newDefaultVoice>]]
LIST INFORMATION about / speak with voices:
voices [<options>] <voice>...
List / speak with ALL VOICES, optionally FILTERED BY LANGUAGES:
voices [<options>] -l [<lang>...]
LIST LANGUAGES among voices:
voices -L [-a]
MANAGE VOICES in System Preferences:
voices -m
Shared options (synopsis forms 1-3):
-a target all installed voices (default: only active ones)
-k speak demo text with all targeted voices
-k"<text>" speak specified text
-k- speak text provided via stdin
-b output format: print voice names only
-i output format: print voice internals
-q quiet mode: no printed output
Standard options: --help, --man, --version, --home
macOS Service for switching between default voices
This service, which uses an embedded copy of voices
, is helpful if you use text-to-speech in two or more languages and want to quickly
switch the default voice between multiple designated voices cyclically, in combination with the built-in speak-selected-text service.
Every time the service is invoked, the next designated voice is made the default voice, and the localized name of the new voice's language is spoken to confirm the change (this is configurable).
You can invoke the service from any application's standard Services
menu, category General
, or assign it a keyboard shortcut via
System Preferences > Keyboard > Shortcuts > Services
.
Installation
- Download this ZIP file.
- In Finder, open the ZIP file, which creates package
Switch Default Voice.workflow
in the same folder. - Open
Switch Default Voice.workflow
and chooseInstall
when prompted - this will place the package in~/Library/Services/
. - Choose
Done
when prompted and proceed with customization below.
Customization
- Invoke the service for the first time to prompt creating and editing the configuration file.
- From any application, open that application's menu and select
Services > Switch Default Voice
. - You will be prompted to edit the configuration file, where you can specify the voices to switch between; follow the instructions in the file.
- From any application, open that application's menu and select
- To assign a keyboard shortcut to the service, go to
System Preferences > Keyboard > Shortcuts
, categoryServices
, scroll to sub-categoryGeneral
in the list on the right, selectSwitch Default Voice
, and click just inside the right edge of the list item. - To customize the service again later, open
~/.SwitchDefaultVoice-rc
in your text editor.
macOS Service for speaking selected text with a specific voice
This service provides an alternative to switching the default voice: it speaks
selected text in the frontmost application with a fixed alternate voice, which
allows it to be used alongside the built-in speak-selected-text service, which
always uses the default voice (see System Preferences > Dictation & Speech > Text to Speech
).
Typically, you would use this service to speak selected text with a voice that speaks a different language.
You can invoke it from the standard Services
menu, category Text
, whenever text is selected in the frontmost application, or assign it a
keyboard shortcut via System Preferences > Keyboard > Shortcuts > Services
; e.g., ⌥`
(Opt-`) to parallel the default shortcut for
the built-in service, ⌥⎋
(Opt-Esc).
Invoking the service again while text from a previous invocation is still being spoken aborts speaking.
Caveat: This only works if text - any text - is selected in the activate applciation at the time the service is invoked again.
If desired, you can duplicate the service so as to be able to speak with one of multiple alternate voices:
Once installed, duplicate ~/Library/Services/Speak With Specific Voice.workflow
in Finder, give it a meaningful name,
and customize the duplicate as described below.
Installation
- Download this ZIP file.
- In Finder, open the ZIP file, which creates package
Speak With Specific Voice.workflow
in the same folder. - Open
Speak With Specific Voice.workflow
and chooseInstall
when prompted - this will place the package in~/Library/Services/
. - Choose
Open in Automator
when prompted and proceed with customization below.
Customization
- In Automator, follow the instructions at the top of the document, which currently only require you to specify the name of the desired voice.
- Apply your customizations between the lines
# ------- BEGIN: CUSTOMIZE
and# ------- END: CUSTOMIZE
.
- Apply your customizations between the lines
- To assign a keyboard shortcut, go to
System Preferences > Keyboard > Shortcuts
, categoryServices
, scroll to sub-categoryGeneral
in the list on the right, selectSpeak With Specific Voice.workflow
, and click just inside the right edge of the list item. - To customize the service again later, open
~/Library/Services/Speak With Specific Voice.workflow
in Automator.- If you have trouble navigating to
~/Library
, activate Finder, hold down the Option key while selecting theGo
menu, and selectLibrary
; from there, navigate to subfolderServices
and open packageSpeak With Specific Voice.workflow
.
- If you have trouble navigating to
License
Copyright (c) 2015-2018 Michael Klement mklement0@gmail.com (http://same2u.net), released under the MIT license.
Acknowledgements
This project gratefully depends on the following open-source components, according to the terms of their respective licenses.
npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: (D)
denotes a development-time-only dependency, (O)
an optional dependency, and (P)
a peer dependency.
npm dependencies
<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'CHANGELOG.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->Changelog
Versioning complies with semantic versioning (semver).
<!-- NOTE: An entry template for a new version is automatically added each time `make version` is called. Fill in changes afterwards. -->-
v0.3.4 (2018-03-21):
- [doc] Links to workflow ZIPs fixed.
-
v0.3.3 (2018-03-08):
- [fix] It is now ensured that the system versions of standard utilities such
as
awk
are called, to prevent unexpected behavior stemming from user-installed versions in /usr/local/bin getting called.
- [fix] It is now ensured that the system versions of standard utilities such
as
-
v0.3.2 (2017-01-03):
- [doc] Limitations of support for third-party voices noted.
- [fix]
voices -m
now works on macOS Sierra.
-
v0.3.1 (2015-11-03):
- [doc] Added link to Alfred 2 workflow speak.waf as a superior alternative to the OSX services.
-
v0.3.0 (2015-10-27):
- [Potentially breaking change]
-i
for reporting voice internals now reports an extra variableBundleID
as the last item, i.e., the voice's bundle ID.
- [Potentially breaking change]
-
v0.2.3 (2015-09-20):
- [doc]
voices
now has a man page (if manually installed, usevoices --man
);voices -h
now just prints concise usage information.
- [doc]
-
v0.2.2 (2015-09-15):
- [dev] Makefile improvements; various other behind-the-scenes tweaks.
-
v0.2.1 (2015-07-30):
- [doc] Read-me corrections.
-
v0.2.0 (2015-07-29):
- [enhancement]
voices
now honors custom speaking rates when requested to speak with the-k
option - [enhancement] OSX Service
Switch Default Voice.workflow
is now configuration file-based and supports more than 2 voices for cyclical switching; default confirmation text spoken on switching is now the localized name of the new voice's language. - [new] OSX Service
Speak With Specific Voice.workflow
allows speaking selected text with a fixed alternate voice.
- [enhancement]
-
v0.1.9 (2015-07-28):
- [doc] Corrected the mistaken claim that changing the default voice also changes the VoiceOver default voice: the VoiceOver feature has its own default voice, separate from the TTS feature; this utility only changes the TTS default voice, not also the VoiceOver one.
-
v0.1.8 (2015-07-28):
- [fix] Regression: default customization data for the OSX service reset to original values (two US English-voices).
-
v0.1.7 (2015-07-28):
- [fix] When switching default voices, any custom speaking rate (words per minute) configured for a given voice via System Preferences is now honored. Note, however, that speaking text with
voices
' own-k
option does not honor custom speaking rates due to a limitation in the underlyingsay
utility.
- [fix] When switching default voices, any custom speaking rate (words per minute) configured for a given voice via System Preferences is now honored. Note, however, that speaking text with
-
v0.1.6 (2015-07-28):
- [dev] Pre-commit hook fixed to ensure that the modified workflow and ZIP file are added to the index before committing.
-
v0.1.5 (2015-07-27):
- [doc] Read-me and CLI help amended with respect to supported OSX versions.
-
v0.1.4 (2015-07-27):
- [enhancement] Added Automator-based OSX service for switching between two default voices.
- [fix] Inability to determine the default voice on a pristine system is now handled more gracefully.
-
v0.1.3 (2015-07-06):
- [doc] CLI-help copyediting; wording of
--version
streamlined.
- [doc] CLI-help copyediting; wording of
-
v0.1.2 (2015-07-01):
- [doc] CLI help improved.
-
v0.1.1 (2015-06-30):
- [doc] Read-me improvements.
-
v0.1.0 (2015-06-29):
- Initial release.