edu.cmu.sphinx.jsgf

Class JSGFGrammar

java.lang.Object

edu.cmu.sphinx.linguist.language.grammar.Grammar

edu.cmu.sphinx.jsgf.JSGFGrammar

All Implemented Interfaces:

GrammarInterface, Configurable

Direct Known Subclasses:

GrXMLGrammar

public class JSGFGrammar
extends Grammar

Defines a BNF-style grammar based on JSGF grammar rules in a file.

The Java Speech Grammar Format (JSGF) is a BNF-style, platform-independent, and vendor-independent textual representation of grammars for use in speech recognition. It is used by the Java Speech API (JSAPI) . Here we only intend to give a couple of examples of grammars written in JSGF, so that you can quickly learn to write your own grammars. For more examples and a complete specification of JSGF, go to http://java.sun.com/products/java-media/speech/forDevelopers/JSGF/ .

Example 1: "Hello World" in JSGF

The example below shows how a JSGF grammar that generates the sentences "Hello World":

  #JSGF V1.0
  public <helloWorld> = Hello World;
 

Figure 1: Hello grammar that generates the sentences "Hello World".

The above grammar is saved in a file called "hello.gram". It defines a public grammar rule called "helloWorld". In order for this grammar rule to be publicly accessible, we must be declared it "public". Non-public grammar rules are not visible outside of the grammar file. The location of the grammar file(s) is(are) defined by the baseGrammarURLproperty. Since all JSGF grammar files end with ".gram", it will automatically search all such files at the given URL for the grammar. The name of the grammar to search for is specified by grammarName. In this example, the grammar name is "helloWorld".

Example 2: Command Grammar in JSGF

This examples shows a grammar that generates basic control commands like "move a menu thanks please", "close file", "oh mighty computer please kindly delete menu thanks". It is the same as one of the command and control examples in the JSGF specification . It is considerably more complex than the previous example. It defines the public grammar called "basicCmd".

  #JSGF V1.0
  public <basicCmd> = <startPolite> <command> <endPolite>;
  <command> = <action> <object>;
  <action> = /10/ open |/2/ close |/1/ delete |/1/ move;
  <object> = [the | a] (window | file | menu);
  <startPolite> = (please | kindly | could you | oh mighty computer) *;
  <endPolite> = [ please | thanks | thank you ];
 

Figure 2: Command grammar that generates simple control commands.

The features of JSGF that are shown in this example includes:

• using other grammar rules within a grammar rule.
• the OR "|" operator.
• the grouping "(...)" operator.
• the optional grouping "[...]" operator.
• the zero-or-many "*" (called Kleene star) operator.
• a probability (e.g., "open" is more likely than the others).

From JSGF to Grammar Graph

After the JSGF grammar is read in, it is converted to a graph of words representing the grammar. Lets call this the grammar graph. It is from this grammar graph that the eventual search structure used for speech recognition is built. Below, we show the grammar graphs created from the above JSGF grammars. The nodes "<sil>" means "silence".

Figure 3: Grammar graph created from the Hello World grammar.

Figure 4: Grammar graph created from the Command grammar.

Limitations

There is a known limitation with the current JSGF support. Grammars that contain non-speech loops currently cause the recognizer to hang.

For example, in the following grammar

  #JSGF V1.0
  grammar jsgf.nastygram;
  public <nasty> = I saw a ((cat* | dog* | mouse*)+)+;
 

the production: ((cat* | dog* | mouse*)+)+ can result in a continuous loop, since (cat* | dog* | mouse*) can represent no speech (i.e. zero cats, dogs and mice), this is equivalent to ()+. To avoid this problem, the grammar writer should ensure that there are no rules that could possibly match no speech within a plus operator or kleene star operator.

Dynamic grammar behavior

It is possible to modify the grammar of a running application. Some rules and notes:

• Unlike a JSAPI recognizer, the JSGF Grammar only maintains one Rule Grammar. This restriction may be relaxed in the future.
• The grammar should not be modified while a recognition is in process
• The call to JSGFGrammar.loadJSGF will load in a completely new grammar, tossing any old grammars or changes. No call to commitChanges is necessary (although such a call would be harmless in this situation).
• RuleGrammars can be modified via calls to RuleGrammar.setEnabled and RuleGrammar.setRule). In order for these changes to take place, JSGFGrammar.commitChanges must be called after all grammar changes have been made.

Implementation Notes

1. All internal probabilities are maintained in LogMath log base.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.net.URL	baseURL
protected GrammarNode	firstNode
protected boolean	loadGrammar
protected java.util.logging.Logger	logger
protected JSGFRuleGrammarManager	manager
static java.lang.String	PROP_BASE_GRAMMAR_URL The property that defines the location of the JSGF grammar file.
static java.lang.String	PROP_GRAMMAR_NAME The property that defines the location of the JSGF grammar file.
protected edu.cmu.sphinx.jsgf.JSGFGrammar.RuleStack	ruleStack

Fields inherited from class edu.cmu.sphinx.linguist.language.grammar.Grammar

dictionary, initialNode, PROP_ADD_FILLER_WORDS, PROP_ADD_SIL_WORDS, PROP_DICTIONARY, PROP_OPTIMIZE_GRAMMAR, PROP_SHOW_GRAMMAR

Constructor Summary

Constructors

Constructor and Description
JSGFGrammar()
JSGFGrammar(java.lang.String location, java.lang.String grammarName, boolean showGrammar, boolean optimizeGrammar, boolean addSilenceWords, boolean addFillerWords, Dictionary dictionary)
JSGFGrammar(java.net.URL baseURL, java.lang.String grammarName, boolean showGrammar, boolean optimizeGrammar, boolean addSilenceWords, boolean addFillerWords, Dictionary dictionary)

Method Summary

Modifier and Type	Method and Description
void	commitChanges() Commit changes to all loaded grammars and all changes of grammar since the last commitChange
protected GrammarNode	createGrammar() Creates the grammar.
protected void	dumpGrammar() Dumps interesting things about this grammar
JSGFRuleGrammarManager	getGrammarManager() Returns manager used to load grammars
java.lang.String	getGrammarName()
GrammarNode	getInitialNode() Returns the initial node for the grammar
JSGFRuleGrammar	getRuleGrammar() Returns the RuleGrammar of this JSGFGrammar.
void	loadJSGF(java.lang.String grammarName) The JSGF grammar specified by grammarName will be loaded from the base URL (tossing out any previously loaded grammars)
void	newProperties(PropertySheet ps) This method is called when this configurable component needs to be reconfigured.
protected edu.cmu.sphinx.jsgf.JSGFGrammar.GrammarGraph	processRule(JSGFRule rule) Parses the given Rule into a network of GrammarNodes.
void	setBaseURL(java.net.URL url) Sets the URL context of the JSGF grammars.

Methods inherited from class edu.cmu.sphinx.linguist.language.grammar.Grammar

allocate, createGrammar, createGrammarNode, createGrammarNode, createGrammarNode, createGrammarNode, createGrammarNode, deallocate, dumpGrammar, dumpRandomSentences, dumpRandomSentences, dumpStatistics, getDictionary, getGrammarNodes, getNumNodes, getRandomSentence, newGrammar, postProcessGrammar

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROP_BASE_GRAMMAR_URL

@S4String
public static final java.lang.String PROP_BASE_GRAMMAR_URL

The property that defines the location of the JSGF grammar file.

See Also:

Constant Field Values

PROP_GRAMMAR_NAME

@S4String(defaultValue="default.gram")
public static final java.lang.String PROP_GRAMMAR_NAME

The property that defines the location of the JSGF grammar file.

See Also:

Constant Field Values

manager

protected JSGFRuleGrammarManager manager

ruleStack

protected edu.cmu.sphinx.jsgf.JSGFGrammar.RuleStack ruleStack

baseURL

protected java.net.URL baseURL

loadGrammar

protected boolean loadGrammar

firstNode

protected GrammarNode firstNode

logger

protected java.util.logging.Logger logger

Constructor Detail

JSGFGrammar

public JSGFGrammar(java.lang.String location,
                   java.lang.String grammarName,
                   boolean showGrammar,
                   boolean optimizeGrammar,
                   boolean addSilenceWords,
                   boolean addFillerWords,
                   Dictionary dictionary)
            throws java.net.MalformedURLException,
                   java.lang.ClassNotFoundException

Throws:

java.net.MalformedURLException

java.lang.ClassNotFoundException

JSGFGrammar

public JSGFGrammar(java.net.URL baseURL,
                   java.lang.String grammarName,
                   boolean showGrammar,
                   boolean optimizeGrammar,
                   boolean addSilenceWords,
                   boolean addFillerWords,
                   Dictionary dictionary)

JSGFGrammar

public JSGFGrammar()

Method Detail

newProperties

public void newProperties(PropertySheet ps)
                   throws PropertyException

Description copied from interface: Configurable

This method is called when this configurable component needs to be reconfigured.

Specified by:

newProperties in interface Configurable

Overrides:

newProperties in class Grammar

Parameters:

ps - a property sheet holding the new data

Throws:

PropertyException - if there is a problem with the properties.

getRuleGrammar

public JSGFRuleGrammar getRuleGrammar()

Returns the RuleGrammar of this JSGFGrammar.

Returns:

the RuleGrammar

getGrammarManager

public JSGFRuleGrammarManager getGrammarManager()

Returns manager used to load grammars

Returns:

manager with loaded grammars

setBaseURL

public void setBaseURL(java.net.URL url)

Sets the URL context of the JSGF grammars.

Parameters:

url - the URL context of the grammars

getGrammarName

public java.lang.String getGrammarName()

Returns:

the name of this grammar.

loadJSGF

public void loadJSGF(java.lang.String grammarName)
              throws java.io.IOException,
                     JSGFGrammarParseException,
                     JSGFGrammarException

The JSGF grammar specified by grammarName will be loaded from the base URL (tossing out any previously loaded grammars)

Parameters:

grammarName - the name of the grammar

Throws:

java.io.IOException - if an error occurs while loading or compiling the grammar

JSGFGrammarException - other grammar exception

JSGFGrammarParseException - failed to parse grammar file

createGrammar

protected GrammarNode createGrammar()
                             throws java.io.IOException

Creates the grammar.

Specified by:

createGrammar in class Grammar

Returns:

the initial node of the Grammar

Throws:

java.io.IOException - if the grammar could not be loaded

getInitialNode

public GrammarNode getInitialNode()

Returns the initial node for the grammar

Specified by:

getInitialNode in interface GrammarInterface

Overrides:

getInitialNode in class Grammar

Returns:

the initial grammar node

processRule

protected edu.cmu.sphinx.jsgf.JSGFGrammar.GrammarGraph processRule(JSGFRule rule)
                                                            throws JSGFGrammarException

Parses the given Rule into a network of GrammarNodes.

Parameters:

rule - the Rule to parse

Returns:

a grammar graph

Throws:

JSGFGrammarException - exception during parse

commitChanges

public void commitChanges()
                   throws java.io.IOException,
                          JSGFGrammarParseException,
                          JSGFGrammarException

Commit changes to all loaded grammars and all changes of grammar since the last commitChange

Throws:

JSGFGrammarParseException - parse exception occurred

JSGFGrammarException - other exception occurred

java.io.IOException - exception during IO

dumpGrammar

protected void dumpGrammar()

Dumps interesting things about this grammar