swirec_preload_file

File that loads grammars during Recognizer initialization.

Value

Path of the preload file

Default

$SWISRSDK/config/SWIgrmPreload.xml

How to set

Shown in precedence order (see Rules of parameter precedence):

Set in the browser, using the Vendor-Specific-Parameters header in a RECOGNIZE or SET-PARAMS method.

If using the Management Station, set on the Nuance recognition service.

If not using Management Station, set in a Recognizer configuration file.

Usage

Set by system administrators for all applications using the recognition server.

Frequently used to avoid runtime delays (while telephone callers are waiting) for loading large grammars or non-default language models.

Typically used for systems with a single-tenant because all recognizers load the specified grammars (and most likely the grammars are not useful to other tenants).

This parameter loads grammars (and their associated language models) before application sessions begin. By default, the recognizer loads models for the default language. But if the preload file contains a grammar in a non-default language, the recognizer will load the models for that language too.

The preload file is an xml file that contains a list of grammars to be preloaded.

When using this preload feature, copy the default preload file to a system- or application-specific location, edit the file to add the desired grammars, and set this parameter to point to the file. Doing this avoids any chance of overwriting your custom version of the xml file during any future Recognizer upgrade.

Here is a sample preload file:

<?xml version="1.0"?>
 <osr_config xml:base="c:/myworkingdir/dummy.xml">
  <preload>
   <grammar uri="../grammars/elephant.grxml">
   </grammar>
  </preload>
 </osr_config>

Description of the contents of the preload file:

  • <osr_config> Required. The file begins and ends with this element.
  • xml:base=file Strongly recommended. This property defines a base path for resolving any relative paths in the list of preloaded grammars. The path must include a filename (a filename is required, but the file itself is not used and does not need to exist). By default, the base path is the location of the preload file.

    Recommendation: set the base to the application’s working directory. This enables using the same relative path for the preload file, grammar loading and activation, and having identical relative paths will simplify any needed debugging.

  • <preload> Required. Starts and ends the list of grammars to be preloaded.
  • <grammar> Each grammar has the following attributes:
    • uri: Required. Specifies the URI of the grammar. A grammar is loaded and cached using the complete URI.
    • type: Optional. Defines the media type as follows:

    Media type

    Description

    application/srgs+xml

    SRGS format.

    application/x-swi-grammar

    Nuance binary grammar format. (If the file is not in compiled binary form, Recognizer writes SWIrec_ERROR_INVALID_DATA to the diagnostic log.)

    application/x-swi-ngram+xml

    Nuance n-gram source grammar format.

    application/x-swi-parameter

    Nuance parameter grammar. For details, see Parameters set in parameter grammar files.

    application/x-swi-wordlist

    Nuance wordlist grammar. For details, see Wordlist (directory-assistance) grammars.

    NULL

    Nuance Speech Suite automatically detects the media type.

    All other values

    Writes SWIrec_ERROR_INVALID_MEDIA_TYPE to the diagnostic log.

  • Property: Optional. Sets any of the following caching properties. Because the preload feature is typically used for frequently-used grammars and large grammars that require extra time to load, Recognizer assumes the grammars are important enough to remain locked in cache to avoid future loading.

    Property

    Description

    swirec_disk_cache_lock

    Locks the grammar into the disk cache. When the system needs space, it will not remove locked grammars (even if swirec_disk_cache_size is exceeded) unless they become outdated and need to be updated. The default is 0. To lock, set to 1.

    Locking is useful, for example, for large grammars that are costly to re-load (for example, a stock quote grammar).

    In general, the purpose of locking a grammar into cache is to avoid unnecessary updates to that grammar. For this reason, consider also setting a reasonably long expiration time for the grammar (or set the inet.maxstale property via the swirec_default_loadfree_properties parameter) to prevent the grammar from expiring.

    swirec_memory_cache_lock

    Locks the grammar into the memory cache. When the system needs space, it will not remove locked grammars (even if swirec_disk_cache_size is exceeded) unless they become outdated and need to be updated. The default is 0. To lock, set to 1.

    swirec_mem_flush_on_free

    Circumvents the default cache management scheme by forcing the system to remove the grammar from memory as soon as the application frees the grammar; for example, at the end of a telephone call.

    You cannot force a flush of the disk cache, but you can prevent initial caching by using swirec_default_loadfree_properties to set the inet.maxage property to 0.

When the system administrator starts recognition servers, the servers consult the preload file and load the grammars using the complete URI. Any load errors are written to the diagnostic log file.

Sample definition in a preload file where a simple grammar definition might appear as follows:

...
<grammar uri="mygram2.xml"> </grammar>
...

Here is a complete preload file:

<?xml version="1.0"?>
 <osr_config xml:base="c:/work/dummyfile">
  <preload>
   <grammar uri="http://myuri/mygram.xml" type="application/srgs+xml">
    <property name="swirec_disk_cache_lock">
     <value>0</value>
    </property>
    <property name="swirec_language">
     <value>en-us</value>
    </property>
   </grammar>
   <grammar uri="../grammars/various/elephant.grxml">
   </grammar>
   <grammar uri="../grammars/various/dtmf_time.grxml">
    <property name="inet_timeout_io">
     <value>7500</value>
    </property>
   </grammar>
  </preload>
 </osr_config>

In the example above, note the following:

  • The mygram.xml grammar is fetched from a server via HTTP, the grammar media type is defined (this definition is used if the server does not define a media type), and the grammar is unlocked in the disk cache.
  • The elephant.grxml grammar specifies a relative path. The path is resolved as C:/grammars/various/elephant.grxml.
  • The dtmf_time.grxml grammar sets a inet timer property for file I/O.