text to SpeakJet conversion tool

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

Andrew Davie

text2speakjet - English text to SpeakJet / AtariVox speech data

A small stand-alone Python tool that turns plain English into SpeakJet (AtariVox) MSA byte codes. By default the output is DASM .byte lines; it can also produce a C array, decimal text or raw binary.

It needs Python 3.8 or later and nothing else (standard library only). Unzip the attachment and keep the files together in one folder:

  • "text2speakjet.py" - the tool
  • "cmudict.dict.gz" - CMU Pronouncing Dictionary (~134,000 words)
  • "LICENSE.cmudict" - the dictionary's licence (keep it with the dictionary)
  • "exceptions.txt" - your own pronunciations, checked before the dictionary
  • "README.md" - this guide

Quick start

python3 text2speakjet.py "Welcome to WenHop"
; "Welcome to WenHop" -- 19 bytes + terminator, ~1.0s
welcome_to_wenhop
                    .byte 147, 14, 159, 195, 7, 133, 140, 4  ; WW STRESS EHLL KO FAST AX MM, pause 30ms  Welcome
                    .byte 192, 7, 139, 4                     ; TU FAST UW, pause 30ms                    to
                    .byte 147, 14, 131, 141, 184, 135, 199   ; WW STRESS EH NE HO OH PO                  WenHop
                    .byte $FF

Each word gets its own .byte line, with a comment naming its codes. The phrase ends with a $FF terminator byte (change or remove it with --terminator).

On macOS/Linux you can run chmod +x text2speakjet.py once and then run it as ./text2speakjet.py

Output formats

  • (default) - DASM .byte lines under a label
  • --format c - C array
  • --format dec - decimal bytes on one line, e.g. 192, 14, 131, 141, 255
  • --format bin - raw bytes (use -o FILE or redirect; never written to a terminal)

python3 text2speakjet.py -n phraseWellDone "Well done"
python3 text2speakjet.py --format c "Well done"
python3 text2speakjet.py --format dec "Ten, nine, eight"
python3 text2speakjet.py --format bin -o hello.bin "Hello"

The same phrase as a C array:

// "Well done" -- 8 bytes + terminator, ~0.4s
const unsigned char well_done[] = {
    147, 14, 159, 4,    // WW STRESS EHLL, pause 30ms  Well
    175, 14, 134, 141,  // DO STRESS UX NE             done
    0xFF
};

Output options:
  • -o FILE - write to a file instead of the terminal
  • -n NAME - label or array name. Without it, the name is made from the first few words of the text.
  • --terminator N - a different end byte; --terminator none leaves it off
  • --separator ' ' - separator for --format dec (default is a comma and a space)
  • --c-type TYPE - C element type (default: const unsigned char)

Many phrases at once

Put one phrase per line in a text file, as name: text

# lines starting with # are ignored
phraseGreeting: Hello there!
phraseGameOver: Game over, man. Game over.
That line has no name, so it gets one made from its text

python3 text2speakjet.py -f phrases.txt -o phrases.asm
You get one label (or array) per line. Without -f or any text, it reads the same format from stdin.

How words are turned into speech

Each word is looked up in this order:
  • exceptions.txt
  • the CMU dictionary
  • two dictionary words joined together (wenhop = wen + hop)
  • a guess from the spelling (the NRL letter-to-sound rules)

Steps 3 and 4 are guesses, so the tool prints a warning for each one:

warning: 'fnorbix' not in the dictionary -- spelling rules: F N AO1 R B IH0 K S
If the guess sounds wrong, add the word to exceptions.txt.

The pronunciation is then turned into SpeakJet allophones. The tool picks the right variant for each sound from its neighbours: front or back (KE/KO, LE/LO, NE/NO), start or end of a word (BE/EB, DO/OD), TU/TT, and the combined sounds (AWRR, EHLL, IYUW...). It also adds:

  • STRESS before each stressed vowel.
  • FAST before each unstressed vowel. Turn this off with --no-fast
  • No stress on small words like "a", "the", "to", "at" and "you". "a", "to", "for", "of", "and" and "from" use their short spoken forms.
  • Pauses between words: 30ms by default. Change it with --word-gap 0-6 (pause code) or turn it off with --word-gap none
  • Pauses for punctuation: , ; : 200ms, ... and -- 300ms, . ! ? 700ms. A pause at the very end is dropped.
  • Numbers as words: 42 is spoken "forty two", 3.5 "three point five".
Fine-tuning inside the text

Mix these into the text wherever you need them.

Control codes, in square brackets. They apply to what follows:
[pitch 96]                       Pitch, 0-255 (SpeakJet default 88)
[speed 86]                       Speed, 0-127 (default 114)
[volume 100]                     Volume, 0-127
[bend 5]                         Bend, 0-15
[fast] [slow] [stress] [relax]   apply to the next sound only
[pause 0-6] or [p0]-[p6]         0, 100, 200, 700, 30, 60, 90ms
[reset] [wait]                   Reset, Wait

A pause written in brackets replaces the normal pause between words at that point.

Raw codes, in curly brackets. They're copied in as they are:
{OHIY TT}      allophones by name
{M2}           sound effect by name (R0-R9, A0-A9, B0-B9, C0-C9, D0-D11, M0-M2)
{200 14}       plain byte values (0-254)

One word's pronunciation, in round brackets, as ARPAbet with stress digits (1 = stressed, 2 = secondary, 0 = unstressed):
I am (M EH1 L AH0 N) Husk
Example combining all three:
python3 text2speakjet.py "[pitch 100] Ten, nine [slow] eight {M2} [reset]"
If the phrase changes pitch, speed, volume or bend, a Reset (31) is added at the end automatically so later speech isn't affected. Turn that off with --no-reset

Whole-phrase options

  • --pitch N - Pitch at the start of the phrase
  • --speed N - Speed at the start of the phrase
  • --intonation BASE - Pitch raised on stressed words and falling on the last word, around BASE (BASE is optional, default 88). Adds 2 bytes per pitch change.

The exceptions file

exceptions.txt has one word per line, then its pronunciation, in one of two forms:

# ARPAbet: the tool still picks variants and adds STRESS/FAST
wenhop      W EH1 N HH AA2 P

# SpeakJet codes in curly brackets: used exactly as written
husk        {HO STRESS UX SE KO}

It ships with a few made-up names from my game as examples; replace them with your own. ARPAbet without stress digits is accepted; the tool then guesses which vowel is stressed. Lookups ignore upper/lower case. --dict FILE adds more exception files (repeatable), and --no-exceptions skips exceptions.txt

ARPAbet symbols:

Vowels: AA (hot), AE (hat), AH (but), AO (fall), AW (now), AY (bite), EH (bed), ER (bird), EY (gate), IH (sit), IY (see), OW (go), OY (boy), UH (book), UW (food)

Consonants: B, CH, D, DH (that), F, G, HH, JH (jet), K, L, M, N, NG (sing), P, R, S, SH, T, TH (thin), V, W, Y, Z, ZH (azure)

To see how the dictionary says a word, run with -v

Checking what it did

  • -v prints each word's dictionary pronunciation, the allophones chosen and where the pronunciation came from (cmudict, exceptions, GUESS...).
  • --list-codes prints every MSA code with its name and duration.
  • The duration in each header comment is an estimate from the SpeakJet manual's sound lengths, not a measurement.

Limits

  • Ordinary dictionary words come out clear and correctly stressed. Made-up words and names are guesses until you add them to exceptions.txt
  • It doesn't produce expressive pitch the way a hand-tuned phrase does. Use the [pitch N] markup (or --intonation as a starting point) for that.
  • Where a word has more than one pronunciation in the dictionary, the first one is used. Use (...) or exceptions.txt to choose another.