Articulate.js - The Developers Guide

Please note that, except for specifying which DOM elements to speak, Articulate.js ignores the jQuery selector when executing functions or reading attributes.

Basic Functions

`$(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

`$().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

`$().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

`$().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.

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

`$().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 table 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 table 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 table 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 table below

HTML Data Attributes

`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

 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');

Default Array of Ignored HTML 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