Speak2Me · User Guide

Speak2Me is a speech synthesis module for the J1 Template that enables a so-called Text-to-Speech (TTS) converter. The converter reads the important contents of a web page aloud — your visitors can simply sit back and listen to a page instead of reading it.

While a page is read, Speak2Me scrolls the page automatically to the text that is currently spoken and highlights the active paragraph — word by word, like the lyrics in a karaoke video. The voice, the reading speed, the pitch, and the volume can be changed by the visitor in a simple settings dialog.

10-15 Minutes to read

Speak2Me is based on the jQuery plugin Articulate.js written by Adam Coti. The version shipped with the J1 Template is a heavily modified and extended version of the original plugin: it adds automatic page scrolling, paragraph and word highlighting, a voice selection dialog, and several fixes for the different speech engines of modern browsers. For that reason, the original plugin cannot be used as a replacement for the version shipped with the template.

Getting started

The J1 Speak2Me module is a Text-to-Speech (TTS) reader for the J1 Template. It is based on the jQuery plugin Articulate.js written by Adam Coti. The version shipped with J1 Template is a heavily modified version of the original plugin: it adds automatic page scrolling, paragraph and word highlighting, a voice selection dialog, and workarounds for the different speech engines of modern browsers.

With Speak2Me enabled, your visitors can have any content page read aloud by the browser. A click on the speaker symbol opens the Text-2-Speech Control dialog. Here the visitor selects a voice and adjusts the reading speed, the pitch, and the volume. A click on the Speak button starts the reading — the page scrolls automatically to the text that is currently spoken, and the active paragraph is highlighted word by word while reading.

Where the voices come from

Speak2Me does not ship any voices, and no audio data is loaded from external servers. The module uses the Web Speech API — a standard interface built into all modern browsers. The voices themselves are provided by the browser and the operating system of the visitor:

Chrome: Google Chrome offers the well-known Google voices (for example Google UK English Female or Google Deutsch) in addition to the voices installed on the operating system.
Edge: Microsoft Edge offers the high-quality Microsoft Natural voices (for example Microsoft Libby Online (Natural)) in addition to the voices installed on the operating system.

Because the voices come from the browser, the list of available voices is different on every system. Speak2Me detects the language of your site and preselects a suitable default voice for the visitor’s browser automatically.

Browser support

The quality of the Web Speech API differs a lot between browsers. Only the browsers Chrome and Edge provide a speech output in a quality that is good enough for reading longer pages. For that reason, the module is disabled by default for browsers with a poor or incomplete speech implementation (Firefox, Opera, Avast, and Safari) and on mobile devices. On these systems, the speaker symbol is simply not offered — all other functions of your site are not affected.

The speech engine of Chrome stops speaking (silently) after about 15 seconds of continuous audio output — a long-known bug of the browser. Speak2Me works around this problem: long texts are split into smaller chunks, and the speech output is paused and resumed in a configurable cycle. Your visitors will not notice anything of this — the reading continues seamlessly.

How reading a page works

You do not need to know the technical details to use Speak2Me, but it helps to understand what happens behind the scenes. Reading a page runs in a few simple steps:

The visitor opens the Text-2-Speech Control dialog, adjusts the voice settings, and clicks the Speak button.
Speak2Me scans the page once to find the exact positions of all paragraphs and headlines. The positions are needed later for automatic scrolling and highlighting.
A copy of the page content is prepared for speaking: technical elements (like code blocks, forms, or navigation menus) are removed, and special elements (like links, images, or tables) are announced by short spoken hints — for example Link or Image element.
The prepared text is split into smaller chunks and passed to the speech engine of the browser, one chunk after the other.
While speaking, the page scrolls automatically to the text that is currently read, the active paragraph is highlighted, and inside the paragraph the spoken word is marked — like the lyrics in a karaoke video.
Using the control dialog, the visitor can pause, resume, or stop the reading at any time.

How Speak2Me is used in J1 Template

Good news first: you do not need to write any JavaScript code to use Speak2Me in the J1 Template. The template ships with a ready-to-use integration, and the module is configured by simple settings in a YAML configuration file.

The integration consists of four building blocks:

The core module (speak2me.js): The (modified) jQuery plugin that does the real work: it prepares the page content for speaking, controls the speech engine of the browser, scrolls the page, and highlights the spoken text. The plugin is described in detail in the section Programming Interface of this manual.
The J1 adapter (speak2me.js, adapter): A small piece of JavaScript, called an adapter, that connects the core module with the J1 Template. The adapter reads your YAML settings, checks the browser of the visitor, loads the control dialog into the page, fills the voice list, and passes button clicks and slider changes to the core module.
The dialog data file (speak2me.html): An HTML data file that contains the Text-2-Speech Control dialog (the modal). All texts, buttons, and sliders of the dialog are generated from your YAML settings at build time.
The YAML configuration (speak2me.yml): All settings of the module live in YAML configuration files. Here you enable or disable the module, select the content to be read, and control the texts and default values of the control dialog. See the section Configuration for all details.

J1 Integration

Speak2Me is fully integrated in the J1 Template. The template offers the speaker symbol to open the Text-2-Speech Control dialog, loads the dialog into every content page, fills the voice list with the voices available in the visitor’s browser, and connects all buttons and sliders of the dialog with the core module.

The only thing you have to do is to enable the module in the YAML configuration. All other settings are optional and come with useful default values.

Module sources

The sources for Speak2Me are stored within the asset path of the J1 Template. You’ll find the core module under /assets/theme/j1/modules/speak2me:

Structure of the J1 Speak2Me application tree (base components)

  ├───assets
  │   ├───data
  │   │       speak2me.html
  │   └───theme
  │       └───j1
  │           ├───adapter
  │           │   └───js
  │           │           speak2me.js
  │           └───modules
  │               └───speak2me
  │                   └───js
  │                           speak2me.js
  │                           speak2me.min.js
  └───_data
      └───modules
          │   speak2me.yml
          └───defaults
                  speak2me.yml

The parts of the module have the following jobs:

speak2me.js (module): The (modified) jQuery plugin Articulate.js — the core of the module. It prepares the page content for speaking, controls the speech engine of the browser, scrolls the page, and highlights the spoken text.
speak2me.js (adapter): The J1 adapter for Speak2Me. It reads the YAML settings, checks the browser, loads the control dialog, fills the voice list, and passes all user actions (buttons and sliders) to the core module.
speak2me.html: The HTML data file that contains the Text-2-Speech Control dialog. All texts and default values of the dialog are generated from the YAML configuration at build time.
speak2me.yml (two files): The YAML configuration of the module. The file under _data/modules/defaults contains the default settings, the file under _data/modules contains your user settings.

The core module and the adapter use the same filename speak2me.js. When working on the sources, always check the path of a file to be sure which of the two files you are editing.

Configuration

Speak2Me is configured by two YAML files. The default settings live in _data/modules/defaults/speak2me.yml — this file documents all available options and should not be changed. Your personal user settings live in _data/modules/speak2me.yml. At build time, both files are merged: every option you set in the user file overwrites the default value.

By default, Speak2Me is disabled. To activate the module, set the option enabled to true in your user configuration:

settings:
  enabled: true

The most important options are listed below. You’ll find the full list, including all texts and default values of the control dialog, in the (well documented) defaults file _data/modules/defaults/speak2me.yml:

Option	Default	Description
`enabled`	false	Enables or disables the Speak2Me module.
`speechSelector`	main	A CSS selector for the part of the page that should be read aloud. The default `main` reads the main content area of a page — without the header, the footer, and the navigation.
`dialogContainerID`	speak2me_container	The ID of the (invisible) container element the control dialog is loaded into.
`chrome_pause_resume_cycle`	5000	The cycle time in milliseconds used to pause and resume the speech output in Chrome. The pause/resume cycle works around a long-known bug of the Chrome browser that stops the speech output (silently) after about 15 seconds. Change this value only if you notice interruptions.
`mobilesDisabled`	true	If set to true, the module is disabled on mobile devices. The speech engines on mobile systems are too limited for reading longer pages.
`browsersDisabled`	Firefox, Opera, Avast, Safari	A list of browsers the module is disabled for. The listed browsers provide a poor or incomplete implementation of the Web Speech API.
`modal.title`	Text-2-Speech Control	The title of the control dialog.
`modal.settings`	(see defaults file)	The texts, the button styles, and the ranges (minimum, maximum, step, and start value) of the Speed, Pitch, and Volume sliders of the control dialog.

Initialization

Speak2Me is initialized automatically on every page load by the J1 adapter — you do not need to add any code to your pages. The adapter runs the following steps:

Wait until the J1 core system is up and the page content is available.
Check the browser and the device of the visitor. If the browser is listed in browsersDisabled, or a mobile device is detected and mobilesDisabled is set, the initialization stops here — the speaker symbol is not offered.
Load the Text-2-Speech Control dialog (the modal from the data file speak2me.html) into the dialog container of the page.
Read the list of voices offered by the browser and fill the voice selection of the dialog. A suitable default voice for the language of your site is preselected.
Connect the buttons (Speak, Pause, Resume, and Stop) and the sliders (Speed, Pitch, and Volume) of the dialog with the core module.

Customization

The most common customizations can be done by simple settings in your user configuration _data/modules/speak2me.yml:

Select the content to be read: By default, the main content of a page is read (option speechSelector: main). If you want to read a different part of the page only, set the option to a CSS selector of your choice — for example an ID like #article.
Translate the control dialog: All texts of the control dialog (the title, the section headings, the button texts, and the slider labels) are set by the options under modal in the YAML configuration. To offer the dialog in another language, simply overwrite the texts in your user settings.
Change the default voice settings: The start values of the Speed, Pitch, and Volume sliders are set by the options voice_speed_value, voice_pitch_value, and voice_volume_value. A speed of 0.9 (a bit slower than normal) has proven to be a good default for reading web pages.
Exclude content from reading: Content that should not be spoken can be marked directly in your pages. Add the attribute data-speak2me-ignore or the CSS class speak2me-ignore to any element — the element is then skipped by the reader. Elements marked by the class not-spoken are skipped as well, and they are also excluded from scrolling and highlighting. See the section Marking content in your pages for all details.

Programming Interface

Speak2Me is implemented as a jQuery plugin named speak2me. The plugin reads the content of the element it is called on aloud, using the speech engine of the browser (the Web Speech API). In the J1 Template, you normally do not call the plugin yourself — the J1 adapter and the control dialog do all the work for you. The sections below describe the plugin interface for users who want to use the reader standalone or want to understand the integration in detail.

The plugin offers the following core features:

Read a page aloud: The plugin converts the content of any element into spoken audio. The speech is generated by the browser — no audio data is loaded from external servers.
Prepare the content for listening: Before speaking, the content is cleaned up: technical elements (like code blocks, forms, or navigation menus) are removed, and special elements (like links, images, or tables) are announced by short spoken hints — for example Link or Image element.
Follow the spoken text: While speaking, the page scrolls automatically to the text that is currently read. The active paragraph is highlighted, and inside the paragraph the spoken word is marked — like the lyrics in a karaoke video.
Full control at runtime: The reading can be paused, resumed, and stopped at any time. The voice, the reading speed, the pitch, and the volume can be changed by simple method calls.

Initialization

To use the reader standalone (outside of the J1 integration), two steps are needed: load the required JavaScript files, and call the plugin on the element whose content should be read aloud.

JS load

The plugin requires jQuery to be loaded first. Load the module script after its dependency at the end of the body section of your page:

<script src="/assets/js/jquery.min.js"></script>
<script src="/assets/theme/j1/modules/speak2me/js/speak2me.min.js"></script>

JS initialization

The plugin is called on the element whose content should be read — for example the main element of a page. If the plugin is called without a method name, the method speak is used automatically and the reading starts:

// Read the main content of the page aloud
$('main').speak2me('speak');

The speech engine is provided by the browser. The plugin works best in Chrome and Edge — other browsers offer a poor or incomplete implementation of the Web Speech API. Use the method enabled to check if speech synthesis is available before starting the reader.

Methods

All methods of the plugin are called using the jQuery plugin pattern: the name of the method is passed as the first (string) argument, followed by the arguments of the method (if any). Most methods return the jQuery object the plugin was called on, so calls can be chained.

speak

Starts reading the content of the element given by selector. Before speaking, the content is scanned and prepared: ignored elements are removed, spoken hints are added, and the text is split into smaller chunks for a reliable speech output.

$(selector).speak2me('speak');

pause

Pauses the speech output. The current reading position is kept, so the reading can be continued later.

$(selector).speak2me('pause');

resume

Continues a paused reading at the position where it was paused.

$(selector).speak2me('resume');

stop

Stops the speech output completely and removes all highlights from the page. A stopped reading cannot be resumed — the next speak call starts reading from the top again.

$(selector).speak2me('stop');

enabled

Returns true if the browser supports speech synthesis (the Web Speech API), otherwise false. Use this method to check the browser before offering any speech controls:

if ($(selector).speak2me('enabled')) {
  // browser supports speech synthesis
}

isSpeaking

Returns true while the browser is speaking, otherwise false.

$(selector).speak2me('isSpeaking');

isPaused

Returns true if the speech output is currently paused, otherwise false.

$(selector).speak2me('isPaused');

rate

Sets the reading speed used for the next speak call. A value of 1.0 is the normal speed of the selected voice — smaller values slow the reading down, larger values speed it up. Calling the method without an argument resets the speed to the default (1.0).

$(selector).speak2me('rate', 0.9);

pitch

Sets the voice pitch used for the next speak call. Valid values are 0.1 (very low) to 2.0 (very high); the default is 1.0. Calling the method without an argument resets the pitch to the default.

$(selector).speak2me('pitch', 1.0);

volume

Sets the volume of the speech output. Valid values are 0 (muted) to 1.0 (full volume); the default is 1.0. Calling the method without an argument resets the volume to the default.

$(selector).speak2me('volume', 0.8);

ignore

Adds HTML tags (or CSS selectors) to the list of elements that should not be spoken. The given elements are removed from the prepared content before speaking. Any number of arguments can be passed:

$(selector).speak2me('ignore', 'h4', 'table');

recognize

The opposite of ignore: removes HTML tags from the built-in list of ignored elements, so they are spoken again. For example, nav elements are ignored by default — to have them read anyway:

$(selector).speak2me('recognize', 'nav');

replace

Defines text replacements applied before speaking. Replacements are passed as pairs: the text to search for, followed by the text to speak instead. Use this method to fix words the speech engine pronounces badly — for example abbreviations:

$(selector).speak2me('replace', 'e.g.', 'for example', 'Dr.', 'Doctor');

customize

Changes the spoken hints used to announce special elements. For the tags img, table, and figure, a new announcement text is set. For the tags q, ol, ul, and blockquote, a text spoken before and a text spoken after the element is set:

// Announce images with a custom text
$(selector).speak2me('customize', 'img', 'Picture');
// Wrap quotes into custom texts
$(selector).speak2me('customize', 'q', 'Quote begins', 'Quote ends');

getVoices

Reads the list of voices offered by the browser. Called without arguments, the method returns the voice list as an array. Called with a selector (and an optional prompt text), the method creates a ready-to-use dropdown menu filled with all usable voices inside the given element and returns the number of listed voices:

// Return the voice list as an array
var voices = $(selector).speak2me('getVoices');
// Create a voice selection dropdown
$(selector).speak2me('getVoices', '#voiceSelector', 'Choose a voice');

setVoice

Selects the voice used for the next speak call. The voice can be selected by its name or by a language. A language is given as a two-letter code (like en) or as a full language code (like en-GB):

// Select a voice by name
$(selector).speak2me('setVoice', 'name', 'Google UK English Female');
// Select a voice by language
$(selector).speak2me('setVoice', 'language', 'en-GB');

Marking content in your pages

Besides the methods ignore and recognize, the reader can be controlled directly in your HTML content by data attributes and CSS classes. This is the recommended way in the J1 Template, because no JavaScript code is needed:

data-speak2me-ignore: Elements marked by this attribute (and everything inside them) are not spoken. The J1 Template uses this attribute, for example, to exclude the control dialog itself from reading. The CSS class speak2me-ignore works the same way.
not-spoken (CSS class): Elements marked by this class are not spoken either — and they are additionally excluded from automatic scrolling and highlighting. Use this class for visible elements that should be skipped entirely.
data-speak2me-recognize: Protects an element from being ignored. An element marked by this attribute is spoken, even if its tag is on the (built-in or user) ignore list.
data-speak2me-prepend: The text given by this attribute is spoken before the content of the element — for example a spoken introduction for a section.
data-speak2me-append: The text given by this attribute is spoken after the content of the element — for example a spoken closing remark.

A number of HTML tags is ignored by default because they contain technical or non-readable content: audio, button, canvas, code, del, pre, dialog, embed, form, head, iframe, img, meter, nav, noscript, object, picture, script, select, style, textarea, and video. Images and figures are not read, but they are announced, and the alternate text of an image (the alt attribute) or the caption of a figure is spoken — a good reason to maintain meaningful alternate texts for your images.

Callbacks

No public callbacks or events available.

The plugin listens to the (internal) events of the browser’s speech engine to synchronize scrolling and highlighting with the spoken text. These events are used by the module only and are not a public callback interface.

Examples

Read the main content of the current page aloud:

// Start the reader
$('main').speak2me('speak');

Read a page a bit slower using a female English voice:

// Configure the voice, then start the reader
$('main').speak2me('rate', 0.9);
$('main').speak2me('setVoice', 'name', 'Google UK English Female');
$('main').speak2me('speak');

Skip all tables and fix the pronunciation of an abbreviation:

// Configure the content processing, then start the reader
$('main').speak2me('ignore', 'table');
$('main').speak2me('replace', 'J1', 'Jay One');
$('main').speak2me('speak');

Stop the reading:

// Stop the reader
$('main').speak2me('stop');