Failure(4XX) codes.
5.2.1.1. Success 2xx
200 Success
201 Success with some optional parameters ignored.
5.2.1.2. Failure 4xx
401 Method not allowed
402 Method not valid in this state
403 Unsupported Parameter
404 Illegal Value for Parameter
405 Not found (e.g., Resource URI not initialized
or doesn’t exist)
406 Mandatory Parameter Missing
407 Method or Operation Failed (e.g., Grammar compilation
failed in the recognizer. Detailed cause codes MAY BE
available through a resource specific header field.)
408 Unrecognized or unsupported message entity
409 Unsupported Parameter Value
421-499 Resource specific Failure codes
5.3. Event
The server resource may need to communicate a change in state or the
occurrence of a certain event to the client. These messages are used
when a request does not complete immediately and the response returns
a status of PENDING or IN-PROGRESS. The intermediate results and
events of the request are indicated to the client through the event
message from the server. Events have the request-id of the request
that is in progress and is generating these events and status value.
The status value is COMPLETE if the request is done and this was the
last event, else it is IN-PROGRESS.
event-line = event-name SP request-id SP request-state SP
mrcp-version CRLF
The mrcp-version used here is identical to the one used in the
Request/Response Line and indicates the version of MRCP protocol
running on the server.
The request-id used in the event should match the one sent in the
request that caused this event.
The request-state indicates if the Request/Command causing this event
is complete or still in progress, and is the same as the one
mentioned in Section 5.2. The final event will contain a COMPLETE
status indicating the completion of the request.
The event-name identifies the nature of the event generated by the
media resource. The set of valid event names are dependent on the
resource generating it, and will be addressed in later sections.
event-name = synthesizer-event
/ recognizer-event
5.4. Message Headers
MRCP header fields, which include general-header (Section 5.4) and
resource-specific-header (Sections 7.4 and 8.4), follow the same
generic format as that given in Section 2.1 of RFC 2822 [7]. Each
header field consists of a name followed by a colon (":") and the
field value. Field names are case-insensitive. The field value MAY
be preceded by any amount of linear whitespace (LWS), though a single
SP is preferred. Header fields can be extended over multiple lines
by preceding each extra line with at least one SP or HT.
message-header = 1*(generic-header / resource-header)
The order in which header fields with differing field names are
received is not significant. However, it is "good practice" to send
general-header fields first, followed by request-header or response-
header fields, and ending with the entity-header fields.
Multiple message-header fields with the same field-name MAY be
present in a message if and only if the entire field value for that
header field is defined as a comma-separated list (i.e., #(values)).
It MUST be possible to combine the multiple header fields into one
"field-name:field-value" pair, without changing the semantics of the
message, by appending each subsequent field-value to the first, each
separated by a comma. Therefore, the order in which header fields
with the same field-name are received is significant to the
interpretation of the combined field value, and thus a proxy MUST NOT
change the order of these field values when a message is forwarded.
Generic Headers
generic-header = active-request-id-list
/ proxy-sync-id
/ content-id
/ content-type
/ content-length
/ content-base
/ content-location
/ content-encoding
/ cache-control
/ logging-tag
All headers in MRCP will be case insensitive, consistent with HTTP
and RTSP protocol header definitions.
5.4.1. Active-Request-Id-List
In a request, this field indicates the list of request-ids to which
it should apply. This is useful when there are multiple Requests
that are PENDING or IN-PROGRESS and you want this request to apply to
one or more of these specifically.
In a response, this field returns the list of request-ids that the
operation modified or were in progress or just completed. There
could be one or more requests that returned a request-state of
PENDING or IN-PROGRESS. When a method affecting one or more PENDING
or IN-PROGRESS requests is sent from the client to the server, the
response MUST contain the list of request-ids that were affected in
this header field.
The active-request-id-list is only used in requests and responses,
not in events.
For example, if a STOP request with no active-request-id-list is sent
to a synthesizer resource (a wildcard STOP) that has one or more
SPEAK requests in the PENDING or IN-PROGRESS state, all SPEAK
requests MUST be cancelled, including the one IN-PROGRESS. In
addition, the response to the STOP request would contain the
request-id of all the SPEAK requests that were terminated in the
active-request-id-list. In this case, no SPEAK-COMPLETE or
RECOGNITION-COMPLETE events will be sent for these terminated
requests.
active-request-id-list = "Active-Request-Id-List" ":" request-id
*("," request-id) CRLF
5.4.2. Proxy-Sync-Id
When any server resource generates a barge-in-able event, it will
generate a unique Tag and send it as a header field in an event to
the client. The client then acts as a proxy to the server resource
and sends a BARGE-IN-OCCURRED method (Section 7.10) to the
synthesizer server resource with the Proxy-Sync-Id it received from
the server resource. When the recognizer and synthesizer resources
are part of the same session, they may choose to work together to
achieve quicker interaction and response. Here, the proxy-sync-id
helps the resource receiving the event, proxied by the client, to
decide if this event has been processed through a direct interaction
of the resources.
proxy-sync-id = "Proxy-Sync-Id" ":" 1*ALPHA CRLF
5.4.3. Accept-Charset
See [H14.2]. This specifies the acceptable character set for
entities returned in the response or events associated with this
request. This is useful in specifying the character set to use in
the Natural Language Semantics Markup Language (NLSML) results of a
RECOGNITON-COMPLETE event.
5.4.4. Content-Type
See [H14.17]. Note that the content types suitable for MRCP are
restricted to speech markup, grammar, recognition results, etc., and
are specified later in this document. The multi-part content type
"multi-part/mixed" is supported to communicate multiple of the above
mentioned contents, in which case the body parts cannot contain any
MRCP specific headers.
5.4.5. Content-Id
This field contains an ID or name for the content, by which it can be
referred to. The definition of this field conforms to RFC 2392 [14],
RFC 2822 [7], RFC 2046 [13] and is needed in multi-part messages. In
MRCP whenever the content needs to be stored, by either the client or
the server, it is stored associated with this ID. Such content can
be referenced during the session in URI form using the session:URI
scheme described in a later section.
5.4.6. Content-Base
The content-base entity-header field may be used to specify the base
URI for resolving relative URLs within the entity.
content-base = "Content-Base" ":" absoluteURI CRLF
Note, however, that the base URI of the contents within the entity-
body may be redefined within that entity-body. An example of this
would be a multi-part MIME entity, which in turn can have multiple
entities within it.
5.4.7. Content-Encoding
The content-encoding entity-header field is used as a modifier to the
media-type. When present, its value indicates what additional
content coding has been applied to the entity-body, and thus what
decoding mechanisms must be applied in order to obtain the media-type
referenced by the content-type header field. Content-encoding is
primarily used to allow a document to be compressed without losing
the identity of its underlying media type.
content-encoding = "Content-Encoding" ":"
*WSP content-coding
*(*WSP "," *WSP content-coding *WSP )
CRLF
content-coding = token
token = 1*(alphanum / "-" / "." / "!" / "%" / "*"
/ "_" / "+" / "`" / "’" / "~" )
Content coding is defined in [H3.5]. An example of its use is
Content-Encoding:gzip
If multiple encodings have been applied to an entity, the content
codings MUST be listed in the order in which they were applied.
5.4.8. Content-Location
The content-location entity-header field MAY BE used to supply the
resource location for the entity enclosed in the message when that
entity is accessible from a location separate from the requested
resource’s URI.
content-location = "Content-Location" ":" ( absoluteURI /
relativeURI ) CRLF
The content-location value is a statement of the location of the
resource corresponding to this particular entity at the time of the
request. The media server MAY use this header field to optimize
certain operations. When providing this header field, the entity
being sent should not have been modified from what was retrieved from
the content-location URI.
For example, if the client provided a grammar markup inline, and it
had previously retrieved it from a certain URI, that URI can be
provided as part of the entity, using the content-location header
field. This allows a resource like the recognizer to look into its
cache to see if this grammar was previously retrieved, compiled, and
cached. In which case, it might optimize by using the previously
compiled grammar object.
If the content-location is a relative URI, the relative URI is
interpreted relative to the content-base URI.
5.4.9. Content-Length
This field contains the length of the content of the message body
(i.e., after the double CRLF following the last header field).
Unlike HTTP, it MUST be included in all messages that carry content
beyond the header portion of the message. If it is missing, a
default value of zero is assumed. It is interpreted according to
[H14.13].
5.4.10. Cache-Control
If the media server plans on implementing caching, it MUST adhere to
the cache correctness rules of HTTP 1.1 (RFC2616), when accessing and
caching HTTP URI. In particular, the expires and cache-control
headers of the cached URI or document must be honored and will always
take precedence over the Cache-Control defaults set by this header
field. The cache-control directives are used to define the default
caching algorithms on the media server for the session or request.
The scope of the directive is based on the method it is sent on. If
the directives are sent on a SET-PARAMS method, it SHOULD apply for
all requests for documents the media server may make in that session.
If the directives are sent on any other messages, they MUST only
apply to document requests the media server needs to make for that
method. An empty cache-control header on the GET-PARAMS method is a
request for the media server to return the current cache-control
directives setting on the server.
cache-control = "Cache-Control" ":" *WSP cache-directive
*( *WSP "," *WSP cache-directive *WSP )
CRLF
cache-directive = "max-age" "=" delta-seconds
/ "max-stale" "=" delta-seconds
/ "min-fresh" "=" delta-seconds
delta-seconds = 1*DIGIT
Here, delta-seconds is a time value to be specified as an integer
number of seconds, represented in decimal, after the time that the
message response or data was received by the media server.
These directives allow the media server to override the basic
expiration mechanism.
max-age
Indicates that the client is OK with the media server using a
response whose age is no greater than the specified time in
seconds. Unless a max-stale directive is also included, the
client is not willing to accept the media server using a stale
response.
min-fresh
Indicates that the client is willing to accept the media server
using a response whose freshness lifetime is no less than its
current age plus the specified time in seconds. That is, the
client wants the media server to use a response that will still be
fresh for at least the specified number of seconds.
max-stale
Indicates that the client is willing to accept the media server
using a response that has exceeded its expiration time. If max-
stale is assigned a value, then the client is willing to accept
the media server using a response that has exceeded its expiration
time by no more than the specified number of seconds. If no value
is assigned to max-stale, then the client is willing to accept the
media server using a stale response of any age.
The media server cache MAY BE requested to use stale response/data
without validation, but only if this does not conflict with any
"MUST"-level requirements concerning cache validation (e.g., a
"must-revalidate" cache-control directive) in the HTTP 1.1
specification pertaining the URI.
If both the MRCP cache-control directive and the cached entry on the
media server include "max-age" directives, then the lesser of the two
values is used for determining the freshness of the cached entry for
that request.
5.4.11. Logging-Tag
This header field MAY BE sent as part of a SET-PARAMS/GET-PARAMS
method to set the logging tag for logs generated by the media server.
Once set, the value persists until a new value is set or the session
is ended. The MRCP server should provide a mechanism to subset its
output logs so that system administrators can examine or extract only
the log file portion during which the logging tag was set to a
certain value.
MRCP clients using this feature should take care to ensure that no
two clients specify the same logging tag. In the event that two
clients specify the same logging tag, the effect on the MRCP server’s
output logs in undefined.
logging-tag = "Logging-Tag" ":" 1*ALPHA CRLF
6. Media Server
The capability of media server resources can be found using the RTSP
DESCRIBE mechanism. When a client issues an RTSP DESCRIBE method for
a media resource URI, the media server response MUST contain an SDP
description in its body describing the capabilities of the media
server resource. The SDP description MUST contain at a minimum the
media header (m-line) describing the codec and other media related
features it supports. It MAY contain another SDP header as well, but
support for it is optional.
The usage of SDP messages in the RTSP message body and its
application follows the SIP RFC 2543 [4], but is limited to media-
related negotiation and description.
6.1. Media Server Session
As discussed in Section 3.2, a client/server should share one RTSP
session-id for the different resources it may use under the same
session. The client MUST allocate a set of client RTP/RTCP ports for
a new session and MUST NOT send a Session-ID in the SETUP message for
the first resource. The server then creates a Session-ID and
allocates a set of server RTP/RTCP ports and responds to the SETUP
message.
If the client wants to open more resources with the same server under
the same session, it will send the session-id (that it got in the
earlier SETUP response) in the SETUP for the new resource. A SETUP
message with an existing session-id tells the server that this new
resource will feed from/into the same RTP/RTCP stream of that
existing session.
If the client wants to open a resource from a media server that is
not where the first resource came from, it will send separate SETUP
requests with no session-id header field in them. Each server will
allocate its own session-id and return it in the response. Each of
them will also come back with their own set of RTP/RTCP ports. This
would be the case when the synthesizer engine and the recognition
engine are on different servers.
The RTSP SETUP method SHOULD contain an SDP description of the media
stream being set up. The RTSP SETUP response MUST contain an SDP
description of the media stream that it expects to receive and send
on that session.
The SDP description in the SETUP method from the client SHOULD
describe the required media parameters like codec, Named Signaling
Event (NSE) payload types, etc. This could have multiple media
headers (i.e., m-lines) to allow the client to provide the media
server with more than one option to choose from.
The SDP description in the SETUP response should reflect the media
parameters that the media server will be using for the stream. It
should be within the choices that were specified in the SDP of the
SETUP method, if one was provided.
Example:
C->S:
SETUP rtsp://media.server.com/recognizer/ RTSP/1.0
CSeq:1
Transport:RTP/AVP;unicast;client_port=46456-46457
Content-Type:application/sdp
Content-Length:190
v=0
o=- 123 456 IN IP4 10.0.0.1
s=Media Server
p=+1-888-555-1212
c=IN IP4 0.0.0.0
t=0 0
m=audio 46456 RTP/AVP 0 96
a=rtpmap:0 pcmu/8000
a=rtpmap:96 telephone-event/8000
a=fmtp:96 0-15
S->C:
RTSP/1.0 200 OK
CSeq:1
Session:0a030258_00003815_3bc4873a_0001_0000
Transport:RTP/AVP;unicast;client_port=46456-46457;
server_port=46460-46461
Content-Length:190
Content-Type:application/sdp
v=0
o=- 3211724219 3211724219 IN IP4 10.3.2.88
s=Media Server
c=IN IP4 0.0.0.0
t=0 0
m=audio 46460 RTP/AVP 0 96
a=rtpmap:0 pcmu/8000
a=rtpmap:96 telephone-event/8000
a=fmtp:96 0-15
If an SDP description was not provided in the RTSP SETUP method, then
the media server may decide on parameters of the stream but MUST
specify what it chooses in the SETUP response. An SDP announcement
is only returned in a response to a SETUP message that does not
specify a Session. That is, the server will not return an SDP
announcement for the synthesizer SETUP of a session already
established with a recognizer.
C->S:
SETUP rtsp://media.server.com/recognizer/ RTSP/1.0
CSeq:1
Transport:RTP/AVP;unicast;client_port=46498
S->C:
RTSP/1.0 200 OK
CSeq:1
Session:0a030258_000039dc_3bc48a13_0001_0000
Transport:RTP/AVP;unicast; client_port=46498;
server_port=46502-46503
Content-Length:193
Content-Type:application/sdp
v=0
o=- 3211724947 3211724947 IN IP4 10.3.2.88
s=Media Server
c=IN IP4 0.0.0.0
t=0 0
m=audio 46502 RTP/AVP 0 101
a=rtpmap:0 pcmu/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
7. Speech Synthesizer Resource
This resource is capable of converting text provided by the client
and generating a speech stream in real-time. Depending on the
implementation and capability of this resource, the client can
control parameters like voice characteristics, speaker speed, etc.
The synthesizer resource is controlled by MRCP requests from the
client. Similarly, the resource can respond to these requests or
generate asynchronous events to the server to indicate certain
conditions during the processing of the stream.
7.1. Synthesizer State Machine
The synthesizer maintains states because it needs to correlate MRCP
requests from the client. The state transitions shown below describe
the states of the synthesizer and reflect the request at the head of
the queue. A SPEAK request in the PENDING state can be deleted or
stopped by a STOP request and does not affect the state of the
resource.
Idle Speaking Paused
State State State
| | |
|----------SPEAK------->| |--------|
|<------STOP------------| CONTROL |
|<----SPEAK-COMPLETE----| |------->|
|<----BARGE-IN-OCCURRED-| |
| |--------| |
| CONTROL |-----------PAUSE--------->|
| |------->|<----------RESUME---------|
| | |----------|
| | PAUSE |
| | |--------->|
| |--------|----------| |