speak.awf

Contents

• speak.awf — introduction
• Installation
  • Prerequisites
  • Installation from the npm registry
  • Manual installation
• Customization
  • Configuration with a custom system keyboard shortcut
• License
  • Acknowledgements
  • npm dependencies
• Changelog

speak.awf — introduction

This project is an Alfred 2 workflow for OS X 10.10+ that speaks the active application's text with a specific voice (not just the default voice) using TTS (text-to-speech synthesis).
Note: Use of workflows in Alfred 2 requires the paid Power Pack add-on - an investment well worth making.

The workflow comes with:

• The speak [<voice>] keyword that speaks the active application's text either with the default voice or the specified voice.
  • To make a given voice the new default voice without speaking anything, use Option+Return.
• Templates for defining multiple global keyboard shortcuts for speaking with a predefined voice each.

This is particularly useful for multilingual setups: you can define dedicated keyboard shortcuts to speak with language-specific voices.
For instance, you could have one keyboard shortcut for speaking English texts, and another for Spanish.

Since this workflow is based on the system feature for speaking the active application's text:

• It act as a toggle: invoking a shortcut again while speech is still in progress stops it.

• You can, but do not need to select the text to speak - depending on the application, all text may be spoken implicitly (e.g., in TextEdit.app), or, in Safari.app, Reader view (if available) is automatically activated to read only the text of interest.

Note:

• A side effect of speaking with a given voice is that that voice implicitly becomes the new default voice.
  This means that invoking speech without specifying a voice will from then on will use that voice by default.

• This workflow sends keystrokes behind the scenes to activate the system feature for speaking the active application's text with the default voice. For the most part, this works fine, but occasionally, especially under heavy system load, this may fail.
  (If you know of a way to invoke this system feature programmatically, do let me know.)

  • If speaking doesn't start, at least the part of switching to the target voice should have succeeded, so you can then try to use the system keyboard shortcut (Option+Esc by default) to tigger speaking.

Installation

Prerequisites

• OS X 10.10 or higher
• Alfred 2 with its paid Power Pack add-on.
• The global TTS keyboard shortcut must be activated:
  • Open System Preferences.
  • In pane Dication & Speech, anchor Text to Speech, ensure that Speak selected text when the key is pressed is checked.
  • No further steps are needed if you leave the default global keyboard shortcut, ⌥⎋ (Option+Esc), in place (recommended).
    • If you do use a custom shortcut, you must modify the workflow as described under Customization below.

Installation from the npm registry

^{Note: Even if you don't use Node.js itself: its package manager, npm, works across platforms and is easy to install; try
curl -L http://git.io/n-install | bash}

With Node.js installed, install the package as follows:

[sudo] npm install speak.awf -g

Note:

• Whether you need sudo depends on how you installed Node.js and whether you've changed permissions later; if you get an EACCES error, try again with sudo.
• Alfred 2 will prompt you to import the workflow - confirm.
  • Caveat: If you reinstall, existing customizations will be lost, unfortunately, and have to be reapplied.
• After importing, proceed with customization below.

Manual installation

• Click here to start the download.
• Open the downloaded file: Alfred 2 will prompt you to import the workflow - confirm.
  • Caveat: If you reinstall, existing customizations will be lost, unfortunately, and have to be reapplied.
• After importing, proceed with customization below.

Customization

Customization has two to three parts:

• Decide what predefined voices you want text to be spoken with by global hotkey (keyboard shortcut).
• Assign a hotkey to each such voice.
• If you've chosen a custom hotkey for the Speak selected text when the key is pressed system feature (not recommended): see the next chapter.

Unless already there right after having installed the workflow, open Alfred 2's Preferences... dialog via Alfred 2's menu-bar icon and locate workflow Speak Active App's Text.

The workflow comes with three predefined hotkey-based definitions, based on preinstalled voices "Alex", "Vicki", and "Victoria" Adapt them to your needs:

• Double-click on each Hotkey box:
  • Assign the desired hotkey by clicking in the Hotkey field and pressing the desired key combination.
    • Recommendation: use ⌥1 (Option+1), ⌥2, ... for the voices of interest.
  • Specify the desired voice in the Text input field , using a voice name as displayed in System Preferences > Dication & Speech > Text to Speech

To define additional hotkey-triggered voices:

• Control-click any existing Hotkey box and select Copy.
• Control-click again and select Paste - a new, empty Hotkey box will appear.
• Do the same thing for any existing Run Script box.
• From the right edge of the new Hotkey box, drag a connection to the new Run Script box.
• Customize the Hotkey box as described above.

Configuration with a custom system keyboard shortcut

Note that you'll have to do the following every time you reinstall/upgrade the workflow:

• Open Alfred's Preferences, locate this workflow (Speak Active App's Text), control-click on it in the list on the left, and select Show in Finder.
• Open file toggleSpeaking in a text editor and follow the instructions at the top of the file.

License

Copyright (c) 2015 Michael Klement [e-mail] (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

• doctoc (D)
• json (D)
• replace (D)
• semver (D)
• tap (D)

Changelog

Versioning complies with semantic versioning (semver).

• v0.1.6 (2015-11-01):

  • [enhancement] Option+Enter makes a specific voice the new default voice; on the speak-with-default-voice and no-matching-voice-found result items it instead displays System Preferences for managing the installed/active voices.
  • [enhancement] Speak-with-default-voice result item now names the current default voice.
  • [doc] README.md corrections.

• v0.1.5 (2015-10-30):

  • [doc] README.md update: npm badge and install instructions added.

• v0.1.4 (2015-10-30):

  • [fix] Removed accidentally-left-behind debug output.

• v0.1.3 (2015-10-30):

  • First version to be published at the npm registry.

• v0.1.2 (2015-10-30):

  • [fix] Fix for neglecting to include the updated-by-commit-hook alfredworkflow/version file in the commit.

• v0.1.1 (2015-10-30):

  • [doc] README.md improvements.

• v0.1.0 (2015-10-30):

  • Initial release.