SpeakJet
SpeakJet library for Arduino

This is the Arduino SpeakJet library. It provides an object-oriented class for driving a SpeakJet http://www.sparkfun.com/datasheets/Components/General/speakjet-usermanual.pdf speech synthesizer chip, such as installed on SparkFun VoiceBox shield https://www.sparkfun.com/products/10661

It supports speaking of:

The version of the package that this documentation refers to can be downloaded from http://www.airspayce.com/mikem/arduino/SpeakJet/SpeakJet-1.4.zip You can find the latest version at http://www.airspayce.com/mikem/arduino/SpeakJet

Tested with SparkFun VoiceBox on Uno, Duemilanove, Diecimila, Mega. Tested with Arduino 0021 and 1.0.2

Electrical connection to the SpeakJet

The connection to the SpeakJet chip requires 3 digital pins:

Naturally, ground and 5V are also required to supply the chip.

The SpeakJet library uses SoftwareSerial to send Serial commands at 9600 baud to the SpeakJet chip, using any of the Arduino Digital output pins. The default is pin D2. No serial data is read from the SpeakJet chip.

The SpeakJet constructor is where you specify the Arduino digital pins to use for each of these functions. The default values work with a standard SparkFun VoideBox shield https://www.sparkfun.com/products/10661

Dictionaries

The SpeakJet library comes with a standard dictionary of approximately 1400 words, phrases and sound effects. The functions speakWord() and speakWords() speak sound effects and words from this dictionary. It is based on the PhraseALator.Dic dictionary file provided by SpeakJet, but converted to a 'C' structure for use by this SpeakJet library (see standardDict.cpp).

Alternatively you can create your own dictionary (either as a subset of the standard dictionary, or from scratch with your own words, or a combination of the two) and use speakWordfromDictionary() and speakWordsfromDictionary().

The included convertDict.pl perl script reads one or more dictionary files in the same format as PhraseALator.Dic and emits a 'C' file suitable for including in a header file or a .c or .cpp file.

Also included is a smaller dictionary (numericDict.cpp) that includes mostly only numbers, and is used to speak integers and digits with speakNumber() and speakDigits().

In SpeakJet, a Dictionary is an array of DictionaryItem structures, terminated by an empty DictionaryItem. You can build these by hand in your sketch, or you can rely on convertDict to create them from a text .dic file. In any case, it is essential that the Dictionary, and all the words and code sequences it points to are in PROGMEN. This will save you RAM.

The standard dictionary and it set of 1400 or so words occupies about 30kbytes of Flash program memory. This is far biger than some Arduinos can handle, and is quite close to the total permissable program size for say the Arduino Uno. Fortunately the standard dictionary is only linked if you use speakWord() or speakWords().

The supplied standard and numeric dicitonaries only support English, but you could contruct your own dictionaries to support other languages.

convertDict.pl

This support script is used to convert text dictionary files into 'C' structures suitable for including in sketches or other C program files. It is used to create the numericDict.cpp and standardDict.cpp header files that are shippped with the SpeakJet library, but you can use to to create your own dictionary header files.

Command line arguments can be used to control the C variable name of the dictionary, so you can have several different dictionaries in your sketch. It can be used to creat a single dictionary out of one or more dictionary text files.

Caution: while the .dic file format permits words to be defined in terms of other words, this is not supported by convertDict.pl. Any word defintion that is not in terms of basic phonemes is flagged as an error and is not added to the dictionary structure. This is mainly to avoid the fx* words int the PhraseALator.Dic file being included in the standard dictionary and blowing the size out to more that 32 k.

The format of the input dictionary files is: [words] word=\PH \PH \PH \PH .... where 'word' is the ASCII text of the word to be spoken, and \PH \PH ... is a sequence of standard phoneme mnemonics or control codes that will be used to speak the word.

convertDict.pl will automatically append the EndOfPhrase byte required by every DictionaryEntry code array.

Examples.

A number of example sketches and a test suite illustrating the use of the public functions in SpeakJet is included.

Installation

Install in the usual way: unzip the distribution zip file to the libraries sub-folder of your sketchbook.

This software is Copyright (C) 2011 Mike McCauley. Use is subject to license conditions. The main licensing options available are GPL V2 or Commercial:

Open Source Licensing GPL V2

This is the appropriate option if you want to share the source code of your application with everyone you distribute it to, and you also want to give them the right to share who uses it. If you wish to use this software under Open Source Licensing, you must contribute all your source code to the open source community in accordance with the GPL Version 2 when your application is distributed. See http://www.gnu.org/copyleft/gpl.html

Commercial Licensing

This is the appropriate option if you are creating proprietary applications and you are not prepared to distribute and share the source code of your application. Contact info@.nosp@m.airs.nosp@m.payce.nosp@m..com for details.

Revision History
Version:
1.0 Initial release
1.1 Improve documentation
1.3 Now Compiles amd runs with Arduino 0021. Added more documentation. Constructor invertPin argument removed (not available before Arduino 1.0)
1.4 Updated author and distribution location details to airspayce.com