Rss Categories

Compiling Grammars

Reference Number: AA-01089 Views: 12017 0 Rating/ Voters

When your speech application first begins the process of decoding audio, it sends a grammar with the audio to the Speech Engine. In order for the Engine to read the grammar, the grammar has to be compiled into a binary format that the Engine can read.

It used to be that the Engine had to load and compile its grammars each time that a grammar was used, which was time consuming and used up significant resources in the process. Grammars with thousands of words can take several seconds to compile.

If you are using a large grammar, you probably do not want to wait several seconds to load it every time your application needs to use it. This is especially true for telephony applications, where you cannot have a caller waiting while the Engine compiles a grammar.

In Speech Engine version 8.0 and later, the Engine has incorporated a feature which keeps compiled grammars in its cache automatically, allowing you to use large grammars without having to wait for them to be compiled after the very first time a grammar is loaded.

Grammars, once loaded, do not need to be compiled again if no changes have been made to them.

Understanding this process is made easier if you understand the distinction between the LumenVox client and server. The client is the application which uses our SpeechPort library — it may be a custom application you have built using our API, our own MRCP server, or a voice platform that has done an API-level integration of LumenVox.

The client loads grammars and audio and sends them in a packet to the speech server, which is the process that uses the grammar and audio to perform decodes. It is the server that needs the compiled grammar.

Because clients and servers may reside on different machines using different environments and architectures, the speech server performing the decode should ideally compile the grammar, or a machine whose LumenVox version matches that of the production ASR machine intending to use those precompiled grammars. Note that LumenVox precompiled grammars can be shared across Windows and Linux environments, as well as between 32-bit and 64-bit installation. Moving between LumenVox version releases should be avoided wherever possible, since changes to the grammar compilation process may change between releases. See our Release Notes for details of known changes.

Before the server compiles the grammar, it takes a hash of the grammar(a hash is a way to quickly create a unique identifier for a file, and if the contents of a file change even slightly, so does the hash).

The server saves the hash and compiles the grammar, writing a copy of the compiled grammar to disk.

The next time a grammar is passed to the server, the server takes a hash of the grammar and checks to see if it already has a compiled version of it in cache. If so, it uses the precompiled one, and saves itself the resources and time of compilation.

If the hashes don't match, then there has been a change to the grammar, and the Engine compiles the new one.

All of this means that there will only be a delay the first time a grammar is loaded. After that, grammar caching ensures the Engine does not recompile the same grammar.

Grammar Loader

If you wish to avoid any grammar-compilation delay in the decode process, you may pre-compile the grammars using the grammar loader tool provided with Speech Engine version 10.0 and later. This tool separates the process of compiling grammars from the decode process, allowing you to control when grammar compilation occurs.

On Windows, the tool is called GrammarLoader, and is located at


On Linux, the tool is calls lv_grammar_loader, and is located at


To use the grammar loader, specify a grammar, the IP address of a machine running the SRE, and an optional timeout value in seconds. If you run the tool without any arguments, a usage message will remind you of these arguments.

Usage: GrammarLoader <grammar-file> <server-ip> [timeout] [-o <output-file>]

Pre-loads the specified grammar and optionally generates a precompiled
grammar file at the specified output-file location

      URI or file reference of the source grammar to be
                    loaded and/or precompiled. This may be a file reference
                    or can be an HTTP reference

         Domain name or IP address of the ASR server to use when
                    loading or precompiling the specified grammar. This can
                    be a local machine or remote, as needed.

  timeout           An optional value (in seconds) to indicate the maximum
                    time to wait for the grammar to compile and load. If not
                    specified, a default value of 3600 seconds (1 hour) will
                    be used. A timeout error will occur if this time is

  -o   When the -o parameter is specified, the following parameter
                    will be interpreted as the name and location to save the
                    resulting precompiled grammar. This should be a file
                    location on the local machine, or reachable from the local
                    machine using the caller's file access permissions. Note a
                    suffix of .lvgram will be added to the output filename if
                    not specified.

Pre-Loading grammars =>> This utility can be used to load grammars onto the
specified ASR server. Typically this can be done during quiet times of the
day, so as to minimize the impact of grammar compilation during production
hours, when the ASR is busy servicing active requests. This activity is
known as 'pre-loading' grammars.

Precompiled grammars =>> Source SRGS grammars can be compiled into a portable
binary format using this utility, which avoids further compilation effort
whenever the precompiled grammar needs to be used by the ASR. Such precompiled
grammars can be produced on non-production machines if needed and then these
can be moved onto grammar servers (or the ASR server) and used by the ASR
by specifying the file or HTTP reference to it. This can help avoid unwanted
compilation delays and resource use on ASR servers, since the grammar will
already be compiled and ready to use.


This will pre-load the grammar specified on the machine onto
the ASR located on the machine, using the default timeout
value of 3600 seconds (one hour). No precompiled output file is produced.

GrammarLoader test.grxml 180

This will pre-load the test.grxml grammar onto the ASR located on the machine, using a timeout of 180 seconds (3 minutes). No
precompiled output file is produced.

GrammarLoader test.grxml -o newfile

This will pre-load the test.grxml grammar onto the ASR located on the machine, using a default timeout of 1 hour. A precompiled
grammar will be generated in the current folder, named newfile.lvgram upon
successful compilation.


If a timeout value is not given, the grammar is compiled synchronously, and the tool will return after compilation is complete or after 1 hour has passed (whichever is earlier).If a timeout is given, and the grammar compilation process takes longer than the time specified, the tool will print a message and return before grammar compilation is complete, however the compilation process will continue at the server.

If you load a grammar that has already been compiled, a success message will be printed and the tool will return immediately. In this way, you can verify that a previously submitted grammar has been compiled successfully.

Example on Windows, loading digits.gram on an SRE running on the local machine, with a timeout of 30 seconds. The grammar is compiled before the timeout is exceeded, and the success message is printed.

C:\Program Files\LumenVox\Engine\GrammarLoader digits.gram 30
Loaded grammar digits.gram successfully!
Version 11.0

Starting with LumenVox Version 11.0, a new method of generating precompiled grammars was introduced. This allows users to create portable precompiled grammars on non-production machines, or at convenient times as to minimize impact on production systems.

To utilize this mechanism, specifying the -o option followed by the name of the precompiled grammar to be generated will force the GrammarLoader utility to produce the compiled version of the specified grammar at the designated output location.

These precompiled grammars are portable, meaning they can be copied or moved to convenient file locations or HTTP grammar servers as needed, and can be loaded in the same way as raw SRGS grammars, with the exception that the compilation process will not be needed before these can be used.

Note that a similar option was also introduced to the Speech Tuner starting with LumenVox version 11.0

See the Using Precompiled Grammars article for more details on how and when to use precompiled grammars, as well as some of the benefits of using them.