ListenUp provides shortcodes for adding voice (text to speech) to elements of a post or page.
Last updated: 2021-06-13
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.
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.
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.
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.
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.”
[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 voice=female pitch=”0.50″]
[ListenUpExcerpt class=”button”]Hear Summary[/ListenUpExcerpt]
[ListenUpExcerpt class=”button” link=”Hear Summary”] (same as above)
[ListenUpImage title=”Hear Image Description”][/ListenUpImage]
[ListenUpCustom name=”contributors” link=”Acknowledgments”]
[ListenUpCustom name=”lincoln-quote”]Gettysburg Address[/ListenUpCustom]
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.
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.
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″