LetterToSoundImpl

java.lang.Object
- com.sun.speech.freetts.lexicon.LetterToSoundImpl

All Implemented Interfaces:

LetterToSound
```
public class LetterToSoundImpl
extends Object
implements LetterToSound
```
Provides the phone list for words using the CMU6 letter-to-sound (LTS) rules, which are based on the Black, Lenzo, and Pagel paper, "Issues in Building General Letter-to-Sound Rules." Proceedings of ECSA Workshop on Speech Synthesis, pages 77-80, Australia, 1998.
The LTS rules are a simple state machine, with one entry point for each letter of the alphabet (lower case letters are always assumed, and the rules keep an array with one entry per letter that point into the state machine).
The state machine consists of a huge array, with most entries containing a decision and the indices of two other entries. The first of these two indices represents where to go if the decision is true, and the second represents where to go if the decision is false. All entries that do not contain a decision are final entries, and these contain a phone.
The decision in this case is a simple character comparison, but it is done in the context of a window around the character in the word. The decision consists of a index into the context window and a character value. If the character in the context window matches the character value, then the decision is true.
The machine traversal for each letter starts at that letter's entry in the state machine and ends only when it reaches a final state. If there is no phone that can be mapped, the phone in the final state is set to 'epsilon.'
The context window for a character is generated in the following way:
- Pad the original word on either side with '#' and '0' characters the size of the window for the LTS rules (in this case, the window size is 4). The "#" is used to indicate the beginning and end of the word. So, the word "monkey" would turn into "000#monkey#000".
- For each character in the word, the context window consists of the characters in the padded form the preceed and follow the word. The number of characters on each side is dependent upon the window size. So, for this implementation, the context window for the 'k' in monkey is "#money#0".
Here's how the phone for 'k' in 'monkey' might be determined:
- Create the context window "#money#0".
- Start at the state machine entry for 'k' in the state machine.
- Grab the 'index' from the current state. This represents an index into the context window.
- Compare the value of the character at the index in the context window to the character from the current state. If there is a match, the next state is the qtrue value. If there isn't a match, the next state is the qfalse state.
- Keep on working through the machine until you read a final state.
- When you get to the final state, the phone is the character in that state.
This implementation will either read from a straight ASCII file or a binary file. When reading from an ASCII file, you can specify when the input line is tokenized: load, lookup, or never. If you specify 'load', the entire file will be parsed when it is loaded. If you specify 'lookup', the file will be loaded, but the parsing for each line will be delayed until it is referenced and the parsed form will be saved away. If you specify 'never', the lines will parsed each time they are referenced. The default is 'load'. To specify the load type, set the system property as follows:
```
   -Dcom.sun.speech.freetts.lexicon.LTSTokenize=load
 
```
[[[TODO: This implementation uses ASCII 'a'-'z', which is not internationalized.]]]

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`(package private) static class`	`LetterToSoundImpl.DecisionState` A `State` that represents a decision to be made.
`(package private) static class`	`LetterToSoundImpl.FinalState` A `State` that represents a final state in the state machine.
`(package private) static interface`	`LetterToSoundImpl.State` A marker interface for the states in the LTS state machine.

Field Summary

Fields
Modifier and Type	Field and Description
`private char[]`	`fval_buff` An array of characters to hold a string for checking against a rule.
`(package private) static String`	`INDEX` Entry in file represents the beginning of a new letter index.
`protected HashMap`	`letterIndex` The indexes of the starting points for letters in the state machine.
`private static int`	`MAGIC` Magic number for binary LTS files.
`private int`	`numStates` The number of states in the state machine.
`(package private) static String`	`PHONE` Entry in file represents a final state.
`private static List`	`phonemeTable` The list of phones that can be returned by the LTS rules.
`(package private) static String`	`STATE` Entry in file represents a state.
`private Object[]`	`stateMachine` The LTS state machine.
`protected boolean`	`tokenizeOnLoad` If true, the state string is tokenized when it is first read.
`protected boolean`	`tokenizeOnLookup` If true, the state string is tokenized the first time it is referenced.
`(package private) static String`	`TOTAL` Entry in file represents the total number of states in the file.
`private static int`	`VERSION` Current binary file version.
`private static int`	`WINDOW_SIZE` The 'window size' of the LTS rules.

Constructor Summary

Constructors
Constructor and Description

LetterToSoundImpl(URL ltsRules, boolean binary)
Class constructor.

Constructors
Constructor and Description
`LetterToSoundImpl(URL ltsRules, boolean binary)` Class constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`compare(LetterToSoundImpl other)` Compares this LTS to another for debugging purposes.
`void`	`dumpBinary(String path)` Dumps a binary form of the letter to sound rules.
`private List`	`findPhonemes()` Returns a list of all the phonemes used by the LTS rules.
`protected char[]`	`getFullBuff(String word)` Makes a character array that looks like "000#word#000".
`String[]`	`getPhones(String word, String partOfSpeech)` Calculates the phone list for a given word.
`protected LetterToSoundImpl.State`	`getState(int i)` Gets the `State` at the given index.
`protected LetterToSoundImpl.State`	`getState(String s)` Gets the `State` based upon the `String`.
`protected LetterToSoundImpl.State`	`getState(String type, StringTokenizer tokenizer)` Gets the `State` based upon the `type` and `tokenizer.`
`private void`	`loadBinary(InputStream is)` Loads the LTS rules from the given binary input stream.
`private void`	`loadText(InputStream is)` Loads the LTS rules from the given text input stream.
`static void`	`main(String[] args)` Translates between text and binary forms of the CMU6 LTS rules.
`protected void`	`parseAndAdd(String line)` Creates a word from the given input line and add it to the state machine.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - TOTAL
```
static final String TOTAL
```
    Entry in file represents the total number of states in the file. This should be at the top of the file. The format should be "TOTAL n" where n is an integer value.
    
    See Also:
    
    Constant Field Values
  - INDEX
```
static final String INDEX
```
    Entry in file represents the beginning of a new letter index. This should appear before the list of a new set of states for a particular letter. The format should be "INDEX n c" where n is the index into the state machine array and c is the character.
    
    See Also:
    
    Constant Field Values
  - STATE
```
static final String STATE
```
    Entry in file represents a state. The format should be "STATE i c t f" where 'i' represents an index to look at in the decision string, c is the character that should match, t is the index of the state to go to if there is a match, and f is the of the state to go to if there isn't a match.
    
    See Also:
    
    Constant Field Values
  - PHONE
```
static final String PHONE
```
    Entry in file represents a final state. The format should be "PHONE p" where p represents a phone string that comes from the phone table.
    
    See Also:
    
    Constant Field Values
  - tokenizeOnLoad
```
protected boolean tokenizeOnLoad
```
    If true, the state string is tokenized when it is first read. The side effects of this are quicker lookups, but more memory usage and a longer startup time.
  - tokenizeOnLookup
```
protected boolean tokenizeOnLookup
```
    If true, the state string is tokenized the first time it is referenced. The side effects of this are quicker lookups, but more memory usage.
  - MAGIC
```
private static final int MAGIC
```
    Magic number for binary LTS files.
    
    See Also:
    
    Constant Field Values
  - VERSION
```
private static final int VERSION
```
    Current binary file version.
    
    See Also:
    
    Constant Field Values
  - stateMachine
```
private Object[] stateMachine
```
    The LTS state machine. Entries can be String or State. An ArrayList could be used here -- I chose not to because I thought it might be quicker to avoid dealing with the dynamic resizing.
  - numStates
```
private int numStates
```
    The number of states in the state machine.
  - WINDOW_SIZE
```
private static final int WINDOW_SIZE
```
    The 'window size' of the LTS rules.
    
    See Also:
    
    Constant Field Values
  - fval_buff
```
private char[] fval_buff
```
    An array of characters to hold a string for checking against a rule. This will be reused over and over again, so the goal was just to have a single area instead of new'ing up a new one for every word. The name choice is to match that in Flite's cst_lts.c.
  - letterIndex
```
protected HashMap letterIndex
```
    The indexes of the starting points for letters in the state machine.
  - phonemeTable
```
private static List phonemeTable
```
    The list of phones that can be returned by the LTS rules.
- Constructor Detail
  - LetterToSoundImpl
```
public LetterToSoundImpl(URL ltsRules,
                         boolean binary)
                  throws IOException
```
    Class constructor.
    
    Parameters:
    
    ltsRules - a URL pointing to the text containing the letter to sound rules
    
    binary - if true, the URL is a binary source
    
    Throws:
    
    NullPointerException - if the ltsRules are null
    
    IOException - if errors are encountered while reading the compiled form or the addenda
- Method Detail
  - loadText
```
private void loadText(InputStream is)
               throws IOException
```
    Loads the LTS rules from the given text input stream. The stream is not closed after the rules are read.
    
    Parameters:
    
    is - the input stream
    
    Throws:
    
    IOException - if an error occurs on input.
  - loadBinary
```
private void loadBinary(InputStream is)
                 throws IOException
```
    Loads the LTS rules from the given binary input stream. The input stream is not closed after the rules are read.
    
    Parameters:
    
    is - the input stream
    
    Throws:
    
    IOException - if an error occurs on input.
  - parseAndAdd
```
protected void parseAndAdd(String line)
```
    Creates a word from the given input line and add it to the state machine. It expects the TOTAL line to come before any of the states.
    
    Parameters:
    
    line - the line of text from the input file
  - dumpBinary
```
public void dumpBinary(String path)
                throws IOException
```
    Dumps a binary form of the letter to sound rules. This method is not thread-safe.
    Binary format is:
```
   MAGIC
   VERSION
   NUM STATES
   for each state ...
 
```
    Parameters:
    
    path - the path to dump the file to
    
    Throws:
    
    IOException - if a problem occurs during the dump
  - findPhonemes
```
private List findPhonemes()
```
    Returns a list of all the phonemes used by the LTS rules.
    
    Returns:
    
    a list of all the phonemes
  - getState
```
protected LetterToSoundImpl.State getState(int i)
```
    Gets the State at the given index. This may replace a String at the current spot with an actual State instance.
    
    Parameters:
    
    i - the index into the state machine
    
    Returns:
    
    the State at the given index.
  - getState
```
protected LetterToSoundImpl.State getState(String s)
```
    Gets the State based upon the String.
    
    Parameters:
    
    s - the string to parse
    
    Returns:
    
    the parsed State
  - getState
```
protected LetterToSoundImpl.State getState(String type,
                                           StringTokenizer tokenizer)
```
    Gets the State based upon the type and tokenizer.
    Parameters: type - one of STATE or PHONE tokenizer - a StringTokenizer containing the State Returns: the parsed State
  getFullBuff protected char[] getFullBuff(String word) Makes a character array that looks like "000#word#000". Parameters: word - the original word Returns: the padded word getPhones public String[] getPhones(String word, String partOfSpeech) Calculates the phone list for a given word. If a phone list cannot be determined, null is returned. This particular implementation ignores the part of speech. Specified by: getPhones in interface LetterToSound Parameters: word - the word to find partOfSpeech - the part of speech. Returns: the list of phones for word or null compare public boolean compare(LetterToSoundImpl other) Compares this LTS to another for debugging purposes. Parameters: other - the other LTS to compare to Returns: true if these are equivalent main public static void main(String[] args) Translates between text and binary forms of the CMU6 LTS rules.

Class LetterToSoundImpl

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TOTAL

INDEX

STATE

PHONE

tokenizeOnLoad

tokenizeOnLookup

MAGIC

VERSION

stateMachine

numStates

WINDOW_SIZE

fval_buff

letterIndex

phonemeTable

Constructor Detail

LetterToSoundImpl

Method Detail

loadText

loadBinary

parseAndAdd

dumpBinary

findPhonemes

getState

getState

getState

getFullBuff

getPhones

compare

main