ListenUp

A plugin for speaking segments of post content using a browser’s built-in, JavaScript SpeechSynthesis API.
ListenUp provides shortcodes for adding voice (text to speech) to elements of a post or page.
Reference: https://wicg.github.io/speech-api/
Last updated: 2021-06-13
Installation
Install the plugin using the link at the very top of the Add New Plugin Dashboard panel and selecting the zip file, or upload the unzipped folder to your plugins directory using your favorite FTP program. Once uploaded, Activate the plugin to make it ready for use.
Description
Four shortcodes are available:
ListenUp, will speak all the text content between its opening and closing tags using your browser’s default voice. For example:
[ListenUp]We hold these truths to be self-evident,
that all men are created equal.[/ListenUp]
ListenUpExcerpt, will fetch the post excerpt and speak it. If the post excerpt is empty, the beginning of the content will be read up to “more” tag. If no “more” tag is present, the first 55 words of the content will be read. The enclosed content provides the link to initiate speaking. When used without a closing tag, i.e.: [ListenUpExcerpt], it will provide a default link: Hear the excerpt. Example:
[ListenUpExcerpt]Hear a Brief Summary[/ListenUpExcerpt]
ListenUpImage, will fetch and speak the description of the first image to be found in the content between its openning and closing tags.
[ListenUpImage]<img src=”https://github.com/LarryAronson/ https://example.com/wp-content/uploads/example.jpg” />.[/ListenUpimage]
ListenUpCustom, will fetch the contents of a custom field and speak it. Like ListenUpExcerpt it may be used as a single standalone tag or as a container. For example:
[ListenUpCustom name=”bob”]Hear what Robert says.[/ListenUpCustom]
For all uses, while speaking is in progress, a subsequent click on the linked text will cancel the reading and reset the VoiceSynthesis API. In all cases if there’s nothing left to speak after filtering the content for control characters and html elements, the plugin will exit without altering the post content.
Attributes
A number attributes can be added to each shortcode to control its operation and style the speaking voice. The following attributes are recognized by the voice synthesis engine and are valid for both shortcodes.
Voice Attributes:
speed The speaking rate. The value should be a floating point number between 0.1 and 10.0 indicating a multiple of the normal rate = 1.0. Additionally, the speed can be specified as either fast (equal to 1.67) or slow (0.67).
pitch The vocal pitch. The value should be a floating point number greater than 0.0 and less than or equal to 2.0, with 1.0 being the default. Additionally the pitch can be specified as high (1.75) or low (0.25).
voice A voice name that’s supported by a browser (see notes). Additionally the value can be specified as male or female. Do not enclose this attribute value in quote marks as this can run afoul of WordPress’s character substitution filters.
lang A 2-character code for a language that’s supported by a browser (see notes). Do not enclose the value in quote marks.
Usage Attributes:
id (ListenUpExcerpt and ListenUpCustom)
By default, the current post’s excerpt is read. If this parameter is set to an integer, the excerpt of a post with that id will be read instead.
link (ListenUpExcerpt and ListenUpCustom) The text for the link when the shortcode is used without a closing tag. Default is: “Hear the excerpt” for ListenUpExcerpt and the custom field name for ListenUpCustom.
name (ListenUpCustom only) The key for the custom field attached to the current post or the post referenced by the id attribute. If there are multiple values to the custom field, only the first instance will be fetched and spoken.
class Specifies the CSS class for styling the content. for ListenUp, the default class is ListenUp-content. For ListenUpExcerpt it’s ListenUp-excerpt and for ListenUpCustom it’s ListenUp-custom. An alternate class, ListenUp-button can be invoked by coding: class=”button”. This styles the excerpt or custom field content link to look like a button. Setting the class attribute to a non-existent class, e.g. “null”, will allow the theme’s styles to dominate.
intro Text to be read before other content separated from it by a brief pause. This provides a means for saying something when there’s no visible content to speak. For example, to provide a spoken description when the shortcode encloses an image tag.
title Tooltip text to appear when the cursor is over the link or content (hover state.) The default is “Click to Listen. Click again to Cancel.”
Examples:
ListenUp
[ListenUp intro=”Introduction”]some post content[/ListenUp]
[ListenUp title=”Hear what she said.”]some post content[/ListenUp]
[ListenUp voice=female class=”my-vocal-class”]some post content[/ListenUp]
[ListenUp voice=Amalie lang=fr]Parlez vous Français?[/ListenUp]
ListenUpExcerpt
[ListenUpExcerpt speed=fast]
[ListenUpExcerpt voice=female pitch=”0.50″]
[ListenUpExcerpt class=”button”]Hear Summary[/ListenUpExcerpt]
[ListenUpExcerpt class=”button” link=”Hear Summary”] (same as above)
ListenUpImage
[ListenUpImage title=”Hear Image Description”][/ListenUpImage]
_
ListenUpCustom_
[ListenUpCustom name=”contributors” link=”Acknowledgments”]
[ListenUpCustom name=”lincoln-quote”]Gettysburg Address[/ListenUpCustom]
Usage Notes:
Files:
This plugin distribution consists of this README.html file plus three other files:
ListenUp.php — The main plugin file.
ListenUp.css — The stylesheet containing the default classes.
sayText.js — A JavaScript function for accessing the speechSynthesis API.
The files are rather short—less than 300 lines of code not counting this README file.
ListenUp is safe to use. No changes are made to your WordPress database and no options are saved. The plugin’s functions are not loaded on Dashboard panels.
The styles in ListenUp.css will be loaded into frontend pages and posts. Additional style classes may be added to this file in order to keep them separate from your theme’s stylesheet.
sayText.js contains a single JavaScript function: lup_sayText(what, how). When the plugin is active, this function is loaded into the footer of all frontend pages and posts.
lup_sayText may be invoked anywhere you want to convert text to speech. The first argument to the function is the text to be spoken. Quote marks in the text should be properly escaped and control characters should be removed. The second argument is an array of voice attributes. Here’s an example of how you might use it:

Italian: “1, 2, 3″

**Caveats** This is experimental software. Support for speech synthesis is not universal. Browsers differ in their implementation of the JavaScript APIs used for speech recognition and synthesis. I’ve tested this using recent versions of browsers on MacOS, with Chrome on an Android smartphone and Safari on an iPad. It works more or less on all these platforms. If speech synthesis is not available on a user’s browser, the plugin will issue an alert message when the shortcode content is clicked. Speech synthesis relies on an external speech conversion service that’s built into users’ browsers so an internet connection must be available in order for this to work. JavaScript must be enabled in the user’s browser but, then, WordPress won’t work without it. Avoid using the plugin with a very long content segment. I believe the API limit is 32k characters. The plugin works by enclosing the content or link text in a span () element with an onclick handler. The default style classes set the display property of this span element to “inline-block.” You should take this into account when specifying your own class attributes. You can use these shortcodes multiple times within a post. However, you should having standalone tags appearing before containers of the same tag type since WordPress makes the assumption that a shortcode is a container until it fails to find a closing tag. Note also that the cancel action is global. That is, when speaking is in progress, clicking on any ListenUp or ListenUpExcerpt element will cancel speaking, not just the element previously clicked on. The user needs to click once again to start speaking another ListenUp element. Links within the content enclosed by ListenUp tags will function normally when clicked, however the plugin will also start speaking the content containing the link and will continue speaking on the target and subsequent web pages until finished. Users will need to return to a page using the plugin to cancel the speaking or else wait it out. ListenUpImage depends on WordPress supplying the attachment id as a class name on the image tag, e.g: “wp-image-9999”. If your version of WordPress does not do this, you can supply the attachment id via the shortcode’s “id” attribute. If the attachment record’s…