Story Talker
version 0.1.0.0

Contents

About Story Talker

Story Talker is a free, open-source GUI frontend to the Festival Text-to-speech Synthesis engine. It is designed for speaking long plain text or HTML files, such as e-books and web articles. It is not intended as a general-purpose screen reader and does not target the blind. Story Talker enhances Festival by offering pause and resume of spoken text. It will automatically bookmark the last sentence spoken so that you may later restart speaking from the bookmark. Story Talker was developed for Linux, but may run under any platform that can run Python, wxPython, and Festival (not tested).

Copyright and License

Story Talker is copyright 2003 by Gary Cramblitt.

Contact garycramblitt at comcast dot net.

Story Talker is licensed under the GNU General Public License. A copy of the license is included with the software in file gpl-license. Portions of the code (pexpect.py and Python libraries) are licensed under the Python Software Foundation License.

Requirements and Installation

Story Talker requires:

First make sure you have Festival installed and working correctly on your system. You will probably find a suitable binary version of Festival on your Linux distribution CDs, or you can download a copy of the source code from The Centre for Speech Technology Research at the University of Edinburgh.

When you have Festival installed, make sure that it speaks text files correctly by typing the following commands in a console window.

        festival
        (SayText "hello world")

Press Ctrl-D to exit Festival.

Most Linux distributions come with Python. If not, you can obtain a copy at www.python.org. To check your version of Python simply type

        python

in any terminal window. The Python version is displayed in the Python startup banner. To check if you have wxPython installed, type

        from wxPython.wx import *

at the Python prompt. If no error is displayed, you have wxPython installed. To check the version of wxPython, type

        print wx.__version__

The version should be 2.4.0.7 or greater. If you don't have wxPython installed or don't have the correct version, you can obtain it from www.wxpython.org.

If you want to be able to speak web pages (HTML), download and install the html2text utility following the instructions in the INSTALL file that comes with that package.

Download the latest version of Story Talker from sourceforge.net/projects/storytalker. Unpack the file to any convenient folder. For example,

        tar -xfvz storytalker-0.1.0.0.tar.gz /usr/share/storytalker

To permit you to right-click on a file in KDE Konqueror and send it to StoryTalker, create a file called storytalker.desktop containing

[Desktop Entry]
Comment=
InitialPreference=3
ServiceTypes=text/plain,text/html
MimeType=text/plain;text/html
Actions=storytalker
X-KDE-Submenu=Speak

[Desktop Action storytalker]
Name=Speak via StoryTalker
Icon=unknown
Exec=/usr/share/storytalker/storytalker.py
Terminal=false
Type=Application

Substitute the path where you installed Story Talker for the Exec parameter. Copy this file to the /share/apps/konqueror/servicemenus directory in your KDEHOME. For most users, this means to copy the file to ~/.kde/share/apps/konqueror/servicemenus.

Uninstallation

To remove Story Talker from your system, delete the folder you unpacked it to when you installed Story Talker. For example,

        rm -Rf /usr/share/storytalker

Also delete the storytalker folder in your home folder, for example

        rm -Rf ~/storytalker

Getting Started

Assuming you have your windowing GUI running, type the following command to start Story Talker:

        python /usr/share/storytalker/storytalker.py

The main Story Talker screen appears.

Story Talker main screen

To speak a file, click File on the main menu, then Open. Locate a file you wish to speak and click OK button.

To speak a web page on the Internet, click File on the main menu, then Open URL. Enter the web page address and click OK. Story Talker will retrieve the web page from the Internet to a local temporary file, then convert it to plain text using the html2text utility.

Story Talker will begin speaking the file, while simultaneously displaying and highlighting the spoken text on the screen. Use the toolbar to control speaking.

When you pause speaking, then exit from Story Talker, it will remember the last spoken sentence position in the file. If you later open the same file in Story Talker, it will begin speaking from that remembered position. This is just like placing a bookmark into a paper book to remember where you were in the book. By default, Story Talker will remember up to 10 such bookmarks, but you can increase this in the preferences screen explained below.

The status bar at the bottom of the main screen displays the latest operation performed by Story Talker. Click anywhere on the status bar to display a log, which may be useful for debugging.

You can customize Story Talker's behaviour using the Preferences screen. To change your preferences, click File on the menu, then click Preferences.

general preferences screen

There are three tabs of preferences. On the General tab, you may specify the following preferences.

On the Filter Commands tab, you may specify Filters that convert any desired file into plain text for speaking.

filter commands preferences screen

When you open a file, Story Talker asks the operating system for the MIME type of the file. If the returned MIME type matches the first column of the grid you see here, then the opened file is passed to the Filter given in the second column, with command-line arguments specified in the third column. To add a new filter, click the Add Mime Type button. A blank row is added to the grid. Enter a MIME type, Filter command, and arguments in the new row. To delete a Filter, click a row of the grid, then click the Delete Filter button.

Important: Before clicking the OK button, if you made any edits to a cell of the grid, click another cell of the grid in order to save the changes.

The Recent Files tab allows you delete bookmarks.

recent files preferences screen

Click a row of the grid and click the Delete button. You can also specify the maximum number of bookmarks that Story Talker will keep.

Command-line Arguments

You may specify any file name or internet URL on the command line when starting Story Talker. When specifying a URL, it must begin with "http:". For example,

        python /home/share/usr/storytalker.py http://developer.kde.org

If a URL is specified, Story Talker will retrieve the web page from the Internet and convert it to plain text in a temporary local file. It will then begin speaking the file.

Future

It is expected that in the near future (perhaps 2004), Story Talker will become obsolete. Both the KDE and Gnome projects are developing similar capabilities to Story Talker. Since KDE and Gnome will integrate this capability directly into the desktop, their solutions will offer a more reliable, flexible user experience. Story Talker fulfills a need today (late 2003) until these capabilities are available.

Credits

Python by the Python project.

wxPython by Robin Dunn and the wxPython project team.

Festival by The Centre for Speech Technology Research at the University of Edinburgh.

pexpect.py module by Noah Spurrier.

html2text by Arno Unkrig and Martin Bayer.

Design Notes

This section is targeted towards programmers working on Story Talker.

Basic Architecture

Story Talker may be likened to a media player, such as MPlayer, or Xine, except instead of playing binary media files, it "plays" or speaks text files. The user may specify a file on the command line or open a file from the Story Talker GUI. If the file name is an Internet URL, the webpage is retrieved to a temporary local file. The operating system is queried to determine the MIME type of the file. (If no MIME type is returned by the operating system, and a URL was opened, then "text/html" is assumed.) If any Filters have been specified for the MIME type, then the file is passed to the Filter, along with a temporary file name. The Filter is expected to convert the file to plain Jane text and write it to the specified temporary file. When the Filter exits, Story Talker starts Festival as a piped subprocess. It begins parsing the text file, looking for end-of-sentence delimiters. By default, this is a period followed by one or more whitespace, or two newlines in a row, but users may configure a regular expression which is used to find the end-of-sentence delimiters. Each sentence is passed to the Festival subprocess via a pipe using the Festival "SayText" function.

If the user pauses or stops speaking by clicking a button on the toolbar, Story Talker stops parsing the input file. By default, Festival will continue speaking the entire last sentence sent to it, but the user can configure Story Talker to stop speaking immediately by killing (SIGKILL) the Festival subprocess. If this is the case, Story Talker will restart Festival when resuming speaking.

The Filter architecture of Story Talker is largely inspired by The Art of Unix Programming by Eric Steven Raymond. Eric is the author of the famous The Cathedral and the Bazaar. The Art of Unix Programming should be mandatory reading by any *nix programmer.

Thus, hardwiring policy and mechanism together has two bad effects; it makes policy rigid and harder to change in response to user requirements, and it means that trying to change policy has a strong tendency to destabilize the mechanisms.

On the other hand, by separating the two we make it possible to experiment with new policy without breaking mechanisms. We also make it much easier to write good tests for the mechanism (policy, because it ages so quickly, often does not justify the investment).

This design rule has wide application outside of the GUI context. In general, it implies that we should look for ways to separate interfaces from engines.


- Eric Steven Raymond
- The Art of Unix Programming

Story Talker applies this principle by separating the GUI interface from Filters. Filters convert files to plain text for input to Story Talker.

Story Talker currently comes with a filter to convert HTML files to plain text.

Filters run as separate subprocesses. The commands to run Filters can be configured in the GUI preferences. This allows Story Talker to be easily extended to handle data of almost any format by writing a new Filter, in any suitable programming language. Some possible Filters that could be written are:

When the Story Talker GUI launches a Filter, it passes three pieces of information to the Filter subprocess via the command line:

Story Talker waits for the Filter subprocess to exit before speaking the plain text file.

Preferences

The Story Talker GUI maintains an in-memory dictionary of user preferences (self.prefs{}), which defaults to the following:

{'BufLen': 1024,
 'FilterAgents': {'text/html': {'Args': '-rcfile "%phtml2speaktext" -o "%t" -nobs "%f"',
                                'Cmd': 'html2text'}},
 'KillToStopTalking': 0,
 'LogSayText': 0,
 'MaxRecentFiles': 10,
 'PollInterval': 500,
 'RecentFiles': {},
 'SentenceRe': '([\\.\\?\\:\\;]\\s)|(\\n\\n)',
 'SpeakWelcome': 1}

When Story Talker exits normally, the preferences dictionary is written to file ~/storytalker/storytalker.cfg. This file is also read when Story Talker starts.

Generously hosted by SourceForge.net
SourceForge.net Logo