Articulate.js

Articulate.js, a jQuery plugin, enables developers, with as little as one line of code, to create links that allow users to click, sit back, and listen to the browser read aloud the important content on a Web page. In some ways, it can turn a thoughtful essay or article into a mini podcast. And because it uses built-in JavaScript functionality, no browser extensions or other system software is needed.

Read the featured article on CSS Tricks.

Visit the Articulate.js Web site for more information.

Most Recent Update

v1.1.0: Added methods that retrieve a list of available voices and sets the voice based on the name or language. See CodePen demo and documentation below.

CodePen Demos

Basic Functions

Voice Parameters

Get and Set Voices

Text Manipulation

HTML Data Attributes

Installation

Simply include the "articulate.min.js" file in your project.

Usage

Leverage the powerful selector options of jQuery to specify which parts of the Web page that you want spoken. For example, depending on how you have the Web page organized, a single line of code, like the following, can direct Articulate.js to speak the entire contents of an article or blog post:

$('article').articulate('speak');

Or how about only the primary headers and paragraphs:

$('h1,h2,p').articulate('speak');

Internally, Articulate.js clones the matched set of elements and all their descendant elements and text nodes. It then parses this clone using a default set of rules, deciding what should be spoken and ignored, then adding the appropriate pauses to make everything sound more like a narrative.

Documentation

Basic Functions

Method	Description
$(selector).articulate('speak');	Speaks aloud the specified DOM element(s) and their descendants
$().articulate('pause');	Pauses the speaking
$().articulate('resume');	Resumes the speaking after it has been paused
$().articulate('stop');	Stops the speaking permanently

Voice Parameters

Method	Description
$().articulate('rate', number);	Sets the rate of the speaking voice; default = 1.1; range = [0.1 - 10]
$().articulate('pitch', number);	Sets the pitch of the speaking voice; default = 1.0; range = [0 - 2]
$().articulate('volume', number);	Sets the volume of the speaking voice; default = 1.0; range = [0 - 1]

Note: Omitting number resets the parameter to its default value; changes take effect only when next speak call is made

Read-Only Attributes

Method	Description
$().articulate('enabled');	Returns (true / false) specifying whether the browser supports the Web Speech API
$().articulate('isSpeaking');	Returns (true / false) specifying whether speaking has not yet been completed or stopped
$().articulate('isPaused');	Returns (true / false) specifying whether speaking is paused

Note: $().articulate('isSpeaking'); returns the value of true even when paused

Get and Set Voices

Method	Description
$().articulate('getVoices');	Returns an array of voice objects; each object has two properties: name and language
$().articulate('getVoices',selector,text);	Populates the DOM element(s) selector with a dropdown menu for voice selection; optional text overwrites default dropdown menu instruction
$().articulate('setVoice','name',voice);	Sets voice; must match exactly one of the names returned when using getVoices
$().articulate('setVoice','language',twoDigit);	Sets voice by finding the first voice that matches the twoDigit language code; this is case-insensitive
$().articulate('setVoice','language',code);	Sets voice by finding the first voice that exactly matches the complete language code

Note: Default text for getVoices dropdown menu is: 'Choose a Different Voice'.

Note: Language codes consist of two-characters that specify the language, followed by a hyphen, followed by additional characters that specify the particular country or regional dialect of that language. For example, the codes "en-US" and "en-GB" are both English language, but each represent a different country.

Note: Setting a voice by specifying only a two-digit language code is useful for when you have text on the page in another language, but don't want to bother checking to see if that language is available. For example, a page otherwise in English may have a paragraph in German that you want spoken. That paragraph can have a link like this:

$('p').articulate('setVoice','language','de').articulate('speak');

If the German language is available, it will be appropriately spoken. If not, the current voice will remain.

Text Manipulation

Method	Description
$().articulate('ignore',tagName,tagName,...);	Adds one or more HTML tags to the default array of ignored HTML tags; omitting tagName clears the array of user-specified ignored HTML tags; see Reference Information below
$().articulate('recognize',tagName,tagName,...);	Removes one or more HTML tags from the default array of ignored HTML tags; omitting tagName clears the array of user-specified recognized HTML tags; see Reference Information below
$().articulate('replace',oldText,newText,...);	Replaces oldText with newText when speaking; this is case-insensitive; multiple pairs of text can be specified; omitting parameters deletes previous replace commands
$().articulate('customize',tagName,prepend);	Replaces default text spoken prior to the description of the HTML tags <img>, <table>, and <figure>; omitting parameters reverts values to its defaults; see Reference Information below
$().articulate('customize',tagName,prepend,append);	Replaces default text spoken prior to and after the content of the HTML tags <q>, <ol>, <ul>, and <blockquote>; omitting parameters reverts values to its defaults; see Reference Information below

HTML Data Attributes

Data Attribute	Description
data-articulate-ignore	Content from that DOM element and its descendents are ignored
data-articulate-recognize	Content from that DOM element is spoken, overriding the default
data-articulate-spell	Content from that DOM element is spelled out
data-articulate-prepend=text	Specified text is spoken prior to the content of its DOM element
data-articulate-append=text	Specified text is spoken after to the content of its DOM element
data-articulate-swap=text	Specified text is spoken in place of the content of its DOM element

Miscellaneous

<!-- <articulate>text</articulate> -->

Specified text is spoken when encountered in the HTML; the syntax must match exactly — one space separating the opening and closing <articulate> tags and their neighboring comment markers

Reference Information

Chaining calls is acceptable. For example, the following works just fine:

$('article').articulate('rate',1.3).articulate('speak');

Ignored Tags: audio, button, canvas, code, del, dialog, dl, embed, form, head, iframe, meter, nav, noscript, object, s, script, select, style, textarea, video

HTML Tag	Default Prepend Text	Default Append Text
<img>	There's an embedded image with the description,	n/a
<table>	There's an embedded table with the caption,	n/a
<figure>	There's an embedded figure with the caption,	n/a
<q> and “ ”	Quote,	, Unquote,
<ol>	Start of list.	End of list.
<ul>	Start of list.	End of list.
<blockquote>	Blockquote start.	Blockquote end.

Note: A comma followed by a space results in a pause when spoken; a period results in a slightly longer pause

Examples

$().articulate('ignore','h5','h6','em'); // Do not speak the content of <h5>, <h6>, and <em> tags

$().articulate('recognize','button','code'); // Speak the content of <button> and <code> tags

$().articulate('replace','i.e.','That is'); // When 'i.e.' is encountered, say 'That is'

$().articulate('customize','img','Embedded'); // Change default intro text spoken when <img> is encountered

$().articulate('customize','ol','Start of numbered List.','End of Numbered List'); // Change default intro and outro text spoken when <ol> is encountered

---

<div class="speech">
  <h1 data-articulate-prepend="An analysis of">The Gettysburg Address</h1>

  <p>Despite the speech's prominent place in the history and popular culture 
  of the <span data-articulate-append="of America">United States</span>, the 
  exact wording and location of the speech are disputed. The five known manuscripts 
  of the Gettysburg Address in Lincoln's hand differ in a number of details, and 
  also differ from contemporary newspaper reprints of the speech.</p>

  <p><span data-articulate-swap="Experienced researchers locate">Modern scholarship locates</span> 
  the speakers' platform 40 yards <span data-articulate-ignore>(or more)</span> 
  away from the Traditional Site within Soldiers' National Cemetery at 
  the Soldiers' National Monument and entirely within private, adjacent 
  Evergreen Cemetery.</p>

  <!-- <articulate>This is the end of the article.</articulate> -->
</div>

Using $('div.speech').articulate('speak'); The above will be spoken as:

An analysis of The Gettysburg Address. Despite the speech's prominent place in the history and popular culture of the United States of America, the exact wording and location of the speech are disputed. The five known manuscripts of the Gettysburg Address in Lincoln's hand differ in a number of details, and also differ from contemporary newspaper reprints of the speech. Experienced researchers locate the speakers' platform 40 yards away from the Traditional Site within Soldiers' National Cemetery at the Soldiers' National Monument and entirely within private, adjacent Evergreen Cemetery. This is the end of the article.

Share Links

Facebook

Twitter

LinkedIn

About Adam Coti

I've been a freelance front-end Web developer for over eighteen years. My availability varies, but feel free to contact me if you're interested in the services I offer. My Web site with portfolio and client list is at www.purefreedom.com. Also, take a look at some recent articles I've written for CSS-Tricks.