Implementing ReadSpeaker Listen Link on Your Web Site
Below are in-page and downloadable code examples, information on CMS plug-ins, recommendations on placement of the ReadSpeaker Listen link, controlling what gets read, setting the read rate, and including links for reading of PDF files. The section ends with a discussion of known issues users and developers may confront.
If you want to test ReadSpeaker on your own site quickly, you can download all of the code and associated files for this page. The files assume you are using PHP on your web server but should be easy to modify for any environment.
Below is a block that shows the code for including the Listen link in a web page. A section describing the main parameters you will set follows the block.
<div> <a href="http://app.readspeaker.com/cgi-bin/rsent?customerid=5204&lang=en_us&speed=[speed from 0 to 200, 140 recommended]&readid=[ID of element you want read]&url=[full URL of page]&audiofilename=[file name for downloadable MP3 (optional)]" onclick="readpage(this.href, '[ID of element where you want player controls to display]'); return false;" target="_blank"> <img style="border-style: none" src="img/listen-en-us-icon.gif" alt="Listen to this section" title="Listen to this section" /><a> <div> <div id="[player controls display ID]"><div>
<div id="[ID of element you want read (container for your content)]"> [Your page content goes here.] </div>
Important parameters in query string:
customerid — The OSU customer ID must be part of each request. It is 5204
speed — Rate at which the MP3 download of the page is read. Can be any number between 0 and 200. We recommend 140 as a fast, yet understandable playback speed.
readid — The ID of the element you want read by ReadSpeaker. Element ID must be unique.
url — The full URL to the current page, e.g. http://osu.edu/resources/my-page.html.
audiofilename — File name for the MP3 of the content associated with the Listen link. This parameter is optional. If you do not include it, ReadSpeaker assigns the MP3 an arbitrary file name. You should have no spaces in your file name — use hypens or underscores to separate words.
You can have multiple Listen links on your page. Only make sure that readid parameter in the query string matches the section you want read and that this ID is unique on the page.
Placement and Appearance of ReadSpeaker Listen Link
VoiceCorp maintains a page with a large variety of ReadSpeaker Listen link images. Of course, you are welcome to customize one for your own web site, as well. It is also possible to start ReadSpeaker from a simple HTML link. We recommend using an image link, however, since it makes the functionality more obvious.
The Listen link should be close to the content and top-level heading of the page, so that there is an immediate mental link between the content and the Listen link. From user observation conducted by VoiceCorp, the best place for the Listen link is just above the page content heading, aligned to the left. An alternative is to place it to the right of the main content heading.
If you have “print”, “share”, or other utility links at the top of page main content, group the Listen link with these.
If you have a page that has multiple discrete “chunks” of content within the main content area, such as is commonly seen on blog home pages, we recommend having a listen button for each chunk or item.
Important! Make sure that the DIV for the ReadSpeaker controls is outside of the block you want read. If the controls are instantiated within the read block you will get unpredictable results when the Listen link is clicked.
Controlling Read Area
ReadSpeaker will read and highlight all content within the element specified by the read-id parameter in the query string of the call. (See source code for example.) However, you have finer-grained control within the element being read: Because we precede the following paragraph with a HTML comment of RSPEAK_STOP it does not get read.
This paragraph doesn't get read!
Speaking begins again here because it has been turned back on with a RSPEAK_START comment.
Assigning a class of rs_skip to an element also causes ReadSpeaker to ignore it. Here is an example:
ReadSpeaker ignores me!
You can include more than one listen button on a page if you want more control.
Pronunciation and the “Paul” Voice
The OSU implementation of ReadSpeaker does not recognize in-page language changes. So, though marked up correctly using the HTML lang attribute, qu'est-ce que c'est does not get read with French pronunciation. Also, currently the OSU license is for English reading only. So foreign language sites will be read with incorrect pronunciation. The Steering Committee may explore extending the set of available languages.
Developers can request corrections to ReadSpeaker's pronunciation of OSU-specific terms and vocabulary. Pronunciation tweaking must be done by VoiceCorp. The Steering Committee will work out a protocol for requesting pronunciation corrections. In the meantime, you may send pronunciation correction requests to Ken Petri (firstname.lastname@example.org).
For our first correction, we requested that the name Gordon Gee be pronounced properly. The training can differentiate between basic usages: The name Gordon Gee is pronounced differently than the phrase golly gee.
The “Paul” voice, which is the one OSU has purchased, pronounces many American English terms correctly. For example, it reads iTunes and U.S. properly.
Reading of PDF
Only text-based PDF's are voiced by ReadSpeaker. The PDF does not have to be tagged PDF. It only need be text-based. But an image-based PDF will return no audio content.
Because only one ReadSpeaker player instance can be running in a ReadSpeaker block at any one time, we advise linking to ReadSpeaker-generated MP3's of PDF's outside of the main ReadSpeaker block or ending the block before the PDF link and starting a new block (with a new Listen Button) after the PDF links.
Immediately below this paragraph is a link to a sample PDF followed by a link to a ReadSpeaker-generated MP3. To have this work properly, make sure the Listen button at the top of this page is not active/expanded.
Note: For PDF files, embedded image alternative text is not spoken.
Here is a sample code block for inserting the PDF and MP3 download link:
<a href="[PATH TO PDF FILE]">Title of My PDF (pdf)<a> <span> <a href="http://app.readspeaker.com/cgi-bin/rsent?customerid=5204&lang=en_us&speed=140&save=1&audiofilename=[DESIRED FILENAME FOR MP3 OF PDF DOWNLOAD]&url=[FULL URL TO PDF FILE]> <img style="border-style: none" src="img/listen-pdf-icon.png" alt="Download MP3 of Title of My PDF" title="Download MP3 of Title of My PDF" /><a> <span>
In testing we have discovered a couple of problems you may encounter.
The first problem is mentioned above in the discussion of PDF:
You cannot have two instances of ReadSpeaker running within a single ReadSpeaker block. If you embed a call to ReadSpeaker within a block of HTML that is already designated to be read, either the embedded block will fail to play back or you will get unpredictable page display problems.
A second problem relates to Flash movies or applications embedded in your page:
ReadSpeaker uses a Flash-based streaming audio player to voice web pages. The ReadSpeaker player does not always “play nice” with other Flash movies embedded in the web page. For example, you will notice that the simple Flash button below appears to re-load after ReadSpeaker finishes reading this section of the page.
To work around this problem, we advise that you end the area spoken by ReadSpeaker before or begin the ReadSpeaker area after any Flash movies or links to ReadSpeaker-generated PDF MP3s.