Speech-enable your website!

Introduction


Based on LAME and the Festival TTS Engine, this flexible jQuery plugin can take text (the input) and generate audio from it. It can be implemented in various ways (the methods) and allows you to preview MP3 audio (the output) in real-time. jTalk can also create high quality WAV files for download. The plugin itself weighs in at around 6kB.

With jTalk, you can:


Features and Examples



Talking Elements (tag method)

The jTalk tag method speaks the text contained within the targeted element. The target element can be referenced by class or id.

Triggering inside linked element (self)

This demo shows the default settings. Click on the linked words to speak them. Words do not have to be hyperlinked - you could use any element, as long as it has a unique class name or id that jQuery can reference. For example, click on the italic words to say them. Automagically!

You can also call the function on hover, on mousedown, on mouseup - pretty much any regular javascript event handler.

If more than one element exists with the same class name, jTalk will apply itself to all of them.

view example code

The basic syntax using a hyperlink and element id:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk();
});
</script>
<a href="#" id="myelement">This will be spoken</a>
The basic syntax using class, with no hyperlink:
<script type="text/javascript">
$(document).ready(function() {
$('.myclass').jTalk();
});
</script>
<p class="myclass">This will be spoken</p>
Usage with a mouseover (hover) handler:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
handler: 'mouseover'
}); }); </script> <p id="myelement'">This will be spoken</p>

Triggering from a different element (triggered)

A trigger element can speak the contents of another element. Click here to say the line below.

A knowledge is a steep that few may climb, but duty is a path that all must tread

view example code

Using a trigger element to call the function:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
trigger_el: 'mytrigger'

}); }); </script> <a href="#" id="mytrigger">Click here</a> <p id="myelement">This will be spoken</p>

Targeting all tags of a certain type (group)

This construct allows you to add jTalk to a group of specified HTML tags. Although it may seem the same as the default method, it's only supposed to target DOM tags and not ids (which should be unique) or classes (which are style and not strictly DOM-based).

Below, I've added the <blockquote> tag to jTalk - it'll add every instance it finds on the page.

This is a blockquote

This is another blockquote

view example code

Adding jTalk to a group of HTML element tags:
<script type="text/javascript">
$(document).ready(function() {
$('blockquote').jTalk({});
});
</script>
<blockquote>
<p>This is a blockquote</p>
</blockquote>
<blockquote>
<p>This is another blockquote</p>
</blockquote>

Reading through multiple target elements (multiple)

This method allows you to pass an array of target elements to read through. This uses a lot of processing power, so go easy!

Note - This differs from the group method in that it speaks all of the elements at once (i.e., concatenates them).

You're once.

Twice.

Three times a lady.

Read the above elements.

view example code

Sending an array of DOM elements to read through (note - no trigger element is required):
<script type="text/javascript">
$(document).ready(function() {
$('#myelement).jTalk({
target_el: Array('element_1', 'element_2', 'elem...')
}); }); </script> <a id="myelement" href="#">This will read the targeted elements.</a>

Sending a string of text to talk (string)

You don't have to use the contents of an element at all - you can send a string of text to say directly to the function. Click here for a defined message.

view example code

Sending a string of text to speak:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement).jTalk({
text: 'Hello World'
}); }); </script> <a id="myelement" href="#">This will be clicked and a string will be spoken</a>

Using an input field (input)

This method allows your visitors to input their own - ideal for form fields.

view example code

Using an input field, referenced by class (note the trigger variable is the button id):
<script type="text/javascript">
$(document).ready(function() {
$('.mytextarea').jTalk({
method: 'input',
trigger_el: 'demo-input-submit'
}); }); </script> <input type="text" class="demo-input" id="mytext" value="Hello World!" /> <input id="demo-input-submit" type="button" name="Button" value="Say It!">

Using a textarea (textarea)

This method allows your visitors to input their own text.

view example code

Using an input text area, referenced by class (note the trigger variable is the button id):
<script type="text/javascript">
$(document).ready(function() {
$('.mytextarea').jTalk({
method: 'textarea',
trigger_el: 'demo-textarea-submit'
}); }); </script> <textarea class="mytextarea" id="mytext" name="mytext">This will be spoken.</textarea> <input id="demo-textarea-submit" type="button" name="Button" value="Say It!">

Hiding the Link Icon

By default, a small icon is placed next to every jTalk-enabled element (or its trigger). This allows your visitors to differentiate between talking links from normal ones. You can override this behaviour by sending the linkicon option as false:

<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
linkicon: false
});
});
</script>
<a href="#" id="myelement">This will be spoken</a>

top


Talking Selections (highlight method)

The jTalk highlight method speaks the text that has been highlighted (drag-selected) by the user. The target element can be referenced by class or id. The process begins when the mouse button is released. Double and triple-click features are also supported.

Drag, highlight and speak

Select a section of text in the paragraph below (pink for female voice, blue for male).

There's a voice that keeps on calling me. Down the road, that's where I'll always be. Every stop I make, I make a new friend. Can't stay for long, just turn around and I'm gone again. Maybe tomorrow, I'll want to settle down, Until tomorrow, I'll just keep moving on.

Ten years ago a crack commando unit was sent to prison by a military court for a crime they didn't commit. These men promptly escaped from a maximum security stockade to the Los Angeles underground. Today, still wanted by the government, they survive as soldiers of fortune. If you have a problem and no one else can help, and if you can find them, maybe you can hire the A-team.

view example code

Talking highlights - speaking selected text:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
method: 'highlight',
handler: 'mouseup'

}); }); </script> <p id="myelement">This is the paragraph where the highlighted (selected) text will come from.</p>

Double and Triple Clicking

You can also double and triple click to select single words and whole lines respectively. Try it out below.

Double.

view example code

Double-click and speaking single word:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement).jTalk({
method: 'highlight',
handler: 'dbclick'
}); }); </script> <p id="myelement">Double-click any word in this sentence to hear it spoken.</p>

Triple-click me. The quick brown fox jumped over the lazy dog.

view example code

Triple-click to speak a whole sentence:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
method: 'highlight',
handler: 'trplclick'
}); }); </script> <p id="myelement">Triple-click to read this whole sentence.</p>

top


Talking RSS Feeds (rss method)

The extremely easy-to-use rss method reads out the first n headlines from any valid RSS newsfeed.

BBC News : http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/world/rss.xml

Click here for The Register's top 10 stories.

Try it out - enter an RSS feed URL:

If the submitted URL is incorrect, an error message is spoken.

view example code

Fetching newsfeeds from the BBC - element contents used as RSS url:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
method: 'rss'
}); }); </script> <p id="myelement">http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/world/rss.xml</p>
Fetching 5 stories from theregister.co.uk - passing the RSS url and count as variables:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
method: 'rss', rsscount: 10,
rssurl: 'http://www.theregister.co.uk/headlines.rss'

}); }); </script> <a id="myelement" href="#">Click here for The Register's top 10 stories.</a>

Text Substitution

Using the substitute option with your jTalk command allows you to pass an array of words to be substituted for their replacements. This is handy for custom pronunctiations and extending abbreviations for example. It has similar functionality to the extended method described here.

I like Microsoft products on my PC.

Let's change one simple word to many.

view example code

Sending a list of word substitutions - watch out for the tricky comma syntax:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
substitute: Array('like,love','microsoft,apple', 'pc,mac')
}); }); </script> <a href="#" id="myelement">I like Microsoft products on my PC.</a>
Substituting one word for multiple words (and yes, commas in the substitution are ignored):
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
substitute: Array('simple, little, but perfectly adequate')// ignored comma in substitution
}); }); </script> <a href="#" id="myelement">Let's change one simple word to many.</a>

Bonus Methods

To make life easy, I've implemented a few predefined methods. Using these bonus methods on your pages will provide a series of handy audio prompts.

Talking Clock

This method speaks either the local or server time based on GMT. It accepts variables in PHP's date format - allowing for a wide variety of outputs. It may be wrong in certain timezones - I'm working on it!

view example code

Bonus method - speaking clock with format configuration: (note the Array!)
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
bonus: Array('clock','local','l jS \of F Y h:i:s')
}); }); </script> <a href="#" id="myelement">Click here to hear the date and time</a>

Talking URL

This method speaks the full URL that's in your browser's address bar.

view example code

Bonus method - says the full URL currently in the browser: (note the Array!)
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
bonus: Array('url')
}); }); </script> <a href="#" id="myelement">Click to hear the current web address</a>

Talking IP

This method tells you your IP address. It can also tell you the IP address of another server (Google). If you pass a server name, it also speaks that.

view example code

Bonus method - says your IP addresses : (note the Array!)
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
bonus: Array('ip')
}); }); </script> <a href="#" id="myelement">What's my IP address?</a>
Bonus method - says the IP of a given domain - note the second parameter:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
bonus: Array('ip','google.com')
}); }); </script> <a href="#" id="myelement">IP address of Google.com?</a>

Password Protection

This method allows you to password-protect the processing of speech.

Click here to say this - only if the password is correct.

(password is 'secret')

view example code

Bonus method - password-protection:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
bonus: Array('password','password_input_id')
}); }); </script> <a href="#myelement">Click here to say this - only if the password is correct.</a></p
<form id="form1" name="form1" method="post" action="">
<input name="passwordinput" type="text" id="password_input_id" />
</form>

top


The Extension Method

All information regarding the extension method and creating new jTalk methods can be found under the Extending jTalk tab.


Advanced Methods Using jQuery

Coupling jTalk with advanced jQuery methods can provide you with a myriad of additional methods for implementing speech on your pages. From traversing, filtering and talking anything within the DOM tree to complex regular expressions (regex) commands, it's possible to have jTalk find and speak anything on your (and other) websites. See more ways to extend jTalk here.

Search Example

You can do things like this:

<a href="#" class="inline" onclick="$(this).jTalk({
usecache: true,
text:$(body).find('p:contains(\'fantastic\')').text().replace('.','; ') // full-stop to semi colon for pause
});">Search for the word 'fantastic' in the above three sentences</a>

What a fantastic day.

Here's another short sentence that doesn't contain our word.

I think that the jTalk plug-in is fantastic.

Search for the word 'fantastic' in the above three sentences (talks those containing it)

Talking Page Titles

How about simply reading out the title of the current webpage?

<a href="#" class="inline" onclick="$(this).jTalk({text:document.title});">title</a>

Talking Page and DOM Statistics

Want to know how many words or paragraphs on the page? How many <h2> headings, or occurences of the word jQuery? Let jTalk tell you the answer! This method could come in extremely helpful for trouble-shooting a document's source code without even looking at it!

<a href="#" class="inline" onclick="$(this).jTalk({text:$('p').size()});">Count paragraphs</a>

Image Dimensions

jTalk can tell you the dimensions of an image. Click the image below for an example.

<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
text: 'This image is '+$('#myimage').width()+' pixels wide, and '+$('#myimage').height()+' pixels high.' }); </script> <a href="#myelement"><img id="myimage" src="images/logo.gif" alt="" border="0" /></a>

top


Transport and Download Controls

Showing a Transport Bar

There are two types of transport control - HTML and Flash. The default is HTML.

You can show transport controls for generated speech by setting the transport variable. The transport bar usually requires 3 variables - one to enable/disable it, one to designate the id of the element it should be attached to, and a final (optional) one to define which type of transport - Flash or HTML. The element of the text to be spoken and its parent element should both have a unique id set.

Click here to add a standard transport bar

Click here to add a Flash transport bar (experimental - cannot yet be controlled or effected via regular methods)

Note - If the autoplay option is set to false, a transport bar is automatically shown (see below).

Note - only one transport bar or transport/download bar combination is ever shown on the page at any one time. This is intentional.

view example code

Attaching a transport bar - note the element ids that should be added:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
transport: true,
transportdiv: '
myparentelement' // If this is omitted, the system will attempt to delegate the parent
}); }); </script> <div id="myparentelement"><a href="#" id="myelement">This will be spoken</a></div>

Displaying a Download Link

If you'd like your users to download the actual generated audio file, you can use the built-in download option to do so. As with transport controls, the target element and its parent should both have unique ids.

Click to show a download control for this piece of splendid speech.

view example code

Attaching a download link - note the element ids that should be added:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
download: true,
downloaddiv: 'myelement'
// If this is omitted, the system will attempt to delegate the parent
}); }); </script> <a href="#" id="myelement">This will be spoken</a>

Controlling and Overriding Playback

You can perform the following actions on the audio which is currently active when using an html transport bar (not Flash).

Incidentally, if you look at the jTalk source code, you can see that audio playback can be accessed from, and bound to, pretty much any DOM object. This potentially allows you to control playback from images, links and even Flash movies (via JavaScript for Flash).

Click here to generate the paragraph above, then expand the code section below to try it out.

view example code

Controlling playback of the audio:
// The player element id should always be the same - 'jtalk_player'
// STOP
$('#jtalk_player').stop();
// PLAY
$('#jtalk_player').play();
// PAUSE
$('#jtalk_player').pause();
// POSITION THE PLAYHEAD (in percentage)
$('#jtalk_player').playHead(25);
// POSITION THE PLAYHEAD (in milliseconds)
$('#jtalk_player').playHeadTime(10000);
// VOLUME - this is different to the speech volume!
$('#jtalk_player').volume(50);
// MIN VOLUME - used to mute the audio
$('#jtalk_player').volumeMin();
// MAX VOLUME
$('#jtalk_player').volumeMax();
// ON SOUND COMPLETE - what to do when the audio is finished
$('#jtalk_player').onSoundComplete(function(){
alert('Sound Completed');
});

Adding Effects to Transport and Download Controls

As transport and download controls are valid DOM objects, you can attach regular jQuery actions to them.

Click here to load some speech with a transport bar and then expand the code section below to try it out.

view example code

Controlling the appearance of transport bar (same methods can be applied to the download bar):
// The transport bar should always retain the class 'jtalk_transport'
// THE TRANSPORT BAR SUPPORTS REGULAR jQUERY MODIFIERS
$('.jtalk_transport').hide('slow');
$('.jtalk_transport').show('slow');
$('.jtalk_transport').slideUp(250);
$('.jtalk_transport').slideDown(250);
$('.jtalk_transport').fadeOut('fast');
$('.jtalk_transport').fadeIn('fast');
...etc
// TO DESTROY THE TRANSPORT BAR
$('.jtalk_transport').remove();

top


Auto-playing Audio

You can choose whether the speech starts immediately after it has been processed. This is default behaviour. If autoplay is disabled, there is no method to play the audio so a transport bar is automatically shown (but only if the audio is in MP3 format).

view example code

Auto-playing with a custom loading message and no overlay block:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
autoplay: true, loading: true,
loadingdiv: 'myelement',
// If this is omitted, the system will attempt to delegate the parent loadingmsg: 'The speech is being generated...please wait', overlay: false
}); }); </script> <a href="#" id="myelement">This will be spoken</a>

Loading Feedback (overlay, message)

There are two available methods to provide feedback to your visitors that audio is being processed.

Modal Overlay Block

This method simply blocks out the screen with a transparent overlay, preventing any further user interaction whist the audio is being processed. It is turned on by default.

view example code

Turning the overlay block off:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
overlay: false
}); }); </script> <a href="#" id="myelement">This will be spoken</a>

Loading Message

This method shows a discreet text-only message whilst the audio is being processed. You can pass the message, and the div it should be attached to, at runtime.

Note - you should ideally disable the overlay block so the message is clearly visible.

view example code

Auto-playing with a custom loading message and no overlay block:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
autoplay: true, loading: true,
loadingdiv: 'myelement',
// If this is omitted, the system will attempt to delegate the parent loadingmsg: 'The speech is being generated...please wait', overlay: false
}); }); </script> <a href="#" id="myelement">This will be spoken</a>

Output Format

jTalk supports the output of WAV files. Although there is no live playback, there may be situations where you require a higher quality audio file. A download link is automatically added for WAV files.

view example code

Outputting as a WAV file - no live preview, download link is added:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
format: 1,
downloaddiv: 'myelement' // If this is omitted, the system will attempt to delegate the parent
}); }); </script> <a href="#" id="myelement">This will be spoken</a>

top


Loading Alternative Sound Files

You can pass the URL of an MP3 file to play instead of the speech. Used in conjuction with a transport bar, it's handy method of embedding music on your pages. Click here to load a track and attach a transport and download link.

view example code

Playing an alternative audio file (soundurl), with a transport bar:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
transport: true,
transportdiv: 'myelement', // If this is omitted, the system will attempt to delegate the parent soundurl: 'http://www.example.com/your-audio-file.mp3'
}); }); </script> <a href="#" id="myelement">Play external audio</a>

Changing the Voice

You can have different voices on the same page - allowing for virtual jQuery conversations with distinctly different sounds.

More voices will be added as and when they are made available.

view example code

How to choose a different voice:
<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
voice: 'voice_don_diphone'
}); }); </script> <a href="#" id="myelement">This will be spoken</a>

Using jTalk over SSL

jTalk supports SSL (Secure Socket Layer) out of the box. This means all of your requests, operations and audio transactions are carried out over an encrypted connection. Click here to generate this sensitive speech data over SSL (note the download link uses https).

top


Instructions and Documentation



Requirements

To implement and run jTalk you'll need:

  1. The jTalk plugin
  2. The other jQuery files
  3. PHP hosting
  4. A Festival installation
  5. A LAME installation
  6. Lots of webspace
  7. A modern browser

definitely
preferably on your own server

Installation

  1. Download and Unzip
  2. Enter your regkey in jtalk_proxy.php
  3. Upload files
  4. Visit the included example page
  5. Talk!

Folder Permissions

You need to set the permissions on your local cache directories so that the system can write to them. You can do this by chmod'ing the 'audio_cache' and 'request_cache' directories to 777. Most FTP clients support permission operations.

Including the Required Files

jTalk requires a couple of other plugins to work - the excellent blockUI and the equally splendid jPlayer. Along with the core jQuery library, these files must be included in the <head> section of every page that you wish to run jTalk on.

<script language="JavaScript" type="text/javascript" src="js/jquery-1.3.2.min.js"></script>
<script language="JavaScript" type="text/javascript" src="js/jquery.blockUI.js"></script>
<script language="JavaScript" type="text/javascript" src="js/jquery.jplayer.pack.js"></script> <script language="JavaScript" type="text/javascript" src="js/jquery.jTalk.pack.js"></script>

Adding the Discreet Player Element

For jTalk to play audio, it needs a dedicated element on the page in which to inject the discreet (invisible) Flash player. Although the player is invisible, this element must still be kept empty.

Important - the player element is not the same as a transport bar (which simply controls playback).

Important - the id is mandatory and its value must be jtalk_player (although you could change this in the plugin's source code if you really must).

<div id="jtalk_player"></div>

Initialising jTalk

There are two ways to invoke/initialise jTalk - either from inside the jQuery document ready statement or by using inline jQuery calls (pseudo-global method).

1. The $(document).ready() Method

By far the most elegant method is to include your jTalk functions from within jQuery's ready function. This ensures that your web page has fully loaded and all the talkable elements have been rendered on the page. The commands themselves can be placed anywhere in the page using regular <script> tags.

<script type="text/javascript">
$(document).ready(function() { // place your jTalk code here });</script>

2. The Inline Mark-Up Method

This method is used to make calls to jTalk from within your page mark-up. It can be viewed as a global method as it doesn't need to be within jQuery's document ready statement. The syntax is identical to the regular method, yet as the options must be typed inline, it can sometimes make for spaghetti code and doesn't really follow the rules of keeping script and mark-up separate. It's handy though and adds a certain immediacy when working with jTalk.

No handler variable is required as the behavioural mark-up takes care of it (onclick in the code below).

Important - The class variable must be set to 'inline' for this to work reliably. Also note the use of $(this) to refer to the containing element.

<a href="#" class="inline" onclick="$(this).jTalk();">This will be spoken.</a>

Delegating jTalk to New Elements

You can delegate and apply jTalk to new elements at runtime by simply referencing them. The below sentence starts off with no jTalk method attached. After clicking the link below it, it will have.

This sentence is looking forward to receiving the jTalk method!

Click here to attach jTalk to the above sentence (after delegation, you can listen to the above sentence by clicking it).

Note - To allow the newly-delegated elements to show transport and download bars, you should always use unique ids.

<p id="delegate-slave">Method will be attached to this element</p>
<a id="delegate-master" href="#" class="inline" onclick="$('#delegate-slave').jTalk();">Delegate jTalk</a>

You could take this even further by using jQuery to create whole new DOM elements and delegating them at runtime.

top

jTalk Configuration Options

jTalk has the following variables which can be set for each call:

Important! - strings must be enclosed in single or double quotes, other variable must not!

Option Name
Description
Default Value
Type
method
can currently be tag, highlight, input, textarea or rss
'tag'
string
can be click, change, mouseover, mouseup, load, dblclick or trplclick
null
string
the id of the element which is triggering the speech
null
string
an array of target elements to read through
null
array
a string of text to send (as opposed to what's between the element)
null
string
striptags
remove html and script tags from the input
true
boolean
substitute words with a given replacement
null
array
charlimit
the maximum characters allowed for processing
500
integer
triggers the bonus methods and passes an array
null
array
add a custom extension method to jTalk
null
array
whether to play the sound immediately
true
boolean
show a lightbox-style modal window whilst generating audio
true
boolean
overlaytype
what the overlay blocks - can be page or element
'page'
string
the directory path of the jPlayer object (JPlayer.swf) - usually located with the JavaScript files - this is not the same as the Flash transport bar!
'flash'
string
followlinks
allows hyperlinks within the active element to work
false
boolean
show a small icon next to speech-enabled elements
true
boolean
linkiconclass
css class for the link icon
'jtalk_link'
string
show loading message
false
boolean
loadingmsg
loading message
'Processing audio...please wait'
string
loadingdiv
element to which the loading message is appended
null
string
show transport buttons below element (only if mp3)
false
boolean
transportdiv
element to which the transport bar is appended
null
string
transporttype
what type of transport bar to show - can be html or flash - currently replays on tab change (Firefox bug, not mine!)
'html'
string
show a download link to created audio
false
boolean
downloaddiv
element to which the download link is appended
null
string
pass an alternative file URL to the player (mp3 only) - can be virtually anywhere on the internet
null
string
which voice to use
'voice_nitech_us_awb_arctic_hts'
string
volume
volume when generating speech, not the player
1
integer
can be mp3 (0) or wav (1) - must be mp3 for realtime playback
0
integer
samplerate
sample rate in kHz of output audio
22
integer
bitrate
bit rate in kbps of output audio
32
integer
Location (relative or absolute) of the proxy relay script
'jtalk_proxy.php'
string
URL of the jTalk server
'http://speech.jtalkplugin.com'
string
URL of the SSL-enabled jTalk server
'https://speech.jtalkplugin.com'
string
allows SSL encryption at the above URL
false
boolean
address for rss feeds (if none, element contents is used for URL)
null
string
rsscount
number of RSS headlines to read
5
integer
if an audio file for the same speech string already exists on the remote jTalk server, the cached file will be served instead of creating a new one
true
boolean
if true, audio files will be copied from the jTalk remote server to a local cache and subsequently served from there. Still a little unpredictable!
true
boolean
directory in which to save locally cached audio files (see above)
'audio_cache'
string
a folder to store cached requests (not audio!)
'request_cache'
string
amount of time, in seconds, before request cache is updated, use 0 to disable
0
integer

* - only included for future extensibility and not implemented yet

** - I've imposed a forced maximum character limit on my server to help reduce the load

top

Event Handlers

The plugin supports all of jQuery's event handlers (not DOM invoked).

The most commonly used are:

For a full list visit http://docs.jquery.com/Events.

Certain methods are restricted to a single handler to prevent odd behaviour. If no handler is specified, the default one of click is used.

Note - Be careful when adding event handlers to inline jTalk markup - adding an extra handler to these can cause double-triggering. For example:

<a href="#" class="inline" onmouseover="$(this).jTalk({handler: 'mouseup'});">This will double trigger.</a>

Recognized Speech Tokens

The Festival engine is quite elaborate and covers most of the common multi-word tokens in English including, numbers, money symbols, Roman numerals, dates, times, plurals of symbols, number ranges, telephone number and various other symbols. This means that you can enter something like: "I had to exchange 5, and I ended up with around $8". Note the word "pounds" and "dollars", which is introduced by their respective signs, ends up after the end of the number expression.

Also, how about: "On my birthday, on April 5th 1985, I received 27 cards; I was twelve". See how the four different types of number are dealt with differently - smart eh?

Punctuation and its Effects

Certain punctuation symbols are significant in jTalk in that they can effect the way a word or phrase is spoken. Full-stop, commas, semi-colons and question marks can all make a difference to the final outcome.

  • This is a list
  • Without any punctuation
  • It flows together and doesn't sound very nice
  • Make it easy on yourself;
  • because breaking up;
  • is so very hard to do;

Styling jTalk

There's not much to style really, but you can change most aspects of jTalk's appearance via the included 'jtalk.css' file. The style declarations apply to the transport and download bars, the loading notification and the link icon. If you wish to style the overlay, see the blockUI jQuery file.

The PHP Proxy

jTalk comes with a PHP proxy which allows you to send and receive requests to my LAME and Festival server. Without these files, browser security would prevent any transactions across different internet servers and domains.

The proxy script comprises three files - all must be uploaded to the same directory where your pages containing jTalk are.

The Cache Options

There are three main caching options in jTalk:

  1. Server Caching
  2. Local Caching
  3. Request Caching

Server Caching

Every time jTalk processes a piece of text, it creates an audio file on the jTalk speech server (speech.jtalkplugin.com). Over time, a huge amount of space can be used up. To speed up speech processing, lessen the CPU load and save space, a cache option can be set. This cache is turned on by default.

When turned on, if the jTalk server receives the exact same string for a file that it has already processed, it will serve that audio file instead of creating a new one. To force the creation of a new audio file, simply send the 'usecache' option as false.

Note - this feature is totally different from request caching (see below)

Local Caching

When local caching is enabled, jTalk will attempt to 'fetch' or 'scrape' the generated audio file and store a local copy of it on your server (the webspace where you are deploying jTalk). You can specify the destination folder for these cached files in the options - this directory must already exist within your webspace. All subsequent requests for audio files containing the exact same string will be served from this local store.

Request Caching

When enabled, request caching stores all of your HTTP queries and RSS scrapes (XML). This can free up valuable resources and provide a little extra speed if you've lots of repetitive queries sending the same strings of speech to be processed. You can also set a lifetime value which governs how long the cache is used before making a fresh request. Request caching can be disabled by setting the lifetime to 0 (default).

Note - this feature has absolutely nothing to do with saving actual audio files - that's handled by server caching (above).

Setting up your own jTalk Server

jTalk relies on custom Festival and LAME installations for its speech and audio processing. As such, if you want to rely on this in a production environment, you'll need root access on a dedicated machine. Setting up Festival and LAME can be a pain in the literal back-end, but if you need help on a CentOs system, give me a shout.

The plugin currently makes cross-browser AJAX calls (via a lightweight PHP proxy which comes with the plugin) to Festival on my server and stores the audio there. If it gets too hectic, I'll have to consider throttling access.

Troubleshooting

If you can't get jTalk working, try working through the following list (after checking your installation etc. is correct).

Failing all these, it might be worth dropping me an email to check that the main jTalk server isn't down (try pinging speech.jtalkplugin.com and if there's no response, it may be down).

top


Extending jTalk


The three main ways to extend jTalk are:

  1. By using the bult-in extension method (relatively simple)
  2. By using advanced jQuery methods to provide the input string for speech conversion (see below)
  3. By adding new methods to the jTalk plugin source code (advanced and not covered here)


1. Using the Built-in extension Method

jTalk includes built-in support for extending methods via the extension option. Creating a new method is relatively simple if you're familiar with jQuery/JavaScript and PHP. Extended methods should be placed in the jtalk_methods.php file.

Caveats: You cannot use the exit() command in the jtalk_methods.php file. If jTalk finds one of these at runtime, it'll tell you with a JavaScript alert.

Example Methods:

Method with simple output relaying - would be placed in jtalk_methods.php:

// BEGIN YOUR jTalk METHOD
if ($_POST['extension'][0] == "mymethod"){
$_POST['speech'] = 'Hello World!';
} // END YOUR jTalk METHOD

...and the jTalk code on your page might look like this:

<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
extension: Array('mymethod')
}); }); </script> <a href="#" id="myelement">My Custom Method</a>

Method with more complex options - again, this goes in jtalk_methods.php:

// BEGIN YOUR jTalk METHOD
if ($_POST['extension'][0] == "complexmethod"){
// VARIABLES FROM THE jTalk JAVASCRIPT CALL
$var_1 = $_POST['extension'][1];
$var_2 = $_POST['extension'][2];
$var_3 = $_POST['extension'][3];
// PERFORM YOUR COMPLEX CODE HERE
$complexmethod_output = $whatever;
// FORMAT YOUR OUTPUT AND SEND IT ONWARDS, VIA THE PROXY
$_POST['speech'] = $complexmethod_output; // string, what will be spoken $_POST['volume'] = $whatever_volume; // integer, audio volume $_POST['format'] = $whatever_format; // 0 (mp3) or 1 (wav) $_POST['voice'] = $whatever_voice; // string, voice to choose
} // END YOUR jTalk METHOD

...and the jTalk code might look like this:

<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
extension: Array('complexmethod','variable_1','variable_2','variable_3')
}); }); </script> <a href="#" id="myelement">My Complex Custom Method</a>

top

Example Working Extension

This extended method performs a word substitution function, such as you might find in a swear filter. This could quite easily form the basics of a language extension, swapping out words for their foreign language alternatives. Watch this space.

Susan is a very naughty and silly girl!

In jtalk_methods.php:

// BEGIN YOUR jTalk METHOD
if ($_POST['extension'][0] == "swearfilter"){
// VARIABLES FROM THE jTalk JAVASCRIPT CALL
$input = $_POST['speech'];
// BAD WORD FUNCTION
function filterwords($text){
// BAD WORDS AND SUBSTITUTIONS
$badwords = array(
array('naughty','good'),
array('silly','clever')
);
// LOOP THROUGH BADWORDS
$badCount = sizeof($badwords);
for($i=0; $i<$badCount; $i++){
$text = preg_replace('/\b'.$badwords[$i][0].'\b/ie',$badwords[$i][1],$text); } return $text; } // CALL THE FUNCTION $output = filterwords($input); // FORMAT YOUR OUTPUT AND SEND IT ONWARDS, VIA THE PROXY
$_POST['speech'] = $output; // string, what will be spoken
} // END YOUR jTalk METHOD

...and the jTalk code:

<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
extension: Array('swearfilter')
}); }); </script> <a href="#" id="myelement">Susan is a very naughty and silly girl!</a>

2. Using Advanced jQuery to Extend jTalk Options (repeated)

Coupling jTalk with advanced jQuery methods can provide you with a myriad of additional methods for implementing speech on your pages. From traversing, filtering and talking anything within the DOM tree to complex regular expressions (regex) commands, it's possible to have jTalk find and speak anything on your (and other) websites.

Search Example

You can do things like this:

<a href="#" class="inline" onclick="$(this).jTalk({
usecache: true,
text:$(body).find('p:contains(\'stones\')').text().replace('.','; ') // full-stop to semi colon for pause
});">Search for the word 'stones' in the above three sentences</a>

Papa was a rolling stone.

Looking under rocks and stones.

Sticks and stones may break my bones.

Search for the word 'stones' in the above three sentences (talks only those containing it)

Talking Page Titles

How about simply reading out the title of the current webpage?

<a href="#" class="inline" onclick="$(this).jTalk({text:document.title});">title</a>

Talking Page and DOM Statistics

Want to know how many words or paragraphs on the page? How many <h2> headings, or occurences of the word jQuery? Let jTalk tell you the answer! This method could come in extremely helpful for trouble-shooting a document's source code without even looking at it!

<a href="#" class="inline" onclick="$(this).jTalk({text:$('p').size()});">Count paragraphs</a>

Image Dimensions

jTalk can tell you the dimensions of an image. Click the image below for an example.

<script type="text/javascript">
$(document).ready(function() {
$('#myelement').jTalk({
text: 'This image is '+$('#myimage').width()+' pixels wide, and '+$('#myimage').height()+' pixels high.' }); </script> <a href="#myelement"><img id="myimage" src="images/logo.gif" alt="" border="0" /></a>

top


To Do List


The jTalk API


We've now built a prototype API which accepts simple GET requests, outputs JSON responses and creates rendered audio files without the need for the jTalk plugin. This allows you to use an unlimited array of custom methods to send your speech string and then fetch and serve the audio (e.g. via a Flash MP3 widget or HTML5 element). In this sense, it could be viewed as being far more flexible than the client-side plugin itself.

Please attempt to use this method BEFORE contacting me with a request for a plugin license.

API URL (aka Speech Server)

URL: http://speech.jtalkplugin.com/api/
Server Status: UP

Call Method

The API accepts a regular HTTP GET request and returns a JSON-ified response. You can use whichever method your environment requires including AJAX, jQuery and cURL. When calling, the JSONP method must be used in order to avoid same origin policy issues.

Direct Browser Example

These links output JSON to the browser in a new window (they're on a local network, so we don't need the JSONP wrapper).

Simple example: http://speech.jtalkplugin.com/api/?speech=Hello World

Without caching: http://speech.jtalkplugin.com/api/?speech=Hello Fresh World&usecache=false

Over SSL: https://speech.jtalkplugin.com/api/?speech=Hello World

With custom output name: http://speech.jtalkplugin.com/api/?speech=Hello Again&filename=MyFileName

Note - if the audio file already exists in the cache, setting the file name may not work. This is fixed by not using a cache.

Request Parameters

Variables that can be passed to the API

* - The only required variable is speech

jQuery Example

<script type="text/javascript">
// The callback=? parameter is our jsonp callback function - required for x-domain calls
$.getJSON("http://speech.jtalkplugin.com/api/?callback=?", {speech: "Hello World", usecache: "false" },
function(json) {
	if (json.success == true){
		// Success - perform your audio operations here
		var audiofile = json.data.url;
	} else {
		// Failure
		alert("Error:" + json.msg);
	}
});
</script>>

cURL Example

// create a new cURL resource
$ch = curl_init();

// Build our querystring
$url_with_params = "http://speech.jtalkplugin.com/api/?speech=Hello World&usecache=false&format=mp3";

// Set URL and other appropriate options
curl_setopt($ch, CURLOPT_URL, $url_with_params);
curl_setopt($ch, CURLOPT_HEADER, false);

// Result of request in JSON format
$json_result = trim(curl_exec($ch));

// Optional convert back to *array*
$php_result = json_decode($json_result,true);

// Close cURL resource, and free up system resources
curl_close($ch);

Example JSON Response

  {
    "success":true,
    "msg":"Speech file successfully created",
    "data":{
	"speech":"Hello World!",
	"url":"http://speech.jtalkplugin.com/audio/1207130404280.mp3",
	"format":"MP3",
	"size":6687,
	"usecache":true,
	"samplerate":22,
	"bitrate":32,
	"striptags":true,
	"volume":1,
	"voice":"voice_nitech_us_awb_arctic_hts",
	"https":false
    }
}

Limitations

All API requests are logged (and I check them regularly). If you abuse the API, your IP address is liable to be permanently blocked.


Download jTalk


Downloads and free license keys have now been suspended indefinitely.

Up until this point, jTalk has been running within a prototype environment and demand has now far exceeded the capabilities of the speech server. In an attempt to take jTalk to the next level, a bespoke, dedicated environment is now being built. During this migration, the existing jTalk website will continue to operate - as will the plugins and the API - but jTalk will be undergoing some radical changes behind the curtain.

Changes will include:

To support this shift to a higher calibre of service, a number of volume-based commercial solutions are also being developed, with optional support packages. For further information and to be kept up-to-date with jTalk's evolution, please drop us a line at Protected email address

I'm also looking for partners, so if you're part of a business or organisation that feels as though they could help develop jTalk (i.e. primarily fund commercial development), then do please get in touch.


jTalk plugin concept and code copyright ©2010-2012 Russell McVeigh · Last updated on 17th August 2012

Valid XHTML 1.0 Transitional