Recognizer DEFINE-GRAMMAR
The DEFINE-GRAMMAR method, sent from the client to the server, supplies one or more grammars and instructs the server to define them—downloading any that are referenced remotely and compiling each one. Defining grammars ahead of time lets the server do this work before recognition begins, so it is not paid for on the critical path of a later RECOGNIZE request.
If the recognizer resource for the session is idle and is able to load and compile the grammar, the method returns a COMPLETE response with a Status-Code indicating success.
If the recognizer cannot define the grammar—for example, the download failed, the grammar failed to compile, or it was supplied in an unsupported form—the response carries a 407 failure status code together with a Completion-Cause header field describing the reason.
Ways to specify a grammar
MRCP offers several ways to specify or reference a grammar in a DEFINE-GRAMMAR request; the full set is described in the MRCPv1 and MRCPv2 specifications. The methods supported by Capacity Private Cloud are summarized below. The type of reference in use is indicated by the Content-Type header of the request.
Inline XML grammars (GrXML)
With an inline XML-based SRGS (GrXML) grammar, the grammar text is embedded directly in the request body. In MRCPv1 the Content-Type is application/grammar+xml:
| C->S:DEFINE-GRAMMAR 543258 MRCP/1.0 Content-Type:application/grammar+xml Content-Id:helpgrammar@root-level.store Content-Length:104 <?xml version="1.0"?> <!-- the default grammar language is US English --> <grammar xml:lang="en-US" version="1.0"> <rule id="request"> I need help </rule> </grammar> S->C:MRCP/1.0 543258 200 COMPLETE Completion-Cause:000 success |
In MRCPv2 the same inline grammar uses the Content-Type application/srgs+xml:
| C->S:MRCP/2.0 ... DEFINE-GRAMMAR 543258 Channel-Identifier:32AECB23433801@speechrecog Content-Type:application/srgs+xml Content-ID:<helpgrammar@root-level.store> Content-Length:... <?xml version="1.0"?> <!-- the default grammar language is US English --> <grammar xmlns="http://www.w3.org/2001/06/grammar" xml:lang="en-US" version="1.0"> <rule id="request"> I need help </rule> </grammar> S->C:MRCP/2.0 ... 543258 200 COMPLETE Channel-Identifier:32AECB23433801@speechrecog Completion-Cause:000 success |
Inline ABNF grammars
An inline ABNF-style SRGS grammar likewise embeds the grammar text in the request body. In MRCPv1 the Content-Type is application/grammar:
| C->S:DEFINE-GRAMMAR 543259 MRCP/1.0 Content-Type:application/grammar Content-Id:helpgrammar@root-level.store Content-Length:... #ABNF 1.0; //// the default grammar language is US English //// language en-US; //////////////////////////////////////////////////// $request = I need help ; S->C:MRCP/1.0 543259 200 COMPLETE Completion-Cause:000 success |
In MRCPv2 the Content-Type for inline ABNF is application/srgs:
| C->S:MRCP/2.0 ... DEFINE-GRAMMAR 543259 Channel-Identifier:32AECB23433801@speechrecog Content-Type:application/srgs Content-ID:<helpgrammar@root-level.store> Content-Length:... #ABNF 1.0; //// the default grammar language is US English //// language en-US; //////////////////////////////////////////////////// $request = I need help ; S->C:MRCP/2.0 ... 543259 200 COMPLETE Channel-Identifier:32AECB23433801@speechrecog Completion-Cause:000 success |
Fetching grammars from a URI
Grammars hosted on an HTTP or file server—local or remote—can be referenced with the text/uri-list Content-Type. This works the same way in both MRCPv1 and MRCPv2.
MRCPv1
| C->S:DEFINE-GRAMMAR 543260 MRCP/1.0 Content-Type:text/uri-list Content-Id:helpgrammar@root-level.store Content-Length:... session:help@root-level.store http://www.example.com/Directory-Name-List.grxml http://www.example.com/Department-List.grxml http://www.example.com/TAC-Contact-List.grxml session:menu1@menu-level.store S->C:MRCP/1.0 543260 200 COMPLETE Completion-Cause:000 success |
MRCPv2
| C->S:MRCP/2.0 ... DEFINE-GRAMMAR 543260 Channel-Identifier:32AECB23433801@speechrecog Content-Type:text/uri-list Content-ID:<helpgrammar@root-level.store> Content-Length:... session:help@root-level.store http://www.example.com/Directory-Name-List.grxml http://www.example.com/Department-List.grxml http://www.example.com/TAC-Contact-List.grxml session:menu1@menu-level.store S->C:MRCP/2.0 ... 543260 200 COMPLETE Channel-Identifier:32AECB23433801@speechrecog Completion-Cause:000 success |
Mixing inline and URI references
To combine inline grammars and URI references in a single request, use the multipart/mixed Content-Type. Within the multipart block, MRCPv1 may carry text/uri-list, application/grammar, or application/grammar+xml parts; MRCPv2 may carry text/uri-list, application/srgs, or application/srgs+xml parts.
MRCPv1
| C->S:DEFINE-GRAMMAR 543263 MRCP/1.0 Content-Type:multipart/mixed; boundary="break" Content-Length:... --break Content-Type:text/uri-list Content-Length:... http://www.example.com/Directory-Name-List.grxml http://www.example.com/Department-List.grxml http://www.example.com/TAC-Contact-List.grxml --break Content-Type:application/grammar+xml Content-ID:<request1@form-level.store> Content-Length:... <?xml version="1.0"?> <!-- the default grammar language is US English --> <grammar xml:lang="en-US" version="1.0"> <rule id="request"> I need help </rule> </grammar> --break-- S->C:MRCP/1.0 543263 200 COMPLETE Completion-Cause:000 success |
MRCPv2
| C->S:MRCP/2.0 ... DEFINE-GRAMMAR 543263 Channel-Identifier:32AECB23433801@speechrecog Content-Type:multipart/mixed; boundary="break" Content-Length:... --break Content-Type:text/uri-list Content-Length:... http://www.example.com/Directory-Name-List.grxml http://www.example.com/Department-List.grxml http://www.example.com/TAC-Contact-List.grxml --break Content-Type:application/srgs+xml Content-ID:<request1@form-level.store> Content-Length:... <?xml version="1.0"?> <!-- the default grammar language is US English --> <grammar xml:lang="en-US" version="1.0"> <rule id="request"> I need help </rule> </grammar> --break-- S->C:MRCP/2.0 ... 543263 200 COMPLETE Channel-Identifier:32AECB23433801@speechrecog Completion-Cause:000 success |
Reference list with weights
The text/grammar-ref-list Content-Type is similar to text/uri-list but lets you assign a weight to each referenced grammar. Although this media type is not part of the MRCPv1 specification, Capacity Private Cloud supports it under both MRCPv1 and MRCPv2.
MRCPv1
| C->S:DEFINE-GRAMMAR 543264 MRCP/1.0 Content-Type:text/grammar-ref-list Content-Id:helpgrammar@root-level.store Content-Length:... <http://example.com/grammars/field1.gram> <http://example.com/grammars/field2.gram>;weight="0.85" <session:field3@form-level.store>;weight="0.9" <http://example.com/grammars/universals.gram>;weight="0.75" S->C:MRCP/1.0 543264 200 COMPLETE Completion-Cause:000 success |
MRCPv2
| C->S:MRCP/2.0 ... DEFINE-GRAMMAR 543264 Channel-Identifier:32AECB23433801@speechrecog Content-Type:text/grammar-ref-list Content-ID:<helpgrammar@root-level.store> Content-Length:... <http://example.com/grammars/field1.gram> <http://example.com/grammars/field2.gram>;weight="0.85" <session:field3@form-level.store>;weight="0.9" <http://example.com/grammars/universals.gram>;weight="0.75" S->C:MRCP/2.0 ... 543264 200 COMPLETE Channel-Identifier:32AECB23433801@speechrecog Completion-Cause:000 success |