{"id":13587965,"url":"https://github.com/mklement0/voices","last_synced_at":"2025-05-07T20:43:11.464Z","repository":{"id":34347103,"uuid":"38268284","full_name":"mklement0/voices","owner":"mklement0","description":"macOS CLI for changing the default TTS (text-to-speech) voice and printing information about and speaking text with multiple voices.","archived":false,"fork":false,"pushed_at":"2024-01-30T13:44:18.000Z","size":405,"stargazers_count":63,"open_issues_count":3,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-07T20:43:04.669Z","etag":null,"topics":["cli","macos","macos-services","text-to-speech","tts","voices"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mklement0.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-29T20:01:12.000Z","updated_at":"2024-12-18T13:52:08.000Z","dependencies_parsed_at":"2024-08-01T16:33:58.792Z","dependency_job_id":"9735b686-8561-4066-97df-491d4cf964f7","html_url":"https://github.com/mklement0/voices","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Fvoices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Fvoices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Fvoices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Fvoices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mklement0","download_url":"https://codeload.github.com/mklement0/voices/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252954140,"owners_count":21830894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","macos","macos-services","text-to-speech","tts","voices"],"created_at":"2024-08-01T15:06:26.764Z","updated_at":"2025-05-07T20:43:11.439Z","avatar_url":"https://github.com/mklement0.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"[![npm version](https://img.shields.io/npm/v/voices.svg)](https://npmjs.com/package/voices) [![license](https://img.shields.io/npm/l/voices.svg)](https://github.com/mklement0/voices/blob/master/LICENSE.md)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n**Contents**\n\n- [voices \u0026mdash; TTS CLI for macOS](#voices-\u0026mdash-tts-cli-for-macos)\n- [Examples](#examples)\n- [Installation](#installation)\n  - [Installation from the npm registry](#installation-from-the-npm-registry)\n  - [Manual installation](#manual-installation)\n- [Usage](#usage)\n- [macOS Service for switching between default voices](#macos-service-for-switching-between-default-voices)\n  - [Installation](#installation-1)\n  - [Customization](#customization)\n- [macOS Service for speaking selected text with a specific voice](#macos-service-for-speaking-selected-text-with-a-specific-voice)\n  - [Installation](#installation-2)\n  - [Customization](#customization-1)\n- [License](#license)\n  - [Acknowledgements](#acknowledgements)\n  - [npm dependencies](#npm-dependencies)\n- [Changelog](#changelog)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# voices \u0026mdash; TTS CLI for macOS\n\n[**IMPORTANT**: PARTIALLY BROKEN AS OF macOS Sonoma (14): many installed voices aren't recognized, and the default voice isn't listed with `-l`] \n\n`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**.\n\n`voices` complements the standard `say` utility by:\n\n * providing a way to change the default voice\n * operating on _active_ voices - those selected for active use - rather than all _installed_ voices\n * filtering voices by language\n * speaking text with _multiple_ voices.\n   * On a related note: For a simple `say` wrapper that supports text with _embedded instructions to change the voice mid-text_ (e.g.,\n`[[voice alex]]`), assuming you have [Powershell](https://github.com/PowerShell/PowerShell#get-powershell) installed, see [this comment](https://github.com/mklement0/voices/issues/6#issuecomment-666714554).\n\n**Caveats**: \n\n* 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](https://github.com/mklement0/voices/issues) welcome.\n\n* `voices` currently only fully supports voices provided by _Apple_. Support \nfor third-party voices such as [InfoVox iVox](http://www.assistiveware.com/product/infovox-ivox) is limited to _speaking_ with them, \nand *the macOS Services documented below will not work with them*.\n\n* Additionally, as of macOS 10.15, _Siri_ voices are _not_ supported, due to lack of API support (see [this Stack Overflow question](https://stackoverflow.com/q/61122378/45375)).\n\nSee the examples below, concise [usage information](#usage) further below,\nor read the [manual](doc/voices.md).\n\nAdditionally, two **macOS Services** are offered:\n\n* a **service for switching between two or more default voices** - see [below](#macos-service-for-switching-between-default-voices).\n* a **service for speaking selected text with a specific voice** - see [below](#macos-service-for-speaking-selected-text-with-a-specific-voice)\n\nNote: If you have [Alfred](http://alfredapp.com/) with its [Power Pack](https://www.alfredapp.com/powerpack/), consider workflow\n**[speak.awf](https://github.com/mklement0/speak.awf)** as a superior alternative.\n\n# Examples\n\n```shell\n  # List all active voices; add -a to list all installed ones.\nvoices -l\n\n  # Print information about the default voice and speak its demo text.\nvoices -d -k\n\n  # Print information about voice 'Alex'.\nvoices alex\n\n  # Make 'Alex' the new default voice, print information about it, and\n  # speak text that announces the change.\nvoices -k'The new default voice is Alex.' -d alex\n\n  # List languages for which at least one voice is active.\nvoices -L\n\n  # List active French voices.\nvoices -l fr\n\n  # Print information about all active voices and speak\n  # their respective demo text.\nvoices -l -k\n\n  # Print information about all active Spanish voices and speak their\n  # respective demo text.\nvoices -k -l es\n  \n  # Say \"hello\", first with voice Alex, then with Jill, suppressing printed\n  # output.\nvoices -k\"hello\" -q alex jill\n```\n\n# Installation\n\n**Supported platforms**\n\n* **macOS**\n\nVerified to work from OS X 10.8 (Mountain Lion) up to macOS 10.12 (Sierra).\n\nThe change-the-default-voice feature makes use of undocumented system internals, so its future compatiblity is uncertain.\n[Do let me know](https://github.com/mklement0/voices/issues) if you find the feature broken in a future macOS version.\n\n## Installation from the npm registry\n\n\u003csup\u003eNote: 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`](https://github.com/mklement0/n-install)\u003c/sup\u003e\n\nWith [Node.js](http://nodejs.org/) installed, install [the package](https://www.npmjs.com/package/voices) as follows:\n\n    [sudo] npm install voices -g\n\n**Note**:\n\n* Whether you need `sudo` depends on how you installed Node.js / io.js and whether you've [changed permissions later](https://docs.npmjs.com/getting-started/fixing-npm-permissions); if you get an `EACCES` error, try again with `sudo`.\n* The `-g` ensures [_global_ installation](https://docs.npmjs.com/getting-started/installing-npm-packages-globally) and is needed to put `voices` in your system's `$PATH`.\n\n## Manual installation\n\n* Download [the CLI](https://raw.githubusercontent.com/mklement0/voices/stable/bin/voices) as `voices`.\n* Make it executable with `chmod +x voices`.\n* Move it or symlink it to a folder in your `$PATH`, such as `/usr/local/bin`.\n\n# Usage\n\nFind concise usage information below; for complete documentation, read the\n[manual online](doc/voices.md), or, once installed, run `man voices`\n(`voices --man` if installed manually).\n\n\u003c!-- DO NOT EDIT THE FENCED CODE BLOCK and RETAIN THIS COMMENT: The fenced code block below is updated by `make update-readme/release` with CLI usage information. --\u003e\n\n```nohighlight\n$ voices --help\n\n\nGet or set or speak with the DEFAULT VOICE:\n\n    voices [\u003coptions\u003e] [-d [\u003cnewDefaultVoice\u003e]]\n\nLIST INFORMATION about / speak with voices:\n\n    voices [\u003coptions\u003e] \u003cvoice\u003e...\n\nList / speak with ALL VOICES, optionally FILTERED BY LANGUAGES:\n\n    voices [\u003coptions\u003e] -l [\u003clang\u003e...]\n\nLIST LANGUAGES among voices:\n\n    voices -L [-a]\n\nMANAGE VOICES in System Preferences:\n\n    voices -m\n\nShared options (synopsis forms 1-3):\n\n    -a          target all installed voices (default: only active ones)\n    -k          speak demo text with all targeted voices\n    -k\"\u003ctext\u003e\"  speak specified text\n    -k-         speak text provided via stdin\n    -b          output format: print voice names only\n    -i          output format: print voice internals\n    -q          quiet mode: no printed output\n\nStandard options: --help, --man, --version, --home\n```\n\n# macOS Service for switching between default voices\n\nThis 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\nswitch the default voice between multiple designated voices cyclically, in combination with the built-in speak-selected-text service.\n\nEvery time the service is invoked, the next designated voice is made the default voice, and the localized name of the new voice's\nlanguage is spoken to confirm the change (this is configurable).\n\nYou can invoke the service from any application's standard `Services` menu, category `General`, or assign it a keyboard shortcut via\n`System Preferences \u003e Keyboard \u003e Shortcuts \u003e Services`.\n\n## Installation\n\n* Download [this ZIP file](https://raw.githubusercontent.com/mklement0/voices/stable/osx-service/Switch%20Default%20Voice.workflow.zip).\n* In Finder, open the ZIP file, which creates package `Switch Default Voice.workflow` in the same folder.\n* Open `Switch Default Voice.workflow` and choose `Install` when prompted - this will place the package in `~/Library/Services/`.\n* Choose `Done` when prompted and proceed with customization below.\n\n## Customization\n\n* Invoke the service for the first time to prompt creating and editing the configuration file.\n  * From any application, open that application's menu and select `Services \u003e Switch Default Voice`.\n  * You will be prompted to edit the configuration file, where you can specify the voices to switch between; follow the instructions in the file.\n* To assign a keyboard shortcut to the service, go to `System Preferences \u003e Keyboard \u003e Shortcuts`, category `Services`,\n  scroll to sub-category `General` in the list on the right, select `Switch Default Voice`, and click just inside the right edge of the list item.\n* To customize the service again later, open `~/.SwitchDefaultVoice-rc` in your text editor.\n\n# macOS Service for speaking selected text with a specific voice\n\nThis service provides an alternative to switching the default voice: it speaks\nselected text in the frontmost application with a fixed alternate voice, which\nallows it to be used _alongside_ the built-in speak-selected-text service, which\nalways uses the _default_ voice (see `System Preferences \u003e Dictation \u0026 Speech \u003e Text to Speech`).\n\nTypically, you would use this service to speak selected text with a voice\nthat speaks a _different language_.\n\nYou can invoke it from the standard `Services` menu, category `Text`, whenever text is selected in the frontmost application, or assign it a\nkeyboard shortcut via `System Preferences \u003e Keyboard \u003e Shortcuts \u003e Services`; e.g., `` ⌥` `` (Opt-\\`) to parallel the default shortcut for\nthe built-in service, `⌥⎋` (Opt-Esc).\n\nInvoking the service again while text from a previous invocation is still being spoken aborts speaking.  \n_Caveat_: This only works if text - _any_ text - is selected in the activate applciation at the time the service is invoked again.\n\nIf desired, you can duplicate the service so as to be able to speak with one of _multiple_ alternate voices:  \nOnce installed, duplicate `~/Library/Services/Speak With Specific Voice.workflow` in Finder, give it a meaningful name, \nand customize the duplicate as described below.\n\n## Installation\n\n* Download [this ZIP file](https://raw.githubusercontent.com/mklement0/voices/stable/osx-service/Speak%20With%20Specific%20Voice.workflow.zip).\n* In Finder, open the ZIP file, which creates package `Speak With Specific Voice.workflow` in the same folder.\n* Open `Speak With Specific Voice.workflow` and choose `Install` when prompted - this will place the package in `~/Library/Services/`.\n* Choose `Open in Automator` when prompted and proceed with customization below.\n\n## Customization\n\n* In Automator, follow the instructions at the top of the document, which currently only require you to specify the name of the desired voice.\n  * Apply your customizations between the lines `#  ------- BEGIN: CUSTOMIZE` and `#  ------- END: CUSTOMIZE`.\n* To assign a keyboard shortcut, go to `System Preferences \u003e Keyboard \u003e Shortcuts`, category `Services`, scroll to sub-category `General` in the list on the right, select `Speak With Specific Voice.workflow`, and click just inside the right edge of the list item.\n* To customize the service again later, open `~/Library/Services/Speak With Specific Voice.workflow` in Automator.\n  * If you have trouble navigating to `~/Library`, activate Finder, hold down the Option key while selecting the `Go` menu, and select `Library`; from there, navigate to subfolder `Services` and open package `Speak With Specific Voice.workflow`.\n\n\u003c!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'LICENSE.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. --\u003e\n\n# License\n\nCopyright (c) 2015-2018 Michael Klement \u003cmklement0@gmail.com\u003e (http://same2u.net), released under the [MIT license](https://spdx.org/licenses/MIT#licenseText).\n\n## Acknowledgements\n\nThis project gratefully depends on the following open-source components, according to the terms of their respective licenses.\n\n[npm](https://www.npmjs.com/) 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.\n\n\u003c!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the dependencies from 'package.json'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. --\u003e\n\n## npm dependencies\n\n* [doctoc (D)](https://github.com/thlorenz/doctoc)\n* [json (D)](https://github.com/trentm/json)\n* [marked-man (D)](https://github.com/kapouer/marked-man#readme)\n* [replace (D)](https://github.com/harthur/replace)\n* [semver (D)](https://github.com/npm/node-semver#readme)\n* [tap (D)](https://github.com/isaacs/node-tap)\n* [urchin (D)](https://git.sdf.org/tlevine/urchin)\n\n\u003c!-- 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. --\u003e\n\n# Changelog\n\nVersioning complies with [semantic versioning (semver)](http://semver.org/).\n\n\u003c!-- NOTE: An entry template for a new version is automatically added each time `make version` is called. Fill in changes afterwards. --\u003e\n\n* **[v0.3.4](https://github.com/mklement0/voices/compare/v0.3.3...v0.3.4)** (2018-03-21):\n  * [doc] Links to workflow ZIPs fixed.\n\n* **[v0.3.3](https://github.com/mklement0/voices/compare/v0.3.2...v0.3.3)** (2018-03-08):\n  * [fix] It is now ensured that the system versions of standard utilities such\n          as `awk` are called, to prevent unexpected behavior stemming from \n          user-installed versions in /usr/local/bin getting called.\n\n* **[v0.3.2](https://github.com/mklement0/voices/compare/v0.3.1...v0.3.2)** (2017-01-03):\n  * [doc] Limitations of support for third-party voices noted.\n  * [fix] `voices -m` now works on macOS Sierra.\n\n* **[v0.3.1](https://github.com/mklement0/voices/compare/v0.3.0...v0.3.1)** (2015-11-03):\n  * [doc] Added link to Alfred 2 workflow _speak.waf_ as a superior alternative\n    to the OSX services.\n\n* **[v0.3.0](https://github.com/mklement0/voices/compare/v0.2.3...v0.3.0)** (2015-10-27):\n  * [Potentially breaking change] `-i` for reporting voice internals now reports\n    an extra variable `BundleID` as the last item, i.e., the voice's bundle ID.\n\n* **[v0.2.3](https://github.com/mklement0/voices/compare/v0.2.2...v0.2.3)** (2015-09-20):\n  * [doc] `voices` now has a man page (if manually installed, use `voices --man`);\n          `voices -h` now just prints concise usage information.\n\n* **[v0.2.2](https://github.com/mklement0/voices/compare/v0.2.1...v0.2.2)** (2015-09-15):\n  * [dev] Makefile improvements; various other behind-the-scenes tweaks.\n\n* **[v0.2.1](https://github.com/mklement0/voices/compare/v0.2.0...v0.2.1)** (2015-07-30):\n  * [doc] Read-me corrections.\n\n* **[v0.2.0](https://github.com/mklement0/voices/compare/v0.1.9...v0.2.0)** (2015-07-29):\n  * [enhancement] `voices` now honors custom speaking rates when requested to speak with the `-k` option\n  * [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.\n  * [new] OSX Service `Speak With Specific Voice.workflow` allows speaking selected text with a fixed alternate voice.\n\n* **[v0.1.9](https://github.com/mklement0/voices/compare/v0.1.8...v0.1.9)** (2015-07-28):\n  * [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.\n\n* **[v0.1.8](https://github.com/mklement0/voices/compare/v0.1.7...v0.1.8)** (2015-07-28):\n  * [fix] Regression: default customization data for the OSX service reset to original values (two US English-voices).\n\n* **[v0.1.7](https://github.com/mklement0/voices/compare/v0.1.6...v0.1.7)** (2015-07-28):\n  * [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 underlying `say` utility.\n\n* **[v0.1.6](https://github.com/mklement0/voices/compare/v0.1.5...v0.1.6)** (2015-07-28):\n  * [dev] Pre-commit hook fixed to ensure that the modified workflow and ZIP file are added to the index before committing.\n\n* **[v0.1.5](https://github.com/mklement0/voices/compare/v0.1.4...v0.1.5)** (2015-07-27):\n  * [doc] Read-me and CLI help amended with respect to supported OSX versions.\n\n* **[v0.1.4](https://github.com/mklement0/voices/compare/v0.1.3...v0.1.4)** (2015-07-27):\n  * [enhancement] Added Automator-based OSX service for switching between two default voices.\n  * [fix] Inability to determine the default voice on a pristine system is now handled more gracefully.\n\n* **[v0.1.3](https://github.com/mklement0/voices/compare/v0.1.2...v0.1.3)** (2015-07-06):\n  * [doc] CLI-help copyediting; wording of `--version` streamlined.\n\n* **[v0.1.2](https://github.com/mklement0/voices/compare/v0.1.1...v0.1.2)** (2015-07-01):\n  * [doc] CLI help improved.\n\n* **[v0.1.1](https://github.com/mklement0/voices/compare/v0.1.0...v0.1.1)** (2015-06-30):\n  * [doc] Read-me improvements.\n\n* **v0.1.0** (2015-06-29):\n  * Initial release.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmklement0%2Fvoices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmklement0%2Fvoices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmklement0%2Fvoices/lists"}