xml2rfc-2.9.6/ 0000755 0001750 0001750 00000000000 13243345234 013672 5 ustar henrik henrik 0000000 0000000 xml2rfc-2.9.6/setup.py 0000644 0001750 0001750 00000006715 13243345226 015416 0 ustar henrik henrik 0000000 0000000 #!/usr/bin/env python
# --------------------------------------------------
# Copyright The IETF Trust 2011, All Rights Reserved
# --------------------------------------------------
import os
import re
from codecs import open
from setuptools import setup
import sys
description = "Xml2rfc generates RFCs and IETF drafts from document source in XML according to the dtd in RFC2629."
here = os.path.abspath(os.path.dirname(__file__))
# Get the long description from the README file
with open(os.path.join(here, 'README'), encoding='utf-8') as file:
long_description = file.read()
# Get the requirements from the local requirements.txt file
with open(os.path.join(here, 'requirements.txt'), encoding='utf-8') as file:
requirements = file.read().splitlines()
# Check python versions
major, minor = sys.version_info[:2]
if not ((major == 2 and minor >= 6) or (major == 3 and minor >= 3)):
print("")
print("The xml2rfc installation requires python 2.6, 2.7, or 3.3")
print("Can't proceed, quitting.")
exit()
def parse(changelog):
ver_line = "^([a-z0-9+-]+) \(([^)]+)\)(.*?) *$"
sig_line = "^ -- ([^<]+) <([^>]+)> (.*?) *$"
entries = []
if type(changelog) == type(''):
changelog = open(changelog, encoding='utf-8')
for line in changelog:
if re.match(ver_line, line):
package, version, rest = re.match(ver_line, line).groups()
entry = {}
entry["package"] = package
entry["version"] = version
entry["logentry"] = ""
elif re.match(sig_line, line):
author, email, date = re.match(sig_line, line).groups()
entry["author"] = author
entry["email"] = email
entry["datetime"] = date
entry["date"] = " ".join(date.split()[:3])
entries += [ entry ]
else:
entry["logentry"] += line
changelog.close()
return entries
changelog_entry_template = """
Version %(version)s (%(date)s)
------------------------------------------------
%(logentry)s
"""
long_description += """
Changelog
=========
""" + "\n".join([ changelog_entry_template % entry for entry in parse("changelog")[:3] ])
setup(
# Package metadata
name='xml2rfc',
version='2.9.6',
author='Henrik Levkowetz, Josh Bothun',
author_email='tools-discuss@ietf.org',
maintainer = "Henrik Levkowetz",
maintainer_email = "henrik@levkowetz.com",
url='https://tools.ietf.org/tools/xml2rfc/trac/',
description=description,
long_description=long_description,
download_url = "https://pypi.python.org/pypi/xml2rfc",
classifiers= [
'Development Status :: 5 - Production/Stable',
'Environment :: Console',
'Operating System :: MacOS :: MacOS X',
'Operating System :: Microsoft :: Windows',
'Operating System :: POSIX :: Linux',
'Programming Language :: Python',
'Topic :: Text Processing',
'Topic :: Text Processing :: Markup :: XML',
'License :: OSI Approved :: BSD License',
],
license="Simplified BSD Licence",
# Program data
#scripts=['scripts/xml2rfc'],
entry_points = {
'console_scripts' : [
'xml2rfc = xml2rfc.run:main',
],
},
packages=['xml2rfc', 'xml2rfc/writers'],
package_data={'xml2rfc': [
'templates/*',
'data/*',
]},
install_requires = requirements,
zip_safe = False, # We're reading templates from a package directory.
)
xml2rfc-2.9.6/setup.cfg 0000644 0001750 0001750 00000000103 13243345234 015505 0 ustar henrik henrik 0000000 0000000 [bdist_wheel]
universal = 1
[egg_info]
tag_build =
tag_date = 0
xml2rfc-2.9.6/tests/ 0000755 0001750 0001750 00000000000 13243345234 015034 5 ustar henrik henrik 0000000 0000000 xml2rfc-2.9.6/tests/valid/ 0000755 0001750 0001750 00000000000 13243345234 016133 5 ustar henrik henrik 0000000 0000000 xml2rfc-2.9.6/tests/valid/rfc7911.html 0000644 0001750 0001750 00000073426 13237622212 020126 0 ustar henrik henrik 0000000 0000000
Advertisement of Multiple Paths in BGP
Advertisement of Multiple Paths in BGP
This document defines a BGP extension that allows the advertisement of multiple paths for the same address prefix without the new paths implicitly replacing any previous ones. The essence of the extension is that each path is identified by a Path Identifier in addition to the address prefix.
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7911.
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
1. Introduction
The BGP specification [RFC4271] defines an Update-Send Process to advertise the routes chosen by the Decision Process to other BGP speakers. No provisions are made to allow the advertisement of multiple paths for the same address prefix or Network Layer Reachability Information (NLRI). In fact, a route with the same NLRI as a previously advertised route implicitly replaces the previous advertisement.
This document defines a BGP extension that allows the advertisement of multiple paths for the same address prefix without the new paths implicitly replacing any previous ones. The essence of the extension is that each path is identified by a Path Identifier in addition to the address prefix.
The availability of the additional paths can help reduce or eliminate persistent route oscillations [RFC3345] . It can also help with optimal routing and routing convergence in a network by providing potential alternate or backup paths, respectively.
1.1. Specification of Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] .
2. How to Identify a Path
As defined in [RFC4271] , a path refers to the information reported in the Path Attribute field of an UPDATE message. As the procedures specified in [RFC4271] allow only the advertisement of one path for a particular address prefix, a path for an address prefix from a BGP peer can be keyed on the address prefix.
In order for a BGP speaker to advertise multiple paths for the same address prefix, a new identifier (termed "Path Identifier" hereafter) needs to be introduced so that a particular path for an address prefix can be identified by the combination of the address prefix and the Path Identifier.
The assignment of the Path Identifier for a path by a BGP speaker is purely a local matter. However, the Path Identifier MUST be assigned in such a way that the BGP speaker is able to use the (Prefix, Path Identifier) to uniquely identify a path advertised to a neighbor. A BGP speaker that re-advertises a route MUST generate its own Path Identifier to be associated with the re-advertised route. A BGP speaker that receives a route should not assume that the identifier carries any particular semantics.
In order to carry the Path Identifier in an UPDATE message, the NLRI encoding MUST be extended by prepending the Path Identifier field, which is of four octets.
For example, the NLRI encoding specified in [RFC4271] is extended as the following:
+--------------------------------+
| Path Identifier (4 octets) |
+--------------------------------+
| Length (1 octet) |
+--------------------------------+
| Prefix (variable) |
+--------------------------------+
The usage of the extended NLRI encodings is specified in Section 5 .
The ADD-PATH Capability is a BGP capability [RFC5492] , with Capability Code 69. The Capability Length field of this capability is variable. The Capability Value field consists of one or more of the following tuples:
+------------------------------------------------+
| Address Family Identifier (2 octets) |
+------------------------------------------------+
| Subsequent Address Family Identifier (1 octet) |
+------------------------------------------------+
| Send/Receive (1 octet) |
+------------------------------------------------+
The meaning and use of the fields are as follows:
Address Family Identifier (AFI): This field is the same as the one used in [RFC4760] .
Subsequent Address Family Identifier (SAFI): This field is the same as the one used in [RFC4760] .
Send/Receive:
This field indicates whether the sender is (a) able to receive multiple paths from its peer (value 1), (b) able to send multiple paths to its peer (value 2), or (c) both (value 3) for the <AFI, SAFI>.
If any other value is received, then the capability SHOULD be treated as not understood and ignored [RFC5492] .
A BGP speaker that wishes to indicate support for multiple AFI/SAFIs MUST do so by including the information in a single instance of the ADD-PATH Capability.
The Path Identifier specified in Section 3 can be used to advertise multiple paths for the same address prefix without subsequent advertisements replacing the previous ones. Apart from the fact that this is now possible, the route advertisement rules of [RFC4271] are not changed. In particular, a new advertisement for a given address prefix and a given Path Identifier replaces a previous advertisement for the same address prefix and Path Identifier. If a BGP speaker receives a message to withdraw a prefix with a Path Identifier not seen before, it SHOULD silently ignore it.
For a BGP speaker to be able to send multiple paths to its peer, that BGP speaker MUST advertise the ADD-PATH Capability with the Send/Receive field set to either 2 or 3, and MUST receive from its peer the ADD-PATH Capability with the Send/Receive field set to either 1 or 3, for the corresponding <AFI, SAFI>.
A BGP speaker MUST follow the procedures defined in [RFC4271] when generating an UPDATE message for a particular <AFI, SAFI> to a peer unless the BGP speaker advertises the ADD-PATH Capability to the peer indicating its ability to send multiple paths for the <AFI, SAFI>, and also receives the ADD-PATH Capability from the peer indicating its ability to receive multiple paths for the <AFI, SAFI>, in which case the speaker MUST generate a route update for the <AFI, SAFI> based on the combination of the address prefix and the Path Identifier, and use the extended NLRI encodings specified in this document. The peer SHALL act accordingly in processing an UPDATE message related to a particular <AFI, SAFI>.
A BGP speaker SHOULD include the best route [RFC4271] when more than one path is advertised to a neighbor, unless it is a path received from that neighbor.
As the Path Identifiers are locally assigned, and may or may not be persistent across a control plane restart of a BGP speaker, an implementation SHOULD take special care so that the underlying forwarding plane of a "Receiving Speaker" as described in [RFC4724] is not affected during the graceful restart of a BGP session.
6. Deployment Considerations
The extension proposed in this document provides a mechanism for a BGP speaker to advertise multiple paths over a BGP session. Care needs to be taken in its deployment to ensure consistent routing and forwarding in a network [ADDPATH] .
The only explicit indication that the encoding described in Section 3 is in use in a particular BGP session is the exchange of Capabilities described in Section 4 . If the exchange is successful [RFC5492] , then the BGP speakers will be able to process all BGP UPDATES properly, as described in Section 5 . However, if, for example, a packet analyzer is used on the wire to examine an active BGP session, it may not be able to properly decode the BGP UPDATES because it lacks prior knowledge of the exchanged Capabilities.
When deployed as a provider edge router or a peering router that interacts with external neighbors, a BGP speaker usually advertises at most one path to the internal neighbors in a network. In the case where the speaker is configured to advertise multiple paths to the internal neighbors, and additional information is needed for the application, the speaker could use attributes such as the Edge_Discriminator attribute [FAST] . The use of that type of additional information is outside the scope of this document.
7. IANA Considerations
IANA has assigned the value 69 for the ADD-PATH Capability described in this document. This registration is in the "Capability Codes" registry.
8. Security Considerations
This document defines a BGP extension that allows the advertisement of multiple paths for the same address prefix without the new paths implicitly replacing any previous ones. As a result, multiple paths for a large number of prefixes may be received by a BGP speaker, potentially depleting memory resources or even causing network-wide instability, which can be considered a denial-of-service attack. Note that this is not a new vulnerability, but one that is present in the base BGP specification [RFC4272] .
The use of the ADD-PATH Capability is intended to address specific needs related to, for example, eliminating route oscillations that were induced by the MULTI_EXIT_DISC (MED) attribute . While describing the applications for the ADD-PATH Capability is outside the scope of this document, users are encouraged to examine their behavior and potential impact by studying the best practices described in [ADDPATH] .
Security concerns in the base operation of BGP also apply.
9. References
9.1. Normative References
[RFC2119]
Bradner, S. , "Key words for use in RFCs to Indicate Requirement Levels ", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC4271]
Rekhter, Y. , Li, T. and S. Hares , "A Border Gateway Protocol 4 (BGP-4) ", RFC 4271, DOI 10.17487/RFC4271, January 2006.
[RFC4760]
Bates, T. , Chandra, R. , Katz, D. and Y. Rekhter , "Multiprotocol Extensions for BGP-4 ", RFC 4760, DOI 10.17487/RFC4760, January 2007.
[RFC5492]
Scudder, J. and R. Chandra , "Capabilities Advertisement with BGP-4 ", RFC 5492, DOI 10.17487/RFC5492, February 2009.
9.2. Informative References
[ADDPATH]
Uttaro, J. , Francois, P. , Patel, K. , Haas, J. , Simpson, A. and R. Fragassi , "Best Practices for Advertisement of Multiple Paths in IBGP ", Work in Progress, draft-ietf-idr-add-paths-guidelines-08, April 2016.
[FAST]
Mohapatra, P. , Fernando, R. , Filsfils, C. and R. Raszuk , "Fast Connectivity Restoration Using BGP Add-path ", Work in Progress, draft-pmohapat-idr-fast-conn-restore-03, January 2013.
[RFC3345]
McPherson, D. , Gill, V. , Walton, D. and A. Retana , "Border Gateway Protocol (BGP) Persistent Route Oscillation Condition ", RFC 3345, DOI 10.17487/RFC3345, August 2002.
[RFC4272]
Murphy, S. , "BGP Security Vulnerabilities Analysis ", RFC 4272, DOI 10.17487/RFC4272, January 2006.
[RFC4724]
Sangli, S. , Chen, E. , Fernando, R. , Scudder, J. and Y. Rekhter , "Graceful Restart Mechanism for BGP ", RFC 4724, DOI 10.17487/RFC4724, January 2007.
[STOP-OSC]
Walton, D. , Retana, A. , Chen, E. and J. Scudder , "BGP Persistent Route Oscillation Solutions ", Work in Progress, draft-ietf-idr-route-oscillation-stop-03, April 2016.
We would like to thank David Cook and Naiming Shen for their contributions to the design and development of the extension.
Many people have made valuable comments and suggestions, including Rex Fernando, Eugene Kim, Danny McPherson, Dave Meyer, Pradosh Mohapatra, Keyur Patel, Robert Raszuk, Eric Rosen, Srihari Sangli, Dan Tappan, Mark Turner, Jeff Haas, Jay Borkenhagen, Mach Chen, Denis Ovsienko, Carlos Pignataro, Meral Shirazipour, and Kathleen Moriarty.
Daniel Walton
Walton
Cumulus Networks
185 E. Dana Street
Mountain View ,
CA
94041
United States of America
EMail: dwalton@cumulusnetworks.com
Alvaro Retana
Retana
Cisco Systems, Inc.
Kit Creek Rd.
Research Triangle Park ,
NC
27709
United States of America
EMail: aretana@cisco.com
Enke Chen
Chen
Cisco Systems, Inc.
170 W. Tasman Dr.
San Jose ,
CA
95134
United States of America
EMail: enkechen@cisco.com
John Scudder
Scudder
Juniper Networks
1194 N. Mathilda Ave
Sunnyvale ,
CA
94089
United States of America
EMail: jgs@juniper.net
xml2rfc-2.9.6/tests/valid/references.txt 0000644 0001750 0001750 00000004042 13113013721 021002 0 ustar henrik henrik 0000000 0000000 [Erratum3657]
RFC Errata, Erratum 3657, RFC 2978.
[I-D.ietf-avt-rtcp-port-for-ssm]
Begen, A., "RTP Control Protocol (RTCP) Port for Source-
Specific Multicast (SSM) Sessions", draft-ietf-avt-rtcp-
port-for-ssm-04 (work in progress), December 2010.
[INITIALS]
Doe, J., Doe, A., Doe, B., Doe, C., Doe, D., Doe, Doe, E.,
Doe, F., and G. Doe, "All initial sets, no PI", RFC 7539,
DOI 10.17487/RFC7539, may 2015.
[INITIALS-PI]
Doe, J., Doe, A., Doe, B. D., Doe, C. D., Doe, D.D., Doe,
Doe, E. D., Doe, F.D., and G. D. Doe, "All initial sets,
with PI", RFC 7539, DOI 10.17487/RFC7539, may 2015.
[INITIALS2]
Doe, J. D. and A. Doe, "Lots of authors", RFC 7539,
DOI 10.17487/RFC7539, may 2015.
[INITIALS3]
Doe, J. D. and B. D. Doe, "Lots of authors", RFC 7539,
DOI 10.17487/RFC7539, may 2015.
[INITIALS4]
Doe, J. D. and Doe, "Lots of authors", RFC 7539,
DOI 10.17487/RFC7539, may 2015.
[RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
June 1999.
[RFC3424] Daigle, L. and IAB, "IAB Considerations for UNilateral
Self-Address Fixing (UNSAF) Across Network Address
Translation", RFC 3424, November 2002.
[RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552, July
2003.
[SDO-3GPP]
"3GPP Home Page", .
xml2rfc-2.9.6/tests/valid/rfc7911.exp.xml 0000644 0001750 0001750 00000065774 13237622212 020564 0 ustar henrik henrik 0000000 0000000
Advertisement of Multiple Paths in BGP
Cumulus Networks
185 E. Dana Street
Mountain View
CA
94041
United States of America
dwalton@cumulusnetworks.com
Cisco Systems, Inc.
Kit Creek Rd.
Research Triangle Park
NC
27709
United States of America
aretana@cisco.com
Cisco Systems, Inc.
170 W. Tasman Dr.
San Jose
CA
95134
United States of America
enkechen@cisco.com
Juniper Networks
1194 N. Mathilda Ave
Sunnyvale
CA
94089
United States of America
jgs@juniper.net
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. The essence of the extension is
that each path is identified by a Path Identifier in addition to the
address prefix.
The BGP specification
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. The essence of the extension is
that each path is identified by a Path Identifier in addition to the
address prefix.
The availability of the additional paths can help reduce or eliminate
persistent route oscillations
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
As defined in
In order for a BGP speaker to advertise multiple paths for the same
address prefix, a new identifier (termed "Path Identifier" hereafter)
needs to be introduced so that a particular path for an address prefix
can be identified by the combination of the address prefix and the Path
Identifier.
The assignment of the Path Identifier for a path by a BGP speaker is
purely a local matter. However, the Path Identifier MUST be assigned in
such a way that the BGP speaker is able to use the (Prefix, Path
Identifier) to uniquely identify a path advertised to a neighbor. A BGP
speaker that re-advertises a route MUST generate its own Path Identifier
to be associated with the re-advertised route. A BGP speaker that
receives a route should not assume that the identifier carries any
particular semantics.
In order to carry the Path Identifier in an UPDATE message, the NLRI
encoding MUST be extended by prepending the Path Identifier field, which
is of four octets.
For example, the NLRI encoding specified in
+--------------------------------+
| Path Identifier (4 octets) |
+--------------------------------+
| Length (1 octet) |
+--------------------------------+
| Prefix (variable) |
+--------------------------------+
The usage of the extended NLRI encodings is specified in
The ADD-PATH Capability is a BGP capability
+------------------------------------------------+
| Address Family Identifier (2 octets) |
+------------------------------------------------+
| Subsequent Address Family Identifier (1 octet) |
+------------------------------------------------+
| Send/Receive (1 octet) |
+------------------------------------------------+
The meaning and use of the fields are as follows:
Address Family Identifier (AFI): This field is the same as the one used in
Subsequent Address Family Identifier (SAFI): This field is the same as the one used in
Send/Receive: This field indicates whether the sender is (a) able to
receive multiple paths from its peer (value 1), (b) able to send
multiple paths to its peer (value 2), or (c) both (value 3) for
the <AFI, SAFI>. If any other value is received, then the capability SHOULD be
treated as not understood and ignored
A BGP speaker that wishes to indicate support for multiple
AFI/SAFIs MUST do so by including the information in a single instance of
the ADD-PATH Capability.
The Path Identifier specified in
For a BGP speaker to be able to send multiple paths to its peer, that
BGP speaker MUST advertise the ADD-PATH Capability with the Send/Receive
field set to either 2 or 3, and MUST receive from its peer the ADD-PATH
Capability with the Send/Receive field set to either 1 or 3, for the
corresponding <AFI, SAFI>.
A BGP speaker MUST follow the procedures defined in
A BGP speaker SHOULD include the best route
As the Path Identifiers are locally assigned, and may or may not be
persistent across a control plane restart of a BGP speaker, an
implementation SHOULD take special care so that the underlying
forwarding plane of a "Receiving Speaker" as described in
The extension proposed in this document provides a mechanism for a
BGP speaker to advertise multiple paths over a BGP session. Care needs
to be taken in its deployment to ensure consistent routing and
forwarding in a network
The only explicit indication that the encoding described in
When deployed as a provider edge router or a peering router that
interacts with external neighbors, a BGP speaker usually advertises at
most one path to the internal neighbors in a network. In the case where the
speaker is configured to advertise multiple paths to the internal
neighbors, and additional information is needed for the application, the
speaker could use attributes such as the Edge_Discriminator attribute
IANA has assigned the value 69 for the ADD-PATH Capability
described in this document. This registration is in the "Capability
Codes" registry.
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. As a result, multiple paths for
a large number of prefixes may be received by a BGP speaker, potentially
depleting memory resources or even causing network-wide instability, which
can be considered a denial-of-service attack. Note that this is not a new
vulnerability, but one that is present in the base BGP specification
The use of the ADD-PATH Capability is intended to address specific
needs related to, for example, eliminating route oscillations that
were induced by the MULTI_EXIT_DISC (MED) attribute .
While describing the applications for the
ADD-PATH Capability is outside the scope of this document, users
are encouraged to examine their behavior and potential impact by
studying the best practices described in
Security concerns in the base operation of BGP also apply.
A Border Gateway Protocol 4 (BGP-4)
This document discusses the Border Gateway Protocol (BGP), which is an inter-Autonomous System routing protocol.
The primary function of a BGP speaking system is to exchange network reachability information with other BGP systems. This network reachability information includes information on the list of Autonomous Systems (ASes) that reachability information traverses. This information is sufficient for constructing a graph of AS connectivity for this reachability from which routing loops may be pruned, and, at the AS level, some policy decisions may be enforced.
BGP-4 provides a set of mechanisms for supporting Classless Inter-Domain Routing (CIDR). These mechanisms include support for advertising a set of destinations as an IP prefix, and eliminating the concept of network "class" within BGP. BGP-4 also introduces mechanisms that allow aggregation of routes, including aggregation of AS paths.
This document obsoletes RFC 1771. [STANDARDS-TRACK]
Capabilities Advertisement with BGP-4
This document defines an Optional Parameter, called Capabilities, that is expected to facilitate the introduction of new capabilities in the Border Gateway Protocol (BGP) by providing graceful capability advertisement without requiring that BGP peering be terminated.
This document obsoletes RFC 3392. [STANDARDS-TRACK]
Multiprotocol Extensions for BGP-4
This document defines extensions to BGP-4 to enable it to carry routing information for multiple Network Layer protocols (e.g., IPv6, IPX, L3VPN, etc.). The extensions are backward compatible - a router that supports the extensions can interoperate with a router that doesn't support the extensions. [STANDARDS-TRACK]
Key words for use in RFCs to Indicate Requirement Levels
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
Border Gateway Protocol (BGP) Persistent Route Oscillation Condition
BGP Persistent Route Oscillation Solutions
Best Practices for Advertisement of Multiple Paths in IBGP
Fast Connectivity Restoration Using BGP Add-path
Graceful Restart Mechanism for BGP
This document describes a mechanism for BGP that would help minimize the negative effects on routing caused by BGP restart. An End-of-RIB marker is specified and can be used to convey routing convergence information. A new BGP capability, termed "Graceful Restart Capability", is defined that would allow a BGP speaker to express its ability to preserve forwarding state during BGP restart. Finally, procedures are outlined for temporarily retaining routing information across a TCP session termination/re-establishment.
The mechanisms described in this document are applicable to all routers, both those with the ability to preserve forwarding state during BGP restart and those without (although the latter need to implement only a subset of the mechanisms described in this document). [STANDARDS-TRACK]
BGP Security Vulnerabilities Analysis
Border Gateway Protocol 4 (BGP-4), along with a host of other infrastructure protocols designed before the Internet environment became perilous, was originally designed with little consideration for protection of the information it carries. There are no mechanisms internal to BGP that protect against attacks that modify, delete, forge, or replay data, any of which has the potential to disrupt overall network routing behavior.
This document discusses some of the security issues with BGP routing data dissemination. This document does not discuss security issues with forwarding of packets. This memo provides information for the Internet community.
We would like to thank David Cook and Naiming Shen for their
contributions to the design and development of the extension.
Many people have made valuable comments and suggestions, including
Rex Fernando, Eugene Kim, Danny McPherson, Dave Meyer, Pradosh
Mohapatra, Keyur Patel, Robert Raszuk, Eric Rosen, Srihari Sangli, Dan
Tappan, Mark Turner, Jeff Haas, Jay Borkenhagen, Mach Chen, Denis Ovsienko,
Carlos Pignataro, Meral Shirazipour, and Kathleen Moriarty.
xml2rfc-2.9.6/tests/valid/abbreviations.nroff 0000644 0001750 0001750 00000000211 12472420024 022003 0 ustar henrik henrik 0000000 0000000 .in 3
Various abbreviations which aren't end of sentence: Jr. AND Sr. AND
i.e. AND Mr. AND Mrs. etc. \%-- done. Start of next sentence. xml2rfc-2.9.6/tests/valid/status_ietf_exp_no.nroff 0000644 0001750 0001750 00000001573 13237442436 023104 0 ustar henrik henrik 0000000 0000000 .pl 10.0i
.po 0
.ll 7.2i
.lt 7.2i
.nr LL 7.2i
.nr LT 7.2i
.hy 0
.ad l
.ds LH RFC 9999
.ds CH Abbreviated Title
.ds RH December 2010
.ds LF Doe
.ds CF Best Current Practice
.ds RF FORMFEED[Page %]
.ti 0
Status of This Memo
.in 3
This document is not an Internet Standards Track specification; it is
published for examination, experimental implementation, and evaluation.
This document defines an Experimental Protocol for the Internet
community. This document is a product of the Internet Engineering Task
Force (IETF). It has been approved for publication by the Internet
Engineering Steering Group (IESG). Not all documents approved by the
IESG are candidates for any level of Internet Standard; see Section 2
of RFC 5741.
Information about the current status of this document, any errata, and
how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc9999.
xml2rfc-2.9.6/tests/valid/header_footer_rfc.txt 0000644 0001750 0001750 00000000223 12336226773 022341 0 ustar henrik henrik 0000000 0000000 Doe Best Current Practice [Page 1]
RFC 9999 Abbreviated Title December 2010 xml2rfc-2.9.6/tests/valid/rfc7911.v2v3.xml 0000644 0001750 0001750 00000065670 13237622212 020563 0 ustar henrik henrik 0000000 0000000
Advertisement of Multiple Paths in BGP
Cumulus Networks
185 E. Dana Street
Mountain View
CA
94041
United States of America
dwalton@cumulusnetworks.com
Cisco Systems, Inc.
Kit Creek Rd.
Research Triangle Park
NC
27709
United States of America
aretana@cisco.com
Cisco Systems, Inc.
170 W. Tasman Dr.
San Jose
CA
95134
United States of America
enkechen@cisco.com
Juniper Networks
1194 N. Mathilda Ave
Sunnyvale
CA
94089
United States of America
jgs@juniper.net
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. The essence of the extension is
that each path is identified by a Path Identifier in addition to the
address prefix.
Introduction
The BGP specification
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. The essence of the extension is
that each path is identified by a Path Identifier in addition to the
address prefix.
The availability of the additional paths can help reduce or eliminate
persistent route oscillations
Specification of Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
How to Identify a Path
As defined in
In order for a BGP speaker to advertise multiple paths for the same
address prefix, a new identifier (termed "Path Identifier" hereafter)
needs to be introduced so that a particular path for an address prefix
can be identified by the combination of the address prefix and the Path
Identifier.
The assignment of the Path Identifier for a path by a BGP speaker is
purely a local matter. However, the Path Identifier MUST be assigned in
such a way that the BGP speaker is able to use the (Prefix, Path
Identifier) to uniquely identify a path advertised to a neighbor. A BGP
speaker that re-advertises a route MUST generate its own Path Identifier
to be associated with the re-advertised route. A BGP speaker that
receives a route should not assume that the identifier carries any
particular semantics.
Extended NLRI Encodings
In order to carry the Path Identifier in an UPDATE message, the NLRI
encoding MUST be extended by prepending the Path Identifier field, which
is of four octets.
For example, the NLRI encoding specified in
The usage of the extended NLRI encodings is specified in
ADD-PATH Capability
The ADD-PATH Capability is a BGP capability
The meaning and use of the fields are as follows:
Address Family Identifier (AFI):
This field is the same as the one used in
Subsequent Address Family Identifier (SAFI):
This field is the same as the one used in
Send/Receive:
This field indicates whether the sender is (a) able to
receive multiple paths from its peer (value 1), (b) able to send
multiple paths to its peer (value 2), or (c) both (value 3) for
the <AFI, SAFI>.
If any other value is received, then the capability SHOULD be
treated as not understood and ignored
A BGP speaker that wishes to indicate support for multiple
AFI/SAFIs MUST do so by including the information in a single instance of
the ADD-PATH Capability.
Operation
The Path Identifier specified in
For a BGP speaker to be able to send multiple paths to its peer, that
BGP speaker MUST advertise the ADD-PATH Capability with the Send/Receive
field set to either 2 or 3, and MUST receive from its peer the ADD-PATH
Capability with the Send/Receive field set to either 1 or 3, for the
corresponding <AFI, SAFI>.
A BGP speaker MUST follow the procedures defined in
A BGP speaker SHOULD include the best route
As the Path Identifiers are locally assigned, and may or may not be
persistent across a control plane restart of a BGP speaker, an
implementation SHOULD take special care so that the underlying
forwarding plane of a "Receiving Speaker" as described in
Deployment Considerations
The extension proposed in this document provides a mechanism for a
BGP speaker to advertise multiple paths over a BGP session. Care needs
to be taken in its deployment to ensure consistent routing and
forwarding in a network
The only explicit indication that the encoding described in
When deployed as a provider edge router or a peering router that
interacts with external neighbors, a BGP speaker usually advertises at
most one path to the internal neighbors in a network. In the case where the
speaker is configured to advertise multiple paths to the internal
neighbors, and additional information is needed for the application, the
speaker could use attributes such as the Edge_Discriminator attribute
IANA Considerations
IANA has assigned the value 69 for the ADD-PATH Capability
described in this document. This registration is in the "Capability
Codes" registry.
Security Considerations
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. As a result, multiple paths for
a large number of prefixes may be received by a BGP speaker, potentially
depleting memory resources or even causing network-wide instability, which
can be considered a denial-of-service attack. Note that this is not a new
vulnerability, but one that is present in the base BGP specification
The use of the ADD-PATH Capability is intended to address specific
needs related to, for example, eliminating route oscillations that
were induced by the MULTI_EXIT_DISC (MED) attribute .
While describing the applications for the
ADD-PATH Capability is outside the scope of this document, users
are encouraged to examine their behavior and potential impact by
studying the best practices described in
Security concerns in the base operation of BGP also apply.
Normative References
A Border Gateway Protocol 4 (BGP-4)
This document discusses the Border Gateway Protocol (BGP), which is an inter-Autonomous System routing protocol.
The primary function of a BGP speaking system is to exchange network reachability information with other BGP systems. This network reachability information includes information on the list of Autonomous Systems (ASes) that reachability information traverses. This information is sufficient for constructing a graph of AS connectivity for this reachability from which routing loops may be pruned, and, at the AS level, some policy decisions may be enforced.
BGP-4 provides a set of mechanisms for supporting Classless Inter-Domain Routing (CIDR). These mechanisms include support for advertising a set of destinations as an IP prefix, and eliminating the concept of network "class" within BGP. BGP-4 also introduces mechanisms that allow aggregation of routes, including aggregation of AS paths.
This document obsoletes RFC 1771. [STANDARDS-TRACK]
Capabilities Advertisement with BGP-4
This document defines an Optional Parameter, called Capabilities, that is expected to facilitate the introduction of new capabilities in the Border Gateway Protocol (BGP) by providing graceful capability advertisement without requiring that BGP peering be terminated.
This document obsoletes RFC 3392. [STANDARDS-TRACK]
Multiprotocol Extensions for BGP-4
This document defines extensions to BGP-4 to enable it to carry routing information for multiple Network Layer protocols (e.g., IPv6, IPX, L3VPN, etc.). The extensions are backward compatible - a router that supports the extensions can interoperate with a router that doesn't support the extensions. [STANDARDS-TRACK]
Key words for use in RFCs to Indicate Requirement Levels
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
Informative References
Border Gateway Protocol (BGP) Persistent Route Oscillation Condition
BGP Persistent Route Oscillation Solutions
Best Practices for Advertisement of Multiple Paths in IBGP
Fast Connectivity Restoration Using BGP Add-path
Graceful Restart Mechanism for BGP
This document describes a mechanism for BGP that would help minimize the negative effects on routing caused by BGP restart. An End-of-RIB marker is specified and can be used to convey routing convergence information. A new BGP capability, termed "Graceful Restart Capability", is defined that would allow a BGP speaker to express its ability to preserve forwarding state during BGP restart. Finally, procedures are outlined for temporarily retaining routing information across a TCP session termination/re-establishment.
The mechanisms described in this document are applicable to all routers, both those with the ability to preserve forwarding state during BGP restart and those without (although the latter need to implement only a subset of the mechanisms described in this document). [STANDARDS-TRACK]
BGP Security Vulnerabilities Analysis
Border Gateway Protocol 4 (BGP-4), along with a host of other infrastructure protocols designed before the Internet environment became perilous, was originally designed with little consideration for protection of the information it carries. There are no mechanisms internal to BGP that protect against attacks that modify, delete, forge, or replay data, any of which has the potential to disrupt overall network routing behavior.
This document discusses some of the security issues with BGP routing data dissemination. This document does not discuss security issues with forwarding of packets. This memo provides information for the Internet community.
Acknowledgments
We would like to thank David Cook and Naiming Shen for their
contributions to the design and development of the extension.
Many people have made valuable comments and suggestions, including
Rex Fernando, Eugene Kim, Danny McPherson, Dave Meyer, Pradosh
Mohapatra, Keyur Patel, Robert Raszuk, Eric Rosen, Srihari Sangli, Dan
Tappan, Mark Turner, Jeff Haas, Jay Borkenhagen, Mach Chen, Denis Ovsienko,
Carlos Pignataro, Meral Shirazipour, and Kathleen Moriarty.
xml2rfc-2.9.6/tests/valid/draft-miek-test.html 0000644 0001750 0001750 00000151434 13241652176 022035 0 ustar henrik henrik 0000000 0000000
Writing I-Ds and RFCs using Pandoc and xml2rfc 2.x
Writing I-Ds and RFCs using Pandoc and xml2rfc 2.xdraft-gieben-writing-rfcs-pandoc-02
This memo presents a technique for using Pandoc syntax as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series.
This version is adapted to work with "xml2rfc" version 2.x.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 5, 2013.
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This document presents a technique for using Pandoc syntax as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series.
This version is adapted to work with xml2rfc version 2.x.
Pandoc is an "almost plain text" format and therefor particularly well suited for editing RFC-like documents.
Note: this document is typeset in Pandoc and does not render completely correct when reading it on github.
Pandoc2rfc -- designed to do the right thing, until it doesn't.
When writing [RFC4641] we directly wrote the XML. Needless to say it was tedious even thought the XML of xml2rfc is very "light". The latest version of xml2rfc version 2 can be found here .
During the last few years people have been developing markup languages that are very easy to remember and type. These languages have become known as almost plain text -markup languages. One of the first was the Markdown syntax. One that was developed later and incorporates Markdown and a number of extensions is Pandoc . The power of Pandoc also comes from the fact that it can be translated to numerous output formats, including, but not limited to: HTML, (plain) Markdown and docbook XML.
So using Pandoc for writing RFCs seems like a sane choice. As xml2rfc uses XML, the easiest way would be to create docbook XML and transform that using XSLT. Pandoc2rfc does just that. The conversions are, in some way amusing, as we start off with (almost) plain text, use elaborate XML and end up with plain text again.
+-------------------+ pandoc +---------+
| ALMOST PLAIN TEXT | ------> | DOCBOOK |
+-------------------+ +---------+
| |
non-existent | | xsltproc
faster way | |
v v
+------------+ xml2rfc +---------+
| PLAIN TEXT | <-------- | XML2RFC |
+------------+ +---------+
Figure 1: Attempt to justify Pandoc2rfc.
The XML generated (the output after the xsltproc step in Figure 1 ) is suitable for inclusion in either the middle or back section of an RFC. The simplest way is to create a template XML file and include the appropriate XML:
<?xml version='1.0' ?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY pandocMiddle PUBLIC '' 'middle.xml'>
<!ENTITY pandocBack PUBLIC '' 'back.xml'>
]>
<rfc ipr='trust200902' docName='draft-gieben-pandoc-rfcs-02'>
<front>
<title>Writing I-Ds and RFCs using Pandoc v2</title>
</front>
<middle>
&pandocMiddle;
</middle>
<back>
&pandocBack;
</back>
</rfc>
Figure 2: A minimal template.xml.
See the Makefile for an example of this. In this case you need to edit 3 documents:
middle.pdc - contains the main body of text;
back.pdc - holds appendices and references;
template.xml (probably a fairly static file).
The draft (draft.txt ) you are reading now, is automatically created when you call make . The homepage of Pandoc2rfc is this github repository .
It needs xsltproc and pandoc to be installed. See the Pandoc user manual for the details on how to type in Pandoc style. And ofcourse xml2rfc version two.
When using Pandoc2rfc consider adding the following sentence to an Acknowledgements section:
This document was produced using the Pandoc2rfc tool.
When starting a new project with pandoc2rfc you'll need to copy the following files:
Makefile
transform.xslt
And the above mentioned files:
middle.pdc
back.pdc
template.xml
After that you can start editing.
Sections with an anchor and title attributes (Section 7.2 );
Lists
Figure/artwork with a title (Section 7.4 );
Block quote this is converted to <list style="empty"> paragraph (Section 7.5 );
References
Citations, by using internal references;
Spanx style=verb, style=emph and style=strong (Section 7.7 );
Tables with an anchor and title (Section 7.8 );
Indexes, by using footnotes (Section 7.9 ).
Lists inside a table (xml2rfc doesn't handle this);
Pandoc markup in the caption for figures/artwork. Pandoc markup for table captions is supported;
crefs: for comments (no input syntax available), use HTML comments: <!-- ... --> ;
The following people have helped to make Pandoc2rfc what it is today: Benno Overeinder, Erlend Hamnaberg, Matthijs Mekking, Trygve Laugstøl.
This document was prepared using Pandoc2rfc.
So, what syntax do you need to use to get the correct output? Well, it is just Pandoc. The best introduction to the Pandoc style is given in this README from Pandoc itself .
For convenience we list the most important ones in the following sections.
Paragraphs are separated with an empty line.
Just use the normal sectioning commands available in Pandoc, for instance:
# Section1 One
Bla
Converts to: <section title="Section1 One" anchor="section1-one"> If you have another section that is also named "Section1 One", that anchor will be called "section1-one-1", but only when the sections are in the same source file!
Referencing the section is done with see [](#section1-one) , as in see Section 7.2 .
A good number of styles are supported.
A symbol list.
* Item one;
* Item two.
Converts to <list style="symbol"> :
A numbered list.
1. Item one;
1. Item two.
Converts to <list style="numbers"> :
Item one;
Item two.
Using the default list markers from Pandoc:
A list using the default list markers.
#. Item one;
#. Item two.
Converts to <list style="empty"> :
Use the supported Pandoc syntax:
ii. Item one;
ii. Item two.
Converts to <list style="format %i."> :
i.
Item one;
ii.
Item two.
If you use uppercase Roman numerals, they convert to a different style:
II. Item one;
II. Item two.
Yields <list style="format (%d) "> :
(1)
Item one;
(2)
Item two.
A numbered list.
a. Item one;
b. Item two.
Converts to <list style="letters"> :
Item one;
Item two.
Uppercasing the letters works too (note two spaces after the letter.
A. Item one;
B. Item two.
Becomes:
A.
Item one;
B.
Item two.
This is more like a description list, so we need to use:
First item that needs clarification:
: Explanation one
More stuff, because item is difficult to explain.
* item1
* item2
Second item that needs clarification:
: Explanation two
Converts to: <list style="hanging"> and <t hangText="First item that...">
If you want a newline after the hangTexts, search for the string OPTION in transform.xsl and uncomment it.
Indent the paragraph with 4 spaces.
Like this
Converts to: <figure><artwork> ... Note that xml2rfc supports a caption with <artwork> . Pandoc does not support this, but Pandoc2rfc does. If you add a @Figure: some text as the last line, the artwork gets a title attribute with the text after @Figure: . It will also be possible to reference the artwork. If a caption is supplied the artwork will be centered. If a caption is needed but the figure should not be centered use @figure:\ .
The reference anchor attribute will be: fig: + first 10 (normalized) characters from the caption . Where normalized means:
Take the first 10 characters of the caption (i.e. this is the text after the string @Figure: );
Spaces and single quotes (') are translated to a minus - ;
Uppercase letters translated to lowercase.
So the first artwork with a caption will get fig:a-minimal- as a reference. See for instance Figure 2 .
This anchoring is completely handled from within the xslt . Note that duplicate anchors are an XML validation error which will make xml2rfc fail.
Any paragraph like:
> quoted text
Converts to: <t><list style="empty"> ... paragraph, making it indented.
Any reference like:
[Click here](URI)
Converts to: <ulink target="URI">Click here ...
Any reference like:
[Click here](#localid)
Converts to: <link target="localid">Click here ...
For referring to RFCs (for which you manually need add the reference source in the template, with an external XML entity), you can just use:
[](#RFC2119)
And it does the right thing. Referencing sections is done with:
See [](#pandoc-constructs)
The word 'Section' is inserted automatically: ... see Section 7 ... For referencing figures/artworks see Section 7.4 . For referencing tables see Section 7.8 .
The verb style can be selected with back-tics: `text` Converts to: <spanx style="verb"> ...
And the emphasis style with asterisks: *text* or underscores: _text_ Converts to: <spanx style="emph"> ...
And the emphasis style with double asterisks: **text** Converts to: <spanx style="strong"> ...
A table can be entered as:
Right Left Center Default
------- ------ ---------- -------
12 12 12 12
123 123 123 123
1 1 1 1
Table: A caption describing the table.
Figure 3: A caption describing the figure describing the table.
Is translated to <texttable> element in xml2rfc . You can choose multiple styles as input, but they all are converted to the same style (plain <texttable> ) table in xml2rfc . The column alignment is copied over to the generated XML.
The caption is always translated to a title attribute. If a table has a caption, it will also get a reference. The reference anchor attribute will be: tab- + first 10 (normalized) characters from the caption . Where normalized means:
Take the first 10 characters of the caption (i.e. this is the text after the string Table: );
Spaces and single quotes (') are translated to a minus - ;
Uppercase letters translated to lowercase.
So the first table with a caption will get tab-a-caption- for reference use. See for instance
This anchoring is completely handled from within the xslt . Note that duplicate anchors are an XML validation error which will make xml2rfc fail.
The footnote syntax of Pandoc is slightly abused to support an index. Footnotes are entered in two steps, you have a marker in the text, and later you give actual footnote text. Like this:
[^1]
[^1]: footnote text
We re-use this syntax for the <iref> tag. The above text translates to:
<iref item="footnote text"/>
Sub items are also supported. Use an exclamation mark (! ) to separate them:
[^1]: item!sub item
As an author you will probably break up a draft in multiple files, each dealing with a subject or section. When doing so sections with the same title will clash with each other. Pandoc can deal with this situation, but only if the different sections are in the same file or processed in the same Pandoc run. Concatenating the different section files before processing them is a solution to this problem. You can, for instance, amend the Makefile and add something like this:
allsections.pdc: section.pdc.1 section.pdc.2 section.pdc.3
cat $@ > allsections.pdc
And then process allsection.pdc in the normal way.
If you use double quotes in the documents title in the docName attribute, like:
<rfc ipr="trust200902" docName="draft-gieben-writing-rfcs-pandoc-02">
The Makefile will pick this up automatically and make a symbolic link:
draft-gieben-writing-rfcs-pandoc-00.txt -> draft.txt
This makes uploading the file to the i-d tracker a bit easier.
The draft.xml target will generate an XML file with all XML included, so you can upload just one file to the I-D tracker.
If you are a VIM user you might be interested in a syntax highlighting file (see [VIM] ) that slightly lightens up your reading experience while viewing a draft.txt from VIM.
This document raises no security issues.
This document has no actions for IANA.
11. References
11.1. Informative References
11.2. Normative References
This appendix consists out of a few tests that should all render to proper xml2rfc XML.
Test a very long title.
This is discarded by xml2rfc .
This is a blockquote, how does it look?
A verbatim code block
jkasjksajassjasjsajsajkas
Refer to RFC 2119 if you will. Or maybe you want to inspect Figure 2 in Section 2 again. Or you might want to Click here .
underscores: underscores
asterisks: asterisks
double asterisks: double asterisks
backticks: backticks
First we do
And then
And the other around.
First we do
Then
Something
Another thing
Description lists:
Item to explain:
It works because of herbs.
Another item to explain:
More explaining.
lists in description lists.
Item to explain:
It works because of
One
Two
Another item to explain:
More explaining
Item to explain:
It works because of
One1
Two1
Itemize list
Another item
Another item to explain again:
More explaining
list with description lists.
More
Item to explain:
Explanation ...
Item to explain:
Another explanation ...
Go'bye
Multiple paragraphs in a list.
Artwork
This is the first bullet point and it needs multiple paragraphs...
This is the next bullet. New paragraphs should be indented with 4 four spaces.
Another item with some artwork, indented by 8 spaces.
Final item.
xml2rfc does not allow this, so the second paragraph is faked with a
<vspace blankLines='1'>
Ordered lists.
First item
Second item
A lowercase roman list:
i.
Item 1
ii.
Item 2
An uppercase roman list.
(1)
Item1
(2)
Item2
(3)
Item 3
And default list markers.
Some surrounding text, to make it look better.
First item. Use lot of text to get a real paragraphs sense. First item. Use lot of text to get a real paragraphs sense. First item. Use lot of text to get a real paragraphs sense. First item. Use lot of text to get a real paragraphs sense.
Second item. So this is the second para in your list. Enjoy;
Another item.
Text at the end.
Lowercase letters list.
First item
Second item
Uppercase letters list.
A.
First item
B.
Second item
And artwork in a description list.
miek.nl. IN NS a.miek.nl.
a.miek.nl. IN A 192.0.2.1 ; <- this is glue
Item1:
Tell something about it. Tell something about it. Tell something about it. Tell something about it. Tell something about it. Tell something about it.
Item2:
Another description
List with a sublist with a paragraph above the sublist
First Item
Second item
Third item
But what do you know
This is another list
Demonstration of simple table
syntax.
Right
Left
Center
Default
12
12
12
12
123
123
123
123
1
1
1
1
Here's the caption. It, too, may span multiple lines. This is a
multiline table. This is verbatim text.
Centered Header
Default Aligned
Right Aligned
Left Aligned
First
row
12.0
Example of a row that spans multiple lines.
Second
row
5.0
Here's another one. Note the blank line between rows.
Sample grid table.
Fruit
Price
Advantages
Bananas
$1.34
built-in wrapper
Oranges
$2.10
cures scurvy
Grid tables without a caption
Fruit
Price
Advantages
Bananas
$1.34
built-in wrapper
Oranges
$2.10
cures scurvy
This table has no caption, and therefor no reference. But you can refer to some of the other tables, with for instance:
See [](#tab-here-s-the)
Which will become "See Table 2 ".
We should also be able to refer to the table numbers directly, to say things like 'Look at Tables 1 , 2 and 3 .'
This is another example:
Another bla bla.. as (1) shows...
This is a figure
This is a figure
This is a figure
This is a figure
Figure 4: This is the caption, with text in `typewriter`. Which isnt converted to a <spanx> style, because this is copied as-is.
And how a figure that is not centered, do to using figure and not Figure .
This is a figure
This is a figure
Figure 5: A non centered figure.
Test the use of @title :
This is a figure with a title
This is a figure with a title
@title: and here it is: a title, don't mess it up *
This is a verse text This is another line
xml2rfc-2.9.6/tests/valid/list_letters.txt 0000644 0001750 0001750 00000000301 12336226773 021413 0 ustar henrik henrik 0000000 0000000 Simulating more than one paragraph in a list item using :
a. First, a short item.
b. Second, a longer list item.
And something that looks like a separate pargraph.
xml2rfc-2.9.6/tests/valid/texttable_small_all.raw.txt 0000644 0001750 0001750 00000000362 12336226773 023511 0 ustar henrik henrik 0000000 0000000 +----------+----------+
| column A | column B |
+----------+----------+
| cell 1A | cell 1B |
+----------+----------+
| cell 2A | cell 2B |
+----------+----------+
| cell 3A | cell 3B |
+----------+----------+ xml2rfc-2.9.6/tests/valid/utf8.exp.xml 0000644 0001750 0001750 00000002542 13237622212 020336 0 ustar henrik henrik 0000000 0000000
Put Your Internet Draft Title
Company
Springfield
IL
US
jdoe@example.com
Insert an abstract: MANDATORY. This template is for creating an
Internet-Draft. With some out of scope characters
in Chinese, by Xing Xing, 这里是中文译本
Text body needs to deal with funny characters
Pure out of scope 这里是中文译本
Some re-mapped characters are ¢ or ©
More re-mapped characters are ˜ and € and ^
xml2rfc-2.9.6/tests/valid/status_irtf_info_yes.nroff 0000644 0001750 0001750 00000001671 13237442436 023443 0 ustar henrik henrik 0000000 0000000 .pl 10.0i
.po 0
.ll 7.2i
.lt 7.2i
.nr LL 7.2i
.nr LT 7.2i
.hy 0
.ad l
.ds LH RFC 9999
.ds CH Abbreviated Title
.ds RH December 2010
.ds LF Doe
.ds CF Best Current Practice
.ds RF FORMFEED[Page %]
.ti 0
Status of This Memo
.in 3
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This document is a product of the Internet Research Task Force (IRTF).
The IRTF publishes the results of Internet-related research and
development activities. These results might not be suitable for
deployment. This RFC represents the consensus of the Workgroup Research
Group of the Internet Research Task Force (IRTF). Documents approved
for publication by the IRSG are not candidates for any level of
Internet Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata, and
how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc9999.
xml2rfc-2.9.6/tests/valid/status_ietf_historic_yes.txt 0000644 0001750 0001750 00000001401 13237442436 024013 0 ustar henrik henrik 0000000 0000000 Status of This Memo
This document is not an Internet Standards Track specification; it is
published for the historical record.
This document defines a Historic Document for the Internet community.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are candidates for any level of Internet
Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc9999.
xml2rfc-2.9.6/tests/valid/texttable_full.html 0000644 0001750 0001750 00000023523 13112656335 022046 0 ustar henrik henrik 0000000 0000000 Table Tester
Test #1 - table_max_chars == sum(longest_words)
12345678901
12345678901
12345678901
1234567890
1234567890
12345678901
Test #2 - table_max_chars == sum(inf)
12
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
Test #3 - table_max_chars < sum(longest_words)
Steal from columns with % and em widths
123456789012
123456789012
123456789012
123456789012
123456789012
123456789012
Steal from relative widths
123456789012
123456789012
123456789012
123456789012
123456789012
123456789012
Steam from unspecified widths
123456789012
123456789012
123456789012
123456789012
123456789012
123456789012
Test #4 - table_max_chars >= sum(ttcol_widths)
123 5678
123 5678
123 5678
123 5678
123 5678
123 5678
table_max_chars > sum(mnsc)
123 567890 2345
123 567890 234
123 567890 234
123 567890 234
123 567890 234
123 567890 234
Test #6 - table_max_chars == sum(mnsc)
123 5678901
123 5678901
123 5678901
123 567890
123 567890
123 56789
Test #7 table_max_chars > sum(mnsb)
Test #8 table_max_chars == sum(mnsb)
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
Test #9 table_max_chars > sum(mnsa)
123 567890 23456
123 567890 23456
123 567890 23456
123456789 0123456
1234567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
123 5678901 3456
Grow from max words to requested lengths
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
123 567890 23456
xml2rfc-2.9.6/tests/valid/draft-miek-test.v2v3.xml 0000644 0001750 0001750 00000127032 13241652265 022464 0 ustar henrik henrik 0000000 0000000
]>
Writing I-Ds and RFCs using Pandoc and xml2rfc 2.x
Google
123 Buckingham Palace Road
London
SW1W 9SH
UK
miek@miek.nl
http://miek.nl/
RFC Beautification Working Group
RFC
Request for Comments
I-D
Internet-Draft
XML
Pandoc
Extensible Markup Language
This memo presents a technique for using Pandoc syntax as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series.
This version is adapted to work with "xml2rfc" version 2.x.
Introduction
This document presents a technique for using Pandoc syntax as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series.
This version is adapted to work with xml2rfc version 2.x.
Pandoc is an "almost plain text" format and therefor particularly well suited for editing RFC-like documents.
Note: this document is typeset in Pandoc and does not render completely correct when reading it on github.
Pandoc to RFC
Pandoc2rfc -- designed to do the right thing, until it doesn't.
When writing xml2rfc is very "light". The latest version of xml2rfc version 2 can be found here .
During the last few years people have been developing markup languages that are very easy to remember and type. These languages have become known as almost plain text -markup languages. One of the first was the Markdown syntax. One that was developed later and incorporates Markdown and a number of extensions is Pandoc . The power of Pandoc also comes from the fact that it can be translated to numerous output formats, including, but not limited to: HTML, (plain) Markdown and docbook XML.
So using Pandoc for writing RFCs seems like a sane choice. As xml2rfc uses XML, the easiest way would be to create docbook XML and transform that using XSLT. Pandoc2rfc does just that. The conversions are, in some way amusing, as we start off with (almost) plain text, use elaborate XML and end up with plain text again.
Attempt to justify Pandoc2rfc.
| DOCBOOK |
+-------------------+ +---------+
| |
non-existent | | xsltproc
faster way | |
v v
+------------+ xml2rfc +---------+
| PLAIN TEXT | <-------- | XML2RFC |
+------------+ +---------+
]]>
The XML generated (the output after the xsltproc step in middle or back section of an RFC. The simplest way is to create a template XML file and include the appropriate XML:
A minimal template.xml.
]>
Writing I-Ds and RFCs using Pandoc v2
&pandocMiddle;
&pandocBack;
]]>
See the Makefile for an example of this. In this case you need to edit 3 documents:
middle.pdc - contains the main body of text;
back.pdc - holds appendices and references;
template.xml (probably a fairly static file).
The draft (draft.txt ) you are reading now, is automatically created when you call make . The homepage of Pandoc2rfc is this github repository .
Dependencies
It needs xsltproc and pandoc to be installed. See the Pandoc user manual for the details on how to type in Pandoc style. And ofcourse xml2rfc version two.
When using Pandoc2rfc consider adding the following sentence to an Acknowledgements section:
Starting a new project
When starting a new project with pandoc2rfc you'll need to copy the following files:
Makefile
transform.xslt
And the above mentioned files:
middle.pdc
back.pdc
template.xml
After that you can start editing.
Supported Features
Sections with an anchor and title attributes (
Lists
style=symbols (
style=numbers (
style=empty (
style=format %i, use roman lowercase numerals, (
style=format (%d), use roman uppercase numerals (
style=letters (lower- and uppercase,
style=hanging (
Figure/artwork with a title (
Block quote this is converted to <list style="empty"> paragraph (
References
external (eref) (
internal (xref) (
section (handled by Pandoc, see
figures (handled by XSLT, see
tables (handled by XSLT, see
Citations, by using internal references;
Spanx style=verb, style=emph and style=strong (
Tables with an anchor and title (
Indexes, by using footnotes (
Unsupported Features
Lists inside a table (xml2rfc doesn't handle this);
Pandoc markup in the caption for figures/artwork. Pandoc markup for table captions is supported;
crefs: for comments (no input syntax available), use HTML comments: <!-- ... --> ;
Acknowledgements
The following people have helped to make Pandoc2rfc what it is today: Benno Overeinder, Erlend Hamnaberg, Matthijs Mekking, Trygve Laugstøl.
This document was prepared using Pandoc2rfc.
Pandoc Constructs
So, what syntax do you need to use to get the correct output? Well, it is just Pandoc. The best introduction to the Pandoc style is given in this README from Pandoc itself .
For convenience we list the most important ones in the following sections.
Paragraph
Paragraphs are separated with an empty line.
Section
Just use the normal sectioning commands available in Pandoc, for instance:
Converts to: <section title="Section1 One" anchor="section1-one"> If you have another section that is also named "Section1 One", that anchor will be called "section1-one-1", but only when the sections are in the same source file!
Referencing the section is done with see [](#section1-one) , as in see
List Styles
A good number of styles are supported.
Symbol
Converts to <list style="symbol"> :
Number
Converts to <list style="numbers"> :
Item one;
Item two.
Empty
Using the default list markers from Pandoc:
Converts to <list style="empty"> :
Roman
Use the supported Pandoc syntax:
Converts to <list style="format %i."> :
Item one;
Item two.
If you use uppercase Roman numerals, they convert to a different style:
Yields <list style="format (%d) "> :
Item one;
Item two.
Letter
A numbered list.
Converts to <list style="letters"> :
Item one;
Item two.
Uppercasing the letters works too (note two spaces after the letter.
Becomes:
Item one;
Item two.
Hanging
This is more like a description list, so we need to use:
Converts to: <list style="hanging"> and <t hangText="First item that...">
If you want a newline after the hangTexts, search for the string OPTION in transform.xsl and uncomment it.
Figure/Artwork
Indent the paragraph with 4 spaces.
Converts to: <figure><artwork> ... Note that xml2rfc supports a caption with <artwork> . Pandoc does not support this, but Pandoc2rfc does. If you add a @Figure: some text as the last line, the artwork gets a title attribute with the text after @Figure: . It will also be possible to reference the artwork. If a caption is supplied the artwork will be centered. If a caption is needed but the figure should not be centered use @figure:\ .
References
The reference anchor attribute will be: fig: + first 10 (normalized) characters from the caption . Where normalized means:
Take the first 10 characters of the caption (i.e. this is the text after the string @Figure: );
Spaces and single quotes (') are translated to a minus - ;
Uppercase letters translated to lowercase.
So the first artwork with a caption will get fig:a-minimal- as a reference. See for instance
This anchoring is completely handled from within the xslt . Note that duplicate anchors are an XML validation error which will make xml2rfc fail.
Block Quote
Any paragraph like:
quoted text
]]>
Converts to: <t><list style="empty"> ... paragraph, making it indented.
References
External
Any reference like:
Converts to: <ulink target="URI">Click here ...
Internal
Any reference like:
Converts to: <link target="localid">Click here ...
For referring to RFCs (for which you manually need add the reference source in the template, with an external XML entity), you can just use:
And it does the right thing. Referencing sections is done with:
The word 'Section' is inserted automatically: ... see
Spanx Styles
The verb style can be selected with back-tics: `text` Converts to: <spanx style="verb"> ...
And the emphasis style with asterisks: *text* or underscores: _text_ Converts to: <spanx style="emph"> ...
And the emphasis style with double asterisks: **text** Converts to: <spanx style="strong"> ...
Tables
A table can be entered as:
A caption describing the figure describing the table.
Is translated to <texttable> element in xml2rfc . You can choose multiple styles as input, but they all are converted to the same style (plain <texttable> ) table in xml2rfc . The column alignment is copied over to the generated XML.
References
The caption is always translated to a title attribute. If a table has a caption, it will also get a reference. The reference anchor attribute will be: tab- + first 10 (normalized) characters from the caption . Where normalized means:
Take the first 10 characters of the caption (i.e. this is the text after the string Table: );
Spaces and single quotes (') are translated to a minus - ;
Uppercase letters translated to lowercase.
So the first table with a caption will get tab-a-caption- for reference use. See for instance
This anchoring is completely handled from within the xslt . Note that duplicate anchors are an XML validation error which will make xml2rfc fail.
Indexes
The footnote syntax of Pandoc is slightly abused to support an index. Footnotes are entered in two steps, you have a marker in the text, and later you give actual footnote text. Like this:
We re-use this syntax for the <iref> tag. The above text translates to:
]]>
Sub items are also supported. Use an exclamation mark (! ) to separate them:
Usage guidelines
Working with multiple files
As an author you will probably break up a draft in multiple files, each dealing with a subject or section. When doing so sections with the same title will clash with each other. Pandoc can deal with this situation, but only if the different sections are in the same file or processed in the same Pandoc run. Concatenating the different section files before processing them is a solution to this problem. You can, for instance, amend the Makefile and add something like this:
allsections.pdc
]]>
And then process allsection.pdc in the normal way.
Setting the title
If you use double quotes in the documents title in the docName attribute, like:
]]>
The Makefile will pick this up automatically and make a symbolic link:
draft.txt
]]>
This makes uploading the file to the i-d tracker a bit easier.
Uploading the XML/txt
The draft.xml target will generate an XML file with all XML included, so you can upload just one file to the I-D tracker.
VIM syntax highlighting
If you are a VIM user you might be interested in a syntax highlighting file (see
Security Considerations
This document raises no security issues.
IANA Considerations
This document has no actions for IANA.
Informative References
VIM syntax file for RFCs and I-Ds
Atoom Inc.
miek@miek.nl
Normative References
Key words for use in RFCs to Indicate Requirement Levels
Harvard University
1350 Mass. Ave.
Cambridge
MA 02138
- +1 617 495 3864
sob@harvard.edu
keyword
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. Authors who follow these guidelines should incorporate this phrase near the beginning of their document:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Note that the force of these words is modified by the requirement level of the document in which they are used.
DNSSEC Operational Practices
This document describes a set of practices for operating the DNS with security extensions (DNSSEC). The target audience is zone administrators deploying DNSSEC.</t><t> The document discusses operational aspects of using keys and signatures in the DNS. It discusses issues of key generation, key storage, signature generation, key rollover, and related policies.</t><t> This document obsoletes RFC 2541, as it covers more operational ground and gives more up-to-date requirements with respect to key sizes and the new DNSSEC specification. This memo provides information for the Internet community.
Tests
This appendix consists out of a few tests that should all render to proper xml2rfc XML.
A Very Long Title Considerations With Regards to the Already Deployed Routing Policy
Test a very long title.
Markup in heading
This is discarded by xml2rfc .
Blockquote
This is a blockquote, how does it look?
Reference Tests
Refer to RFC 2119 if you will. Or maybe you want to inspect Click here .
Spanx Tests
underscores: underscores
asterisks: asterisks
double asterisks: double asterisks
backticks: backticks
List Tests
First we do
And then
And the other around.
First we do
Then
Something
Another thing
Description lists:
Item to explain:
It works because of herbs.
Another item to explain:
More explaining.
Multiple paragraphs in such a list.
lists in description lists.
Item to explain:
It works because of
One
Two
Another item to explain:
More explaining
Item to explain:
It works because of
One1
Two1
Itemize list
Another item
Another item to explain again:
More explaining
list with description lists.
More
Item to explain:
Explanation ...
Item to explain:
Another explanation ...
Go'bye
Multiple paragraphs in a list.
This is the first bullet point and it needs multiple paragraphs...
... to be explained properly.
This is the next bullet. New paragraphs should be indented with 4 four spaces.
Another item with some artwork, indented by 8 spaces.
Final item.
xml2rfc does not allow this, so the second paragraph is faked with a
]]>
Ordered lists.
First item
Second item
A lowercase roman list:
Item 1
Item 2
An uppercase roman list.
Item1
Item2
Item 3
And default list markers.
Some surrounding text, to make it look better.
First item. Use lot of text to get a real paragraphs sense. First item. Use lot of text to get a real paragraphs sense. First item. Use lot of text to get a real paragraphs sense. First item. Use lot of text to get a real paragraphs sense.
Second item. So this is the second para in your list. Enjoy;
Another item.
Text at the end.
Lowercase letters list.
First item
Second item
Uppercase letters list.
First item
Second item
And artwork in a description list.
Item1:
Tell something about it. Tell something about it. Tell something about it. Tell something about it. Tell something about it. Tell something about it.
Tell some more about it. Tell some more about it. Tell some more about it.
Item2:
Another description
List with a sublist with a paragraph above the sublist
First Item
Second item
Third item
A paragraph that comes first
But what do you know
This is another list
Table Tests
Demonstration of simple table
syntax.
Right
Left
Center
Default
12
12
12
12
123
123
123
123
1
1
1
1
Here's the caption. It, too, may span multiple lines. This is a
multiline table. This is verbatim text.
Centered Header
Default Aligned
Right Aligned
Left Aligned
First
row
12.0
Example of a row that spans multiple lines.
Second
row
5.0
Here's another one. Note the blank line between rows.
Sample grid table.
Fruit
Price
Advantages
Bananas
$1.34
built-in wrapper
Oranges
$2.10
cures scurvy
Grid tables without a caption
Fruit
Price
Advantages
Bananas
$1.34
built-in wrapper
Oranges
$2.10
cures scurvy
This table has no caption, and therefor no reference. But you can refer to some of the other tables, with for instance:
Which will become "See
We should also be able to refer to the table numbers directly, to say things like 'Look at Tables
Numbered examples
This is another example:
Another bla bla..
as (1) shows...
Figure tests
This is the caption, with text in `typewriter`. Which isnt converted to a <spanx> style, because this is copied as-is.
And how a figure that is not centered, do to using figure and not Figure .
A non centered figure.
Test the use of @title :
Verse tests
This is a verse text This is another line
xml2rfc-2.9.6/tests/valid/status_ietf_bcp_yes.nroff 0000644 0001750 0001750 00000001370 12336226773 023236 0 ustar henrik henrik 0000000 0000000 .pl 10.0i
.po 0
.ll 7.2i
.lt 7.2i
.nr LL 7.2i
.nr LT 7.2i
.hy 0
.ad l
.ds LH RFC 9999
.ds CH Abbreviated Title
.ds RH December 2010
.ds LF Doe
.ds CF Best Current Practice
.ds RF FORMFEED[Page %]
.ti 0
Status of This Memo
.in 3
This memo documents an Internet Best Current Practice.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on BCPs
is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata, and
how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc9999. xml2rfc-2.9.6/tests/valid/top_draft.txt 0000644 0001750 0001750 00000001141 12336226773 020663 0 ustar henrik henrik 0000000 0000000
Network Working Group J. Doe, Ed.
Internet-Draft Company
Intended status: Informational J. Roe
Expires: June 13, 2011
D. Doe
P. Coe
Q. Coe
Company
December 10, 2010
xml2rfc-2.9.6/tests/valid/slashbreak.raw.txt 0000644 0001750 0001750 00000001162 13113036121 021567 0 ustar henrik henrik 0000000 0000000 The RFC Editor has asked that we provide a list of items for which
there will never be a break around the slash. The test says that
PDF/A and S/MIME should not be broken when they occur.
We also deal with the possiblity of some long items such as
this/is/a/long/test which will not break either. We only match exact
items however so PDF/A/3 will be broken as the algorithm currently
stands.
What about addresses: 192.168.20.0/16, 192.168.0.0/24,
192.168.0.0/30, and prefix length indications like /48 /56 /64 /72
/80 /88 /96 and so on? These should not be broken after the forward
slash.
xml2rfc-2.9.6/tests/valid/texttable_full.nroff 0000644 0001750 0001750 00000012216 12336226773 022217 0 ustar henrik henrik 0000000 0000000 .in 3
Table\0Tester
.in 0
.nf
+--------------+--------+--------------------------+
| C1 | C2 | C3 |
+--------------+--------+--------------------------+
| 12 | 12 | 12 |
+--------------+--------+--------------------------+
.fi
.in 3
.in 0
.nf
+------------------+-----------+------------------------------------+
| C1 | C2 | C3 |
+------------------+-----------+------------------------------------+
| 12 | 12 | 12 |
+------------------+-----------+------------------------------------+
.fi
.in 3
.in 0
.nf
+----+----+----+
| C1 | C2 | C3 |
+----+----+----+
| 12 | 12 | 12 |
+----+----+----+
.fi
.in 3
Test #1 \%- table_max_chars == sum(longest_words)
.in 0
.nf
12345678901 12345678901 12345678901 1234567890 1234567890 12345678901
.fi
.in 3
Test #2 \%- table_max_chars == sum(inf)
.in 0
.nf
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
2
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
.fi
.in 3
Test #3 \%- table_max_chars < sum(longest_words)
.in 0
.nf
+-------+----------+-----------+-----------+-----------+------------+
| 12345 | 12345678 | 123456789 | 123456789 | 123456789 | 1234567890 |
| 67890 | 9012 | 012 | 012 | 012 | 12 |
| 12 | | | | | |
+-------+----------+-----------+-----------+-----------+------------+
.fi
.in 3
.ce 1
Steal from columns with % and em widths
.in 0
.nf
+--------+----------+-----------+----------+-----------+------------+
| 123456 | 12345678 | 123456789 | 12345678 | 123456789 | 1234567890 |
| 789012 | 9012 | 012 | 9012 | 012 | 12 |
+--------+----------+-----------+----------+-----------+------------+
.fi
.in 3
.ce 1
Steal from relative widths
.in 0
.nf
+----------+----------+----------+----------+-----------+-----------+
| 12345678 | 12345678 | 12345678 | 12345678 | 123456789 | 123456789 |
| 9012 | 9012 | 9012 | 9012 | 012 | 012 |
+----------+----------+----------+----------+-----------+-----------+
.fi
.in 3
.ce 1
Steam from unspecified widths
Test #4 \%- table_max_chars >= sum(ttcol_widths)
.in 0
.nf
+----------+----------+----------+----------+----------+----------+
| 123 5678 | 123 5678 | 123 5678 | 123 5678 | 123 5678 | 123 5678 |
+----------+----------+----------+----------+----------+----------+
.fi
.in 3
table_max_chars > sum(mnsc)
.in 0
.nf
+----------+----------+----------+----------+-----------+-----------+
| 123 | 123 | 123 | 123 | 123 | 123 |
| 567890 | 567890 | 567890 | 567890 | 567890 | 567890 |
| 2345 | 234 | 234 | 234 | 234 | 234 |
+----------+----------+----------+----------+-----------+-----------+
.fi
.in 3
Test #6 \%- table_max_chars == sum(mnsc)
.in 0
.nf
123 5678901 123 5678901 123 5678901 123 567890 123 567890 123 56789
.fi
.in 3
Test #7 table_max_chars > sum(mnsb)
.in 0
.nf
------------- ---------- ----------- ---------- ---------- ----------
123 5678901 123 123 5678901 123 567890 123 567890 123 567890
5678901
.fi
.in 3
Test #8 table_max_chars == sum(mnsb)
.in 0
.nf
+-----------+-----------+-----------+-----------+----------+--------+
| 123 | 123 | 123 | 123 | 123 | 123 |
| 567890 | 567890 | 567890 | 567890 | 567890 | 567890 |
| 23456 | 23456 | 23456 | 23456 | 23456 | 23456 |
+-----------+-----------+-----------+-----------+----------+--------+
.fi
.in 3
Test #9 table_max_chars > sum(mnsa)
.in 0
.nf
+----------+----------+--------+-----------+------------+-----------+
| 123 | 123 | 123 | 123456789 | 1234567890 | 123 |
| 567890 | 567890 | 567890 | 0123456 | 23456 | 567890 |
| 23456 | 23456 | 23456 | | | 23456 |
+----------+----------+--------+-----------+------------+-----------+
.fi
.in 3
.in 0
.nf
+------------+-----------+-----------+-----------+--------+---------+
| 123 567890 | 123 | 123 | 123 | 123 | 123 |
| 23456 | 567890 | 567890 | 567890 | 567890 | 5678901 |
| | 23456 | 23456 | 23456 | 23456 | 3456 |
+------------+-----------+-----------+-----------+--------+---------+
.fi
.in 3
Grow from max words to requested lengths
.in 0
.nf
+-----------+----------+-----------+-----------+-----------+--------+
| 123 | 123 | 123 | 123 | 123 | 123 |
| 567890 | 567890 | 567890 | 567890 | 567890 | 567890 |
| 23456 | 23456 | 23456 | 23456 | 23456 | 23456 |
+-----------+----------+-----------+-----------+-----------+--------+
.fi
.in 3 xml2rfc-2.9.6/tests/valid/rfc7911.txt 0000644 0001750 0001750 00000042233 13151606075 017775 0 ustar henrik henrik 0000000 0000000
Internet Engineering Task Force (IETF) D. Walton
Request for Comments: 7911 Cumulus Networks
Category: Standards Track A. Retana
ISSN: 2070-1721 E. Chen
Cisco Systems, Inc.
J. Scudder
Juniper Networks
July 2016
Advertisement of Multiple Paths in BGP
Abstract
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. The essence of the extension
is that each path is identified by a Path Identifier in addition to
the address prefix.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7911.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Walton, et al. Standards Track [Page 1]
RFC 7911 ADD-PATH July 2016
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Specification of Requirements . . . . . . . . . . . . . . 2
2. How to Identify a Path . . . . . . . . . . . . . . . . . . . 3
3. Extended NLRI Encodings . . . . . . . . . . . . . . . . . . . 3
4. ADD-PATH Capability . . . . . . . . . . . . . . . . . . . . . 4
5. Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 4
6. Deployment Considerations . . . . . . . . . . . . . . . . . . 5
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
8. Security Considerations . . . . . . . . . . . . . . . . . . . 6
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
9.1. Normative References . . . . . . . . . . . . . . . . . . 6
9.2. Informative References . . . . . . . . . . . . . . . . . 7
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction
The BGP specification [RFC4271] defines an Update-Send Process to
advertise the routes chosen by the Decision Process to other BGP
speakers. No provisions are made to allow the advertisement of
multiple paths for the same address prefix or Network Layer
Reachability Information (NLRI). In fact, a route with the same NLRI
as a previously advertised route implicitly replaces the previous
advertisement.
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. The essence of the extension
is that each path is identified by a Path Identifier in addition to
the address prefix.
The availability of the additional paths can help reduce or eliminate
persistent route oscillations [RFC3345]. It can also help with
optimal routing and routing convergence in a network by providing
potential alternate or backup paths, respectively.
1.1. Specification of Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Walton, et al. Standards Track [Page 2]
RFC 7911 ADD-PATH July 2016
2. How to Identify a Path
As defined in [RFC4271], a path refers to the information reported in
the Path Attribute field of an UPDATE message. As the procedures
specified in [RFC4271] allow only the advertisement of one path for a
particular address prefix, a path for an address prefix from a BGP
peer can be keyed on the address prefix.
In order for a BGP speaker to advertise multiple paths for the same
address prefix, a new identifier (termed "Path Identifier" hereafter)
needs to be introduced so that a particular path for an address
prefix can be identified by the combination of the address prefix and
the Path Identifier.
The assignment of the Path Identifier for a path by a BGP speaker is
purely a local matter. However, the Path Identifier MUST be assigned
in such a way that the BGP speaker is able to use the (Prefix, Path
Identifier) to uniquely identify a path advertised to a neighbor. A
BGP speaker that re-advertises a route MUST generate its own Path
Identifier to be associated with the re-advertised route. A BGP
speaker that receives a route should not assume that the identifier
carries any particular semantics.
3. Extended NLRI Encodings
In order to carry the Path Identifier in an UPDATE message, the NLRI
encoding MUST be extended by prepending the Path Identifier field,
which is of four octets.
For example, the NLRI encoding specified in [RFC4271] is extended as
the following:
+--------------------------------+
| Path Identifier (4 octets) |
+--------------------------------+
| Length (1 octet) |
+--------------------------------+
| Prefix (variable) |
+--------------------------------+
The usage of the extended NLRI encodings is specified in Section 5.
Walton, et al. Standards Track [Page 3]
RFC 7911 ADD-PATH July 2016
4. ADD-PATH Capability
The ADD-PATH Capability is a BGP capability [RFC5492], with
Capability Code 69. The Capability Length field of this capability
is variable. The Capability Value field consists of one or more of
the following tuples:
+------------------------------------------------+
| Address Family Identifier (2 octets) |
+------------------------------------------------+
| Subsequent Address Family Identifier (1 octet) |
+------------------------------------------------+
| Send/Receive (1 octet) |
+------------------------------------------------+
The meaning and use of the fields are as follows:
Address Family Identifier (AFI):
This field is the same as the one used in [RFC4760].
Subsequent Address Family Identifier (SAFI):
This field is the same as the one used in [RFC4760].
Send/Receive:
This field indicates whether the sender is (a) able to receive
multiple paths from its peer (value 1), (b) able to send
multiple paths to its peer (value 2), or (c) both (value 3) for
the .
If any other value is received, then the capability SHOULD be
treated as not understood and ignored [RFC5492].
A BGP speaker that wishes to indicate support for multiple AFI/SAFIs
MUST do so by including the information in a single instance of the
ADD-PATH Capability.
5. Operation
The Path Identifier specified in Section 3 can be used to advertise
multiple paths for the same address prefix without subsequent
advertisements replacing the previous ones. Apart from the fact that
this is now possible, the route advertisement rules of [RFC4271] are
not changed. In particular, a new advertisement for a given address
prefix and a given Path Identifier replaces a previous advertisement
for the same address prefix and Path Identifier. If a BGP speaker
Walton, et al. Standards Track [Page 4]
RFC 7911 ADD-PATH July 2016
receives a message to withdraw a prefix with a Path Identifier not
seen before, it SHOULD silently ignore it.
For a BGP speaker to be able to send multiple paths to its peer, that
BGP speaker MUST advertise the ADD-PATH Capability with the Send/
Receive field set to either 2 or 3, and MUST receive from its peer
the ADD-PATH Capability with the Send/Receive field set to either 1
or 3, for the corresponding .
A BGP speaker MUST follow the procedures defined in [RFC4271] when
generating an UPDATE message for a particular to a peer
unless the BGP speaker advertises the ADD-PATH Capability to the peer
indicating its ability to send multiple paths for the ,
and also receives the ADD-PATH Capability from the peer indicating
its ability to receive multiple paths for the , in which
case the speaker MUST generate a route update for the
based on the combination of the address prefix and the Path
Identifier, and use the extended NLRI encodings specified in this
document. The peer SHALL act accordingly in processing an UPDATE
message related to a particular .
A BGP speaker SHOULD include the best route [RFC4271] when more than
one path is advertised to a neighbor, unless it is a path received
from that neighbor.
As the Path Identifiers are locally assigned, and may or may not be
persistent across a control plane restart of a BGP speaker, an
implementation SHOULD take special care so that the underlying
forwarding plane of a "Receiving Speaker" as described in [RFC4724]
is not affected during the graceful restart of a BGP session.
6. Deployment Considerations
The extension proposed in this document provides a mechanism for a
BGP speaker to advertise multiple paths over a BGP session. Care
needs to be taken in its deployment to ensure consistent routing and
forwarding in a network [ADDPATH].
The only explicit indication that the encoding described in Section 3
is in use in a particular BGP session is the exchange of Capabilities
described in Section 4. If the exchange is successful [RFC5492],
then the BGP speakers will be able to process all BGP UPDATES
properly, as described in Section 5. However, if, for example, a
packet analyzer is used on the wire to examine an active BGP session,
it may not be able to properly decode the BGP UPDATES because it
lacks prior knowledge of the exchanged Capabilities.
Walton, et al. Standards Track [Page 5]
RFC 7911 ADD-PATH July 2016
When deployed as a provider edge router or a peering router that
interacts with external neighbors, a BGP speaker usually advertises
at most one path to the internal neighbors in a network. In the case
where the speaker is configured to advertise multiple paths to the
internal neighbors, and additional information is needed for the
application, the speaker could use attributes such as the
Edge_Discriminator attribute [FAST]. The use of that type of
additional information is outside the scope of this document.
7. IANA Considerations
IANA has assigned the value 69 for the ADD-PATH Capability described
in this document. This registration is in the "Capability Codes"
registry.
8. Security Considerations
This document defines a BGP extension that allows the advertisement
of multiple paths for the same address prefix without the new paths
implicitly replacing any previous ones. As a result, multiple paths
for a large number of prefixes may be received by a BGP speaker,
potentially depleting memory resources or even causing network-wide
instability, which can be considered a denial-of-service attack.
Note that this is not a new vulnerability, but one that is present in
the base BGP specification [RFC4272].
The use of the ADD-PATH Capability is intended to address specific
needs related to, for example, eliminating route oscillations that
were induced by the MULTI_EXIT_DISC (MED) attribute [STOP-OSC].
While describing the applications for the ADD-PATH Capability is
outside the scope of this document, users are encouraged to examine
their behavior and potential impact by studying the best practices
described in [ADDPATH].
Security concerns in the base operation of BGP [RFC4271] also apply.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
Walton, et al. Standards Track [Page 6]
RFC 7911 ADD-PATH July 2016
[RFC4271] Rekhter, Y., Ed., Li, T., Ed., and S. Hares, Ed., "A
Border Gateway Protocol 4 (BGP-4)", RFC 4271,
DOI 10.17487/RFC4271, January 2006,
.
[RFC4760] Bates, T., Chandra, R., Katz, D., and Y. Rekhter,
"Multiprotocol Extensions for BGP-4", RFC 4760,
DOI 10.17487/RFC4760, January 2007,
.
[RFC5492] Scudder, J. and R. Chandra, "Capabilities Advertisement
with BGP-4", RFC 5492, DOI 10.17487/RFC5492, February
2009, .
9.2. Informative References
[ADDPATH] Uttaro, J., Francois, P., Patel, K., Haas, J., Simpson,
A., and R. Fragassi, "Best Practices for Advertisement of
Multiple Paths in IBGP", Work in Progress, draft-ietf-idr-
add-paths-guidelines-08, April 2016.
[FAST] Mohapatra, P., Fernando, R., Filsfils, C., and R. Raszuk,
"Fast Connectivity Restoration Using BGP Add-path", Work
in Progress, draft-pmohapat-idr-fast-conn-restore-03,
January 2013.
[RFC3345] McPherson, D., Gill, V., Walton, D., and A. Retana,
"Border Gateway Protocol (BGP) Persistent Route
Oscillation Condition", RFC 3345, DOI 10.17487/RFC3345,
August 2002, .
[RFC4272] Murphy, S., "BGP Security Vulnerabilities Analysis",
RFC 4272, DOI 10.17487/RFC4272, January 2006,
.
[RFC4724] Sangli, S., Chen, E., Fernando, R., Scudder, J., and Y.
Rekhter, "Graceful Restart Mechanism for BGP", RFC 4724,
DOI 10.17487/RFC4724, January 2007,
.
[STOP-OSC]
Walton, D., Retana, A., Chen, E., and J. Scudder, "BGP
Persistent Route Oscillation Solutions", Work in
Progress, draft-ietf-idr-route-oscillation-stop-03, April
2016.
Walton, et al. Standards Track [Page 7]
RFC 7911 ADD-PATH July 2016
Acknowledgments
We would like to thank David Cook and Naiming Shen for their
contributions to the design and development of the extension.
Many people have made valuable comments and suggestions, including
Rex Fernando, Eugene Kim, Danny McPherson, Dave Meyer, Pradosh
Mohapatra, Keyur Patel, Robert Raszuk, Eric Rosen, Srihari Sangli,
Dan Tappan, Mark Turner, Jeff Haas, Jay Borkenhagen, Mach Chen, Denis
Ovsienko, Carlos Pignataro, Meral Shirazipour, and Kathleen Moriarty.
Authors' Addresses
Daniel Walton
Cumulus Networks
185 E. Dana Street
Mountain View, CA 94041
United States of America
Email: dwalton@cumulusnetworks.com
Alvaro Retana
Cisco Systems, Inc.
Kit Creek Rd.
Research Triangle Park, NC 27709
United States of America
Email: aretana@cisco.com
Enke Chen
Cisco Systems, Inc.
170 W. Tasman Dr.
San Jose, CA 95134
United States of America
Email: enkechen@cisco.com
John Scudder
Juniper Networks
1194 N. Mathilda Ave
Sunnyvale, CA 94089
United States of America
Email: jgs@juniper.net
Walton, et al. Standards Track [Page 8]
xml2rfc-2.9.6/tests/valid/texttable_small_none.txt 0000644 0001750 0001750 00000000124 12336226774 023105 0 ustar henrik henrik 0000000 0000000 column A column B
cell 1A cell 1B
cell 2A cell 2B
cell 3A cell 3B xml2rfc-2.9.6/tests/valid/utf8.v2v3.xml 0000644 0001750 0001750 00000002503 13237622212 020337 0 ustar henrik henrik 0000000 0000000
Put Your Internet Draft Title
Company
Springfield
IL
US
jdoe@example.com
Insert an abstract: MANDATORY. This template is for creating an
Internet-Draft. With some out of scope characters
in Chinese, by Xing Xing, 这里是中文译本
Some unicode strings
Text body needs to deal with funny characters
Pure out of scope 这里是中文译本
Some re-mapped characters are ¢ or ©
More re-mapped characters are ˜ and € and ^
xml2rfc-2.9.6/tests/valid/rfc6635.txt 0000644 0001750 0001750 00000136051 13237442436 020005 0 ustar henrik henrik 0000000 0000000
Internet Architecture Board (IAB) O. Kolkman, Ed.
Request for Comments: 6635
Obsoletes: 5620 J. Halpern, Ed.
Category: Informational Ericsson
ISSN: 2070-1721 IAB
June 2012
RFC Editor Model (Version 2)
Abstract
The RFC Editor model described in this document divides the
responsibilities for the RFC Series into three functions: the RFC
Series Editor, the RFC Production Center, and the RFC Publisher.
Internet Architecture Board (IAB) oversight via the RFC Series
Oversight Committee (RSOC) is described, as is the relationship
between the IETF Administrative Oversight Committee (IAOC) and the
RSOC. This document reflects the experience gained with "RFC Editor
Model (Version 1)", documented in RFC 5620, and obsoletes that
document.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This document is a product of the Internet Architecture Board (IAB)
and represents information that the IAB has deemed valuable to
provide for permanent record. Documents approved for publication by
the IAB are not candidates for any level of Internet Standard; see
Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6635.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document.
Kolkman, et al. Informational [Page 1]
RFC 6635 RFC Editor Model (Version 2) June 2012
Table of Contents
1. Introduction ....................................................3
1.1. The RFC Editor Function ....................................3
2. RFC Editor Model ................................................4
2.1. RFC Series Editor ..........................................7
2.1.1. Strategic Leadership and Management of the
Publication and Production Functions ................8
2.1.2. Representation of the RFC Series ....................8
2.1.2.1. Representation to the IETF .................8
2.1.2.1.1. Volunteerism ....................9
2.1.2.1.2. Policy Authority ................9
2.1.2.2. External Representation ....................9
2.1.3. Development of RFC Production and Publication ......10
2.1.4. Development of the RFC Series ......................10
2.1.5. Workload ...........................................11
2.1.6. Qualifications .....................................11
2.1.7. Conflict of Interest ...............................12
2.2. RFC Production Center .....................................12
2.3. RFC Publisher .............................................13
3. Committees .....................................................14
3.1. RFC Series Oversight Committee (RSOC) .....................14
3.1.1. RSOC Composition ...................................15
4. Administrative Implementation ..................................16
4.1. Vendor Selection for the Production and Publisher
Functions .................................................17
4.2. Budget ....................................................17
4.3. Disagreements among Entities Related to the RFC Editor ....18
4.4. Issues with Contractual Impact ............................19
5. IANA Considerations ............................................19
6. Security Considerations ........................................19
7. Acknowledgments ................................................20
8. References .....................................................21
8.1. Normative References ......................................21
8.2. Informative References ....................................21
Kolkman, et al. Informational [Page 2]
RFC 6635 RFC Editor Model (Version 2) June 2012
1. Introduction
The IAB, on behalf of the Internet technical community, is concerned
with ensuring the continuity of the RFC Series, orderly RFC Editor
succession, RFC quality, and RFC document accessibility. The IAB is
also sensitive to the concerns of the IETF Administrative Oversight
Committee (IAOC) about providing the necessary services in a cost-
effective and efficient manner.
The contemporary RFC Editor model [RFC5620] was first approved in
October 2008, and our understanding of the model has evolved with our
experience since. During the implementation of version 1 of the
model [RFC5620], it was quickly realized that the role of the RFC
Series Editor (RSE) and the oversight responsibilities needed to be
structured differently. In order to gain experience with "running
code", a transitional RSE was hired who analyzed the managerial
environment and provided recommendations. This was followed by the
appointment of an acting RSE, who ably managed the series while work
was undertaken to select and hire a permanent RSE. This version of
the model is based on the recommendations of both temporary RFC
Series Editors and the extensive discussion in the IETF community, on
the rfc-interest list, and within the IAB. As such, this document
obsoletes [RFC5620].
This document, and the resulting structures, will be modified as
needed through normal procedures. The RSE, and the IAB, through the
RFC Oversight Committee (see Section 3.1), will continue to monitor
discussions within the community about potential adjustments to the
RFC Editor model and recognize that the process described in this
document may need to be adjusted to align with any changes that
result from such discussions; hence, the version number in the title.
The IAB and IAOC maintain their chartered responsibility as defined
in [RFC2850] and [RFC4071].
1.1. The RFC Editor Function
The RFC Series is described in [RFC4844]. Its Section 3.1 defines
"RFC Editor":
Originally, there was a single person acting as editor of the RFC
Series (the RFC Editor). The task has grown, and the work now
requires the organized activity of several experts, so there are
RFC Editors, or an RFC Editor organization. In time, there may be
multiple organizations working together to undertake the work
required by the RFC Series. For simplicity's sake, and without
Kolkman, et al. Informational [Page 3]
RFC 6635 RFC Editor Model (Version 2) June 2012
attempting to predict how the role might be subdivided among them,
this document refers to this collection of experts and
organizations as the "RFC Editor".
The RFC Editor is an expert technical editor and series editor,
acting to support the mission of the RFC Series. As such, the RFC
Editor is the implementer handling the editorial management of the
RFC Series, in accordance with the defined processes. In
addition, the RFC Editor is expected to be the expert and prime
mover in discussions about policies for editing, publishing, and
archiving RFCs.
RFC 4844 does not explore the internal organization of the RFC
Editor. However, RFC 4844 envisions changes in the RFC Editor
organizational structure. There have been several iterations on
efforts to improve and clarify this structure. These have been led
by the IAB, in consultation with the community and many leadership
bodies within the community. This first resulted in the publication
of [RFC5620] and then in further discussions leading to this
document. Some of the details on this evolution can be found below.
In undertaking this evolution, the IAB considered changes that
increase flexibility and operational support options, provide for the
orderly succession of the RFC Editor, and ensure the continuity of
the RFC Series, while maintaining RFC quality, maintaining timely
processing, ensuring document accessibility, reducing costs, and
increasing cost transparency. The model set forth below describes
the internal organization of the RFC Editor, while remaining
consistent with RFC 4844.
Note that RFC 4844 uses the term "RFC Editor function" or "RFC
Editor" as the collective set of responsibilities for which this memo
provides a model for internal organization. This memo defines the
term "RFC Series Editor" or "Series Editor" for one of the
organizational components.
2. RFC Editor Model
The RFC Editor model divides the responsibilities for the RFC Series
into the following components:
o RFC Series Editor (RSE)
o RFC Production Center
o RFC Publisher
Kolkman, et al. Informational [Page 4]
RFC 6635 RFC Editor Model (Version 2) June 2012
The structure and relationship of the components of the RFC Series
production and process is schematically represented by the figure
below. The picture does not depict oversight and escalation
relations. It does include the streams and their managers (which are
not part of the RFC Series Editor, the RFC Production Center, or
Publisher facilities) in order to more fully show the context in
which the RFC Series Editor operates.
Kolkman, et al. Informational [Page 5]
RFC 6635 RFC Editor Model (Version 2) June 2012
+-------------+
| |
+--------------+ IAB <------------+
| | | |
| |=============| |
| | | |
| | RSOC <------------+
| | | |
| +-------+-----+ +-----+-----+
| | | |
| +...........|.........+ | Community |
| . | . | at |
| . +-------V-----+ . | Large |
| . | | . | |
| . | RFC | . +-----+-----+
| . | Series | . |
| . | Editor <------------+
| . | | .
| . +-+---------+-+ .
| . | | .
+-------------+ +-----V-------+ . +--V--+ +--V--+ . +-----+
| | | | . | | | | . | |
| Independent | | Independent | . | RFC | | | . | E |
| Authors +--> Submission +-----> | | | . | n |
| | | Editor | . | P | | | . | d |
| | | | . | r | | RFC | . | |
+-------------+ +-------------+ . | o | | | . | U |
+-------------+ +-------------+ . | d | | P | . | s |
| | | | . | u | | u | . | e |
| IAB +--> IAB +-----> c | | b | . | r |
| | | | . | t | | l | . | s |
+-------------+ +-------------+ . | i +---> i +--------> |
+-------------+ +-------------+ . | o | | s | . | & |
| | | | . | n | | h | . | |
| IRTF +--> IRSG +---->| | | e | . | R |
| | | | . | C | | r | . | e |
+-------------+ +-------------+ . | e | | | . | a |
+-------------+ +-------------+ . | n | | | . | d |
| | | | . | t | | | . | e |
| IETF +--> IESG +-----> e | | | . | r |
| | | | . | r | | | . | s |
+-------------+ +-------------+ . +-----+ +-----+ . +-----+
. .
+..... RFC Editor ....+
Structure of RFC Series Production and Process
Figure 1
Kolkman, et al. Informational [Page 6]
RFC 6635 RFC Editor Model (Version 2) June 2012
In this model, documents are produced and approved through multiple
document streams. The stream manager for each stream is responsible
for the content of that stream. The four streams that now exist are
described in [RFC4844]. The RFC Editor function is responsible for
the packaging and distribution of the documents. As such, documents
from these streams are edited and processed by the Production Center
and published by the Publisher. The RFC Series Editor will exercise
strategic leadership and management over the activities of the RFC
Publisher and the RFC Production Center (both of which can be seen as
back-office functions) and will be the entity that:
o Represents the RFC Series and the RFC Editor Function within the
IETF and externally.
o Leads the community in the design of improvements to the RFC
Series.
o Is responsible for planning and seeing to the execution of
improvements in the RFC Editor production and access processes.
o Is responsible for the content of the rfc-editor.org web site,
which is operated and maintained by the RFC Publisher.
o Is responsible for developing consensus versions of vision and
policy documents. These documents will be reviewed by the RFC
Series Oversight Committee (Section 3.1) and subject to its
approval before final publication.
These responsibilities are defined below, although the specific work
items under them are a matter for the actual employment contract and
its Statement of Work (SOW).
The IAB and IAOC maintain their chartered responsibility as defined
in [RFC2850] and [RFC4071]. More details on the oversight by the IAB
via the RFC Series Oversight Committee (RSOC) can be found in
Section 3.1. For example, the RSE does not have the direct authority
to hire or fire RFC Editor contractors or personnel.
2.1. RFC Series Editor
The RFC Series Editor is the individual with overall responsibility
for the quality, continuity, and evolution of the RFC Series.
The RSE is appointed by the IAB, but formally hired by the IAOC. The
IAB delegates the direct oversight over the RSE to the RSOC, which it
appoints.
Kolkman, et al. Informational [Page 7]
RFC 6635 RFC Editor Model (Version 2) June 2012
The RSE is expected to cooperate closely with the IAOC and the stream
managers.
2.1.1. Strategic Leadership and Management of the Publication and
Production Functions
With respect to the RFC Publisher and Production Center functions,
the RSE provides input to the IASA budget, SOWs, and manages vendor
selection processes. The RSE performs annual reviews of the RFC
Production Center and Publisher function, which are then provided to
the RSOC, the IASA, and the community. Normally, private financial
details would not be included in a public version unless the IAOC
concludes it is necessary to make such information public.
The RSE is responsible for the performance of the RFC Production
Center and Publisher. The RSE is responsible for issues that go
beyond the RFC Production Center or Publisher functions, such as
cross-stream coordination of priorities. Issues that require changes
to the budget or contracts shall be brought to the attention of the
IAD by the RSE.
The RSE is also responsible for creating documentation and structures
that will allow for continuity of the RFC Series in the face of
changes in contracts and personnel.
Vendor selection for the RFC Production Center and Publisher
functions is done in cooperation with the streams and under final
authority of the IASA. Details on this process can be found in
Section 4.1.
2.1.2. Representation of the RFC Series
The RSE is the primary representative of the RFC Series. This
representation is important both internally, relative to the IETF,
and externally.
2.1.2.1. Representation to the IETF
The RSE is the primary point of contact to the IETF on matters
relating to the RFC Series in general, or policy matters relating to
specific documents. Issues of practical details in the processing of
specific documents are generally worked through directly with the RFC
Production Center staff.
This includes providing suitable reports to the community at large,
providing email contact for policy questions and inputs, and enabling
and participating in suitable on-line forums for discussion of issues
related to the RFC Series.
Kolkman, et al. Informational [Page 8]
RFC 6635 RFC Editor Model (Version 2) June 2012
Due to the history and nature of the interaction between the RSE and
the IETF, certain principles, described in the following subsections,
must be understood and adhered to by the RSE in his or her
interactions with the community. These apply to the representation
function, as well as to the leadership the RSE provides for
production and series development.
2.1.2.1.1. Volunteerism
The vast majority of Internet technical community work is led,
initiated, and done by community volunteers, including oversight,
policy making, and direct production of, for example, many software
tools. The RSE, while not a volunteer, is dependent upon these
volunteer participants. Also, the spirit of the community is heavily
focused on and draws from these volunteers. As such, the RSE needs
to support the vitality and effectiveness of volunteer participation.
2.1.2.1.2. Policy Authority
All decisions are to be made in the overall interest of the broader
Internet community. The RSE is responsible for identifying
materially concerned interest groups within the Internet community
and reaching out to them. Those interest groups include at least the
IETF community, the IRTF community, the network research community,
and the network operations community. Other interest groups might
also be materially interested.
The RSE must consult with the community on policy issues. The RSE
works with the community to achieve policy that meets the overall
quality, continuity, and evolution goals the RSE is charged with
meeting. As described in Section 3.1, the RSE reports the results of
such interactions to the RSOC, including a description of the
outreach efforts and the specific recommendations on policy. This
enables the RSOC to provide the oversight the IAB is required to
apply, as well as to confirm that the Internet community has been
properly consulted and considered in making policy.
2.1.2.2. External Representation
From time to time, individuals or organizations external to the IETF
need a contact person to talk to about the RFC Series. The RSE, or
the RSE's designate, serves this role.
Over time, the RSE should determine what, if any, means should be
employed to increase end-user awareness of the series, to reinforce
the stature of the series, and to provide the contact point for
outside parties seeking information on the series or the Editor.
Kolkman, et al. Informational [Page 9]
RFC 6635 RFC Editor Model (Version 2) June 2012
2.1.3. Development of RFC Production and Publication
Closely related to providing strategic leadership and management to
the RFC Production Center and Publisher functions is the need to
develop and improve those functions. The RSE is responsible for
ensuring that such ongoing development takes place.
This effort must include the dimensions of document quality,
timeliness of production, and accessibility of results. It must also
specifically take into account issues raised by the IETF community,
including all the streams feeding into the RFC Editor function.
2.1.4. Development of the RFC Series
In order to develop the RFC Series, the RSE is expected to develop a
relationship with the Internet technical community. The Editor is
expected to engage with the Internet technical community in a process
of articulating and refining a vision for the series and its
continuous evolution. The RSE is also expected to engage other users
of the RFC Series, in particular, the consumers of these documents,
such as those people who use them to specify products, write code,
test behaviors, or other related activities.
Concretely:
The RSE is responsible for the coordination of discussion on
series evolution among the series' stream participants and the
broader Internet technical community.
In time, the RSE is expected to develop and refine a vision for
the RFC Series, including examining:
* The RFC Series, as it continues to evolve. The RSE is expected
to take a broad view and look for the best ways to evolve the
series for the benefit of the entire Internet community. As
such, the RSE may even consider evolution beyond the historical
'by engineers for engineers' emphasis; and
* Its publication-technical environment, by looking at whether it
should be slowly changing in terms of publishing and archiving
techniques -- particularly to better serve the communities that
produce and depend on the RFC Series. For example, all of
those communities have been slowly changing to include a
significant population of multi-lingual individuals or non-
native speakers of English. Another example is that some of
these constituencies also have shifted to include significant
Kolkman, et al. Informational [Page 10]
RFC 6635 RFC Editor Model (Version 2) June 2012
groups whose primary focus is on the constraints and
consequences of network engineering, rather than a primary
interest in the engineering issues themselves.
For this type of responsibility, the RSE cooperates closely with the
community, and operates under oversight of the RSOC: thus,
ultimately, under oversight of the IAB.
2.1.5. Workload
On average, the job is expected to take half of a full-time
equivalent position (FTE, thus approx 20 hrs per week), with the
workload per week nearing full time during IETF weeks. In addition,
the job is expected to take more than 20 hours per week in the first
few months of the engagement and when involved in special projects.
2.1.6. Qualifications
The RFC Series Editor is a senior technology professional. The
following qualifications are desired:
1. Strategic leadership and management experience fulfilling the
requirements outlined in this document, the many aspects of this
role, and the coordination of the overall RFC Editor process.
2. Good understanding of the English language and technical
terminology related to the Internet.
3. Good communication skills.
4. Experience with editorial processes.
5. Ability to develop strong understanding of the IETF and RFC
process.
6. Independent worker.
7. Willingness to, and availability for, travel.
8. The ability to work effectively in a multi-actor and matrixed
environment with divided authority and responsibility similar to
that described in this document.
9. Experience with and ability to participate in, and manage,
activities by email and teleconferences, not just face-to-face
interactions.
Kolkman, et al. Informational [Page 11]
RFC 6635 RFC Editor Model (Version 2) June 2012
10. Demonstrated experience in strategic planning and the management
of entire operations.
11. Experience as an RFC author.
2.1.7. Conflict of Interest
The RSE is expected to avoid even the appearance of conflict of
interest or judgment in performing these roles. As such, the RSE is
barred from having any ownership, advisory, or other relationship to
the vendors executing the RFC Publisher or Production Center
functions except as specified elsewhere in this document. If
necessary, an exception can be made after public disclosure of those
relationships and with the explicit permission of the IAB and IAOC.
2.2. RFC Production Center
The RFC Production Center function is performed by a paid contractor,
and the contractor's responsibilities include the following:
1. Editing inputs from all RFC streams to comply with the RFC Style
Manual, under the direction of the RSE;
2. Creating records of edits performed on documents;
3. Identifying where editorial changes might have technical impact
and seeking necessary clarification;
4. Engaging in dialog with authors, document shepherds, IANA,
and/or stream-dependent contacts when clarification is needed;
5. Creating records of dialog with document authors;
6. Requesting advice from the RFC Series Editor as needed;
7. Providing suggestions to the RFC Series Editor as needed;
8. Providing sufficient resources to support reviews of RFC
Publisher performance by the RFC Series Editor and external
reviews of the RFC Editor function initiated by the IAB or IAOC;
9. Coordinating with IANA to ensure correct documentation of IANA-
performed protocol registry actions;
10. Assigning RFC numbers;
Kolkman, et al. Informational [Page 12]
RFC 6635 RFC Editor Model (Version 2) June 2012
11. Establishing publication readiness of each document through
communication with the authors, document shepherds, IANA, and/or
stream-dependent contacts, and, if needed, with the RFC Series
Editor;
12. Forwarding documents that are ready for publication to the RFC
Publisher;
13. Forwarding records of edits and author dialog to the RFC
Publisher so these can be preserved;
14. Liaising with the streams as needed.
All these activities will be done under the general direction, but
not day-to-day management, of the RSE and need some level of
coordination with various submission streams and the RSE.
The RFC Production Center contractor is to be selected through an
IASA Request for Proposal (RFP) process as described in Section 4.1.
2.3. RFC Publisher
The RFC Publisher responsibilities include the following:
1. Announcing and providing on-line access to RFCs.
2. Providing an on-line system to submit RFC Errata.
3. Providing on-line access to approved RFC Errata.
4. Providing backups.
5. Providing storage and preservation of records.
6. Authenticating RFCs for legal proceedings.
All these activities will be done under the general direction, but
not day-to-day management, of the RSE and need some level of
coordination with various submission streams and the RSE.
The RFC Publisher contractor is to be selected through an IASA RFP
process as described in Section 4.1.
Kolkman, et al. Informational [Page 13]
RFC 6635 RFC Editor Model (Version 2) June 2012
3. Committees
3.1. RFC Series Oversight Committee (RSOC)
The IAB is responsible for the oversight of the RFC Series and acts
as a body for final conflict resolution, including the process
described in Section 4.3.
In order to provide continuity over periods longer than the NomCom
appointment cycle [RFC3777] and assure that oversight includes
suitable subject matter expertise, the IAB will establish a group
that implements oversight for the IAB, the RFC Series Oversight
Committee (RSOC).
The RSOC will act with authority delegated from the IAB: in general,
it will be the RSOC that will approve consensus policy and vision
documents as developed by the RSE in collaboration with the
community. While it is expected that the IAB will exercise due
diligence in its supervision of the RSOC, the RSOC should be allowed
the latitude to do its job without undue interference from the IAB.
Therefore, it is expected that the IAB will accord RSOC reports and
recommendations the benefit of the doubt.
For all decisions that affect the RSE individually (e.g., hiring and
firing), the RSOC prepares recommendations for the IAB, but the final
decision is the responsibility of the IAB. For instance the RSOC
would do the following:
o perform annual reviews of the RSE and report the result of these
reviews to the IAB.
o manage RSE candidate selection and advise the IAB on candidate
appointment (in other words, select the RSE subject to IAB
approval).
RSOC members are expected to recognize potential conflicts of
interest and behave accordingly.
For the actual recruitment and selection of the RSE, the RSOC will
propose a budget for the search process. It will work with IASA to
refine that budget and develop remuneration criteria and an
employment agreement or contracting plans, as appropriate.
The RSOC will be responsible for ensuring that the RFC Series is run
in a transparent and accountable manner.
The RSOC shall develop and publish its own rules of order.
Kolkman, et al. Informational [Page 14]
RFC 6635 RFC Editor Model (Version 2) June 2012
The initial RSOC was charged with designing and executing a
solicitation, search, and selection process for the first actual (not
transitional or "acting") RSE appointment. That process involved
iteration on this and related documents and evaluation of various
strategies and options. During the creation of this document, it was
expected that the RSOC would describe the process it ultimately
selected to the community. The RSOC did involve the community in
interim considerations when that was likely to be of value.
Following completion of the selection process, the RSOC will
determine the best way to share information learned and experience
gained with the community and determine how to best preserve that
information for future use.
3.1.1. RSOC Composition
The RSOC will operate under the authority of the IAB, with the IAB
retaining final responsibility. The IAB will delegate authority and
responsibility to the RSOC as appropriate and as RSOC and RSE
relationships evolve. The RSOC will include people who are not
current IAB members. Currently, this is aligned with the IAB program
structure. The IAB will designate the membership of the RSOC with
the following goals: preserving effective stability; keeping it small
enough to be effective, and keeping it large enough to provide
general Internet community expertise, specific IETF expertise,
publication expertise, and stream expertise. Members serve at the
pleasure of the IAB and are expected to bring a balance between
short- and long-term perspectives. Specific input about, and
recommendations of, members will be sought from the streams, the
IASA, and the RSE.
In addition to the members from outside of the IAB appointed to the
RSOC, IAB members may participate as full members of the RSOC. Under
most circumstances, there will be a specific individual IAB member
appointed by the IAB as the program lead, who will be a full member
of the RSOC. This member's role is distinct from any RSOC-internal
organizational roles, such as would be created by the RSOC choosing
to appoint a chair from among its members. Other IAB members may
choose to be full members of the RSOC, with the consent of the IAB.
This consent is primarily concerned with avoiding overpopulating the
RSOC and providing it with relatively stable membership, which will
work best if it is not too large a committee.
The IAOC will appoint an individual to serve as its liaison to the
RSOC. The RSE and the IAOC Liaison will serve as non-voting ex
officio members of the RSOC. Either or both can be excluded from its
discussions if necessary.
Kolkman, et al. Informational [Page 15]
RFC 6635 RFC Editor Model (Version 2) June 2012
4. Administrative Implementation
The exact implementation of the administrative and contractual
activities described here are a responsibility of the IETF
Administrative Oversight Committee (IAOC, [RFC4071]) in cooperation
with the RFC Series Editor. The authority structure is described in
Figure 2 below.
+----------------+ +----------------+
| | | |
| IAB | | IAOC |
| | | |
+==========+-----+ +-+--------------+
| | .
| RSOC | .
| | .
+----+-----+ .
| .
| .
| ...................
| . .
+--------V---V----+ .
| | .
| RFC | .
| Series | .
| Editor | .
| | .
+--------+--------+ .
| .
| .................
| . .
+--+----------------+ .
| . | .
| . | .
+---V-----V--+ +--V----V---+
| RFC | | RFC |
| Production | | Publisher |
| Center | | |
+------------+ +-----------+
Authority Structure of the RFC Series
Legend:
------- IAB RFC Series Oversight
....... IAOC Contract/Budget Oversight
Figure 2
Kolkman, et al. Informational [Page 16]
RFC 6635 RFC Editor Model (Version 2) June 2012
4.1. Vendor Selection for the Production and Publisher Functions
As stated earlier, vendor selection is done in cooperation with the
streams and under the final authority of the IAOC.
The RSE owns and develops the work definition (the SOW) and
participates in the IASA vendor selection process. The work
definition is created within the IASA budget and takes into account
the stream managers and community input.
The process to select and contract for an RFC Production Center, RFC
Publisher, and other RFC-related services, is as follows:
o The IAOC establishes the contract process, including the steps
necessary to issue an RFP when necessary, the timing, and the
contracting procedures.
o The IAOC establishes the Selection Committee, which will consist
of the RSE, the IAD, and other members selected by the RSOC and
the IAOC. The Committee shall be chaired by the RSE.
o The Selection Committee selects the vendor, subject to the
successful negotiation of a contract approved by the IAOC. In the
event that a contract cannot be reached, the matter shall be
referred to the Selection Committee for further action.
o The Selection Committee may select an RFC Publisher either through
the IASA RFP process or, at the Committee's option, the Committee
may select the IETF Secretariat to provide RFC Publisher services,
subject to negotiations in accordance with the IASA procedures.
4.2. Budget
The expenses discussed in this document are not new expenses. They
have been and remain part of the IETF Administrative Support Activity
(IASA, [RFC4071]) budget.
The RFC Series portion of the IASA budget shall include entries for
the RSOC, RSE, RFC Production Center, and the RFC Publisher. The
IASA budget shall also include entries for the streams, including the
independent stream.
The IAOC has the responsibility to approve the total RFC Editor
budget (and the authority to deny it). The RSE must work within the
IAOC budgetary process.
Kolkman, et al. Informational [Page 17]
RFC 6635 RFC Editor Model (Version 2) June 2012
The RSE is responsible for managing the RFC Editor function to
operate within those budgets. If production needs change, the RSE is
responsible for working with the Production Center, and where
appropriate, other RFC Editor component institutions, relevant
streams, and/or the RSOC to determine what the correct response
should be. If they agree that a budgetary change is needed, that
decision needs to be taken to the IAD and the IAOC.
4.3. Disagreements among Entities Related to the RFC Editor
The RFC Series Editor and the RFC Production Center and Publisher
facilities work with the various streams to produce RFCs.
Disagreements may arise between these entities during the execution
of the RFC Editor operations. In particular, different streams may
disagree with each other, or disagree with the RFC Editor function.
Potentially, even the RSOC or the IAOC could find themselves in
disagreement with some aspect of the RFC Editor operations. Note
that disagreements between an author and the RFC Production Center
are not cross-entity issues, and they are to be resolved by the RSE,
in accordance with the rest of this document.
If such cross-entity disagreements arise, the community would
generally hope that they can be resolved politely and directly.
However, this is not always possible. At that point, any relevant
party would first formally request a review and reconsideration of
the decision. If the party still disagrees after the
reconsideration, that party may ask the RSE to decide or, especially
if the RSE is involved, the party may ask the IAB Chair (for a
technical or procedural matter) to mediate or appoint a mediator to
aid in the discussions, although he or she not is obligated to do so.
All parties should work informally and in good faith to reach a
mutually agreeable conclusion. As noted below, any such issues that
involve contractual matters must be brought to the attention of the
IAOC. If the IAB Chair is asked to assist in resolving the matter,
the Chair may ask for advice or seek assistance from anyone the Chair
deems helpful. The Chair may also alert any appropriate individuals
or organizations to the existence of the issue.
If such a conclusion is not possible through the above less formal
processes, then the matter must be registered with the RFC Series
Oversight Committee. The RSOC may choose to offer advice to the RSE
or more general advice to the parties involved and may ask the RSE to
defer a decision until it formulates its advice. However, if a
timely decision cannot be reached through discussion, mediation, and
mutual agreement, the RSE is expected to make whatever decisions are
needed to ensure the smooth operation of the RFC Editor function;
those decisions are final.
Kolkman, et al. Informational [Page 18]
RFC 6635 RFC Editor Model (Version 2) June 2012
The RSE may make final decisions unilaterally only to assure the
functioning of the process, and only while there is an evaluation of
current policies to determine whether they are appropriately
implemented in the decision or need adjustment. In particular, it
should be noted that final decisions about the technical content of
individual documents are the exclusive responsibility of the stream
approvers from which those documents originate, as shown in the
illustration in Figure 1.
If informal agreements cannot be reached, then formal RSOC review and
decision making may be required. If so, the RSE must present the
issues involved to the community so that the community is aware of
the situation. The RSE will then report the issue to the RSOC for
formal resolution by the RSOC with confirmation by the IAB in its
oversight capacity.
IAB and community discussion of any patterns of disputes are expected
to inform future changes to RFC Series policies, including possible
updates to this document.
4.4. Issues with Contractual Impact
If a disagreement or decision has immediate or future contractual
consequences, it falls under BCP 101 [RFC4071] and IASA; thus, the
RSE must identify the issue and provide his or her advice to the
IAOC; additionally, if the RSOC has provided advice, forward that
advice as well. The IAOC must notify the RSOC and IAB regarding the
action it concludes is required to resolve the issue based on its
applicable procedures and provisions in the relevant contracts.
5. IANA Considerations
This document defines several functions within the overall RFC Editor
structure, and it places the responsibility for coordination of
registry value assignments with the RFC Production Center. The IAOC
will facilitate the establishment of the relationship between the RFC
Production Center and IANA.
This document does not create a new registry nor does it register any
values in existing registries, and no IANA action is required.
6. Security Considerations
The same security considerations as those in [RFC4844] apply. The
processes for the publication of documents must prevent the
introduction of unapproved changes. Since the RFC Editor maintains
the index of publications, sufficient security must be in place to
prevent these published documents from being changed by external
Kolkman, et al. Informational [Page 19]
RFC 6635 RFC Editor Model (Version 2) June 2012
parties. The archive of RFC documents, any source documents needed
to recreate the RFC documents, and any associated original documents
(such as lists of errata, tools, and, for some early items, originals
that are not machine readable) need to be secured against any kind of
data storage failure.
The IAOC should take these security considerations into account
during the implementation and enforcement of the RFC Editor component
contracts.
7. Acknowledgments
The RFC Editor model was conceived and discussed in hallways and on
mailing lists. The first iteration of the text on which this
document is based was first written by Leslie Daigle, Russ Housley,
and Ray Pelletier. In addition to the members of the IAOC and IAB in
conjunction with those roles, major and minor contributions were made
by (in alphabetical order): Bob Braden, Brian Carpenter, Sandy
Ginoza, Alice Russo, Joel M. Halpern, Alfred Hoenes, Paul Hoffman,
John Klensin, Subramanian Moonesamy, and Jim Schaad.
The IAOC members at the time this RFC Editor model was approved were
(in alphabetical order): Bernard Aboba (ex officio), Eric Burger,
Dave Crocker, Marshall Eubanks, Bob Hinden, Russ Housley (ex
officio), Ole Jacobsen, Ray Pelletier (non-voting), and Lynn St.
Amour (ex officio).
The IAB members at the time the initial RFC Editor model was approved
were (in alphabetical order): Loa Andersson, Gonzalo Camarillo,
Stuart Cheshire, Russ Housley, Olaf Kolkman, Gregory Lebovitz, Barry
Leiba, Kurtis Lindqvist, Andrew Malis, Danny McPherson, David Oran,
Dave Thaler, and Lixia Zhang. In addition, the IAB included two ex
officio members: Dow Street, who was serving as the IAB Executive
Director, and Aaron Falk, who was serving as the IRTF Chair.
The IAB members at the time the this RFC was approved were (in
alphabetical order): Bernard Aboba, Ross Callon, Alissa Cooper,
Spencer Dawkins, Joel Halpern, Russ Housley, David Kessens, Olaf
Kolkman, Danny McPherson, Jon Peterson, Andrei Robachevsky, Dave
Thaler, and Hannes Tschofenig. In addition, at the time of approval,
the IAB included two ex officio members: Mary Barnes who was serving
as the IAB Executive Director, and Lars Eggert, who was serving as
the IRTF Chair.
Kolkman, et al. Informational [Page 20]
RFC 6635 RFC Editor Model (Version 2) June 2012
8. References
8.1. Normative References
[RFC4844] Daigle, L. and Internet Architecture Board, "The RFC
Series and RFC Editor", RFC 4844, July 2007.
[RFC4071] Austein, R. and B. Wijnen, "Structure of the IETF
Administrative Support Activity (IASA)", BCP 101,
RFC 4071, April 2005.
[RFC2850] Internet Architecture Board and B. Carpenter, "Charter of
the Internet Architecture Board (IAB)", BCP 39, RFC 2850,
May 2000.
8.2. Informative References
[RFC5620] Kolkman, O. and IAB, "RFC Editor Model (Version 1)",
RFC 5620, August 2009.
[RFC3777] Galvin, J., "IAB and IESG Selection, Confirmation, and
Recall Process: Operation of the Nominating and Recall
Committees", BCP 10, RFC 3777, June 2004.
Authors' Addresses
Olaf M. Kolkman (editor)
EMail: olaf@nlnetlabs.nl
Joel M. Halpern (editor)
Ericsson
EMail: joel.halpern@ericsson.com
Internet Architecture Board
EMail: iab@iab.org
Kolkman, et al. Informational [Page 21]
xml2rfc-2.9.6/tests/valid/list_format.txt 0000644 0001750 0001750 00000001700 12336226773 021225 0 ustar henrik henrik 0000000 0000000 First list:
R1 #1
R2 #2
R3 #3
Specify the indent explicitly so that all the items line up nicely.
Different list formatting characters, following what v1 supports:
style="format %i":
i. first item
ii. second item
iii. third item
iv. fourth item
v. 5:th item
vi. 6:th item
vii. 7:th item
viii. 8:th item
ix. 9:th item
x. 10:th item
xi. 11:th item
xii. 12:th item
xiii. 13:th item
xiv. 14:th item
style="format (%d)":
(1) first item
(2) second item
(3) third item
style="format %c)":
a) first item
b) second item
c) third item
style="format %C.":
A. first item
B. second item
C. third item
style="format %d.":
1. first item
2. second item
3. third item
A separate line
A. first sub-item
B. second sub-item
C. third sub-item xml2rfc-2.9.6/tests/valid/status_ietf_std_yes.nroff 0000644 0001750 0001750 00000001375 12336226773 023271 0 ustar henrik henrik 0000000 0000000 .pl 10.0i
.po 0
.ll 7.2i
.lt 7.2i
.nr LL 7.2i
.nr LT 7.2i
.hy 0
.ad l
.ds LH RFC 9999
.ds CH Abbreviated Title
.ds RH December 2010
.ds LF Doe
.ds CF Best Current Practice
.ds RF FORMFEED[Page %]
.ti 0
Status of This Memo
.in 3
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata, and
how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc9999. xml2rfc-2.9.6/tests/valid/list_letters.raw.txt 0000644 0001750 0001750 00000000300 12336226773 022202 0 ustar henrik henrik 0000000 0000000 Simulating more than one paragraph in a list item using :
a. First, a short item.
b. Second, a longer list item.
And something that looks like a separate pargraph. xml2rfc-2.9.6/tests/valid/draft-miek-test.nroff 0000644 0001750 0001750 00000071713 13241306027 022173 0 ustar henrik henrik 0000000 0000000 .\" automatically generated by xml2rfc v2.9.3a2 on 2018-02-15T13:33:11Z
.pl 10.0i
.po 0
.ll 7.2i
.lt 7.2i
.nr LL 7.2i
.nr LT 7.2i
.hy 0
.ad l
.ds LH Internet-Draft
.ds CH Pandoc2rfc Version 2
.ds RH January 2013
.ds LF Gieben
.ds CF Expires July 5, 2013
.ds RF FORMFEED[Page %]
.in 0
.nf
RFC Beautification Working Group R. Gieben
Internet-Draft Google
Intended status: Informational January 1, 2013
Expires: July 5, 2013
.fi
.ce 1
Writing \%I-Ds and RFCs using Pandoc and xml2rfc 2.x
.ce 1
\%draft-gieben-writing-rfcs-pandoc-02
Abstract
.in 3
This memo presents a technique for using Pandoc syntax as a source
format for documents in the \%Internet-Drafts \%(I-Ds) and Request for
Comments (RFC) series.
This version is adapted to work with "xml2rfc" version 2.x.
.in 0
Status of This Memo
.in 3
This \%Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
\%Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as \%Internet-Drafts. The list of current \%Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
\%Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use \%Internet-Drafts as reference
material or to cite them other than as "work in progress."
This \%Internet-Draft will expire on July 5, 2013.
.in 0
Copyright Notice
.in 3
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
\%(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section\04.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
.bp
.ti 0
Table of Contents
.in 0
.nf
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Pandoc to RFC . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Dependencies . . . . . . . . . . . . . . . . . . . . . . 5
3. Starting a new project . . . . . . . . . . . . . . . . . . . 5
4. Supported Features . . . . . . . . . . . . . . . . . . . . . 5
5. Unsupported Features . . . . . . . . . . . . . . . . . . . . 6
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7
7. Pandoc Constructs . . . . . . . . . . . . . . . . . . . . . . 7
7.1. Paragraph . . . . . . . . . . . . . . . . . . . . . . . . 7
7.2. Section . . . . . . . . . . . . . . . . . . . . . . . . . 7
7.3. List Styles . . . . . . . . . . . . . . . . . . . . . . . 7
7.3.1. Symbol . . . . . . . . . . . . . . . . . . . . . . . 7
7.3.2. Number . . . . . . . . . . . . . . . . . . . . . . . 8
7.3.3. Empty . . . . . . . . . . . . . . . . . . . . . . . . 8
7.3.4. Roman . . . . . . . . . . . . . . . . . . . . . . . . 8
7.3.5. Letter . . . . . . . . . . . . . . . . . . . . . . . 9
7.3.6. Hanging . . . . . . . . . . . . . . . . . . . . . . . 9
7.4. Figure/Artwork . . . . . . . . . . . . . . . . . . . . . 10
7.4.1. References . . . . . . . . . . . . . . . . . . . . . 10
7.5. Block Quote . . . . . . . . . . . . . . . . . . . . . . . 11
7.6. References . . . . . . . . . . . . . . . . . . . . . . . 11
7.6.1. External . . . . . . . . . . . . . . . . . . . . . . 11
7.6.2. Internal . . . . . . . . . . . . . . . . . . . . . . 11
7.7. Spanx Styles . . . . . . . . . . . . . . . . . . . . . . 12
7.8. Tables . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.8.1. References . . . . . . . . . . . . . . . . . . . . . 12
7.9. Indexes . . . . . . . . . . . . . . . . . . . . . . . . . 13
8. Usage guidelines . . . . . . . . . . . . . . . . . . . . . . 13
8.1. Working with multiple files . . . . . . . . . . . . . . . 13
8.2. Setting the title . . . . . . . . . . . . . . . . . . . . 13
8.3. Uploading the XML/txt . . . . . . . . . . . . . . . . . . 14
8.4. VIM syntax highlighting . . . . . . . . . . . . . . . . . 14
9. Security Considerations . . . . . . . . . . . . . . . . . . . 14
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
11.1. Informative References . . . . . . . . . . . . . . . . . 14
11.2. Normative References . . . . . . . . . . . . . . . . . . 14
11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Appendix A. Tests . . . . . . . . . . . . . . . . . . . . . . . 15
A.1. A Very Long Title Considerations With Regards to the
Already Deployed Routing Policy . . . . . . . . . . . . . 15
A.2. Markup in heading . . . . . . . . . . . . . . . . . . . . 15
A.3. Blockquote . . . . . . . . . . . . . . . . . . . . . . . 15
A.4. Verbatim code blocks . . . . . . . . . . . . . . . . . . 15
A.5. Reference Tests . . . . . . . . . . . . . . . . . . . . . 15
A.6. Spanx Tests . . . . . . . . . . . . . . . . . . . . . . . 15
.bp
A.7. List Tests . . . . . . . . . . . . . . . . . . . . . . . 16
A.8. Table Tests . . . . . . . . . . . . . . . . . . . . . . . 19
A.9. Numbered examples . . . . . . . . . . . . . . . . . . . . 20
A.10. Figure tests . . . . . . . . . . . . . . . . . . . . . . 20
A.11. Verse tests . . . . . . . . . . . . . . . . . . . . . . . 21
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21
.fi
.in 3
.in 4
.ti 0
1. Introduction
.in 3
This document presents a technique for using Pandoc syntax as a
source format for documents in the \%Internet-Drafts \%(I-Ds) and Request
for Comments (RFC) series.
This version is adapted to work with "xml2rfc" version 2.x.
Pandoc is an "almost plain text" format and therefor particularly
well suited for editing \%RFC-like documents.
.in 6
Note: this document is typeset in Pandoc and does not render
completely correct when reading it on github.
.in 4
.ti 0
2. Pandoc to RFC
.in 6
Pandoc2rfc \%-- designed to do the right thing, until it doesn't.
.in 3
When writing [RFC4641] we directly wrote the XML. Needless to say it
was tedious even thought the XML of xml2rfc [1] is very "light". The
latest version of xml2rfc version 2 can be found here [2].
During the last few years people have been developing markup
languages that are very easy to remember and type. These languages
have become known as "almost plain \%text"-markup languages. One of
the first was the Markdown [3] syntax. One that was developed later
and incorporates Markdown and a number of extensions is Pandoc [4].
The power of Pandoc also comes from the fact that it can be
translated to numerous output formats, including, but not limited to:
HTML, (plain) Markdown and "docbook" XML.
So using Pandoc for writing RFCs seems like a sane choice. As
"xml2rfc" uses XML, the easiest way would be to create "docbook" XML
and transform that using XSLT. Pandoc2rfc does just that. The
conversions are, in some way amusing, as we start off with (almost)
plain text, use elaborate XML and end up with plain text again.
.bp
.in 0
.nf
+-------------------+ pandoc +---------+
| ALMOST PLAIN TEXT | ------> | DOCBOOK |
+-------------------+ +---------+
| |
non-existent | | xsltproc
faster way | |
v v
+------------+ xml2rfc +---------+
| PLAIN TEXT | <-------- | XML2RFC |
+------------+ +---------+
.fi
.in 3
.ce 1
Figure\01: Attempt to justify Pandoc2rfc.
The XML generated (the output after the "xsltproc" step in Figure\01)
is suitable for inclusion in either the "middle" or "back" section of
an RFC. The simplest way is to create a template XML file and
include the appropriate XML:
.in 0
.nf
]>
Writing I-Ds and RFCs using Pandoc v2
&pandocMiddle;
&pandocBack;
.fi
.in 3
.ce 1
Figure\02: A minimal template.xml.
See the Makefile for an example of this. In this case you need to
edit 3 documents:
.in 7
.ti 3
1. middle.pdc \%- contains the main body of text;
.ti 3
2. back.pdc \%- holds appendices and references;
.bp
.ti 3
3. template.xml (probably a fairly static file).
.in 3
The draft ("draft.txt") you are reading now, is automatically created
when you call "make". The homepage of Pandoc2rfc is this github
repository [5].
.in 6
.ti 0
2.1. Dependencies
.in 3
It needs "xsltproc" and "pandoc" to be installed. See the Pandoc
user manual for the details [6] on how to type in Pandoc style. And
ofcourse "xml2rfc" version two.
When using Pandoc2rfc consider adding the following sentence to an
Acknowledgements section:
.in 0
.nf
This document was produced using the Pandoc2rfc tool.
.fi
.in 3
.in 4
.ti 0
3. Starting a new project
.in 3
When starting a new project with "pandoc2rfc" you'll need to copy the
following files:
.in 6
.ti 3
o "Makefile"
.ti 3
o "transform.xslt"
.ti 3
o And the above mentioned files:
.in 9
.ti 6
* "middle.pdc"
.ti 6
* "back.pdc"
.ti 6
* "template.xml"
.in 3
After that you can start editing.
.in 4
.ti 0
4. Supported Features
.in 6
.ti 3
o Sections with an anchor and title attributes (Section\07.2);
.ti 3
o Lists
.in 9
.ti 6
* style=symbols (Section\07.3.1);
.ti 6
* style=numbers (Section\07.3.2);
.ti 6
* style=empty (Section\07.3.3);
.bp
.ti 6
* style=format %i, use roman lowercase numerals, (Section\07.3.4);
.ti 6
* style=format (%d), use roman uppercase numerals
(Section\07.3.4);
.ti 6
* style=letters \%(lower- and uppercase, Section\07.3.5);
.ti 6
* style=hanging (Section\07.3.6);
.in 6
.ti 3
o Figure/artwork with a title (Section\07.4);
.ti 3
o Block quote this is converted to "" paragraph
(Section\07.5);
.ti 3
o References
.in 9
.ti 6
* external (eref) (Section\07.6.1);
.ti 6
* internal (xref) (Section\07.6.2), you can refer to:
.in 12
.ti 9
+ section (handled by Pandoc, see Section\07.6));
.ti 9
+ figures (handled by XSLT, see Section\07.4.1);
.ti 9
+ tables (handled by XSLT, see Section\07.8.1).
.in 6
.ti 3
o Citations, by using internal references;
.ti 3
o Spanx style=verb, style=emph and style=strong (Section\07.7);
.ti 3
o Tables with an anchor and title (Section\07.8);
.ti 3
o Indexes, by using footnotes (Section\07.9).
.in 4
.ti 0
5. Unsupported Features
.in 6
.ti 3
o Lists inside a table ("xml2rfc" doesn't handle this);
.ti 3
o Pandoc markup in the caption for figures/artwork. Pandoc markup
for table captions _is_ supported;
.ti 3
o crefs: for comments (no input syntax available), use HTML
comments: \%"";
.bp
.in 4
.ti 0
6. Acknowledgements
.in 3
The following people have helped to make Pandoc2rfc what it is today:
Benno Overeinder, Erlend Hamnaberg, Matthijs Mekking, Trygve
Laugstoel.
This document was prepared using Pandoc2rfc.
.in 4
.ti 0
7. Pandoc Constructs
.in 3
So, what syntax do you need to use to get the correct output? Well,
it is _just_ Pandoc. The best introduction to the Pandoc style is
given in this README from Pandoc itself [7].
For convenience we list the most important ones in the following
sections.
.in 6
.ti 0
7.1. Paragraph
.in 3
Paragraphs are separated with an empty line.
.in 6
.ti 0
7.2. Section
.in 3
Just use the normal sectioning commands available in Pandoc, for
instance:
.in 0
.nf
# Section1 One
Bla
.fi
.in 3
Converts to: ""
If you have another section that is also named "Section1 One", that
anchor will be called \%"section1-one-1", but _only_ when the sections
are in the _same_ source file!
Referencing the section is done with "see \%[](#section1-one)", as in
see Section\07.2.
.in 6
.ti 0
7.3. List Styles
.in 3
A good number of styles are supported.
.in 8
.ti 0
7.3.1. Symbol
.in 0
.nf
A symbol list.
* Item one;
* Item two.
.fi
.in 3
.bp
Converts to "":
.in 6
.ti 3
o Item one;
.ti 3
o Item two.
.in 8
.ti 0
7.3.2. Number
.in 0
.nf
A numbered list.
1. Item one;
1. Item two.
.fi
.in 3
Converts to "":
.in 7
.ti 3
1. Item one;
.ti 3
2. Item two.
.in 8
.ti 0
7.3.3. Empty
.in 3
Using the default list markers from Pandoc:
.in 0
.nf
A list using the default list markers.
#. Item one;
#. Item two.
.fi
.in 3
Converts to "":
.in 6
Item one;
Item two.
.in 8
.ti 0
7.3.4. Roman
.in 3
Use the supported Pandoc syntax:
.in 0
.nf
ii. Item one;
ii. Item two.
.fi
.in 3
Converts to "":
.in 9
.ti 3
i. Item one;
.ti 3
ii. Item two.
.bp
.in 3
If you use uppercase Roman numerals, they convert to a different
style:
.in 0
.nf
II. Item one;
II. Item two.
.fi
.in 3
Yields "":
.in 8
.ti 3
(1) Item one;
.ti 3
(2) Item two.
.ti 0
7.3.5. Letter
.in 3
A numbered list.
.in 0
.nf
a. Item one;
b. Item two.
.fi
.in 3
Converts to "":
.in 7
.ti 3
a. Item one;
.ti 3
b. Item two.
.in 3
Uppercasing the letters works too (note two spaces after the letter.
.in 0
.nf
A. Item one;
B. Item two.
.fi
.in 3
Becomes:
.in 7
.ti 3
A. Item one;
.ti 3
B. Item two.
.in 8
.ti 0
7.3.6. Hanging
.in 3
This is more like a description list, so we need to use:
.bp
.in 0
.nf
First item that needs clarification:
: Explanation one
More stuff, because item is difficult to explain.
* item1
* item2
Second item that needs clarification:
: Explanation two
.fi
.in 3
Converts to: "" and ""
If you want a newline after the hangTexts, search for the string
"OPTION" in "transform.xsl" and uncomment it.
.in 6
.ti 0
7.4. Figure/Artwork
.in 3
Indent the paragraph with 4 spaces.
.in 0
.nf
Like this
.fi
.in 3
Converts to: " ..." Note that "xml2rfc" supports a
caption with "". Pandoc does not support this, but
Pandoc2rfc does. If you add a "@Figure: some text" as the last line,
the artwork gets a "title" attribute with the text after "@Figure:".
It will also be possible to reference the artwork. If a caption is
supplied the artwork will be centered. If a caption is needed but
the figure should not be centered use "@figure:\\".
.in 8
.ti 0
7.4.1. References
.in 3
The reference anchor attribute will be: "fig:" + "first 10
(normalized) characters from the caption". Where normalized means:
.in 6
.ti 3
o Take the first 10 characters of the caption (i.e. this is the text
_after_ the string "@Figure:");
.ti 3
o Spaces and single quotes (') are translated to a minus \%"-";
.ti 3
o Uppercase letters translated to lowercase.
.in 3
So the first artwork with a caption will get \%"fig:a-minimal-" as a
reference. See for instance Figure\02.
.bp
This anchoring is completely handled from within the "xslt". Note
that duplicate anchors are an XML validation error which will make
"xml2rfc" fail.
.in 6
.ti 0
7.5. Block Quote
.in 3
Any paragraph like:
.in 0
.nf
> quoted text
.fi
.in 3
Converts to: " ..." paragraph, making it
indented.
.in 6
.ti 0
7.6. References
.in 8
.ti 0
7.6.1. External
.in 3
Any reference like:
.in 0
.nf
[Click here](URI)
.fi
.in 3
Converts to: "Click here ..."
.in 8
.ti 0
7.6.2. Internal
.in 3
Any reference like:
.in 0
.nf
[Click here](#localid)
.fi
.in 3
Converts to: " ..."
And the emphasis style with asterisks: "*text*" or underscores:
"_text_" Converts to: " ..."
And the emphasis style with double asterisks: "**text**" Converts to:
" ..."
.in 6
.ti 0
7.8. Tables
.in 3
A table can be entered as:
.in 0
.nf
Right Left Center Default
------- ------ ---------- -------
12 12 12 12
123 123 123 123
1 1 1 1
Table: A caption describing the table.
.fi
.in 3
.ce 1
Figure\03: A caption describing the figure describing the table.
Is translated to "" element in "xml2rfc". You can choose
multiple styles as input, but they all are converted to the same
style (plain "") table in "xml2rfc". The column alignment
is copied over to the generated XML.
.in 8
.ti 0
7.8.1. References
.in 3
The caption is _always_ translated to a "title" attribute. If a
table has a caption, it will _also_ get a reference. The reference
anchor attribute will be: \%"tab-" + "first 10 (normalized) characters
from the caption". Where normalized means:
.in 6
.ti 3
o Take the first 10 characters of the caption (i.e. this is the text
_after_ the string "Table:");
.ti 3
o Spaces and single quotes (') are translated to a minus \%"-";
.ti 3
o Uppercase letters translated to lowercase.
.in 3
So the first table with a caption will get \%"tab-a-caption-" for
reference use. See for instance
.bp
This anchoring is completely handled from within the "xslt". Note
that duplicate anchors are an XML validation error which will make
"xml2rfc" fail.
.in 6
.ti 0
7.9. Indexes
.in 3
The footnote syntax of Pandoc is slightly abused to support an index.
Footnotes are entered in two steps, you have a marker in the text,
and later you give actual footnote text. Like this:
.in 0
.nf
[^1]
[^1]: footnote text
.fi
.in 3
We \%re-use this syntax for the "" tag. The above text
translates to:
.in 0
.nf
.bp
.fi
.in 3
The Makefile will pick this up automatically and make a symbolic
link:
.in 0
.nf
draft-gieben-writing-rfcs-pandoc-00.txt -> draft.txt
.fi
.in 3
This makes uploading the file to the \%i-d tracker a bit easier.
.in 6
.ti 0
8.3. Uploading the XML/txt
.in 3
The "draft.xml" target will generate an XML file with all XML
included, so you can upload just one file to the \%I-D tracker.
.in 6
.ti 0
8.4. VIM syntax highlighting
.in 3
If you are a VIM user you might be interested in a syntax
highlighting file (see [VIM]) that slightly lightens up your reading
experience while viewing a draft.txt from VIM.
.in 4
.ti 0
9. Security Considerations
.in 3
This document raises no security issues.
.in 5
.ti 0
10. IANA Considerations
.in 3
This document has no actions for IANA.
.in 5
.ti 0
11. References
.in 7
.ti 0
11.1. Informative References
.in 14
.ti 3
[VIM] Gieben, R., "VIM syntax file for RFCs and \%I-Ds", October
2012, .
.in 7
.ti 0
11.2. Normative References
.in 14
.ti 3
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP\014, RFC\02119, March 1997.
.ti 3
[RFC4641] Kolkman, O. and R. Gieben, "DNSSEC Operational Practices",
RFC\04641, September 2006.
.in 7
.ti 0
11.3. URIs
.ti 3
[1] http://xml.resource.org/experimental
.ti 3
[2] http://pypi.python.org/pypi/xml2rfc/
.ti 3
[3] http://daringfireball.net/projects/markdown/
.bp
.ti 3
[4] http://johnmacfarlane.net/pandoc/
.ti 3
[5] https://github.com/miekg/pandoc2rfc
.ti 3
[6] http://johnmacfarlane.net/pandoc/README.html
.ti 3
[7] http://johnmacfarlane.net/pandoc/README.html
.ti 3
[8] http://miek.nl
.in 13
.ti 0
Appendix\0A. Tests
.in 3
This appendix consists out of a few tests that should all render to
proper "xml2rfc" XML.
.in 6
.ti 0
A.1. A Very Long Title Considerations With Regards to the Already
Deployed Routing Policy
.in 3
Test a very long title.
.in 6
.ti 0
A.2. Markup in heading
.in 3
This is discarded by "xml2rfc".
.in 6
.ti 0
A.3. Blockquote
This is a blockquote, how does it look?
.ti 0
A.4. Verbatim code blocks
.in 0
.nf
A verbatim code block
jkasjksajassjasjsajsajkas
.fi
.in 3
.in 6
.ti 0
A.5. Reference Tests
.in 3
Refer to RFC 2119 [RFC2119] if you will. Or maybe you want to
inspect Figure\02 in Section\02 again. Or you might want to Click here
[8].
.in 6
.ti 0
A.6. Spanx Tests
underscores: _underscores_
asterisks: _asterisks_
double asterisks: *double asterisks*
backticks: "backticks"
.bp
.ti 0
A.7. List Tests
.in 7
.ti 3
1. First we do
.ti 3
2. And then
.in 10
.ti 7
* item 1
.ti 7
* item 2
.in 3
And the other around.
.in 6
.ti 3
o First we do
.ti 3
o Then
.in 10
.ti 6
1. Something
.ti 6
2. Another thing
.in 3
Description lists:
.in 6
.ti 3
Item to explain: It works because of herbs.
.ti 3
Another item to explain: More explaining.
.sp 1
Multiple paragraphs in such a list.
.in 3
lists in description lists.
.in 6
.ti 3
Item to explain: It works because of
.in 10
.ti 6
1. One
.ti 6
2. Two
.in 6
.ti 3
Another item to explain: More explaining
.ti 3
Item to explain: It works because of
.in 10
.ti 6
1. One1
.ti 6
2. Two1
.in 13
.ti 10
+ Itemize list
.ti 10
+ Another item
.bp
.in 6
.ti 3
Another item to explain again: More explaining
.in 3
list with description lists.
.in 7
.ti 3
1. More
.in 10
.ti 7
Item to explain: Explanation ...
.ti 7
Item to explain: Another explanation ...
.in 7
.ti 3
2. Go'bye
.in 3
Multiple paragraphs in a list.
.in 7
.ti 3
1. This is the first bullet point and it needs multiple
paragraphs...
.sp 1
\&... to be explained properly.
.ti 3
2. This is the next bullet. New paragraphs should be indented with
4 four spaces.
.ti 3
3. Another item with some artwork, indented by 8 spaces.
.in 0
.nf
Artwork
.fi
.in 3
.in 7
.ti 3
4. Final item.
.in 3
xml2rfc does not allow this, so the second paragraph is faked with a
.in 0
.nf
.fi
.in 3
Ordered lists.
.in 7
.ti 3
1. First item
.ti 3
2. Second item
.in 3
A lowercase roman list:
.in 9
.ti 3
i. Item 1
.ti 3
ii. Item 2
.in 3
An uppercase roman list.
.in 8
.ti 3
(1) Item1
.bp
.ti 3
(2) Item2
.ti 3
(3) Item 3
.in 3
And default list markers.
Some surrounding text, to make it look better.
.in 6
First item. Use lot of text to get a real paragraphs sense.
First item. Use lot of text to get a real paragraphs sense.
First item. Use lot of text to get a real paragraphs sense.
First item. Use lot of text to get a real paragraphs sense.
Second item. So this is the second para in your list. Enjoy;
Another item.
.in 3
Text at the end.
Lowercase letters list.
.in 7
.ti 3
a. First item
.ti 3
b. Second item
.in 3
Uppercase letters list.
.in 7
.ti 3
A. First item
.ti 3
B. Second item
.in 3
And artwork in a description list.
.in 6
.ti 3
Item1: Tell something about it. Tell something about it. Tell
something about it. Tell something about it. Tell something
about it. Tell something about it.
.in 0
.nf
miek.nl. IN NS a.miek.nl.
a.miek.nl. IN A 192.0.2.1 ; <- this is glue
.fi
.in 3
.sp 1
.in 6
Tell some more about it. Tell some more about it. Tell some more
about it.
.ti 3
Item2: Another description
.in 3
List with a sublist with a paragraph above the sublist
.in 7
.ti 3
1. First Item
.bp
.ti 3
2. Second item
.ti 3
3. Third item
.sp 1
A paragraph that comes first
.in 11
.ti 7
A. But what do you know
.ti 7
B. This is another list
.in 6
.ti 0
A.8. Table\0Tests
.in 0
.nf
+--------+-------+---------+----------+
| Right | Left | Center | Default |
+--------+-------+---------+----------+
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
+--------+-------+---------+----------+
.fi
.in 3
.ce 1
Table\01: Demonstration of simple table syntax.
.in 0
.nf
+-----------+-----------+---------------+---------------------------+
| Centered | Default | Right Aligned | Left Aligned |
| Header | Aligned | | |
+-----------+-----------+---------------+---------------------------+
| First | row | 12.0 | Example of a row that |
| | | | spans multiple lines. |
| Second | row | 5.0 | Here's another one. Note |
| | | | the blank line between |
| | | | rows. |
+-----------+-----------+---------------+---------------------------+
.fi
.in 3
.ce 2
Table\02: Here's the caption. It, too, may span multiple lines. This
is a multiline table. This is verbatim text.
.in 0
.nf
+---------------+---------------+--------------------+
| Fruit | Price | Advantages |
+---------------+---------------+--------------------+
| Bananas | $1.34 | built-in wrapper |
| Oranges | $2.10 | cures scurvy |
+---------------+---------------+--------------------+
.fi
.in 3
.ce 1
Table\03: Sample grid table.
Grid tables without a caption
.bp
.in 0
.nf
+---------------+---------------+--------------------+
| Fruit | Price | Advantages |
+---------------+---------------+--------------------+
| Bananas | $1.34 | built-in wrapper |
| Oranges | $2.10 | cures scurvy |
+---------------+---------------+--------------------+
.fi
.in 3
This table has no caption, and therefor no reference. But you can
refer to some of the other tables, with for instance:
.in 0
.nf
See [](#tab-here-s-the)
.fi
.in 3
Which will become "See Table\02".
We should also be able to refer to the table numbers directly, to say
things like 'Look at Tables 1, 2 and 3.'
.in 6
.ti 0
A.9. Numbered examples
.in 3
This is another example:
.in 7
.ti 3
1. Another bla bla..
.in 3
as (1) shows...
.in 7
.ti 0
A.10. Figure\0tests
.in 0
.nf
This is a figure
This is a figure
This is a figure
This is a figure
.fi
.in 3
.ce 2
Figure\04: This is the caption, with text in `typewriter`. Which isnt
converted to a style, because this is copied \%as-is.
And how a figure that is not centered, do to using "figure" and not
"Figure".
.in 0
.nf
This is a figure
This is a figure
.fi
.in 3
.ce 1
Figure\05: A non centered figure.
Test the use of "@title":
.in 0
.nf
This is a figure with a title
This is a figure with a title
@title: and here it is: a title, don't mess it up *
.bp
.fi
.in 3
.in 7
.ti 0
A.11. Verse tests
.in 3
This is a verse text This is another line
.ti 0
Index
.in 3
L
.in 6
list
.in 9
default markers 18
.in 9
Uppercase Letters 18
.in 3
T
.in 6
table
.in 9
grid 20
.in 9
simple 19
.in 0
Author's Address
.nf
R. (Miek) Gieben
Google
123 Buckingham Palace Road
London SW1W 9SH
UK
Email: miek@miek.nl
URI: http://miek.nl/
.fi
.in 3
xml2rfc-2.9.6/tests/valid/abbreviations.html 0000644 0001750 0001750 00000000212 12472420041 021635 0 ustar henrik henrik 0000000 0000000 Various abbreviations which aren't end of sentence: Jr. AND Sr. AND i.e. AND Mr. AND Mrs. etc. -- done. Start of next sentence.
xml2rfc-2.9.6/tests/valid/status_independent_historic.nroff 0000644 0001750 0001750 00000001641 13237442436 025002 0 ustar henrik henrik 0000000 0000000 .pl 10.0i
.po 0
.ll 7.2i
.lt 7.2i
.nr LL 7.2i
.nr LT 7.2i
.hy 0
.ad l
.ds LH RFC 9999
.ds CH Abbreviated Title
.ds RH December 2010
.ds LF Doe
.ds CF Best Current Practice
.ds RF FORMFEED[Page %]
.ti 0
Status of This Memo
.in 3
This document is not an Internet Standards Track specification; it is
published for the historical record.
This document defines a Historic Document for the Internet community.
This is a contribution to the RFC Series, independently of any other RFC
stream. The RFC Editor has chosen to publish this document at its
discretion and makes no statement about its value for implementation or
deployment. Documents approved for publication by the RFC Editor are
not candidates for any level of Internet Standard; see Section 2 of RFC
5741.
Information about the current status of this document, any errata, and
how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc9999.
xml2rfc-2.9.6/tests/valid/status_irtf_info_nowg.nroff 0000644 0001750 0001750 00000001512 12336226773 023612 0 ustar henrik henrik 0000000 0000000 .pl 10.0i
.po 0
.ll 7.2i
.lt 7.2i
.nr LL 7.2i
.nr LT 7.2i
.hy 0
.ad l
.ds LH RFC 9999
.ds CH Abbreviated Title
.ds RH December 2010
.ds LF Doe
.ds CF Best Current Practice
.ds RF FORMFEED[Page %]
.ti 0
Status of This Memo
.in 3
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This document is a product of the Internet Research Task Force (IRTF).
The IRTF publishes the results of Internet-related research and
development activities. These results might not be suitable for
deployment. Documents approved for publication by the IRSG are not a
candidate for any level of Internet Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata, and
how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc9999. xml2rfc-2.9.6/tests/valid/utf8.nroff 0000644 0001750 0001750 00000004731 13237622212 020057 0 ustar henrik henrik 0000000 0000000 .\" automatically generated by xml2rfc v2.9.3a1 on 2018-02-10T16:32:49Z
.pl 10.0i
.po 0
.ll 7.2i
.lt 7.2i
.nr LL 7.2i
.nr LT 7.2i
.hy 0
.ad l
.ds LH Internet-Draft
.ds CH Abbreviated Title
.ds RH December 2010
.ds LF Doe
.ds CF Expires June 13, 2011
.ds RF FORMFEED[Page %]
.in 0
.nf
Network Working Group J. Doe, Ed.
Internet-Draft Company
Intended status: Informational December 10, 2010
Expires: June 13, 2011
.fi
.ce 1
Put Your Internet Draft Title
.ce 1
\%draft-sample-input-00
Abstract
.in 3
Insert an abstract: MANDATORY. This template is for creating an
\%Internet-Draft. With some out of scope characters in Chinese, by
Xing Xing, 这里是中文译本
.in 0
Status of This Memo
.in 3
This \%Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
\%Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as \%Internet-Drafts. The list of current \%Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
\%Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use \%Internet-Drafts as reference
material or to cite them other than as "work in progress."
This \%Internet-Draft will expire on June 13, 2011.
.in 0
Copyright Notice
.in 3
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
\%(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section\04.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
.bp
.in 4
.ti 0
1. Some unicode strings
.in 3
Text body needs to deal with funny characters
Pure out of scope 这里是中文译本
Some \%re-mapped characters are ¢ or ©
More \%re-mapped characters are ˜ and € and ^
.in 0
Author's Address
.nf
John Doe (editor)
Company
Springfield, IL
US
Email: jdoe@example.com
.fi
.in 3
xml2rfc-2.9.6/tests/valid/rfc6787.txt 0000644 0001750 0001750 00001717204 13151604207 020012 0 ustar henrik henrik 0000000 0000000
Internet Engineering Task Force (IETF) D. Burnett
Request for Comments: 6787 Voxeo
Category: Standards Track S. Shanmugham
ISSN: 2070-1721 Cisco Systems, Inc.
November 2012
Media Resource Control Protocol Version 2 (MRCPv2)
Abstract
The Media Resource Control Protocol Version 2 (MRCPv2) allows client
hosts to control media service resources such as speech synthesizers,
recognizers, verifiers, and identifiers residing in servers on the
network. MRCPv2 is not a "stand-alone" protocol -- it relies on
other protocols, such as the Session Initiation Protocol (SIP), to
coordinate MRCPv2 clients and servers and manage sessions between
them, and the Session Description Protocol (SDP) to describe,
discover, and exchange capabilities. It also depends on SIP and SDP
to establish the media sessions and associated parameters between the
media source or sink and the media server. Once this is done, the
MRCPv2 exchange operates over the control session established above,
allowing the client to control the media processing resources on the
speech resource server.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6787.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
Burnett & Shanmugham Standards Track [Page 1]
RFC 6787 MRCPv2 November 2012
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8
2. Document Conventions . . . . . . . . . . . . . . . . . . . . 9
2.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 10
2.2. State-Machine Diagrams . . . . . . . . . . . . . . . . . 10
2.3. URI Schemes . . . . . . . . . . . . . . . . . . . . . . . 11
3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1. MRCPv2 Media Resource Types . . . . . . . . . . . . . . . 12
3.2. Server and Resource Addressing . . . . . . . . . . . . . 13
4. MRCPv2 Basics . . . . . . . . . . . . . . . . . . . . . . . . 14
4.1. Connecting to the Server . . . . . . . . . . . . . . . . 14
4.2. Managing Resource Control Channels . . . . . . . . . . . 14
4.3. SIP Session Example . . . . . . . . . . . . . . . . . . . 17
4.4. Media Streams and RTP Ports . . . . . . . . . . . . . . . 22
4.5. MRCPv2 Message Transport . . . . . . . . . . . . . . . . 23
4.6. MRCPv2 Session Termination . . . . . . . . . . . . . . . 24
5. MRCPv2 Specification . . . . . . . . . . . . . . . . . . . . 24
5.1. Common Protocol Elements . . . . . . . . . . . . . . . . 25
5.2. Request . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.3. Response . . . . . . . . . . . . . . . . . . . . . . . . 28
5.4. Status Codes . . . . . . . . . . . . . . . . . . . . . . 29
5.5. Events . . . . . . . . . . . . . . . . . . . . . . . . . 31
6. MRCPv2 Generic Methods, Headers, and Result Structure . . . . 32
6.1. Generic Methods . . . . . . . . . . . . . . . . . . . . . 32
6.1.1. SET-PARAMS . . . . . . . . . . . . . . . . . . . . . 32
6.1.2. GET-PARAMS . . . . . . . . . . . . . . . . . . . . . 33
6.2. Generic Message Headers . . . . . . . . . . . . . . . . . 34
6.2.1. Channel-Identifier . . . . . . . . . . . . . . . . . 35
6.2.2. Accept . . . . . . . . . . . . . . . . . . . . . . . 36
Burnett & Shanmugham Standards Track [Page 2]
RFC 6787 MRCPv2 November 2012
6.2.3. Active-Request-Id-List . . . . . . . . . . . . . . . 36
6.2.4. Proxy-Sync-Id . . . . . . . . . . . . . . . . . . . . 37
6.2.5. Accept-Charset . . . . . . . . . . . . . . . . . . . 37
6.2.6. Content-Type . . . . . . . . . . . . . . . . . . . . 37
6.2.7. Content-ID . . . . . . . . . . . . . . . . . . . . . 38
6.2.8. Content-Base . . . . . . . . . . . . . . . . . . . . 38
6.2.9. Content-Encoding . . . . . . . . . . . . . . . . . . 38
6.2.10. Content-Location . . . . . . . . . . . . . . . . . . 39
6.2.11. Content-Length . . . . . . . . . . . . . . . . . . . 40
6.2.12. Fetch Timeout . . . . . . . . . . . . . . . . . . . . 40
6.2.13. Cache-Control . . . . . . . . . . . . . . . . . . . . 40
6.2.14. Logging-Tag . . . . . . . . . . . . . . . . . . . . . 42
6.2.15. Set-Cookie . . . . . . . . . . . . . . . . . . . . . 42
6.2.16. Vendor-Specific Parameters . . . . . . . . . . . . . 44
6.3. Generic Result Structure . . . . . . . . . . . . . . . . 45
6.3.1. Natural Language Semantics Markup Language . . . . . 46
7. Resource Discovery . . . . . . . . . . . . . . . . . . . . . 46
8. Speech Synthesizer Resource . . . . . . . . . . . . . . . . . 48
8.1. Synthesizer State Machine . . . . . . . . . . . . . . . . 48
8.2. Synthesizer Methods . . . . . . . . . . . . . . . . . . . 49
8.3. Synthesizer Events . . . . . . . . . . . . . . . . . . . 49
8.4. Synthesizer Header Fields . . . . . . . . . . . . . . . . 50
8.4.1. Jump-Size . . . . . . . . . . . . . . . . . . . . . . 50
8.4.2. Kill-On-Barge-In . . . . . . . . . . . . . . . . . . 51
8.4.3. Speaker-Profile . . . . . . . . . . . . . . . . . . . 52
8.4.4. Completion-Cause . . . . . . . . . . . . . . . . . . 52
8.4.5. Completion-Reason . . . . . . . . . . . . . . . . . . 53
8.4.6. Voice-Parameter . . . . . . . . . . . . . . . . . . . 53
8.4.7. Prosody-Parameters . . . . . . . . . . . . . . . . . 54
8.4.8. Speech-Marker . . . . . . . . . . . . . . . . . . . . 54
8.4.9. Speech-Language . . . . . . . . . . . . . . . . . . . 55
8.4.10. Fetch-Hint . . . . . . . . . . . . . . . . . . . . . 55
8.4.11. Audio-Fetch-Hint . . . . . . . . . . . . . . . . . . 56
8.4.12. Failed-URI . . . . . . . . . . . . . . . . . . . . . 56
8.4.13. Failed-URI-Cause . . . . . . . . . . . . . . . . . . 56
8.4.14. Speak-Restart . . . . . . . . . . . . . . . . . . . . 56
8.4.15. Speak-Length . . . . . . . . . . . . . . . . . . . . 57
8.4.16. Load-Lexicon . . . . . . . . . . . . . . . . . . . . 57
8.4.17. Lexicon-Search-Order . . . . . . . . . . . . . . . . 58
8.5. Synthesizer Message Body . . . . . . . . . . . . . . . . 58
8.5.1. Synthesizer Speech Data . . . . . . . . . . . . . . . 58
8.5.2. Lexicon Data . . . . . . . . . . . . . . . . . . . . 60
8.6. SPEAK Method . . . . . . . . . . . . . . . . . . . . . . 61
8.7. STOP . . . . . . . . . . . . . . . . . . . . . . . . . . 63
8.8. BARGE-IN-OCCURRED . . . . . . . . . . . . . . . . . . . . 65
8.9. PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.10. RESUME . . . . . . . . . . . . . . . . . . . . . . . . . 68
8.11. CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . 71
Burnett & Shanmugham Standards Track [Page 3]
RFC 6787 MRCPv2 November 2012
8.12. SPEAK-COMPLETE . . . . . . . . . . . . . . . . . . . . . 72
8.13. SPEECH-MARKER . . . . . . . . . . . . . . . . . . . . . . 73
8.14. DEFINE-LEXICON . . . . . . . . . . . . . . . . . . . . . 76
9. Speech Recognizer Resource . . . . . . . . . . . . . . . . . 76
9.1. Recognizer State Machine . . . . . . . . . . . . . . . . 78
9.2. Recognizer Methods . . . . . . . . . . . . . . . . . . . 79
9.3. Recognizer Events . . . . . . . . . . . . . . . . . . . . 79
9.4. Recognizer Header Fields . . . . . . . . . . . . . . . . 79
9.4.1. Confidence-Threshold . . . . . . . . . . . . . . . . 81
9.4.2. Sensitivity-Level . . . . . . . . . . . . . . . . . . 81
9.4.3. Speed-Vs-Accuracy . . . . . . . . . . . . . . . . . . 82
9.4.4. N-Best-List-Length . . . . . . . . . . . . . . . . . 82
9.4.5. Input-Type . . . . . . . . . . . . . . . . . . . . . 82
9.4.6. No-Input-Timeout . . . . . . . . . . . . . . . . . . 83
9.4.7. Recognition-Timeout . . . . . . . . . . . . . . . . . 83
9.4.8. Waveform-URI . . . . . . . . . . . . . . . . . . . . 83
9.4.9. Media-Type . . . . . . . . . . . . . . . . . . . . . 84
9.4.10. Input-Waveform-URI . . . . . . . . . . . . . . . . . 84
9.4.11. Completion-Cause . . . . . . . . . . . . . . . . . . 84
9.4.12. Completion-Reason . . . . . . . . . . . . . . . . . . 86
9.4.13. Recognizer-Context-Block . . . . . . . . . . . . . . 87
9.4.14. Start-Input-Timers . . . . . . . . . . . . . . . . . 87
9.4.15. Speech-Complete-Timeout . . . . . . . . . . . . . . . 88
9.4.16. Speech-Incomplete-Timeout . . . . . . . . . . . . . . 88
9.4.17. DTMF-Interdigit-Timeout . . . . . . . . . . . . . . . 89
9.4.18. DTMF-Term-Timeout . . . . . . . . . . . . . . . . . . 89
9.4.19. DTMF-Term-Char . . . . . . . . . . . . . . . . . . . 89
9.4.20. Failed-URI . . . . . . . . . . . . . . . . . . . . . 89
9.4.21. Failed-URI-Cause . . . . . . . . . . . . . . . . . . 90
9.4.22. Save-Waveform . . . . . . . . . . . . . . . . . . . . 90
9.4.23. New-Audio-Channel . . . . . . . . . . . . . . . . . . 90
9.4.24. Speech-Language . . . . . . . . . . . . . . . . . . . 91
9.4.25. Ver-Buffer-Utterance . . . . . . . . . . . . . . . . 91
9.4.26. Recognition-Mode . . . . . . . . . . . . . . . . . . 91
9.4.27. Cancel-If-Queue . . . . . . . . . . . . . . . . . . . 92
9.4.28. Hotword-Max-Duration . . . . . . . . . . . . . . . . 92
9.4.29. Hotword-Min-Duration . . . . . . . . . . . . . . . . 92
9.4.30. Interpret-Text . . . . . . . . . . . . . . . . . . . 93
9.4.31. DTMF-Buffer-Time . . . . . . . . . . . . . . . . . . 93
9.4.32. Clear-DTMF-Buffer . . . . . . . . . . . . . . . . . . 93
9.4.33. Early-No-Match . . . . . . . . . . . . . . . . . . . 93
9.4.34. Num-Min-Consistent-Pronunciations . . . . . . . . . . 94
9.4.35. Consistency-Threshold . . . . . . . . . . . . . . . . 94
9.4.36. Clash-Threshold . . . . . . . . . . . . . . . . . . . 94
9.4.37. Personal-Grammar-URI . . . . . . . . . . . . . . . . 95
9.4.38. Enroll-Utterance . . . . . . . . . . . . . . . . . . 95
9.4.39. Phrase-Id . . . . . . . . . . . . . . . . . . . . . . 95
9.4.40. Phrase-NL . . . . . . . . . . . . . . . . . . . . . . 95
Burnett & Shanmugham Standards Track [Page 4]
RFC 6787 MRCPv2 November 2012
9.4.41. Weight . . . . . . . . . . . . . . . . . . . . . . . 96
9.4.42. Save-Best-Waveform . . . . . . . . . . . . . . . . . 96
9.4.43. New-Phrase-Id . . . . . . . . . . . . . . . . . . . . 96
9.4.44. Confusable-Phrases-URI . . . . . . . . . . . . . . . 97
9.4.45. Abort-Phrase-Enrollment . . . . . . . . . . . . . . . 97
9.5. Recognizer Message Body . . . . . . . . . . . . . . . . . 97
9.5.1. Recognizer Grammar Data . . . . . . . . . . . . . . . 97
9.5.2. Recognizer Result Data . . . . . . . . . . . . . . . 101
9.5.3. Enrollment Result Data . . . . . . . . . . . . . . . 101
9.5.4. Recognizer Context Block . . . . . . . . . . . . . . 102
9.6. Recognizer Results . . . . . . . . . . . . . . . . . . . 102
9.6.1. Markup Functions . . . . . . . . . . . . . . . . . . 103
9.6.2. Overview of Recognizer Result Elements and Their
Relationships . . . . . . . . . . . . . . . . . . . . 104
9.6.3. Elements and Attributes . . . . . . . . . . . . . . . 105
9.7. Enrollment Results . . . . . . . . . . . . . . . . . . . 109
9.7.1. Element . . . . . . . . . . . . . . . . 110
9.7.2. Element . . . . . . . . . . . 110
9.7.3. Element . . . . . . . 110
9.7.4. Element . . . . . . . . . . . . 110
9.7.5. Element . . . . . . . . . . . . . 111
9.7.6. Element . . . . . . . . . . . . . . 111
9.7.7. Element . . . . . . . . . . . . 111
9.8. DEFINE-GRAMMAR . . . . . . . . . . . . . . . . . . . . . 111
9.9. RECOGNIZE . . . . . . . . . . . . . . . . . . . . . . . . 115
9.10. STOP . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.11. GET-RESULT . . . . . . . . . . . . . . . . . . . . . . . 122
9.12. START-OF-INPUT . . . . . . . . . . . . . . . . . . . . . 123
9.13. START-INPUT-TIMERS . . . . . . . . . . . . . . . . . . . 124
9.14. RECOGNITION-COMPLETE . . . . . . . . . . . . . . . . . . 124
9.15. START-PHRASE-ENROLLMENT . . . . . . . . . . . . . . . . . 126
9.16. ENROLLMENT-ROLLBACK . . . . . . . . . . . . . . . . . . . 127
9.17. END-PHRASE-ENROLLMENT . . . . . . . . . . . . . . . . . . 128
9.18. MODIFY-PHRASE . . . . . . . . . . . . . . . . . . . . . . 128
9.19. DELETE-PHRASE . . . . . . . . . . . . . . . . . . . . . . 129
9.20. INTERPRET . . . . . . . . . . . . . . . . . . . . . . . . 129
9.21. INTERPRETATION-COMPLETE . . . . . . . . . . . . . . . . . 131
9.22. DTMF Detection . . . . . . . . . . . . . . . . . . . . . 132
10. Recorder Resource . . . . . . . . . . . . . . . . . . . . . . 132
10.1. Recorder State Machine . . . . . . . . . . . . . . . . . 133
10.2. Recorder Methods . . . . . . . . . . . . . . . . . . . . 133
10.3. Recorder Events . . . . . . . . . . . . . . . . . . . . 133
10.4. Recorder Header Fields . . . . . . . . . . . . . . . . . 133
10.4.1. Sensitivity-Level . . . . . . . . . . . . . . . . . 134
10.4.2. No-Input-Timeout . . . . . . . . . . . . . . . . . . 134
10.4.3. Completion-Cause . . . . . . . . . . . . . . . . . . 134
10.4.4. Completion-Reason . . . . . . . . . . . . . . . . . 135
10.4.5. Failed-URI . . . . . . . . . . . . . . . . . . . . . 135
Burnett & Shanmugham Standards Track [Page 5]
RFC 6787 MRCPv2 November 2012
10.4.6. Failed-URI-Cause . . . . . . . . . . . . . . . . . . 136
10.4.7. Record-URI . . . . . . . . . . . . . . . . . . . . . 136
10.4.8. Media-Type . . . . . . . . . . . . . . . . . . . . . 136
10.4.9. Max-Time . . . . . . . . . . . . . . . . . . . . . . 137
10.4.10. Trim-Length . . . . . . . . . . . . . . . . . . . . 137
10.4.11. Final-Silence . . . . . . . . . . . . . . . . . . . 137
10.4.12. Capture-On-Speech . . . . . . . . . . . . . . . . . 137
10.4.13. Ver-Buffer-Utterance . . . . . . . . . . . . . . . . 138
10.4.14. Start-Input-Timers . . . . . . . . . . . . . . . . . 138
10.4.15. New-Audio-Channel . . . . . . . . . . . . . . . . . 138
10.5. Recorder Message Body . . . . . . . . . . . . . . . . . 138
10.6. RECORD . . . . . . . . . . . . . . . . . . . . . . . . . 139
10.7. STOP . . . . . . . . . . . . . . . . . . . . . . . . . . 140
10.8. RECORD-COMPLETE . . . . . . . . . . . . . . . . . . . . 141
10.9. START-INPUT-TIMERS . . . . . . . . . . . . . . . . . . . 142
10.10. START-OF-INPUT . . . . . . . . . . . . . . . . . . . . . 142
11. Speaker Verification and Identification . . . . . . . . . . . 143
11.1. Speaker Verification State Machine . . . . . . . . . . . 144
11.2. Speaker Verification Methods . . . . . . . . . . . . . . 146
11.3. Verification Events . . . . . . . . . . . . . . . . . . 147
11.4. Verification Header Fields . . . . . . . . . . . . . . . 148
11.4.1. Repository-URI . . . . . . . . . . . . . . . . . . . 148
11.4.2. Voiceprint-Identifier . . . . . . . . . . . . . . . 148
11.4.3. Verification-Mode . . . . . . . . . . . . . . . . . 149
11.4.4. Adapt-Model . . . . . . . . . . . . . . . . . . . . 150
11.4.5. Abort-Model . . . . . . . . . . . . . . . . . . . . 150
11.4.6. Min-Verification-Score . . . . . . . . . . . . . . . 150
11.4.7. Num-Min-Verification-Phrases . . . . . . . . . . . . 151
11.4.8. Num-Max-Verification-Phrases . . . . . . . . . . . . 151
11.4.9. No-Input-Timeout . . . . . . . . . . . . . . . . . . 151
11.4.10. Save-Waveform . . . . . . . . . . . . . . . . . . . 151
11.4.11. Media-Type . . . . . . . . . . . . . . . . . . . . . 152
11.4.12. Waveform-URI . . . . . . . . . . . . . . . . . . . . 152
11.4.13. Voiceprint-Exists . . . . . . . . . . . . . . . . . 153
11.4.14. Ver-Buffer-Utterance . . . . . . . . . . . . . . . . 153
11.4.15. Input-Waveform-URI . . . . . . . . . . . . . . . . . 153
11.4.16. Completion-Cause . . . . . . . . . . . . . . . . . . 153
11.4.17. Completion-Reason . . . . . . . . . . . . . . . . . 156
11.4.18. Speech-Complete-Timeout . . . . . . . . . . . . . . 156
11.4.19. New-Audio-Channel . . . . . . . . . . . . . . . . . 156
11.4.20. Abort-Verification . . . . . . . . . . . . . . . . . 156
11.4.21. Start-Input-Timers . . . . . . . . . . . . . . . . . 156
11.5. Verification Message Body . . . . . . . . . . . . . . . 157
11.5.1. Verification Result Data . . . . . . . . . . . . . . 157
11.5.2. Verification Result Elements . . . . . . . . . . . . 157
11.6. START-SESSION . . . . . . . . . . . . . . . . . . . . . 161
11.7. END-SESSION . . . . . . . . . . . . . . . . . . . . . . 162
11.8. QUERY-VOICEPRINT . . . . . . . . . . . . . . . . . . . . 163
Burnett & Shanmugham Standards Track [Page 6]
RFC 6787 MRCPv2 November 2012
11.9. DELETE-VOICEPRINT . . . . . . . . . . . . . . . . . . . 164
11.10. VERIFY . . . . . . . . . . . . . . . . . . . . . . . . . 165
11.11. VERIFY-FROM-BUFFER . . . . . . . . . . . . . . . . . . . 165
11.12. VERIFY-ROLLBACK . . . . . . . . . . . . . . . . . . . . 168
11.13. STOP . . . . . . . . . . . . . . . . . . . . . . . . . . 169
11.14. START-INPUT-TIMERS . . . . . . . . . . . . . . . . . . . 170
11.15. VERIFICATION-COMPLETE . . . . . . . . . . . . . . . . . 170
11.16. START-OF-INPUT . . . . . . . . . . . . . . . . . . . . . 171
11.17. CLEAR-BUFFER . . . . . . . . . . . . . . . . . . . . . . 171
11.18. GET-INTERMEDIATE-RESULT . . . . . . . . . . . . . . . . 171
12. Security Considerations . . . . . . . . . . . . . . . . . . . 172
12.1. Rendezvous and Session Establishment . . . . . . . . . . 173
12.2. Control Channel Protection . . . . . . . . . . . . . . . 173
12.3. Media Session Protection . . . . . . . . . . . . . . . . 173
12.4. Indirect Content Access . . . . . . . . . . . . . . . . 174
12.5. Protection of Stored Media . . . . . . . . . . . . . . . 175
12.6. DTMF and Recognition Buffers . . . . . . . . . . . . . . 175
12.7. Client-Set Server Parameters . . . . . . . . . . . . . . 175
12.8. DELETE-VOICEPRINT and Authorization . . . . . . . . . . 175
13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 176
13.1. New Registries . . . . . . . . . . . . . . . . . . . . . 176
13.1.1. MRCPv2 Resource Types . . . . . . . . . . . . . . . 176
13.1.2. MRCPv2 Methods and Events . . . . . . . . . . . . . 176
13.1.3. MRCPv2 Header Fields . . . . . . . . . . . . . . . . 178
13.1.4. MRCPv2 Status Codes . . . . . . . . . . . . . . . . 180
13.1.5. Grammar Reference List Parameters . . . . . . . . . 180
13.1.6. MRCPv2 Vendor-Specific Parameters . . . . . . . . . 181
13.2. NLSML-Related Registrations . . . . . . . . . . . . . . 181
13.2.1. 'application/nlsml+xml' Media Type Registration . . 181
13.3. NLSML XML Schema Registration . . . . . . . . . . . . . 182
13.4. MRCPv2 XML Namespace Registration . . . . . . . . . . . 183
13.5. Text Media Type Registrations . . . . . . . . . . . . . 183
13.5.1. text/grammar-ref-list . . . . . . . . . . . . . . . 183
13.6. 'session' URI Scheme Registration . . . . . . . . . . . 184
13.7. SDP Parameter Registrations . . . . . . . . . . . . . . 185
13.7.1. Sub-Registry "proto" . . . . . . . . . . . . . . . . 186
13.7.2. Sub-Registry "att-field (media-level)" . . . . . . . 186
14. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 188
14.1. Message Flow . . . . . . . . . . . . . . . . . . . . . . 188
14.2. Recognition Result Examples . . . . . . . . . . . . . . 197
14.2.1. Simple ASR Ambiguity . . . . . . . . . . . . . . . . 197
14.2.2. Mixed Initiative . . . . . . . . . . . . . . . . . . 198
14.2.3. DTMF Input . . . . . . . . . . . . . . . . . . . . . 199
14.2.4. Interpreting Meta-Dialog and Meta-Task Utterances . 199
14.2.5. Anaphora and Deixis . . . . . . . . . . . . . . . . 200
14.2.6. Distinguishing Individual Items from Sets with One
Member . . . . . . . . . . . . . . . . . . . . . . . 201
14.2.7. Extensibility . . . . . . . . . . . . . . . . . . . 202
Burnett & Shanmugham Standards Track [Page 7]
RFC 6787 MRCPv2 November 2012
15. ABNF Normative Definition . . . . . . . . . . . . . . . . . . 202
16. XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . 217
16.1. NLSML Schema Definition . . . . . . . . . . . . . . . . 217
16.2. Enrollment Results Schema Definition . . . . . . . . . . 218
16.3. Verification Results Schema Definition . . . . . . . . . 220
17. References . . . . . . . . . . . . . . . . . . . . . . . . . 223
17.1. Normative References . . . . . . . . . . . . . . . . . . 223
17.2. Informative References . . . . . . . . . . . . . . . . . 226
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 228
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 228
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 229
1. Introduction
MRCPv2 is designed to allow a client device to control media
processing resources on the network. Some of these media processing
resources include speech recognition engines, speech synthesis
engines, speaker verification, and speaker identification engines.
MRCPv2 enables the implementation of distributed Interactive Voice
Response platforms using VoiceXML [W3C.REC-voicexml20-20040316]
browsers or other client applications while maintaining separate
back-end speech processing capabilities on specialized speech
processing servers. MRCPv2 is based on the earlier Media Resource
Control Protocol (MRCP) [RFC4463] developed jointly by Cisco Systems,
Inc., Nuance Communications, and Speechworks, Inc. Although some of
the method names are similar, the way in which these methods are
communicated is different. There are also more resources and more
methods for each resource. The first version of MRCP was essentially
taken only as input to the development of this protocol. There is no
expectation that an MRCPv2 client will work with an MRCPv1 server or
vice versa. There is no migration plan or gateway definition between
the two protocols.
The protocol requirements of Speech Services Control (SPEECHSC)
[RFC4313] include that the solution be capable of reaching a media
processing server, setting up communication channels to the media
resources, and sending and receiving control messages and media
streams to/from the server. The Session Initiation Protocol (SIP)
[RFC3261] meets these requirements.
The proprietary version of MRCP ran over the Real Time Streaming
Protocol (RTSP) [RFC2326]. At the time work on MRCPv2 was begun, the
consensus was that this use of RTSP would break the RTSP protocol or
cause backward-compatibility problems, something forbidden by
Section 3.2 of [RFC4313]. This is the reason why MRCPv2 does not run
over RTSP.
Burnett & Shanmugham Standards Track [Page 8]
RFC 6787 MRCPv2 November 2012
MRCPv2 leverages these capabilities by building upon SIP and the
Session Description Protocol (SDP) [RFC4566]. MRCPv2 uses SIP to set
up and tear down media and control sessions with the server. In
addition, the client can use a SIP re-INVITE method (an INVITE dialog
sent within an existing SIP session) to change the characteristics of
these media and control session while maintaining the SIP dialog
between the client and server. SDP is used to describe the
parameters of the media sessions associated with that dialog. It is
mandatory to support SIP as the session establishment protocol to
ensure interoperability. Other protocols can be used for session
establishment by prior agreement. This document only describes the
use of SIP and SDP.
MRCPv2 uses SIP and SDP to create the speech client/server dialog and
set up the media channels to the server. It also uses SIP and SDP to
establish MRCPv2 control sessions between the client and the server
for each media processing resource required for that dialog. The
MRCPv2 protocol exchange between the client and the media resource is
carried on that control session. MRCPv2 exchanges do not change the
state of the SIP dialog, the media sessions, or other parameters of
the dialog initiated via SIP. It controls and affects the state of
the media processing resource associated with the MRCPv2 session(s).
MRCPv2 defines the messages to control the different media processing
resources and the state machines required to guide their operation.
It also describes how these messages are carried over a transport-
layer protocol such as the Transmission Control Protocol (TCP)
[RFC0793] or the Transport Layer Security (TLS) Protocol [RFC5246].
(Note: the Stream Control Transmission Protocol (SCTP) [RFC4960] is a
viable transport for MRCPv2 as well, but the mapping onto SCTP is not
described in this specification.)
2. Document Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
Since many of the definitions and syntax are identical to those for
the Hypertext Transfer Protocol -- HTTP/1.1 [RFC2616], this
specification refers to the section where they are defined rather
than copying it. For brevity, [HX.Y] is to be taken to refer to
Section X.Y of RFC 2616.
All the mechanisms specified in this document are described in both
prose and an augmented Backus-Naur form (ABNF [RFC5234]).
Burnett & Shanmugham Standards Track [Page 9]
RFC 6787 MRCPv2 November 2012
The complete message format in ABNF form is provided in Section 15
and is the normative format definition. Note that productions may be
duplicated within the main body of the document for reading
convenience. If a production in the body of the text conflicts with
one in the normative definition, the latter rules.
2.1. Definitions
Media Resource
An entity on the speech processing server that can be
controlled through MRCPv2.
MRCP Server
Aggregate of one or more "Media Resource" entities on
a server, exposed through MRCPv2. Often, 'server' in
this document refers to an MRCP server.
MRCP Client
An entity controlling one or more Media Resources
through MRCPv2 ("Client" for short).
DTMF
Dual-Tone Multi-Frequency; a method of transmitting
key presses in-band, either as actual tones (Q.23
[Q.23]) or as named tone events (RFC 4733 [RFC4733]).
Endpointing
The process of automatically detecting the beginning
and end of speech in an audio stream. This is
critical both for speech recognition and for automated
recording as one would find in voice mail systems.
Hotword Mode
A mode of speech recognition where a stream of
utterances is evaluated for match against a small set
of command words. This is generally employed either
to trigger some action or to control the subsequent
grammar to be used for further recognition.
2.2. State-Machine Diagrams
The state-machine diagrams in this document do not show every
possible method call. Rather, they reflect the state of the resource
based on the methods that have moved to IN-PROGRESS or COMPLETE
states (see Section 5.3). Note that since PENDING requests
essentially have not affected the resource yet and are in the queue
to be processed, they are not reflected in the state-machine
diagrams.
Burnett & Shanmugham Standards Track [Page 10]
RFC 6787 MRCPv2 November 2012
2.3. URI Schemes
This document defines many protocol headers that contain URIs
(Uniform Resource Identifiers [RFC3986]) or lists of URIs for
referencing media. The entire document, including the Security
Considerations section (Section 12), assumes that HTTP or HTTP over
TLS (HTTPS) [RFC2818] will be used as the URI addressing scheme
unless otherwise stated. However, implementations MAY support other
schemes (such as 'file'), provided they have addressed any security
considerations described in this document and any others particular
to the specific scheme. For example, implementations where the
client and server both reside on the same physical hardware and the
file system is secured by traditional user-level file access controls
could be reasonable candidates for supporting the 'file' scheme.
3. Architecture
A system using MRCPv2 consists of a client that requires the
generation and/or consumption of media streams and a media resource
server that has the resources or "engines" to process these streams
as input or generate these streams as output. The client uses SIP
and SDP to establish an MRCPv2 control channel with the server to use
its media processing resources. MRCPv2 servers are addressed using
SIP URIs.
SIP uses SDP with the offer/answer model described in RFC 3264
[RFC3264] to set up the MRCPv2 control channels and describe their
characteristics. A separate MRCPv2 session is needed to control each
of the media processing resources associated with the SIP dialog
between the client and server. Within a SIP dialog, the individual
resource control channels for the different resources are added or
removed through SDP offer/answer carried in a SIP re-INVITE
transaction.
The server, through the SDP exchange, provides the client with a
difficult-to-guess, unambiguous channel identifier and a TCP port
number (see Section 4.2). The client MAY then open a new TCP
connection with the server on this port number. Multiple MRCPv2
channels can share a TCP connection between the client and the
server. All MRCPv2 messages exchanged between the client and the
server carry the specified channel identifier that the server MUST
ensure is unambiguous among all MRCPv2 control channels that are
active on that server. The client uses this channel identifier to
indicate the media processing resource associated with that channel.
For information on message framing, see Section 5.
SIP also establishes the media sessions between the client (or other
source/sink of media) and the MRCPv2 server using SDP "m=" lines.
Burnett & Shanmugham Standards Track [Page 11]
RFC 6787 MRCPv2 November 2012
One or more media processing resources may share a media session
under a SIP session, or each media processing resource may have its
own media session.
The following diagram shows the general architecture of a system that
uses MRCPv2. To simplify the diagram, only a few resources are
shown.
MRCPv2 client MRCPv2 Media Resource Server
|--------------------| |------------------------------------|
||------------------|| ||----------------------------------||
|| Application Layer|| ||Synthesis|Recognition|Verification||
||------------------|| || Engine | Engine | Engine ||
||Media Resource API|| || || | || | || ||
||------------------|| ||Synthesis|Recognizer | Verifier ||
|| SIP | MRCPv2 || ||Resource | Resource | Resource ||
||Stack | || || Media Resource Management ||
|| | || ||----------------------------------||
||------------------|| || SIP | MRCPv2 ||
|| TCP/IP Stack ||--MRCPv2-|| Stack | ||
|| || ||----------------------------------||
||------------------||---SIP---|| TCP/IP Stack ||
|--------------------| || ||
| ||----------------------------------||
SIP |------------------------------------|
| /
|-------------------| RTP
| | /
| Media Source/Sink |---------/
| |
|-------------------|
Figure 1: Architectural Diagram
3.1. MRCPv2 Media Resource Types
An MRCPv2 server may offer one or more of the following media
processing resources to its clients.
Basic Synthesizer
A speech synthesizer resource that has very limited
capabilities and can generate its media stream
exclusively from concatenated audio clips. The speech
data is described using a limited subset of the Speech
Synthesis Markup Language (SSML)
[W3C.REC-speech-synthesis-20040907] elements. A basic
synthesizer MUST support the SSML tags ,
, , and .
Burnett & Shanmugham Standards Track [Page 12]
RFC 6787 MRCPv2 November 2012
Speech Synthesizer
A full-capability speech synthesis resource that can
render speech from text. Such a synthesizer MUST have
full SSML [W3C.REC-speech-synthesis-20040907] support.
Recorder
A resource capable of recording audio and providing a
URI pointer to the recording. A recorder MUST provide
endpointing capabilities for suppressing silence at
the beginning and end of a recording, and MAY also
suppress silence in the middle of a recording. If
such suppression is done, the recorder MUST maintain
timing metadata to indicate the actual timestamps of
the recorded media.
DTMF Recognizer
A recognizer resource capable of extracting and
interpreting Dual-Tone Multi-Frequency (DTMF) [Q.23]
digits in a media stream and matching them against a
supplied digit grammar. It could also do a semantic
interpretation based on semantic tags in the grammar.
Speech Recognizer
A full speech recognition resource that is capable of
receiving a media stream containing audio and
interpreting it to recognition results. It also has a
natural language semantic interpreter to post-process
the recognized data according to the semantic data in
the grammar and provide semantic results along with
the recognized input. The recognizer MAY also support
enrolled grammars, where the client can enroll and
create new personal grammars for use in future
recognition operations.
Speaker Verifier
A resource capable of verifying the authenticity of a
claimed identity by matching a media stream containing
spoken input to a pre-existing voiceprint. This may
also involve matching the caller's voice against more
than one voiceprint, also called multi-verification or
speaker identification.
3.2. Server and Resource Addressing
The MRCPv2 server is a generic SIP server, and is thus addressed by a
SIP URI (RFC 3261 [RFC3261]).
Burnett & Shanmugham Standards Track [Page 13]
RFC 6787 MRCPv2 November 2012
For example:
sip:mrcpv2@example.net or
sips:mrcpv2@example.net
4. MRCPv2 Basics
MRCPv2 requires a connection-oriented transport-layer protocol such
as TCP to guarantee reliable sequencing and delivery of MRCPv2
control messages between the client and the server. In order to meet
the requirements for security enumerated in SPEECHSC requirements
[RFC4313], clients and servers MUST implement TLS as well. One or
more connections between the client and the server can be shared
among different MRCPv2 channels to the server. The individual
messages carry the channel identifier to differentiate messages on
different channels. MRCPv2 encoding is text based with mechanisms to
carry embedded binary data. This allows arbitrary data like
recognition grammars, recognition results, synthesizer speech markup,
etc., to be carried in MRCPv2 messages. For information on message
framing, see Section 5.
4.1. Connecting to the Server
MRCPv2 employs SIP, in conjunction with SDP, as the session
establishment and management protocol. The client reaches an MRCPv2
server using conventional INVITE and other SIP requests for
establishing, maintaining, and terminating SIP dialogs. The SDP
offer/answer exchange model over SIP is used to establish a resource
control channel for each resource. The SDP offer/answer exchange is
also used to establish media sessions between the server and the
source or sink of audio.
4.2. Managing Resource Control Channels
The client needs a separate MRCPv2 resource control channel to
control each media processing resource under the SIP dialog. A
unique channel identifier string identifies these resource control
channels. The channel identifier is a difficult-to-guess,
unambiguous string followed by an "@", then by a string token
specifying the type of resource. The server generates the channel
identifier and MUST make sure it does not clash with the identifier
of any other MRCP channel currently allocated by that server. MRCPv2
defines the following IANA-registered types of media processing
resources. Additional resource types and their associated methods/
events and state machines may be added as described below in
Section 13.
Burnett & Shanmugham Standards Track [Page 14]
RFC 6787 MRCPv2 November 2012
+---------------+----------------------+--------------+
| Resource Type | Resource Description | Described in |
+---------------+----------------------+--------------+
| speechrecog | Speech Recognizer | Section 9 |
| dtmfrecog | DTMF Recognizer | Section 9 |
| speechsynth | Speech Synthesizer | Section 8 |
| basicsynth | Basic Synthesizer | Section 8 |
| speakverify | Speaker Verification | Section 11 |
| recorder | Speech Recorder | Section 10 |
+---------------+----------------------+--------------+
Table 1: Resource Types
The SIP INVITE or re-INVITE transaction and the SDP offer/answer
exchange it carries contain "m=" lines describing the resource
control channel to be allocated. There MUST be one SDP "m=" line for
each MRCPv2 resource to be used in the session. This "m=" line MUST
have a media type field of "application" and a transport type field
of either "TCP/MRCPv2" or "TCP/TLS/MRCPv2". The port number field of
the "m=" line MUST contain the "discard" port of the transport
protocol (port 9 for TCP) in the SDP offer from the client and MUST
contain the TCP listen port on the server in the SDP answer. The
client may then either set up a TCP or TLS connection to that server
port or share an already established connection to that port. Since
MRCPv2 allows multiple sessions to share the same TCP connection,
multiple "m=" lines in a single SDP document MAY share the same port
field value; MRCPv2 servers MUST NOT assume any relationship between
resources using the same port other than the sharing of the
communication channel.
MRCPv2 resources do not use the port or format field of the "m=" line
to distinguish themselves from other resources using the same
channel. The client MUST specify the resource type identifier in the
resource attribute associated with the control "m=" line of the SDP
offer. The server MUST respond with the full Channel-Identifier
(which includes the resource type identifier and a difficult-to-
guess, unambiguous string) in the "channel" attribute associated with
the control "m=" line of the SDP answer. To remain backwards
compatible with conventional SDP usage, the format field of the "m="
line MUST have the arbitrarily selected value of "1".
When the client wants to add a media processing resource to the
session, it issues a new SDP offer, according to the procedures of
RFC 3264 [RFC3264], in a SIP re-INVITE request. The SDP offer/answer
exchange carried by this SIP transaction contains one or more
additional control "m=" lines for the new resources to be allocated
to the session. The server, on seeing the new "m=" line, allocates
the resources (if they are available) and responds with a
Burnett & Shanmugham Standards Track [Page 15]
RFC 6787 MRCPv2 November 2012
corresponding control "m=" line in the SDP answer carried in the SIP
response. If the new resources are not available, the re-INVITE
receives an error message, and existing media processing going on
before the re-INVITE will continue as it was before. It is not
possible to allocate more than one resource of each type. If a
client requests more than one resource of any type, the server MUST
behave as if the resources of that type (beyond the first one) are
not available.
MRCPv2 clients and servers using TCP as a transport protocol MUST use
the procedures specified in RFC 4145 [RFC4145] for setting up the TCP
connection, with the considerations described hereby. Similarly,
MRCPv2 clients and servers using TCP/TLS as a transport protocol MUST
use the procedures specified in RFC 4572 [RFC4572] for setting up the
TLS connection, with the considerations described hereby. The
a=setup attribute, as described in RFC 4145 [RFC4145], MUST be
"active" for the offer from the client and MUST be "passive" for the
answer from the MRCPv2 server. The a=connection attribute MUST have
a value of "new" on the very first control "m=" line offer from the
client to an MRCPv2 server. Subsequent control "m=" line offers from
the client to the MRCP server MAY contain "new" or "existing",
depending on whether the client wants to set up a new connection or
share an existing connection, respectively. If the client specifies
a value of "new", the server MUST respond with a value of "new". If
the client specifies a value of "existing", the server MUST respond.
The legal values in the response are "existing" if the server prefers
to share an existing connection or "new" if not. In the latter case,
the client MUST initiate a new transport connection.
When the client wants to deallocate the resource from this session,
it issues a new SDP offer, according to RFC 3264 [RFC3264], where the
control "m=" line port MUST be set to 0. This SDP offer is sent in a
SIP re-INVITE request. This deallocates the associated MRCPv2
identifier and resource. The server MUST NOT close the TCP or TLS
connection if it is currently being shared among multiple MRCP
channels. When all MRCP channels that may be sharing the connection
are released and/or the associated SIP dialog is terminated, the
client or server terminates the connection.
When the client wants to tear down the whole session and all its
resources, it MUST issue a SIP BYE request to close the SIP session.
This will deallocate all the control channels and resources allocated
under the session.
All servers MUST support TLS. Servers MAY use TCP without TLS in
controlled environments (e.g., not in the public Internet) where both
nodes are inside a protected perimeter, for example, preventing
access to the MRCP server from remote nodes outside the controlled
Burnett & Shanmugham Standards Track [Page 16]
RFC 6787 MRCPv2 November 2012
perimeter. It is up to the client, through the SDP offer, to choose
which transport it wants to use for an MRCPv2 session. Aside from
the exceptions given above, when using TCP, the "m=" lines MUST
conform to RFC4145 [RFC4145], which describes the usage of SDP for
connection-oriented transport. When using TLS, the SDP "m=" line for
the control stream MUST conform to Connection-Oriented Media
(COMEDIA) over TLS [RFC4572], which specifies the usage of SDP for
establishing a secure connection-oriented transport over TLS.
4.3. SIP Session Example
This first example shows the power of using SIP to route to the
appropriate resource. In the example, note the use of a request to a
domain's speech server service in the INVITE to
mresources@example.com. The SIP routing machinery in the domain
locates the actual server, mresources@server.example.com, which gets
returned in the 200 OK. Note that "cmid" is defined in Section 4.4.
This example exchange adds a resource control channel for a
synthesizer. Since a synthesizer also generates an audio stream,
this interaction also creates a receive-only Real-Time Protocol (RTP)
[RFC3550] media session for the server to send audio to. The SIP
dialog with the media source/sink is independent of MRCP and is not
shown.
C->S: INVITE sip:mresources@example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf1
Max-Forwards:6
To:MediaServer
From:sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314161 INVITE
Contact:
Content-Type:application/sdp
Content-Length:...
v=0
o=sarvi 2890844526 2890844526 IN IP4 192.0.2.12
s=-
c=IN IP4 192.0.2.12
t=0 0
m=application 9 TCP/MRCPv2 1
a=setup:active
a=connection:new
a=resource:speechsynth
a=cmid:1
m=audio 49170 RTP/AVP 0
Burnett & Shanmugham Standards Track [Page 17]
RFC 6787 MRCPv2 November 2012
a=rtpmap:0 pcmu/8000
a=recvonly
a=mid:1
S->C: SIP/2.0 200 OK
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf1;received=192.0.32.10
To:MediaServer ;tag=62784
From:sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314161 INVITE
Contact:
Content-Type:application/sdp
Content-Length:...
v=0
o=- 2890842808 2890842808 IN IP4 192.0.2.11
s=-
c=IN IP4 192.0.2.11
t=0 0
m=application 32416 TCP/MRCPv2 1
a=setup:passive
a=connection:new
a=channel:32AECB234338@speechsynth
a=cmid:1
m=audio 48260 RTP/AVP 0
a=rtpmap:0 pcmu/8000
a=sendonly
a=mid:1
C->S: ACK sip:mresources@server.example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf2
Max-Forwards:6
To:MediaServer ;tag=62784
From:Sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314161 ACK
Content-Length:0
Example: Add Synthesizer Control Channel
This example exchange continues from the previous figure and
allocates an additional resource control channel for a recognizer.
Since a recognizer would need to receive an audio stream for
recognition, this interaction also updates the audio stream to
Burnett & Shanmugham Standards Track [Page 18]
RFC 6787 MRCPv2 November 2012
sendrecv, making it a two-way RTP media session.
C->S: INVITE sip:mresources@server.example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf3
Max-Forwards:6
To:MediaServer ;tag=62784
From:sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314162 INVITE
Contact:
Content-Type:application/sdp
Content-Length:...
v=0
o=sarvi 2890844526 2890844527 IN IP4 192.0.2.12
s=-
c=IN IP4 192.0.2.12
t=0 0
m=application 9 TCP/MRCPv2 1
a=setup:active
a=connection:existing
a=resource:speechsynth
a=cmid:1
m=audio 49170 RTP/AVP 0 96
a=rtpmap:0 pcmu/8000
a=rtpmap:96 telephone-event/8000
a=fmtp:96 0-15
a=sendrecv
a=mid:1
m=application 9 TCP/MRCPv2 1
a=setup:active
a=connection:existing
a=resource:speechrecog
a=cmid:1
S->C: SIP/2.0 200 OK
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf3;received=192.0.32.10
To:MediaServer ;tag=62784
From:sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314162 INVITE
Contact:
Content-Type:application/sdp
Content-Length:...
Burnett & Shanmugham Standards Track [Page 19]
RFC 6787 MRCPv2 November 2012
v=0
o=- 2890842808 2890842809 IN IP4 192.0.2.11
s=-
c=IN IP4 192.0.2.11
t=0 0
m=application 32416 TCP/MRCPv2 1
a=setup:passive
a=connection:existing
a=channel:32AECB234338@speechsynth
a=cmid:1
m=audio 48260 RTP/AVP 0 96
a=rtpmap:0 pcmu/8000
a=rtpmap:96 telephone-event/8000
a=fmtp:96 0-15
a=sendrecv
a=mid:1
m=application 32416 TCP/MRCPv2 1
a=setup:passive
a=connection:existing
a=channel:32AECB234338@speechrecog
a=cmid:1
C->S: ACK sip:mresources@server.example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf4
Max-Forwards:6
To:MediaServer ;tag=62784
From:Sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314162 ACK
Content-Length:0
Example: Add Recognizer
This example exchange continues from the previous figure and
deallocates the recognizer channel. Since a recognizer no longer
needs to receive an audio stream, this interaction also updates the
RTP media session to recvonly.
C->S: INVITE sip:mresources@server.example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf5
Max-Forwards:6
To:MediaServer ;tag=62784
From:sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314163 INVITE
Burnett & Shanmugham Standards Track [Page 20]
RFC 6787 MRCPv2 November 2012
Contact:
Content-Type:application/sdp
Content-Length:...
v=0
o=sarvi 2890844526 2890844528 IN IP4 192.0.2.12
s=-
c=IN IP4 192.0.2.12
t=0 0
m=application 9 TCP/MRCPv2 1
a=resource:speechsynth
a=cmid:1
m=audio 49170 RTP/AVP 0
a=rtpmap:0 pcmu/8000
a=recvonly
a=mid:1
m=application 0 TCP/MRCPv2 1
a=resource:speechrecog
a=cmid:1
S->C: SIP/2.0 200 OK
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf5;received=192.0.32.10
To:MediaServer ;tag=62784
From:sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314163 INVITE
Contact:
Content-Type:application/sdp
Content-Length:...
v=0
o=- 2890842808 2890842810 IN IP4 192.0.2.11
s=-
c=IN IP4 192.0.2.11
t=0 0
m=application 32416 TCP/MRCPv2 1
a=channel:32AECB234338@speechsynth
a=cmid:1
m=audio 48260 RTP/AVP 0
a=rtpmap:0 pcmu/8000
a=sendonly
a=mid:1
m=application 0 TCP/MRCPv2 1
a=channel:32AECB234338@speechrecog
a=cmid:1
Burnett & Shanmugham Standards Track [Page 21]
RFC 6787 MRCPv2 November 2012
C->S: ACK sip:mresources@server.example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf6
Max-Forwards:6
To:MediaServer ;tag=62784
From:Sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:314163 ACK
Content-Length:0
Example: Deallocate Recognizer
4.4. Media Streams and RTP Ports
Since MRCPv2 resources either generate or consume media streams, the
client or the server needs to associate media sessions with their
corresponding resource or resources. More than one resource could be
associated with a single media session or each resource could be
assigned a separate media session. Also, note that more than one
media session can be associated with a single resource if need be,
but this scenario is not useful for the current set of resources.
For example, a synthesizer and a recognizer could be associated to
the same media session (m=audio line), if it is opened in "sendrecv"
mode. Alternatively, the recognizer could have its own "sendonly"
audio session, and the synthesizer could have its own "recvonly"
audio session.
The association between control channels and their corresponding
media sessions is established using a new "resource channel media
identifier" media-level attribute ("cmid"). Valid values of this
attribute are the values of the "mid" attribute defined in RFC 5888
[RFC5888]. If there is more than one audio "m=" line, then each
audio "m=" line MUST have a "mid" attribute. Each control "m=" line
MAY have one or more "cmid" attributes that match the resource
control channel to the "mid" attributes of the audio "m=" lines it is
associated with. Note that if a control "m=" line does not have a
"cmid" attribute it will not be associated with any media. The
operations on such a resource will hence be limited. For example, if
it was a recognizer resource, the RECOGNIZE method requires an
associated media to process while the INTERPRET method does not. The
formatting of the "cmid" attribute is described by the following
ABNF:
cmid-attribute = "a=cmid:" identification-tag
identification-tag = token
To allow this flexible mapping of media sessions to MRCPv2 control
channels, a single audio "m=" line can be associated with multiple
Burnett & Shanmugham Standards Track [Page 22]
RFC 6787 MRCPv2 November 2012
resources, or each resource can have its own audio "m=" line. For
example, if the client wants to allocate a recognizer and a
synthesizer and associate them with a single two-way audio stream,
the SDP offer would contain two control "m=" lines and a single audio
"m=" line with an attribute of "sendrecv". Each of the control "m="
lines would have a "cmid" attribute whose value matches the "mid" of
the audio "m=" line. If, on the other hand, the client wants to
allocate a recognizer and a synthesizer each with its own separate
audio stream, the SDP offer would carry two control "m=" lines (one
for the recognizer and another for the synthesizer) and two audio
"m=" lines (one with the attribute "sendonly" and another with
attribute "recvonly"). The "cmid" attribute of the recognizer
control "m=" line would match the "mid" value of the "sendonly" audio
"m=" line, and the "cmid" attribute of the synthesizer control "m="
line would match the "mid" attribute of the "recvonly" "m=" line.
When a server receives media (e.g., audio) on a media session that is
associated with more than one media processing resource, it is the
responsibility of the server to receive and fork the media to the
resources that need to consume it. If multiple resources in an
MRCPv2 session are generating audio (or other media) to be sent on a
single associated media session, it is the responsibility of the
server either to multiplex the multiple streams onto the single RTP
session or to contain an embedded RTP mixer (see RFC 3550 [RFC3550])
to combine the multiple streams into one. In the former case, the
media stream will contain RTP packets generated by different sources,
and hence the packets will have different Synchronization Source
Identifiers (SSRCs). In the latter case, the RTP packets will
contain multiple Contributing Source Identifiers (CSRCs)
corresponding to the original streams before being combined by the
mixer. If an MRCPv2 server implementation neither multiplexes nor
mixes, it MUST disallow the client from associating multiple such
resources to a single audio stream by rejecting the SDP offer with a
SIP 488 "Not Acceptable" error. Note that there is a large installed
base that will return a SIP 501 "Not Implemented" error in this case.
To facilitate interoperability with this installed base, new
implementations SHOULD treat a 501 in this context as a 488 when it
is received from an element known to be a legacy implementation.
4.5. MRCPv2 Message Transport
The MRCPv2 messages defined in this document are transported over a
TCP or TLS connection between the client and the server. The method
for setting up this transport connection and the resource control
channel is discussed in Sections 4.1 and 4.2. Multiple resource
control channels between a client and a server that belong to
different SIP dialogs can share one or more TLS or TCP connections
between them; the server and client MUST support this mode of
Burnett & Shanmugham Standards Track [Page 23]
RFC 6787 MRCPv2 November 2012
operation. Clients and servers MUST use the MRCPv2 channel
identifier, carried in the Channel-Identifier header field in
individual MRCPv2 messages, to differentiate MRCPv2 messages from
different resource channels (see Section 6.2.1 for details). All
MRCPv2 servers MUST support TLS. Servers MAY use TCP without TLS in
controlled environments (e.g., not in the public Internet) where both
nodes are inside a protected perimeter, for example, preventing
access to the MRCP server from remote nodes outside the controlled
perimeter. It is up to the client to choose which mode of transport
it wants to use for an MRCPv2 session.
Most examples from here on show only the MRCPv2 messages and do not
show the SIP messages that may have been used to establish the MRCPv2
control channel.
4.6. MRCPv2 Session Termination
If an MRCP client notices that the underlying connection has been
closed for one of its MRCP channels, and it has not previously
initiated a re-INVITE to close that channel, it MUST send a BYE to
close down the SIP dialog and all other MRCP channels. If an MRCP
server notices that the underlying connection has been closed for one
of its MRCP channels, and it has not previously received and accepted
a re-INVITE closing that channel, then it MUST send a BYE to close
down the SIP dialog and all other MRCP channels.
5. MRCPv2 Specification
Except as otherwise indicated, MRCPv2 messages are Unicode encoded in
UTF-8 (RFC 3629 [RFC3629]) to allow many different languages to be
represented. DEFINE-GRAMMAR (Section 9.8), for example, is one such
exception, since its body can contain arbitrary XML in arbitrary (but
specified via XML) encodings. MRCPv2 also allows message bodies to
be represented in other character sets (for example, ISO 8859-1
[ISO.8859-1.1987]) because, in some locales, other character sets are
already in widespread use. The MRCPv2 headers (the first line of an
MRCP message) and header field names use only the US-ASCII subset of
UTF-8.
Lines are terminated by CRLF (carriage return, then line feed).
Also, some parameters in the message may contain binary data or a
record spanning multiple lines. Such fields have a length value
associated with the parameter, which indicates the number of octets
immediately following the parameter.
Burnett & Shanmugham Standards Track [Page 24]
RFC 6787 MRCPv2 November 2012
5.1. Common Protocol Elements
The MRCPv2 message set consists of requests from the client to the
server, responses from the server to the client, and asynchronous
events from the server to the client. All these messages consist of
a start-line, one or more header fields, an empty line (i.e., a line
with nothing preceding the CRLF) indicating the end of the header
fields, and an optional message body.
generic-message = start-line
message-header
CRLF
[ message-body ]
message-body = *OCTET
start-line = request-line / response-line / event-line
message-header = 1*(generic-header / resource-header /
generic-field)
resource-header = synthesizer-header
/ recognizer-header
/ recorder-header
/ verifier-header
The message-body contains resource-specific and message-specific
data. The actual media types used to carry the data are specified in
the sections defining the individual messages. Generic header fields
are described in Section 6.2.
If a message contains a message body, the message MUST contain
content-headers indicating the media type and encoding of the data in
the message body.
Request, response and event messages (described in following
sections) include the version of MRCP that the message conforms to.
Version compatibility rules follow [H3.1] regarding version ordering,
compliance requirements, and upgrading of version numbers. The
version information is indicated by "MRCP" (as opposed to "HTTP" in
[H3.1]) or "MRCP/2.0" (as opposed to "HTTP/1.1" in [H3.1]). To be
compliant with this specification, clients and servers sending MRCPv2
messages MUST indicate an mrcp-version of "MRCP/2.0". ABNF
productions using mrcp-version can be found in Sections 5.2, 5.3, and
5.5.
mrcp-version = "MRCP" "/" 1*2DIGIT "." 1*2DIGIT
Burnett & Shanmugham Standards Track [Page 25]
RFC 6787 MRCPv2 November 2012
The message-length field specifies the length of the message in
octets, including the start-line, and MUST be the second token from
the beginning of the message. This is to make the framing and
parsing of the message simpler to do. This field specifies the
length of the message including data that may be encoded into the
body of the message. Note that this value MAY be given as a fixed-
length integer that is zero-padded (with leading zeros) in order to
eliminate or reduce inefficiency in cases where the message-length
value would change as a result of the length of the message-length
token itself. This value, as with all lengths in MRCP, is to be
interpreted as a base-10 number. In particular, leading zeros do not
indicate that the value is to be interpreted as a base-8 number.
message-length = 1*19DIGIT
The following sample MRCP exchange demonstrates proper message-length
values. The values for message-length have been removed from all
other examples in the specification and replaced by '...' to reduce
confusion in the case of minor message-length computation errors in
those examples.
C->S: MRCP/2.0 877 INTERPRET 543266
Channel-Identifier:32AECB23433801@speechrecog
Interpret-Text:may I speak to Andre Roy
Content-Type:application/srgs+xml
Content-ID:
Content-Length:661
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
Burnett & Shanmugham Standards Track [Page 26]
RFC 6787 MRCPv2 November 2012
S->C: MRCP/2.0 82 543266 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C: MRCP/2.0 634 INTERPRETATION-COMPLETE 543266 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
Content-Type:application/nlsml+xml
Content-Length:441
Andre Roy
All MRCPv2 messages, responses and events MUST carry the Channel-
Identifier header field so the server or client can differentiate
messages from different control channels that may share the same
transport connection.
In the resource-specific header field descriptions in Sections 8-11,
a header field is disallowed on a method (request, response, or
event) for that resource unless specifically listed as being allowed.
Also, the phrasing "This header field MAY occur on method X"
indicates that the header field is allowed on that method but is not
required to be used in every instance of that method.
5.2. Request
An MRCPv2 request consists of a Request line followed by the message
header section and an optional message body containing data specific
to the request message.
The Request message from a client to the server includes within the
first line the method to be applied, a method tag for that request
and the version of the protocol in use.
Burnett & Shanmugham Standards Track [Page 27]
RFC 6787 MRCPv2 November 2012
request-line = mrcp-version SP message-length SP method-name
SP request-id CRLF
The mrcp-version field is the MRCP protocol version that is being
used by the client.
The message-length field specifies the length of the message,
including the start-line.
Details about the mrcp-version and message-length fields are given in
Section 5.1.
The method-name field identifies the specific request that the client
is making to the server. Each resource supports a subset of the
MRCPv2 methods. The subset for each resource is defined in the
section of the specification for the corresponding resource.
method-name = generic-method
/ synthesizer-method
/ recognizer-method
/ recorder-method
/ verifier-method
The request-id field is a unique identifier representable as an
unsigned 32-bit integer created by the client and sent to the server.
Clients MUST utilize monotonically increasing request-ids for
consecutive requests within an MRCP session. The request-id space is
linear (i.e., not mod(32)), so the space does not wrap, and validity
can be checked with a simple unsigned comparison operation. The
client may choose any initial value for its first request, but a
small integer is RECOMMENDED to avoid exhausting the space in long
sessions. If the server receives duplicate or out-of-order requests,
the server MUST reject the request with a response code of 410.
Since request-ids are scoped to the MRCP session, they are unique
across all TCP connections and all resource channels in the session.
The server resource MUST use the client-assigned identifier in its
response to the request. If the request does not complete
synchronously, future asynchronous events associated with this
request MUST carry the client-assigned request-id.
request-id = 1*10DIGIT
5.3. Response
After receiving and interpreting the request message for a method,
the server resource responds with an MRCPv2 response message. The
response consists of a response line followed by the message header
Burnett & Shanmugham Standards Track [Page 28]
RFC 6787 MRCPv2 November 2012
section and an optional message body containing data specific to the
method.
response-line = mrcp-version SP message-length SP request-id
SP status-code SP request-state CRLF
The mrcp-version field MUST contain the version of the request if
supported; otherwise, it MUST contain the highest version of MRCP
supported by the server.
The message-length field specifies the length of the message,
including the start-line.
Details about the mrcp-version and message-length fields are given in
Section 5.1.
The request-id used in the response MUST match the one sent in the
corresponding request message.
The status-code field is a 3-digit code representing the success or
failure or other status of the request.
status-code = 3DIGIT
The request-state field indicates if the action initiated by the
Request is PENDING, IN-PROGRESS, or COMPLETE. The COMPLETE status
means that the request was processed to completion and that there
will be no more events or other messages from that resource to the
client with that request-id. The PENDING status means that the
request has been placed in a queue and will be processed in first-in-
first-out order. The IN-PROGRESS status means that the request is
being processed and is not yet complete. A PENDING or IN-PROGRESS
status indicates that further Event messages may be delivered with
that request-id.
request-state = "COMPLETE"
/ "IN-PROGRESS"
/ "PENDING"
5.4. Status Codes
The status codes are classified under the Success (2xx), Client
Failure (4xx), and Server Failure (5xx) codes.
Burnett & Shanmugham Standards Track [Page 29]
RFC 6787 MRCPv2 November 2012
+------------+--------------------------------------------------+
| Code | Meaning |
+------------+--------------------------------------------------+
| 200 | Success |
| 201 | Success with some optional header fields ignored |
+------------+--------------------------------------------------+
Success (2xx)
+------------+------------------------------------------------------+
| Code | Meaning |
+------------+------------------------------------------------------+
| 401 | Method not allowed |
| 402 | Method not valid in this state |
| 403 | Unsupported header field |
| 404 | Illegal value for header field. This is the error |
| | for a syntax violation. |
| 405 | Resource not allocated for this session or does not |
| | exist |
| 406 | Mandatory Header Field Missing |
| 407 | Method or Operation Failed (e.g., Grammar |
| | compilation failed in the recognizer. Detailed cause |
| | codes might be available through a resource-specific |
| | header.) |
| 408 | Unrecognized or unsupported message entity |
| 409 | Unsupported Header Field Value. This is a value that |
| | is syntactically legal but exceeds the |
| | implementation's capabilities or expectations. |
| 410 | Non-Monotonic or Out-of-order sequence number in |
| | request. |
| 411-420 | Reserved for future assignment |
+------------+------------------------------------------------------+
Client Failure (4xx)
+------------+--------------------------------+
| Code | Meaning |
+------------+--------------------------------+
| 501 | Server Internal Error |
| 502 | Protocol Version not supported |
| 503 | Reserved for future assignment |
| 504 | Message too large |
+------------+--------------------------------+
Server Failure (5xx)
Burnett & Shanmugham Standards Track [Page 30]
RFC 6787 MRCPv2 November 2012
5.5. Events
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. The event message consists of an event
header line followed by the message header section and an optional
message body containing data specific to the event message. The
header line has the request-id of the corresponding request and
status value. The request-state value is COMPLETE if the request is
done and this was the last event, else it is IN-PROGRESS.
event-line = mrcp-version SP message-length SP event-name
SP request-id SP request-state CRLF
The mrcp-version used here is identical to the one used in the
Request/Response line and indicates the highest version of MRCP
running on the server.
The message-length field specifies the length of the message,
including the start-line.
Details about the mrcp-version and message-length fields are given in
Section 5.1.
The event-name identifies the nature of the event generated by the
media resource. The set of valid event names depends on the resource
generating it. See the corresponding resource-specific section of
the document.
event-name = synthesizer-event
/ recognizer-event
/ recorder-event
/ verifier-event
The request-id used in the event MUST match the one sent in the
request that caused this event.
The request-state indicates whether the Request/Command causing this
event is complete or still in progress and whether it is the same as
the one mentioned in Section 5.3. The final event for a request has
a COMPLETE status indicating the completion of the request.
Burnett & Shanmugham Standards Track [Page 31]
RFC 6787 MRCPv2 November 2012
6. MRCPv2 Generic Methods, Headers, and Result Structure
MRCPv2 supports a set of methods and header fields that are common to
all resources. These are discussed here; resource-specific methods
and header fields are discussed in the corresponding resource-
specific section of the document.
6.1. Generic Methods
MRCPv2 supports two generic methods for reading and writing the state
associated with a resource.
generic-method = "SET-PARAMS"
/ "GET-PARAMS"
These are described in the following subsections.
6.1.1. SET-PARAMS
The SET-PARAMS method, from the client to the server, tells the
MRCPv2 resource to define parameters for the session, such as voice
characteristics and prosody on synthesizers, recognition timers on
recognizers, etc. If the server accepts and sets all parameters, it
MUST return a response status-code of 200. If it chooses to ignore
some optional header fields that can be safely ignored without
affecting operation of the server, it MUST return 201.
If one or more of the header fields being sent is incorrect, error
403, 404, or 409 MUST be returned as follows:
o If one or more of the header fields being set has an illegal
value, the server MUST reject the request with a 404 Illegal Value
for Header Field.
o If one or more of the header fields being set is unsupported for
the resource, the server MUST reject the request with a 403
Unsupported Header Field, except as described in the next
paragraph.
o If one or more of the header fields being set has an unsupported
value, the server MUST reject the request with a 409 Unsupported
Header Field Value, except as described in the next paragraph.
If both error 404 and another error have occurred, only error 404
MUST be returned. If both errors 403 and 409 have occurred, but not
error 404, only error 403 MUST be returned.
Burnett & Shanmugham Standards Track [Page 32]
RFC 6787 MRCPv2 November 2012
If error 403, 404, or 409 is returned, the response MUST include the
bad or unsupported header fields and their values exactly as they
were sent from the client. Session parameters modified using
SET-PARAMS do not override parameters explicitly specified on
individual requests or requests that are IN-PROGRESS.
C->S: MRCP/2.0 ... SET-PARAMS 543256
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:female
Voice-variant:3
S->C: MRCP/2.0 ... 543256 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
6.1.2. GET-PARAMS
The GET-PARAMS method, from the client to the server, asks the MRCPv2
resource for its current session parameters, such as voice
characteristics and prosody on synthesizers, recognition timers on
recognizers, etc. For every header field the client sends in the
request without a value, the server MUST include the header field and
its corresponding value in the response. If no parameter header
fields are specified by the client, then the server MUST return all
the settable parameters and their values in the corresponding header
section of the response, including vendor-specific parameters. Such
wildcard parameter requests can be very processing-intensive, since
the number of settable parameters can be large depending on the
implementation. Hence, it is RECOMMENDED that the client not use the
wildcard GET-PARAMS operation very often. Note that GET-PARAMS
returns header field values that apply to the whole session and not
values that have a request-level scope. For example, Input-Waveform-
URI is a request-level header field and thus would not be returned by
GET-PARAMS.
If all of the header fields requested are supported, the server MUST
return a response status-code of 200. If some of the header fields
being retrieved are unsupported for the resource, the server MUST
reject the request with a 403 Unsupported Header Field. Such a
response MUST include the unsupported header fields exactly as they
were sent from the client, without values.
Burnett & Shanmugham Standards Track [Page 33]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... GET-PARAMS 543256
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:
Voice-variant:
Vendor-Specific-Parameters:com.example.param1;
com.example.param2
S->C: MRCP/2.0 ... 543256 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:female
Voice-variant:3
Vendor-Specific-Parameters:com.example.param1="Company Name";
com.example.param2="124324234@example.com"
6.2. Generic Message Headers
All MRCPv2 header fields, which include both the generic-headers
defined in the following subsections and the resource-specific header
fields defined later, follow the same generic format as that given in
Section 3.1 of RFC 5322 [RFC5322]. Each header field consists of a
name followed by a colon (":") and the value. Header field names are
case-insensitive. The value MAY be preceded by any amount of LWS
(linear white space), though a single SP (space) is preferred.
Header fields may extend over multiple lines by preceding each extra
line with at least one SP or HT (horizontal tab).
generic-field = field-name ":" [ field-value ]
field-name = token
field-value = *LWS field-content *( CRLF 1*LWS field-content)
field-content =
The field-content does not include any leading or trailing LWS (i.e.,
linear white space occurring before the first non-whitespace
character of the field-value or after the last non-whitespace
character of the field-value). Such leading or trailing LWS MAY be
removed without changing the semantics of the field value. Any LWS
that occurs between field-content MAY be replaced with a single SP
before interpreting the field value or forwarding the message
downstream.
MRCPv2 servers and clients MUST NOT depend on header field order. It
is RECOMMENDED to send general-header fields first, followed by
request-header or response-header fields, and ending with the entity-
header fields. However, MRCPv2 servers and clients MUST be prepared
to process the header fields in any order. The only exception to
Burnett & Shanmugham Standards Track [Page 34]
RFC 6787 MRCPv2 November 2012
this rule is when there are multiple header fields with the same name
in a message.
Multiple header fields with the same name MAY be present in a message
if and only if the entire value for that header field is defined as a
comma-separated list [i.e., #(values)].
Since vendor-specific parameters may be order-dependent, it MUST be
possible to combine multiple header fields of the same name into one
"name:value" pair without changing the semantics of the message, by
appending each subsequent value to the first, each separated by a
comma. The order in which header fields with the same name are
received is therefore significant to the interpretation of the
combined header field value, and thus an intermediary MUST NOT change
the order of these values when a message is forwarded.
generic-header = channel-identifier
/ accept
/ active-request-id-list
/ proxy-sync-id
/ accept-charset
/ content-type
/ content-id
/ content-base
/ content-encoding
/ content-location
/ content-length
/ fetch-timeout
/ cache-control
/ logging-tag
/ set-cookie
/ vendor-specific
6.2.1. Channel-Identifier
All MRCPv2 requests, responses, and events MUST contain the Channel-
Identifier header field. The value is allocated by the server when a
control channel is added to the session and communicated to the
client by the "a=channel" attribute in the SDP answer from the
server. The header field value consists of 2 parts separated by the
'@' symbol. The first part is an unambiguous string identifying the
MRCPv2 session. The second part is a string token that specifies one
of the media processing resource types listed in Section 3.1. The
unambiguous string (first part) MUST be difficult to guess, unique
among the resource instances managed by the server, and common to all
resource channels with that server established through a single SIP
dialog.
Burnett & Shanmugham Standards Track [Page 35]
RFC 6787 MRCPv2 November 2012
channel-identifier = "Channel-Identifier" ":" channel-id CRLF
channel-id = 1*alphanum "@" 1*alphanum
6.2.2. Accept
The Accept header field follows the syntax defined in [H14.1]. The
semantics are also identical, with the exception that if no Accept
header field is present, the server MUST assume a default value that
is specific to the resource type that is being controlled. This
default value can be changed for a resource on a session by sending
this header field in a SET-PARAMS method. The current default value
of this header field for a resource in a session can be found through
a GET-PARAMS method. This header field MAY occur on any request.
6.2.3. Active-Request-Id-List
In a request, this header field indicates the list of request-ids to
which the request applies. This is useful when there are multiple
requests that are PENDING or IN-PROGRESS and the client wants this
request to apply to one or more of these specifically.
In a response, this header field returns the list of request-ids that
the method modified or affected. There could be one or more requests
in 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 or modified by this command in its
header section.
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 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. The response to the STOP request
contains in the Active-Request-Id-List value the request-ids of all
the SPEAK requests that were terminated. After sending the STOP
response, the server MUST NOT send any SPEAK-COMPLETE or RECOGNITION-
COMPLETE events for the terminated requests.
active-request-id-list = "Active-Request-Id-List" ":"
request-id *("," request-id) CRLF
Burnett & Shanmugham Standards Track [Page 36]
RFC 6787 MRCPv2 November 2012
6.2.4. Proxy-Sync-Id
When any server resource generates a "barge-in-able" event, it also
generates a unique tag. The tag is sent as this header field's value
in an event to the client. The client then acts as an intermediary
among the server resources and sends a BARGE-IN-OCCURRED method 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, intermediated
by the client, to decide if this event has been processed through a
direct interaction of the resources. This header field MAY occur
only on events and the BARGE-IN-OCCURRED method. The name of this
header field contains the word 'proxy' only for historical reasons
and does not imply that a proxy server is involved.
proxy-sync-id = "Proxy-Sync-Id" ":" 1*VCHAR CRLF
6.2.5. Accept-Charset
See [H14.2]. This specifies the acceptable character sets 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 Semantic Markup Language (NLSML) results of a
RECOGNITION-COMPLETE event. This header field is only used on
requests.
6.2.6. Content-Type
See [H14.17]. MRCPv2 supports a restricted set of registered media
types for content, including speech markup, grammar, and recognition
results. The content types applicable to each MRCPv2 resource-type
are specified in the corresponding section of the document and are
registered in the MIME Media Types registry maintained by IANA. The
multipart content type "multipart/mixed" is supported to communicate
multiple of the above mentioned contents, in which case the body
parts MUST NOT contain any MRCPv2-specific header fields. This
header field MAY occur on all messages.
Burnett & Shanmugham Standards Track [Page 37]
RFC 6787 MRCPv2 November 2012
content-type = "Content-Type" ":" media-type-value CRLF
media-type-value = type "/" subtype *( ";" parameter )
type = token
subtype = token
parameter = attribute "=" value
attribute = token
value = token / quoted-string
6.2.7. Content-ID
This header field contains an ID or name for the content by which it
can be referenced. This header field operates according to the
specification in RFC 2392 [RFC2392] and is required for content
disambiguation in multipart messages. In MRCPv2, whenever the
associated content is stored by either the client or the server, it
MUST be retrievable using this ID. Such content can be referenced
later in a session by addressing it with the 'session' URI scheme
described in Section 13.6. This header field MAY occur on all
messages.
6.2.8. Content-Base
The Content-Base entity-header MAY be used to specify the base URI
for resolving relative URIs 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 multipart media, which in turn can have multiple entities
within it. This header field MAY occur on all messages.
6.2.9. Content-Encoding
The Content-Encoding entity-header is used as a modifier to the
Content-Type. When present, its value indicates what additional
content encoding 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. Note that the SIP session
Burnett & Shanmugham Standards Track [Page 38]
RFC 6787 MRCPv2 November 2012
can be used to determine accepted encodings (see Section 7). This
header field MAY occur on all messages.
content-encoding = "Content-Encoding" ":"
*WSP content-coding
*(*WSP "," *WSP content-coding *WSP )
CRLF
Content codings are defined in [H3.5]. An example of its use is
Content-Encoding:gzip
If multiple encodings have been applied to an entity, the content
encodings MUST be listed in the order in which they were applied.
6.2.10. Content-Location
The Content-Location entity-header 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. Refer to [H14.14].
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. This header field is provided for optimization purposes
only. The receiver of this header field MAY assume that the entity
being sent is identical to what would have been retrieved or might
already have been 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 this 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. This header field MAY
occur on all messages.
Burnett & Shanmugham Standards Track [Page 39]
RFC 6787 MRCPv2 November 2012
6.2.11. Content-Length
This header field contains the length of the content of the message
body (i.e., after the double CRLF following the last header field).
Unlike in HTTP, it MUST be included in all messages that carry
content beyond the header section. If it is missing, a default value
of zero is assumed. Otherwise, it is interpreted according to
[H14.13]. When a message having no use for a message body contains
one, i.e., the Content-Length is non-zero, the receiver MUST ignore
the content of the message body. This header field MAY occur on all
messages.
content-length = "Content-Length" ":" 1*19DIGIT CRLF
6.2.12. Fetch Timeout
When the recognizer or synthesizer needs to fetch documents or other
resources, this header field controls the corresponding URI access
properties. This defines the timeout for content that the server may
need to fetch over the network. The value is interpreted to be in
milliseconds and ranges from 0 to an implementation-specific maximum
value. It is RECOMMENDED that servers be cautious about accepting
long timeout values. The default value for this header field is
implementation specific. This header field MAY occur in DEFINE-
GRAMMAR, RECOGNIZE, SPEAK, SET-PARAMS, or GET-PARAMS.
fetch-timeout = "Fetch-Timeout" ":" 1*19DIGIT CRLF
6.2.13. Cache-Control
If the server implements content caching, it MUST adhere to the cache
correctness rules of HTTP 1.1 [RFC2616] when accessing and caching
stored content. In particular, the "expires" and "cache-control"
header fields of the cached URI or document MUST be honored and 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 server for the session or request. The scope of
the directive is based on the method it is sent on. If the directive
is sent on a SET-PARAMS method, it applies for all requests for
external documents the server makes during that session, unless it is
overridden by a Cache-Control header field on an individual request.
If the directives are sent on any other requests, they apply only to
external document requests the server makes for that request. An
empty Cache-Control header field on the GET-PARAMS method is a
request for the server to return the current Cache-Control directives
setting on the server. This header field MAY occur only on requests.
Burnett & Shanmugham Standards Track [Page 40]
RFC 6787 MRCPv2 November 2012
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*19DIGIT
Here, delta-seconds is a decimal time value specifying the number of
seconds since the instant the message response or data was received
by the server.
The different cache-directive options allow the client to ask the
server to override the default cache expiration mechanisms:
max-age Indicates that the client can tolerate the server
using content 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 a response based on stale data.
min-fresh Indicates that the client is willing to accept a
server response with cached data whose expiration is
no less than its current age plus the specified time
in seconds. If the server's cache time-to-live
exceeds the client-supplied min-fresh value, the
server MUST NOT utilize cached content.
max-stale Indicates that the client is willing to allow a server
to utilize cached data that has exceeded its
expiration time. If "max-stale" is assigned a value,
then the client is willing to allow the server to use
cached data 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 allow the server to use stale data of any
age.
If the server cache is requested to use stale response/data without
validation, it MAY do so 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 to the corresponding URI).
Burnett & Shanmugham Standards Track [Page 41]
RFC 6787 MRCPv2 November 2012
If both the MRCPv2 Cache-Control directive and the cached entry on
the 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.
6.2.14. Logging-Tag
This header field MAY be sent as part of a SET-PARAMS/GET-PARAMS
method to set or retrieve the logging tag for logs generated by the
server. Once set, the value persists until a new value is set or the
session ends. The MRCPv2 server MAY provide a mechanism to create
subsets of 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.
It is RECOMMENDED that clients include in the logging tag information
to identify the MRCPv2 client User Agent, so that one can determine
which MRCPv2 client request generated a given log message at the
server. It is also RECOMMENDED that MRCPv2 clients not log
personally identifiable information such as credit card numbers and
national identification numbers.
logging-tag = "Logging-Tag" ":" 1*UTFCHAR CRLF
6.2.15. Set-Cookie
Since the associated HTTP client on an MRCPv2 server fetches
documents for processing on behalf of the MRCPv2 client, the cookie
store in the HTTP client of the MRCPv2 server is treated as an
extension of the cookie store in the HTTP client of the MRCPv2
client. This requires that the MRCPv2 client and server be able to
synchronize their common cookie store as needed. To enable the
MRCPv2 client to push its stored cookies to the MRCPv2 server and get
new cookies from the MRCPv2 server stored back to the MRCPv2 client,
the Set-Cookie entity-header field MAY be included in MRCPv2 requests
to update the cookie store on a server and be returned in final
MRCPv2 responses or events to subsequently update the client's own
cookie store. The stored cookies on the server persist for the
duration of the MRCPv2 session and MUST be destroyed at the end of
the session. To ensure support for cookies, MRCPv2 clients and
servers MUST support the Set-Cookie entity-header field.
Note that it is the MRCPv2 client that determines which, if any,
cookies are sent to the server. There is no requirement that all
cookies be shared. Rather, it is RECOMMENDED that MRCPv2 clients
communicate only cookies needed by the MRCPv2 server to process its
requests.
Burnett & Shanmugham Standards Track [Page 42]
RFC 6787 MRCPv2 November 2012
set-cookie = "Set-Cookie:" cookies CRLF
cookies = cookie *("," *LWS cookie)
cookie = attribute "=" value *(";" cookie-av)
cookie-av = "Comment" "=" value
/ "Domain" "=" value
/ "Max-Age" "=" value
/ "Path" "=" value
/ "Secure"
/ "Version" "=" 1*19DIGIT
/ "Age" "=" delta-seconds
set-cookie = "Set-Cookie:" SP set-cookie-string
set-cookie-string = cookie-pair *( ";" SP cookie-av )
cookie-pair = cookie-name "=" cookie-value
cookie-name = token
cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
token =
cookie-av = expires-av / max-age-av / domain-av /
path-av / secure-av / httponly-av /
extension-av / age-av
expires-av = "Expires=" sane-cookie-date
sane-cookie-date =
max-age-av = "Max-Age=" non-zero-digit *DIGIT
non-zero-digit = %x31-39
domain-av = "Domain=" domain-value
domain-value =
path-av = "Path=" path-value
path-value =
secure-av = "Secure"
httponly-av = "HttpOnly"
extension-av =
age-av = "Age=" delta-seconds
The Set-Cookie header field is specified in RFC 6265 [RFC6265]. The
"Age" attribute is introduced in this specification to indicate the
age of the cookie and is OPTIONAL. An MRCPv2 client or server MUST
calculate the age of the cookie according to the age calculation
rules in the HTTP/1.1 specification [RFC2616] and append the "Age"
attribute accordingly. This attribute is provided because time may
have passed since the client received the cookie from an HTTP server.
Rather than having the client reduce Max-Age by the actual age, it
passes Max-Age verbatim and appends the "Age" attribute, thus
maintaining the cookie as received while still accounting for the
fact that time has passed.
Burnett & Shanmugham Standards Track [Page 43]
RFC 6787 MRCPv2 November 2012
The MRCPv2 client or server MUST supply defaults for the "Domain" and
"Path" attributes, as specified in RFC 6265, if they are omitted by
the HTTP origin server. Note that there is no leading dot present in
the "Domain" attribute value in this case. Although an explicitly
specified "Domain" value received via the HTTP protocol may be
modified to include a leading dot, an MRCPv2 client or server MUST
NOT modify the "Domain" value when received via the MRCPv2 protocol.
An MRCPv2 client or server MAY combine multiple cookie header fields
of the same type into a single "field-name:field-value" pair as
described in Section 6.2.
The Set-Cookie header field MAY be specified in any request that
subsequently results in the server performing an HTTP access. When a
server receives new cookie information from an HTTP origin server,
and assuming the cookie store is modified according to RFC 6265, the
server MUST return the new cookie information in the MRCPv2 COMPLETE
response or event, as appropriate, to allow the client to update its
own cookie store.
The SET-PARAMS request MAY specify the Set-Cookie header field to
update the cookie store on a server. The GET-PARAMS request MAY be
used to return the entire cookie store of "Set-Cookie" type cookies
to the client.
6.2.16. Vendor-Specific Parameters
This set of header fields allows for the client to set or retrieve
vendor-specific parameters.
vendor-specific = "Vendor-Specific-Parameters" ":"
[vendor-specific-av-pair
*(";" vendor-specific-av-pair)] CRLF
vendor-specific-av-pair = vendor-av-pair-name "="
value
vendor-av-pair-name = 1*UTFCHAR
Header fields of this form MAY be sent in any method (request) and
are used to manage implementation-specific parameters on the server
side. The vendor-av-pair-name follows the reverse Internet Domain
Name convention (see Section 13.1.6 for syntax and registration
information). The value of the vendor attribute is specified after
the "=" symbol and MAY be quoted. For example:
Burnett & Shanmugham Standards Track [Page 44]
RFC 6787 MRCPv2 November 2012
com.example.companyA.paramxyz=256
com.example.companyA.paramabc=High
com.example.companyB.paramxyz=Low
When used in GET-PARAMS to get the current value of these parameters
from the server, this header field value MAY contain a semicolon-
separated list of implementation-specific attribute names.
6.3. Generic Result Structure
Result data from the server for the Recognizer and Verifier resources
is carried as a typed media entity in the MRCPv2 message body of
various events. The Natural Language Semantics Markup Language
(NLSML), an XML markup based on an early draft from the W3C, is the
default standard for returning results back to the client. Hence,
all servers implementing these resource types MUST support the media
type 'application/nlsml+xml'. The Extensible MultiModal Annotation
(EMMA) [W3C.REC-emma-20090210] format can be used to return results
as well. This can be done by negotiating the format at session
establishment time with SDP (a=resultformat:application/emma+xml) or
with SIP (Allow/Accept). With SIP, for example, if a client wants
results in EMMA, an MRCPv2 server can route the request to another
server that supports EMMA by inspecting the SIP header fields, rather
than having to inspect the SDP.
MRCPv2 uses this representation to convey content among the clients
and servers that generate and make use of the markup. MRCPv2 uses
NSLML specifically to convey recognition, enrollment, and
verification results between the corresponding resource on the MRCPv2
server and the MRCPv2 client. Details of this result format are
fully described in Section 6.3.1.
Content-Type:application/nlsml+xml
Content-Length:...
yes
Result Example
Burnett & Shanmugham Standards Track [Page 45]
RFC 6787 MRCPv2 November 2012
6.3.1. Natural Language Semantics Markup Language
The Natural Language Semantics Markup Language (NLSML) is an XML data
structure with elements and attributes designed to carry result
information from recognizer (including enrollment) and verifier
resources. The normative definition of NLSML is the RelaxNG schema
in Section 16.1. Note that the elements and attributes of this
format are defined in the MRCPv2 namespace. In the result structure,
they must either be prefixed by a namespace prefix declared within
the result or must be children of an element identified as belonging
to the respective namespace. For details on how to use XML
Namespaces, see [W3C.REC-xml-names11-20040204]. Section 2 of
[W3C.REC-xml-names11-20040204] provides details on how to declare
namespaces and namespace prefixes.
The root element of NLSML is . Optional child elements are
, , and , at
least one of which must be present. A single MAY contain
any or all of the optional child elements. Details of the
and elements and their subelements and attributes
can be found in Section 9.6. Details of the
element and its subelements can be found in Section 9.7. Details of
the element and its subelements can be found in
Section 11.5.2.
7. Resource Discovery
Server resources may be discovered and their capabilities learned by
clients through standard SIP machinery. The client MAY issue a SIP
OPTIONS transaction to a server, which has the effect of requesting
the capabilities of the server. The server MUST respond to such a
request with an SDP-encoded description of its capabilities according
to RFC 3264 [RFC3264]. The MRCPv2 capabilities are described by a
single "m=" line containing the media type "application" and
transport type "TCP/TLS/MRCPv2" or "TCP/MRCPv2". There MUST be one
"resource" attribute for each media resource that the server
supports, and it has the resource type identifier as its value.
The SDP description MUST also contain "m=" lines describing the audio
capabilities and the coders the server supports.
In this example, the client uses the SIP OPTIONS method to query the
capabilities of the MRCPv2 server.
Burnett & Shanmugham Standards Track [Page 46]
RFC 6787 MRCPv2 November 2012
C->S:
OPTIONS sip:mrcp@server.example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf7
Max-Forwards:6
To:
From:Sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:63104 OPTIONS
Contact:
Accept:application/sdp
Content-Length:0
S->C:
SIP/2.0 200 OK
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bf7;received=192.0.32.10
To:;tag=62784
From:Sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:63104 OPTIONS
Contact:
Allow:INVITE, ACK, CANCEL, OPTIONS, BYE
Accept:application/sdp
Accept-Encoding:gzip
Accept-Language:en
Supported:foo
Content-Type:application/sdp
Content-Length:...
v=0
o=sarvi 2890844536 2890842811 IN IP4 192.0.2.12
s=-
i=MRCPv2 server capabilities
c=IN IP4 192.0.2.12/127
t=0 0
m=application 0 TCP/TLS/MRCPv2 1
a=resource:speechsynth
a=resource:speechrecog
a=resource:speakverify
m=audio 0 RTP/AVP 0 3
a=rtpmap:0 PCMU/8000
a=rtpmap:3 GSM/8000
Using SIP OPTIONS for MRCPv2 Server Capability Discovery
Burnett & Shanmugham Standards Track [Page 47]
RFC 6787 MRCPv2 November 2012
8. Speech Synthesizer Resource
This resource processes text markup provided by the client and
generates a stream of synthesized speech in real time. Depending
upon the server implementation and capability of this resource, the
client can also dictate parameters of the synthesized speech such as
voice characteristics, speaker speed, etc.
The synthesizer resource is controlled by MRCPv2 requests from the
client. Similarly, the resource can respond to these requests or
generate asynchronous events to the client to indicate conditions of
interest to the client during the generation of the synthesized
speech stream.
This section applies for the following resource types:
o speechsynth
o basicsynth
The capabilities of these resources are defined in Section 3.1.
8.1. Synthesizer State Machine
The synthesizer maintains a state machine to process MRCPv2 requests
from the client. The state transitions shown below describe the
states of the synthesizer and reflect the state of the request at the
head of the synthesizer resource queue. A SPEAK request in the
PENDING state can be deleted or stopped by a STOP request without
affecting the state of the resource.
Burnett & Shanmugham Standards Track [Page 48]
RFC 6787 MRCPv2 November 2012
Idle Speaking Paused
State State State
| | |
|----------SPEAK-------->| |--------|
|<------STOP-------------| CONTROL |
|<----SPEAK-COMPLETE-----| |------->|
|<----BARGE-IN-OCCURRED--| |
| |---------| |
| CONTROL |-----------PAUSE--------->|
| |-------->|<----------RESUME---------|
| | |----------|
|----------| | PAUSE |
| BARGE-IN-OCCURRED | |--------->|
|<---------| |----------| |
| | SPEECH-MARKER |
| |<---------| |
|----------| |----------| |
| STOP | RESUME |
| | |<---------| |
|<---------| | |
|<---------------------STOP-------------------------|
|----------| | |
| DEFINE-LEXICON | |
| | | |
|<---------| | |
|<---------------BARGE-IN-OCCURRED------------------|
Synthesizer State Machine
8.2. Synthesizer Methods
The synthesizer supports the following methods.
synthesizer-method = "SPEAK"
/ "STOP"
/ "PAUSE"
/ "RESUME"
/ "BARGE-IN-OCCURRED"
/ "CONTROL"
/ "DEFINE-LEXICON"
8.3. Synthesizer Events
The synthesizer can generate the following events.
synthesizer-event = "SPEECH-MARKER"
/ "SPEAK-COMPLETE"
Burnett & Shanmugham Standards Track [Page 49]
RFC 6787 MRCPv2 November 2012
8.4. Synthesizer Header Fields
A synthesizer method can contain header fields containing request
options and information to augment the Request, Response, or Event it
is associated with.
synthesizer-header = jump-size
/ kill-on-barge-in
/ speaker-profile
/ completion-cause
/ completion-reason
/ voice-parameter
/ prosody-parameter
/ speech-marker
/ speech-language
/ fetch-hint
/ audio-fetch-hint
/ failed-uri
/ failed-uri-cause
/ speak-restart
/ speak-length
/ load-lexicon
/ lexicon-search-order
8.4.1. Jump-Size
This header field MAY be specified in a CONTROL method and controls
the amount to jump forward or backward in an active SPEAK request. A
'+' or '-' indicates a relative value to what is being currently
played. This header field MAY also be specified in a SPEAK request
as a desired offset into the synthesized speech. In this case, the
synthesizer MUST begin speaking from this amount of time into the
speech markup. Note that an offset that extends beyond the end of
the produced speech will result in audio of length zero. The
different speech length units supported are dependent on the
synthesizer implementation. If the synthesizer resource does not
support a unit for the operation, the resource MUST respond with a
status-code of 409 "Unsupported Header Field Value".
Burnett & Shanmugham Standards Track [Page 50]
RFC 6787 MRCPv2 November 2012
jump-size = "Jump-Size" ":" speech-length-value CRLF
speech-length-value = numeric-speech-length
/ text-speech-length
text-speech-length = 1*UTFCHAR SP "Tag"
numeric-speech-length = ("+" / "-") positive-speech-length
positive-speech-length = 1*19DIGIT SP numeric-speech-unit
numeric-speech-unit = "Second"
/ "Word"
/ "Sentence"
/ "Paragraph"
8.4.2. Kill-On-Barge-In
This header field MAY be sent as part of the SPEAK method to enable
"kill-on-barge-in" support. If enabled, the SPEAK method is
interrupted by DTMF input detected by a signal detector resource or
by the start of speech sensed or recognized by the speech recognizer
resource.
kill-on-barge-in = "Kill-On-Barge-In" ":" BOOLEAN CRLF
The client MUST send a BARGE-IN-OCCURRED method to the synthesizer
resource when it receives a barge-in-able event from any source.
This source could be a synthesizer resource or signal detector
resource and MAY be either local or distributed. If this header
field is not specified in a SPEAK request or explicitly set by a
SET-PARAMS, the default value for this header field is "true".
If the recognizer or signal detector resource is on the same server
as the synthesizer and both are part of the same session, the server
MAY work with both to provide internal notification to the
synthesizer so that audio may be stopped without having to wait for
the client's BARGE-IN-OCCURRED event.
It is generally RECOMMENDED when playing a prompt to the user with
Kill-On-Barge-In and asking for input, that the client issue the
RECOGNIZE request ahead of the SPEAK request for optimum performance
and user experience. This way, it is guaranteed that the recognizer
is online before the prompt starts playing and the user's speech will
not be truncated at the beginning (especially for power users).
Burnett & Shanmugham Standards Track [Page 51]
RFC 6787 MRCPv2 November 2012
8.4.3. Speaker-Profile
This header field MAY be part of the SET-PARAMS/GET-PARAMS or SPEAK
request from the client to the server and specifies a URI that
references the profile of the speaker. Speaker profiles are
collections of voice parameters like gender, accent, etc.
speaker-profile = "Speaker-Profile" ":" uri CRLF
8.4.4. Completion-Cause
This header field MUST be specified in a SPEAK-COMPLETE event coming
from the synthesizer resource to the client. This indicates the
reason the SPEAK request completed.
completion-cause = "Completion-Cause" ":" 3DIGIT SP
1*VCHAR CRLF
+------------+-----------------------+------------------------------+
| Cause-Code | Cause-Name | Description |
+------------+-----------------------+------------------------------+
| 000 | normal | SPEAK completed normally. |
| 001 | barge-in | SPEAK request was terminated |
| | | because of barge-in. |
| 002 | parse-failure | SPEAK request terminated |
| | | because of a failure to |
| | | parse the speech markup |
| | | text. |
| 003 | uri-failure | SPEAK request terminated |
| | | because access to one of the |
| | | URIs failed. |
| 004 | error | SPEAK request terminated |
| | | prematurely due to |
| | | synthesizer error. |
| 005 | language-unsupported | Language not supported. |
| 006 | lexicon-load-failure | Lexicon loading failed. |
| 007 | cancelled | A prior SPEAK request failed |
| | | while this one was still in |
| | | the queue. |
+------------+-----------------------+------------------------------+
Synthesizer Resource Completion Cause Codes
Burnett & Shanmugham Standards Track [Page 52]
RFC 6787 MRCPv2 November 2012
8.4.5. Completion-Reason
This header field MAY be specified in a SPEAK-COMPLETE event coming
from the synthesizer resource to the client. This contains the
reason text behind the SPEAK request completion. This header field
communicates text describing the reason for the failure, such as an
error in parsing the speech markup text.
completion-reason = "Completion-Reason" ":"
quoted-string CRLF
The completion reason text is provided for client use in logs and for
debugging and instrumentation purposes. Clients MUST NOT interpret
the completion reason text.
8.4.6. Voice-Parameter
This set of header fields defines the voice of the speaker.
voice-parameter = voice-gender
/ voice-age
/ voice-variant
/ voice-name
voice-gender = "Voice-Gender:" voice-gender-value CRLF
voice-gender-value = "male"
/ "female"
/ "neutral"
voice-age = "Voice-Age:" 1*3DIGIT CRLF
voice-variant = "Voice-Variant:" 1*19DIGIT CRLF
voice-name = "Voice-Name:"
1*UTFCHAR *(1*WSP 1*UTFCHAR) CRLF
The "Voice-" parameters are derived from the similarly named
attributes of the voice element specified in W3C's Speech Synthesis
Markup Language Specification (SSML)
[W3C.REC-speech-synthesis-20040907]. Legal values for these
parameters are as defined in that specification.
These header fields MAY be sent in SET-PARAMS or GET-PARAMS requests
to define or get default values for the entire session or MAY be sent
in the SPEAK request to define default values for that SPEAK request.
Note that SSML content can itself set these values internal to the
SSML document, of course.
Burnett & Shanmugham Standards Track [Page 53]
RFC 6787 MRCPv2 November 2012
Voice parameter header fields MAY also be sent in a CONTROL method to
affect a SPEAK request in progress and change its behavior on the
fly. If the synthesizer resource does not support this operation, it
MUST reject the request with a status-code of 403 "Unsupported Header
Field".
8.4.7. Prosody-Parameters
This set of header fields defines the prosody of the speech.
prosody-parameter = "Prosody-" prosody-param-name ":"
prosody-param-value CRLF
prosody-param-name = 1*VCHAR
prosody-param-value = 1*VCHAR
prosody-param-name is any one of the attribute names under the
prosody element specified in W3C's Speech Synthesis Markup Language
Specification [W3C.REC-speech-synthesis-20040907]. The prosody-
param-value is any one of the value choices of the corresponding
prosody element attribute from that specification.
These header fields MAY be sent in SET-PARAMS or GET-PARAMS requests
to define or get default values for the entire session or MAY be sent
in the SPEAK request to define default values for that SPEAK request.
Furthermore, these attributes can be part of the speech text marked
up in SSML.
The prosody parameter header fields in the SET-PARAMS or SPEAK
request only apply if the speech data is of type 'text/plain' and
does not use a speech markup format.
These prosody parameter header fields MAY also be sent in a CONTROL
method to affect a SPEAK request in progress and change its behavior
on the fly. If the synthesizer resource does not support this
operation, it MUST respond back to the client with a status-code of
403 "Unsupported Header Field".
8.4.8. Speech-Marker
This header field contains timestamp information in a "timestamp"
field. This is a Network Time Protocol (NTP) [RFC5905] timestamp, a
64-bit number in decimal form. It MUST be synced with the Real-Time
Protocol (RTP) [RFC3550] timestamp of the media stream through the
Real-Time Control Protocol (RTCP) [RFC3550].
Burnett & Shanmugham Standards Track [Page 54]
RFC 6787 MRCPv2 November 2012
Markers are bookmarks that are defined within the markup. Most
speech markup formats provide mechanisms to embed marker fields
within speech texts. The synthesizer generates SPEECH-MARKER events
when it reaches these marker fields. This header field MUST be part
of the SPEECH-MARKER event and contain the marker tag value after the
timestamp, separated by a semicolon. In these events, the timestamp
marks the time the text corresponding to the marker was emitted as
speech by the synthesizer.
This header field MUST also be returned in responses to STOP,
CONTROL, and BARGE-IN-OCCURRED methods, in the SPEAK-COMPLETE event,
and in an IN-PROGRESS SPEAK response. In these messages, if any
markers have been encountered for the current SPEAK, the marker tag
value MUST be the last embedded marker encountered. If no markers
have yet been encountered for the current SPEAK, only the timestamp
is REQUIRED. Note that in these events, the purpose of this header
field is to provide timestamp information associated with important
events within the lifecycle of a request (start of SPEAK processing,
end of SPEAK processing, receipt of CONTROL/STOP/BARGE-IN-OCCURRED).
timestamp = "timestamp" "=" time-stamp-value
time-stamp-value = 1*20DIGIT
speech-marker = "Speech-Marker" ":"
timestamp
[";" 1*(UTFCHAR / %x20)] CRLF
8.4.9. Speech-Language
This header field specifies the default language of the speech data
if the language is not specified in the markup. The value of this
header field MUST follow RFC 5646 [RFC5646] for its values. The
header field MAY occur in SPEAK, SET-PARAMS, or GET-PARAMS requests.
speech-language = "Speech-Language" ":" 1*VCHAR CRLF
8.4.10. Fetch-Hint
When the synthesizer needs to fetch documents or other resources like
speech markup or audio files, this header field controls the
corresponding URI access properties. This provides client policy on
when the synthesizer should retrieve content from the server. A
value of "prefetch" indicates the content MAY be downloaded when the
request is received, whereas "safe" indicates that content MUST NOT
be downloaded until actually referenced. The default value is
"prefetch". This header field MAY occur in SPEAK, SET-PARAMS, or
GET-PARAMS requests.
Burnett & Shanmugham Standards Track [Page 55]
RFC 6787 MRCPv2 November 2012
fetch-hint = "Fetch-Hint" ":"
("prefetch" / "safe") CRLF
8.4.11. Audio-Fetch-Hint
When the synthesizer needs to fetch documents or other resources like
speech audio files, this header field controls the corresponding URI
access properties. This provides client policy whether or not the
synthesizer is permitted to attempt to optimize speech by pre-
fetching audio. The value is either "safe" to say that audio is only
fetched when it is referenced, never before; "prefetch" to permit,
but not require the implementation to pre-fetch the audio; or
"stream" to allow it to stream the audio fetches. The default value
is "prefetch". This header field MAY occur in SPEAK, SET-PARAMS, or
GET-PARAMS requests.
audio-fetch-hint = "Audio-Fetch-Hint" ":"
("prefetch" / "safe" / "stream") CRLF
8.4.12. Failed-URI
When a synthesizer method needs a synthesizer to fetch or access a
URI and the access fails, the server SHOULD provide the failed URI in
this header field in the method response, unless there are multiple
URI failures, in which case the server MUST provide one of the failed
URIs in this header field in the method response.
failed-uri = "Failed-URI" ":" absoluteURI CRLF
8.4.13. Failed-URI-Cause
When a synthesizer method needs a synthesizer to fetch or access a
URI and the access fails, the server MUST provide the URI-specific or
protocol-specific response code for the URI in the Failed-URI header
field in the method response through this header field. The value
encoding is UTF-8 (RFC 3629 [RFC3629]) to accommodate any access
protocol -- some access protocols might have a response string
instead of a numeric response code.
failed-uri-cause = "Failed-URI-Cause" ":" 1*UTFCHAR CRLF
8.4.14. Speak-Restart
When a client issues a CONTROL request to a currently speaking
synthesizer resource to jump backward, and the target jump point is
before the start of the current SPEAK request, the current SPEAK
request MUST restart from the beginning of its speech data and the
Burnett & Shanmugham Standards Track [Page 56]
RFC 6787 MRCPv2 November 2012
server's response to the CONTROL request MUST contain this header
field with a value of "true" indicating a restart.
speak-restart = "Speak-Restart" ":" BOOLEAN CRLF
8.4.15. Speak-Length
This header field MAY be specified in a CONTROL method to control the
maximum length of speech to speak, relative to the current speaking
point in the currently active SPEAK request. If numeric, the value
MUST be a positive integer. If a header field with a Tag unit is
specified, then the speech output continues until the tag is reached
or the SPEAK request is completed, whichever comes first. This
header field MAY be specified in a SPEAK request to indicate the
length to speak from the speech data and is relative to the point in
speech that the SPEAK request starts. The different speech length
units supported are synthesizer implementation dependent. If a
server does not support the specified unit, the server MUST respond
with a status-code of 409 "Unsupported Header Field Value".
speak-length = "Speak-Length" ":" positive-length-value
CRLF
positive-length-value = positive-speech-length
/ text-speech-length
text-speech-length = 1*UTFCHAR SP "Tag"
positive-speech-length = 1*19DIGIT SP numeric-speech-unit
numeric-speech-unit = "Second"
/ "Word"
/ "Sentence"
/ "Paragraph"
8.4.16. Load-Lexicon
This header field is used to indicate whether a lexicon has to be
loaded or unloaded. The value "true" means to load the lexicon if
not already loaded, and the value "false" means to unload the lexicon
if it is loaded. The default value for this header field is "true".
This header field MAY be specified in a DEFINE-LEXICON method.
load-lexicon = "Load-Lexicon" ":" BOOLEAN CRLF
Burnett & Shanmugham Standards Track [Page 57]
RFC 6787 MRCPv2 November 2012
8.4.17. Lexicon-Search-Order
This header field is used to specify a list of active pronunciation
lexicon URIs and the search order among the active lexicons.
Lexicons specified within the SSML document take precedence over the
lexicons specified in this header field. This header field MAY be
specified in the SPEAK, SET-PARAMS, and GET-PARAMS methods.
lexicon-search-order = "Lexicon-Search-Order" ":"
"<" absoluteURI ">" *(" " "<" absoluteURI ">") CRLF
8.5. Synthesizer Message Body
A synthesizer message can contain additional information associated
with the Request, Response, or Event in its message body.
8.5.1. Synthesizer Speech Data
Marked-up text for the synthesizer to speak is specified as a typed
media entity in the message body. The speech data to be spoken by
the synthesizer can be specified inline by embedding the data in the
message body or by reference by providing a URI for accessing the
data. In either case, the data and the format used to markup the
speech needs to be of a content type supported by the server.
All MRCPv2 servers containing synthesizer resources MUST support both
plain text speech data and W3C's Speech Synthesis Markup Language
[W3C.REC-speech-synthesis-20040907] and hence MUST support the media
types 'text/plain' and 'application/ssml+xml'. Other formats MAY be
supported.
If the speech data is to be fetched by URI reference, the media type
'text/uri-list' (see RFC 2483 [RFC2483]) is used to indicate one or
more URIs that, when dereferenced, will contain the content to be
spoken. If a list of speech URIs is specified, the resource MUST
speak the speech data provided by each URI in the order in which the
URIs are specified in the content.
MRCPv2 clients and servers MUST support the 'multipart/mixed' media
type. This is the appropriate media type to use when providing a mix
of URI and inline speech data. Embedded within the multipart content
block, there MAY be content for the 'text/uri-list', 'application/
ssml+xml', and/or 'text/plain' media types. The character set and
encoding used in the speech data is specified according to standard
media type definitions. The multipart content MAY also contain
actual audio data. Clients may have recorded audio clips stored in
memory or on a local device and wish to play it as part of the SPEAK
request. The audio portions MAY be sent by the client as part of the
Burnett & Shanmugham Standards Track [Page 58]
RFC 6787 MRCPv2 November 2012
multipart content block. This audio is referenced in the speech
markup data that is another part in the multipart content block
according to the 'multipart/mixed' media type specification.
Content-Type:text/uri-list
Content-Length:...
http://www.example.com/ASR-Introduction.ssml
http://www.example.com/ASR-Document-Part1.ssml
http://www.example.com/ASR-Document-Part2.ssml
http://www.example.com/ASR-Conclusion.ssml
URI List Example
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Aldine Turnbet
and arrived at 0345p .
The subject is ski trip
SSML Example
Burnett & Shanmugham Standards Track [Page 59]
RFC 6787 MRCPv2 November 2012
Content-Type:multipart/mixed; boundary="break"
--break
Content-Type:text/uri-list
Content-Length:...
http://www.example.com/ASR-Introduction.ssml
http://www.example.com/ASR-Document-Part1.ssml
http://www.example.com/ASR-Document-Part2.ssml
http://www.example.com/ASR-Conclusion.ssml
--break
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams
and arrived at 0342p .
The subject is ski trip
--break--
Multipart Example
8.5.2. Lexicon Data
Synthesizer lexicon data from the client to the server can be
provided inline or by reference. Either way, they are carried as
typed media in the message body of the MRCPv2 request message (see
Section 8.14).
When a lexicon is specified inline in the message, the client MUST
provide a Content-ID for that lexicon as part of the content header
fields. The server MUST store the lexicon associated with that
Content-ID for the duration of the session. A stored lexicon can be
overwritten by defining a new lexicon with the same Content-ID.
Burnett & Shanmugham Standards Track [Page 60]
RFC 6787 MRCPv2 November 2012
Lexicons that have been associated with a Content-ID can be
referenced through the 'session' URI scheme (see Section 13.6).
If lexicon data is specified by external URI reference, the media
type 'text/uri-list' (see RFC 2483 [RFC2483] ) is used to list the
one or more URIs that may be dereferenced to obtain the lexicon data.
All MRCPv2 servers MUST support the "http" and "https" URI access
mechanisms, and MAY support other mechanisms.
If the data in the message body consists of a mix of URI and inline
lexicon data, the 'multipart/mixed' media type is used. The
character set and encoding used in the lexicon data may be specified
according to standard media type definitions.
8.6. SPEAK Method
The SPEAK request provides the synthesizer resource with the speech
text and initiates speech synthesis and streaming. The SPEAK method
MAY carry voice and prosody header fields that alter the behavior of
the voice being synthesized, as well as a typed media message body
containing the actual marked-up text to be spoken.
The SPEAK method implementation MUST do a fetch of all external URIs
that are part of that operation. If caching is implemented, this URI
fetching MUST conform to the cache-control hints and parameter header
fields associated with the method in deciding whether it is to be
fetched from cache or from the external server. If these hints/
parameters are not specified in the method, the values set for the
session using SET-PARAMS/GET-PARAMS apply. If it was not set for the
session, their default values apply.
When applying voice parameters, there are three levels of precedence.
The highest precedence are those specified within the speech markup
text, followed by those specified in the header fields of the SPEAK
request and hence that apply for that SPEAK request only, followed by
the session default values that can be set using the SET-PARAMS
request and apply for subsequent methods invoked during the session.
If the resource was idle at the time the SPEAK request arrived at the
server and the SPEAK method is being actively processed, the resource
responds immediately with a success status code and a request-state
of IN-PROGRESS.
If the resource is in the speaking or paused state when the SPEAK
method arrives at the server, i.e., it is in the middle of processing
a previous SPEAK request, the status returns success with a request-
state of PENDING. The server places the SPEAK request in the
synthesizer resource request queue. The request queue operates
Burnett & Shanmugham Standards Track [Page 61]
RFC 6787 MRCPv2 November 2012
strictly FIFO: requests are processed serially in order of receipt.
If the current SPEAK fails, all SPEAK methods in the pending queue
are cancelled and each generates a SPEAK-COMPLETE event with a
Completion-Cause of "cancelled".
For the synthesizer resource, SPEAK is the only method that can
return a request-state of IN-PROGRESS or PENDING. When the text has
been synthesized and played into the media stream, the resource
issues a SPEAK-COMPLETE event with the request-id of the SPEAK
request and a request-state of COMPLETE.
Burnett & Shanmugham Standards Track [Page 62]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... SPEAK 543257
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:neutral
Voice-Age:25
Prosody-volume:medium
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams and arrived at
0342p .
The subject is
ski trip
S->C: MRCP/2.0 ... 543257 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857206027059
S->C: MRCP/2.0 ... SPEAK-COMPLETE 543257 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Completion-Cause:000 normal
Speech-Marker:timestamp=857206027059
SPEAK Example
8.7. STOP
The STOP method from the client to the server tells the synthesizer
resource to stop speaking if it is speaking something.
The STOP request can be sent with an Active-Request-Id-List header
field to stop the zero or more specific SPEAK requests that may be in
queue and return a response status-code of 200 "Success". If no
Burnett & Shanmugham Standards Track [Page 63]
RFC 6787 MRCPv2 November 2012
Active-Request-Id-List header field is sent in the STOP request, the
server terminates all outstanding SPEAK requests.
If a STOP request successfully terminated one or more PENDING or
IN-PROGRESS SPEAK requests, then the response MUST contain an Active-
Request-Id-List header field enumerating the SPEAK request-ids that
were terminated. Otherwise, there is no Active-Request-Id-List
header field in the response. No SPEAK-COMPLETE events are sent for
such terminated requests.
If a SPEAK request that was IN-PROGRESS and speaking was stopped, the
next pending SPEAK request, if any, becomes IN-PROGRESS at the
resource and enters the speaking state.
If a SPEAK request that was IN-PROGRESS and paused was stopped, the
next pending SPEAK request, if any, becomes IN-PROGRESS and enters
the paused state.
Burnett & Shanmugham Standards Track [Page 64]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... SPEAK 543258
Channel-Identifier:32AECB23433802@speechsynth
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams and arrived at
0342p .
The subject is
ski trip
S->C: MRCP/2.0 ... 543258 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857206027059
C->S: MRCP/2.0 ... STOP 543259
Channel-Identifier:32AECB23433802@speechsynth
S->C: MRCP/2.0 ... 543259 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Active-Request-Id-List:543258
Speech-Marker:timestamp=857206039059
STOP Example
8.8. BARGE-IN-OCCURRED
The BARGE-IN-OCCURRED method, when used with the synthesizer
resource, provides a client that has detected a barge-in-able event a
means to communicate the occurrence of the event to the synthesizer
resource.
This method is useful in two scenarios:
1. The client has detected DTMF digits in the input media or some
other barge-in-able event and wants to communicate that to the
synthesizer resource.
Burnett & Shanmugham Standards Track [Page 65]
RFC 6787 MRCPv2 November 2012
2. The recognizer resource and the synthesizer resource are in
different servers. In this case, the client acts as an
intermediary for the two servers. It receives an event from the
recognition resource and sends a BARGE-IN-OCCURRED request to the
synthesizer. In such cases, the BARGE-IN-OCCURRED method would
also have a Proxy-Sync-Id header field received from the resource
generating the original event.
If a SPEAK request is active with kill-on-barge-in enabled (see
Section 8.4.2), and the BARGE-IN-OCCURRED event is received, the
synthesizer MUST immediately stop streaming out audio. It MUST also
terminate any speech requests queued behind the current active one,
irrespective of whether or not they have barge-in enabled. If a
barge-in-able SPEAK request was playing and it was terminated, the
response MUST contain an Active-Request-Id-List header field listing
the request-ids of all SPEAK requests that were terminated. The
server generates no SPEAK-COMPLETE events for these requests.
If there were no SPEAK requests terminated by the synthesizer
resource as a result of the BARGE-IN-OCCURRED method, the server MUST
respond to the BARGE-IN-OCCURRED with a status-code of 200 "Success",
and the response MUST NOT contain an Active-Request-Id-List header
field.
If the synthesizer and recognizer resources are part of the same
MRCPv2 session, they can be optimized for a quicker kill-on-barge-in
response if the recognizer and synthesizer interact directly. In
these cases, the client MUST still react to a START-OF-INPUT event
from the recognizer by invoking the BARGE-IN-OCCURRED method to the
synthesizer. The client MUST invoke the BARGE-IN-OCCURRED if it has
any outstanding requests to the synthesizer resource in either the
PENDING or IN-PROGRESS state.
Burnett & Shanmugham Standards Track [Page 66]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... SPEAK 543258
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:neutral
Voice-Age:25
Prosody-volume:medium
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams and arrived at
0342p .
The subject is
ski trip
S->C: MRCP/2.0 ... 543258 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857206027059
C->S: MRCP/2.0 ... BARGE-IN-OCCURRED 543259
Channel-Identifier:32AECB23433802@speechsynth
Proxy-Sync-Id:987654321
S->C:MRCP/2.0 ... 543259 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Active-Request-Id-List:543258
Speech-Marker:timestamp=857206039059
BARGE-IN-OCCURRED Example
8.9. PAUSE
The PAUSE method from the client to the server tells the synthesizer
resource to pause speech output if it is speaking something. If a
PAUSE method is issued on a session when a SPEAK is not active, the
server MUST respond with a status-code of 402 "Method not valid in
this state". If a PAUSE method is issued on a session when a SPEAK
is active and paused, the server MUST respond with a status-code of
Burnett & Shanmugham Standards Track [Page 67]
RFC 6787 MRCPv2 November 2012
200 "Success". If a SPEAK request was active, the server MUST return
an Active-Request-Id-List header field whose value contains the
request-id of the SPEAK request that was paused.
C->S: MRCP/2.0 ... SPEAK 543258
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:neutral
Voice-Age:25
Prosody-volume:medium
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams and arrived at
0342p .
The subject is
ski trip
S->C: MRCP/2.0 ... 543258 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857206027059
C->S: MRCP/2.0 ... PAUSE 543259
Channel-Identifier:32AECB23433802@speechsynth
S->C: MRCP/2.0 ... 543259 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Active-Request-Id-List:543258
PAUSE Example
8.10. RESUME
The RESUME method from the client to the server tells a paused
synthesizer resource to resume speaking. If a RESUME request is
issued on a session with no active SPEAK request, the server MUST
Burnett & Shanmugham Standards Track [Page 68]
RFC 6787 MRCPv2 November 2012
respond with a status-code of 402 "Method not valid in this state".
If a RESUME request is issued on a session with an active SPEAK
request that is speaking (i.e., not paused), the server MUST respond
with a status-code of 200 "Success". If a SPEAK request was paused,
the server MUST return an Active-Request-Id-List header field whose
value contains the request-id of the SPEAK request that was resumed.
Burnett & Shanmugham Standards Track [Page 69]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... SPEAK 543258
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:neutral
Voice-age:25
Prosody-volume:medium
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams and arrived at
0342p .
The subject is
ski trip
S->C: MRCP/2.0 ... 543258 200 IN-PROGRESS@speechsynth
Channel-Identifier:32AECB23433802
Speech-Marker:timestamp=857206027059
C->S: MRCP/2.0 ... PAUSE 543259
Channel-Identifier:32AECB23433802@speechsynth
S->C: MRCP/2.0 ... 543259 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Active-Request-Id-List:543258
C->S: MRCP/2.0 ... RESUME 543260
Channel-Identifier:32AECB23433802@speechsynth
S->C: MRCP/2.0 ... 543260 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Active-Request-Id-List:543258
RESUME Example
Burnett & Shanmugham Standards Track [Page 70]
RFC 6787 MRCPv2 November 2012
8.11. CONTROL
The CONTROL method from the client to the server tells a synthesizer
that is speaking to modify what it is speaking on the fly. This
method is used to request the synthesizer to jump forward or backward
in what it is speaking, change speaker rate, speaker parameters, etc.
It affects only the currently IN-PROGRESS SPEAK request. Depending
on the implementation and capability of the synthesizer resource, it
may or may not support the various modifications indicated by header
fields in the CONTROL request.
When a client invokes a CONTROL method to jump forward and the
operation goes beyond the end of the active SPEAK method's text, the
CONTROL request still succeeds. The active SPEAK request completes
and returns a SPEAK-COMPLETE event following the response to the
CONTROL method. If there are more SPEAK requests in the queue, the
synthesizer resource starts at the beginning of the next SPEAK
request in the queue.
When a client invokes a CONTROL method to jump backward and the
operation jumps to the beginning or beyond the beginning of the
speech data of the active SPEAK method, the CONTROL request still
succeeds. The response to the CONTROL request contains the speak-
restart header field, and the active SPEAK request restarts from the
beginning of its speech data.
These two behaviors can be used to rewind or fast-forward across
multiple speech requests, if the client wants to break up a speech
markup text into multiple SPEAK requests.
If a SPEAK request was active when the CONTROL method was received,
the server MUST return an Active-Request-Id-List header field
containing the request-id of the SPEAK request that was active.
C->S: MRCP/2.0 ... SPEAK 543258
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:neutral
Voice-age:25
Prosody-volume:medium
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams
and arrived at 0342p .
The subject is ski trip
S->C: MRCP/2.0 ... 543258 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857205016059
C->S: MRCP/2.0 ... CONTROL 543259
Channel-Identifier:32AECB23433802@speechsynth
Prosody-rate:fast
S->C: MRCP/2.0 ... 543259 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Active-Request-Id-List:543258
Speech-Marker:timestamp=857206027059
C->S: MRCP/2.0 ... CONTROL 543260
Channel-Identifier:32AECB23433802@speechsynth
Jump-Size:-15 Words
S->C: MRCP/2.0 ... 543260 200 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Active-Request-Id-List:543258
Speech-Marker:timestamp=857206039059
CONTROL Example
8.12. SPEAK-COMPLETE
This is an Event message from the synthesizer resource to the client
that indicates the corresponding SPEAK request was completed. The
request-id field matches the request-id of the SPEAK request that
initiated the speech that just completed. The request-state field is
set to COMPLETE by the server, indicating that this is the last event
with the corresponding request-id. The Completion-Cause header field
specifies the cause code pertaining to the status and reason of
request completion, such as the SPEAK completed normally or because
of an error, kill-on-barge-in, etc.
Burnett & Shanmugham Standards Track [Page 72]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... SPEAK 543260
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:neutral
Voice-age:25
Prosody-volume:medium
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams
and arrived at 0342p .
The subject is
ski trip
S->C: MRCP/2.0 ... 543260 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857206027059
S->C: MRCP/2.0 ... SPEAK-COMPLETE 543260 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Completion-Cause:000 normal
Speech-Marker:timestamp=857206039059
SPEAK-COMPLETE Example
8.13. SPEECH-MARKER
This is an event generated by the synthesizer resource to the client
when the synthesizer encounters a marker tag in the speech markup it
is currently processing. The value of the request-id field MUST
match that of the corresponding SPEAK request. The request-state
field MUST have the value "IN-PROGRESS" as the speech is still not
complete. The value of the speech marker tag hit, describing where
the synthesizer is in the speech markup, MUST be returned in the
Speech-Marker header field, along with an NTP timestamp indicating
the instant in the output speech stream that the marker was
encountered. The SPEECH-MARKER event MUST also be generated with a
Burnett & Shanmugham Standards Track [Page 73]
RFC 6787 MRCPv2 November 2012
null marker value and output NTP timestamp when a SPEAK request in
Pending-State (i.e., in the queue) changes state to IN-PROGRESS and
starts speaking. The NTP timestamp MUST be synchronized with the RTP
timestamp used to generate the speech stream through standard RTCP
machinery.
Burnett & Shanmugham Standards Track [Page 74]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... SPEAK 543261
Channel-Identifier:32AECB23433802@speechsynth
Voice-gender:neutral
Voice-age:25
Prosody-volume:medium
Content-Type:application/ssml+xml
Content-Length:...
You have 4 new messages.
The first is from Stephanie Williams
and arrived at 0342p .
The subject is
ski trip
S->C: MRCP/2.0 ... 543261 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857205015059
S->C: MRCP/2.0 ... SPEECH-MARKER 543261 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857206027059;here
S->C: MRCP/2.0 ... SPEECH-MARKER 543261 IN-PROGRESS
Channel-Identifier:32AECB23433802@speechsynth
Speech-Marker:timestamp=857206039059;ANSWER
S->C: MRCP/2.0 ... SPEAK-COMPLETE 543261 COMPLETE
Channel-Identifier:32AECB23433802@speechsynth
Completion-Cause:000 normal
Speech-Marker:timestamp=857207689259;ANSWER
SPEECH-MARKER Example
Burnett & Shanmugham Standards Track [Page 75]
RFC 6787 MRCPv2 November 2012
8.14. DEFINE-LEXICON
The DEFINE-LEXICON method, from the client to the server, provides a
lexicon and tells the server to load or unload the lexicon (see
Section 8.4.16). The media type of the lexicon is provided in the
Content-Type header (see Section 8.5.2). One such media type is
"application/pls+xml" for the Pronunciation Lexicon Specification
(PLS) [W3C.REC-pronunciation-lexicon-20081014] [RFC4267].
If the server resource is in the speaking or paused state, the server
MUST respond with a failure status-code of 402 "Method not valid in
this state".
If the resource is in the idle state and is able to successfully
load/unload the lexicon, the status MUST return a 200 "Success"
status-code and the request-state MUST be COMPLETE.
If the synthesizer could not define the lexicon for some reason, for
example, because the download failed or the lexicon was in an
unsupported form, the server MUST respond with a failure status-code
of 407 and a Completion-Cause header field describing the failure
reason.
9. Speech Recognizer Resource
The speech recognizer resource receives an incoming voice stream and
provides the client with an interpretation of what was spoken in
textual form.
The recognizer resource is controlled by MRCPv2 requests from the
client. The recognizer resource can both respond to these requests
and generate asynchronous events to the client to indicate conditions
of interest during the processing of the method.
This section applies to the following resource types.
1. speechrecog
2. dtmfrecog
The difference between the above two resources is in their level of
support for recognition grammars. The "dtmfrecog" resource type is
capable of recognizing only DTMF digits and hence accepts only DTMF
grammars. It only generates barge-in for DTMF inputs and ignores
speech. The "speechrecog" resource type can recognize regular speech
as well as DTMF digits and hence MUST support grammars describing
either speech or DTMF. This resource generates barge-in events for
speech and/or DTMF. By analyzing the grammars that are activated by
Burnett & Shanmugham Standards Track [Page 76]
RFC 6787 MRCPv2 November 2012
the RECOGNIZE method, it determines if a barge-in should occur for
speech and/or DTMF. When the recognizer decides it needs to generate
a barge-in, it also generates a START-OF-INPUT event to the client.
The recognizer resource MAY support recognition in the normal or
hotword modes or both (although note that a single "speechrecog"
resource does not perform normal and hotword mode recognition
simultaneously). For implementations where a single recognizer
resource does not support both modes, or simultaneous normal and
hotword recognition is desired, the two modes can be invoked through
separate resources allocated to the same SIP dialog (with different
MRCP session identifiers) and share the RTP audio feed.
The capabilities of the recognizer resource are enumerated below:
Normal Mode Recognition Normal mode recognition tries to match all
of the speech or DTMF against the grammar and returns a no-match
status if the input fails to match or the method times out.
Hotword Mode Recognition Hotword mode is where the recognizer looks
for a match against specific speech grammar or DTMF sequence and
ignores speech or DTMF that does not match. The recognition
completes only if there is a successful match of grammar, if the
client cancels the request, or if there is a non-input or
recognition timeout.
Voice Enrolled Grammars A recognizer resource MAY optionally support
Voice Enrolled Grammars. With this functionality, enrollment is
performed using a person's voice. For example, a list of contacts
can be created and maintained by recording the person's names
using the caller's voice. This technique is sometimes also called
speaker-dependent recognition.
Interpretation A recognizer resource MAY be employed strictly for
its natural language interpretation capabilities by supplying it
with a text string as input instead of speech. In this mode, the
resource takes text as input and produces an "interpretation" of
the input according to the supplied grammar.
Voice enrollment has the concept of an enrollment session. A session
to add a new phrase to a personal grammar involves the initial
enrollment followed by a repeat of enough utterances before
committing the new phrase to the personal grammar. Each time an
utterance is recorded, it is compared for similarity with the other
samples and a clash test is performed against other entries in the
personal grammar to ensure there are no similar and confusable
entries.
Burnett & Shanmugham Standards Track [Page 77]
RFC 6787 MRCPv2 November 2012
Enrollment is done using a recognizer resource. Controlling which
utterances are to be considered for enrollment of a new phrase is
done by setting a header field (see Section 9.4.39) in the Recognize
request.
Interpretation is accomplished through the INTERPRET method
(Section 9.20) and the Interpret-Text header field (Section 9.4.30).
9.1. Recognizer State Machine
The recognizer resource maintains a state machine to process MRCPv2
requests from the client.
Idle Recognizing Recognized
State State State
| | |
|---------RECOGNIZE---->|---RECOGNITION-COMPLETE-->|
|<------STOP------------|<-----RECOGNIZE-----------|
| | |
| |--------| |-----------|
| START-OF-INPUT | GET-RESULT |
| |------->| |---------->|
|------------| | |
| DEFINE-GRAMMAR |----------| |
|<-----------| | START-INPUT-TIMERS |
| |<---------| |
|------| | |
| INTERPRET | |
|<-----| |------| |
| | RECOGNIZE |
|-------| |<-----| |
| STOP |
|<------| |
|<-------------------STOP--------------------------|
|<-------------------DEFINE-GRAMMAR----------------|
Recognizer State Machine
If a recognizer resource supports voice enrolled grammars, starting
an enrollment session does not change the state of the recognizer
resource. Once an enrollment session is started, then utterances are
enrolled by calling the RECOGNIZE method repeatedly. The state of
the speech recognizer resource goes from IDLE to RECOGNIZING state
each time RECOGNIZE is called.
Burnett & Shanmugham Standards Track [Page 78]
RFC 6787 MRCPv2 November 2012
9.2. Recognizer Methods
The recognizer supports the following methods.
recognizer-method = recog-only-method
/ enrollment-method
recog-only-method = "DEFINE-GRAMMAR"
/ "RECOGNIZE"
/ "INTERPRET"
/ "GET-RESULT"
/ "START-INPUT-TIMERS"
/ "STOP"
It is OPTIONAL for a recognizer resource to support voice enrolled
grammars. If the recognizer resource does support voice enrolled
grammars, it MUST support the following methods.
enrollment-method = "START-PHRASE-ENROLLMENT"
/ "ENROLLMENT-ROLLBACK"
/ "END-PHRASE-ENROLLMENT"
/ "MODIFY-PHRASE"
/ "DELETE-PHRASE"
9.3. Recognizer Events
The recognizer can generate the following events.
recognizer-event = "START-OF-INPUT"
/ "RECOGNITION-COMPLETE"
/ "INTERPRETATION-COMPLETE"
9.4. Recognizer Header Fields
A recognizer message can contain header fields containing request
options and information to augment the Method, Response, or Event
message it is associated with.
Burnett & Shanmugham Standards Track [Page 79]
RFC 6787 MRCPv2 November 2012
recognizer-header = recog-only-header
/ enrollment-header
recog-only-header = confidence-threshold
/ sensitivity-level
/ speed-vs-accuracy
/ n-best-list-length
/ no-input-timeout
/ input-type
/ recognition-timeout
/ waveform-uri
/ input-waveform-uri
/ completion-cause
/ completion-reason
/ recognizer-context-block
/ start-input-timers
/ speech-complete-timeout
/ speech-incomplete-timeout
/ dtmf-interdigit-timeout
/ dtmf-term-timeout
/ dtmf-term-char
/ failed-uri
/ failed-uri-cause
/ save-waveform
/ media-type
/ new-audio-channel
/ speech-language
/ ver-buffer-utterance
/ recognition-mode
/ cancel-if-queue
/ hotword-max-duration
/ hotword-min-duration
/ interpret-text
/ dtmf-buffer-time
/ clear-dtmf-buffer
/ early-no-match
If a recognizer resource supports voice enrolled grammars, the
following header fields are also used.
Burnett & Shanmugham Standards Track [Page 80]
RFC 6787 MRCPv2 November 2012
enrollment-header = num-min-consistent-pronunciations
/ consistency-threshold
/ clash-threshold
/ personal-grammar-uri
/ enroll-utterance
/ phrase-id
/ phrase-nl
/ weight
/ save-best-waveform
/ new-phrase-id
/ confusable-phrases-uri
/ abort-phrase-enrollment
For enrollment-specific header fields that can appear as part of
SET-PARAMS or GET-PARAMS methods, the following general rule applies:
the START-PHRASE-ENROLLMENT method MUST be invoked before these
header fields may be set through the SET-PARAMS method or retrieved
through the GET-PARAMS method.
Note that the Waveform-URI header field of the Recognizer resource
can also appear in the response to the END-PHRASE-ENROLLMENT method.
9.4.1. Confidence-Threshold
When a recognizer resource recognizes or matches a spoken phrase with
some portion of the grammar, it associates a confidence level with
that match. The Confidence-Threshold header field tells the
recognizer resource what confidence level the client considers a
successful match. This is a float value between 0.0-1.0 indicating
the recognizer's confidence in the recognition. If the recognizer
determines that there is no candidate match with a confidence that is
greater than the confidence threshold, then it MUST return no-match
as the recognition result. This header field MAY occur in RECOGNIZE,
SET-PARAMS, or GET-PARAMS. The default value for this header field
is implementation specific, as is the interpretation of any specific
value for this header field. Although values for servers from
different vendors are not comparable, it is expected that clients
will tune this value over time for a given server.
confidence-threshold = "Confidence-Threshold" ":" FLOAT CRLF
9.4.2. Sensitivity-Level
To filter out background noise and not mistake it for speech, the
recognizer resource supports a variable level of sound sensitivity.
The Sensitivity-Level header field is a float value between 0.0 and
1.0 and allows the client to set the sensitivity level for the
recognizer. This header field MAY occur in RECOGNIZE, SET-PARAMS, or
Burnett & Shanmugham Standards Track [Page 81]
RFC 6787 MRCPv2 November 2012
GET-PARAMS. A higher value for this header field means higher
sensitivity. The default value for this header field is
implementation specific, as is the interpretation of any specific
value for this header field. Although values for servers from
different vendors are not comparable, it is expected that clients
will tune this value over time for a given server.
sensitivity-level = "Sensitivity-Level" ":" FLOAT CRLF
9.4.3. Speed-Vs-Accuracy
Depending on the implementation and capability of the recognizer
resource it may be tunable towards Performance or Accuracy. Higher
accuracy may mean more processing and higher CPU utilization, meaning
fewer active sessions per server and vice versa. The value is a
float between 0.0 and 1.0. A value of 0.0 means fastest recognition.
A value of 1.0 means best accuracy. This header field MAY occur in
RECOGNIZE, SET-PARAMS, or GET-PARAMS. The default value for this
header field is implementation specific. Although values for servers
from different vendors are not comparable, it is expected that
clients will tune this value over time for a given server.
speed-vs-accuracy = "Speed-Vs-Accuracy" ":" FLOAT CRLF
9.4.4. N-Best-List-Length
When the recognizer matches an incoming stream with the grammar, it
may come up with more than one alternative match because of
confidence levels in certain words or conversation paths. If this
header field is not specified, by default, the recognizer resource
returns only the best match above the confidence threshold. The
client, by setting this header field, can ask the recognition
resource to send it more than one alternative. All alternatives must
still be above the Confidence-Threshold. A value greater than one
does not guarantee that the recognizer will provide the requested
number of alternatives. This header field MAY occur in RECOGNIZE,
SET-PARAMS, or GET-PARAMS. The minimum value for this header field
is 1. The default value for this header field is 1.
n-best-list-length = "N-Best-List-Length" ":" 1*19DIGIT CRLF
9.4.5. Input-Type
When the recognizer detects barge-in-able input and generates a
START-OF-INPUT event, that event MUST carry this header field to
specify whether the input that caused the barge-in was DTMF or
speech.
Burnett & Shanmugham Standards Track [Page 82]
RFC 6787 MRCPv2 November 2012
input-type = "Input-Type" ":" inputs CRLF
inputs = "speech" / "dtmf"
9.4.6. No-Input-Timeout
When recognition is started and there is no speech detected for a
certain period of time, the recognizer can send a RECOGNITION-
COMPLETE event to the client with a Completion-Cause of "no-input-
timeout" and terminate the recognition operation. The client can use
the No-Input-Timeout header field to set this timeout. The value is
in milliseconds and can range from 0 to an implementation-specific
maximum value. This header field MAY occur in RECOGNIZE, SET-PARAMS,
or GET-PARAMS. The default value is implementation specific.
no-input-timeout = "No-Input-Timeout" ":" 1*19DIGIT CRLF
9.4.7. Recognition-Timeout
When recognition is started and there is no match for a certain
period of time, the recognizer can send a RECOGNITION-COMPLETE event
to the client and terminate the recognition operation. The
Recognition-Timeout header field allows the client to set this
timeout value. The value is in milliseconds. The value for this
header field ranges from 0 to an implementation-specific maximum
value. The default value is 10 seconds. This header field MAY occur
in RECOGNIZE, SET-PARAMS, or GET-PARAMS.
recognition-timeout = "Recognition-Timeout" ":" 1*19DIGIT CRLF
9.4.8. Waveform-URI
If the Save-Waveform header field is set to "true", the recognizer
MUST record the incoming audio stream of the recognition into a
stored form and provide a URI for the client to access it. This
header field MUST be present in the RECOGNITION-COMPLETE event if the
Save-Waveform header field was set to "true". The value of the
header field MUST be empty if there was some error condition
preventing the server from recording. Otherwise, the URI generated
by the server MUST be unambiguous across the server and all its
recognition sessions. The content associated with the URI MUST be
available to the client until the MRCPv2 session terminates.
Similarly, if the Save-Best-Waveform header field is set to "true",
the recognizer MUST save the audio stream for the best repetition of
the phrase that was used during the enrollment session. The
recognizer MUST then record the recognized audio and make it
available to the client by returning a URI in the Waveform-URI header
field in the response to the END-PHRASE-ENROLLMENT method. The value
Burnett & Shanmugham Standards Track [Page 83]
RFC 6787 MRCPv2 November 2012
of the header field MUST be empty if there was some error condition
preventing the server from recording. Otherwise, the URI generated
by the server MUST be unambiguous across the server and all its
recognition sessions. The content associated with the URI MUST be
available to the client until the MRCPv2 session terminates. See the
discussion on the sensitivity of saved waveforms in Section 12.
The server MUST also return the size in octets and the duration in
milliseconds of the recorded audio waveform as parameters associated
with the header field.
waveform-uri = "Waveform-URI" ":" ["<" uri ">"
";" "size" "=" 1*19DIGIT
";" "duration" "=" 1*19DIGIT] CRLF
9.4.9. Media-Type
This header field MAY be specified in the SET-PARAMS, GET-PARAMS, or
the RECOGNIZE methods and tells the server resource the media type in
which to store captured audio or video, such as the one captured and
returned by the Waveform-URI header field.
media-type = "Media-Type" ":" media-type-value
CRLF
9.4.10. Input-Waveform-URI
This optional header field specifies a URI pointing to audio content
to be processed by the RECOGNIZE operation. This enables the client
to request recognition from a specified buffer or audio file.
input-waveform-uri = "Input-Waveform-URI" ":" uri CRLF
9.4.11. Completion-Cause
This header field MUST be part of a RECOGNITION-COMPLETE event coming
from the recognizer resource to the client. It indicates the reason
behind the RECOGNIZE method completion. This header field MUST be
sent in the DEFINE-GRAMMAR and RECOGNIZE responses, if they return
with a failure status and a COMPLETE state. In the ABNF below, the
cause-code contains a numerical value selected from the Cause-Code
column of the following table. The cause-name contains the
corresponding token selected from the Cause-Name column.
completion-cause = "Completion-Cause" ":" cause-code SP
cause-name CRLF
cause-code = 3DIGIT
cause-name = *VCHAR
Burnett & Shanmugham Standards Track [Page 84]
RFC 6787 MRCPv2 November 2012
+--------+-----------------------+----------------------------------+
| Cause- | Cause-Name | Description |
| Code | | |
+--------+-----------------------+----------------------------------+
| 000 | success | RECOGNIZE completed with a match |
| | | or DEFINE-GRAMMAR succeeded in |
| | | downloading and compiling the |
| | | grammar. |
| | | |
| 001 | no-match | RECOGNIZE completed, but no |
| | | match was found. |
| | | |
| 002 | no-input-timeout | RECOGNIZE completed without a |
| | | match due to a no-input-timeout. |
| | | |
| 003 | hotword-maxtime | RECOGNIZE in hotword mode |
| | | completed without a match due to |
| | | a recognition-timeout. |
| | | |
| 004 | grammar-load-failure | RECOGNIZE failed due to grammar |
| | | load failure. |
| | | |
| 005 | grammar-compilation- | RECOGNIZE failed due to grammar |
| | failure | compilation failure. |
| | | |
| 006 | recognizer-error | RECOGNIZE request terminated |
| | | prematurely due to a recognizer |
| | | error. |
| | | |
| 007 | speech-too-early | RECOGNIZE request terminated |
| | | because speech was too early. |
| | | This happens when the audio |
| | | stream is already "in-speech" |
| | | when the RECOGNIZE request was |
| | | received. |
| | | |
| 008 | success-maxtime | RECOGNIZE request terminated |
| | | because speech was too long but |
| | | whatever was spoken till that |
| | | point was a full match. |
| | | |
| 009 | uri-failure | Failure accessing a URI. |
| | | |
| 010 | language-unsupported | Language not supported. |
| | | |
| 011 | cancelled | A new RECOGNIZE cancelled this |
| | | one, or a prior RECOGNIZE failed |
| | | while this one was still in the |
Burnett & Shanmugham Standards Track [Page 85]
RFC 6787 MRCPv2 November 2012
| | | queue. |
| | | |
| 012 | semantics-failure | Recognition succeeded, but |
| | | semantic interpretation of the |
| | | recognized input failed. The |
| | | RECOGNITION-COMPLETE event MUST |
| | | contain the Recognition result |
| | | with only input text and no |
| | | interpretation. |
| | | |
| 013 | partial-match | Speech Incomplete Timeout |
| | | expired before there was a full |
| | | match. But whatever was spoken |
| | | till that point was a partial |
| | | match to one or more grammars. |
| | | |
| 014 | partial-match-maxtime | The Recognition-Timeout expired |
| | | before full match was achieved. |
| | | But whatever was spoken till |
| | | that point was a partial match |
| | | to one or more grammars. |
| | | |
| 015 | no-match-maxtime | The Recognition-Timeout expired. |
| | | Whatever was spoken till that |
| | | point did not match any of the |
| | | grammars. This cause could also |
| | | be returned if the recognizer |
| | | does not support detecting |
| | | partial grammar matches. |
| | | |
| 016 | grammar-definition- | Any DEFINE-GRAMMAR error other |
| | failure | than grammar-load-failure and |
| | | grammar-compilation-failure. |
+--------+-----------------------+----------------------------------+
9.4.12. Completion-Reason
This header field MAY be specified in a RECOGNITION-COMPLETE event
coming from the recognizer resource to the client. This contains the
reason text behind the RECOGNIZE request completion. The server uses
this header field to communicate text describing the reason for the
failure, such as the specific error encountered in parsing a grammar
markup.
The completion reason text is provided for client use in logs and for
debugging and instrumentation purposes. Clients MUST NOT interpret
the completion reason text.
Burnett & Shanmugham Standards Track [Page 86]
RFC 6787 MRCPv2 November 2012
completion-reason = "Completion-Reason" ":"
quoted-string CRLF
9.4.13. Recognizer-Context-Block
This header field MAY be sent as part of the SET-PARAMS or GET-PARAMS
request. If the GET-PARAMS method contains this header field with no
value, then it is a request to the recognizer to return the
recognizer context block. The response to such a message MAY contain
a recognizer context block as a typed media message body. If the
server returns a recognizer context block, the response MUST contain
this header field and its value MUST match the Content-ID of the
corresponding media block.
If the SET-PARAMS method contains this header field, it MUST also
contain a message body containing the recognizer context data and a
Content-ID matching this header field value. This Content-ID MUST
match the Content-ID that came with the context data during the
GET-PARAMS operation.
An implementation choosing to use this mechanism to hand off
recognizer context data between servers MUST distinguish its
implementation-specific block of data by using an IANA-registered
content type in the IANA Media Type vendor tree.
recognizer-context-block = "Recognizer-Context-Block" ":"
[1*VCHAR] CRLF
9.4.14. Start-Input-Timers
This header field MAY be sent as part of the RECOGNIZE request. A
value of false tells the recognizer to start recognition but not to
start the no-input timer yet. The recognizer MUST NOT start the
timers until the client sends a START-INPUT-TIMERS request to the
recognizer. This is useful in the scenario when the recognizer and
synthesizer engines are not part of the same session. In such
configurations, when a kill-on-barge-in prompt is being played (see
Section 8.4.2), the client wants the RECOGNIZE request to be
simultaneously active so that it can detect and implement kill-on-
barge-in. However, the recognizer SHOULD NOT start the no-input
timers until the prompt is finished. The default value is "true".
start-input-timers = "Start-Input-Timers" ":" BOOLEAN CRLF
Burnett & Shanmugham Standards Track [Page 87]
RFC 6787 MRCPv2 November 2012
9.4.15. Speech-Complete-Timeout
This header field specifies the length of silence required following
user speech before the speech recognizer finalizes a result (either
accepting it or generating a no-match result). The Speech-Complete-
Timeout value applies when the recognizer currently has a complete
match against an active grammar, and specifies how long the
recognizer MUST wait for more input before declaring a match. By
contrast, the Speech-Incomplete-Timeout is used when the speech is an
incomplete match to an active grammar. The value is in milliseconds.
speech-complete-timeout = "Speech-Complete-Timeout" ":"
1*19DIGIT CRLF
A long Speech-Complete-Timeout value delays the result to the client
and therefore makes the application's response to a user slow. A
short Speech-Complete-Timeout may lead to an utterance being broken
up inappropriately. Reasonable speech complete timeout values are
typically in the range of 0.3 seconds to 1.0 seconds. The value for
this header field ranges from 0 to an implementation-specific maximum
value. The default value for this header field is implementation
specific. This header field MAY occur in RECOGNIZE, SET-PARAMS, or
GET-PARAMS.
9.4.16. Speech-Incomplete-Timeout
This header field specifies the required length of silence following
user speech after which a recognizer finalizes a result. The
incomplete timeout applies when the speech prior to the silence is an
incomplete match of all active grammars. In this case, once the
timeout is triggered, the partial result is rejected (with a
Completion-Cause of "partial-match"). The value is in milliseconds.
The value for this header field ranges from 0 to an implementation-
specific maximum value. The default value for this header field is
implementation specific.
speech-incomplete-timeout = "Speech-Incomplete-Timeout" ":" 1*19DIGIT
CRLF
The Speech-Incomplete-Timeout also applies when the speech prior to
the silence is a complete match of an active grammar, but where it is
possible to speak further and still match the grammar. By contrast,
the Speech-Complete-Timeout is used when the speech is a complete
match to an active grammar and no further spoken words can continue
to represent a match.
A long Speech-Incomplete-Timeout value delays the result to the
client and therefore makes the application's response to a user slow.
Burnett & Shanmugham Standards Track [Page 88]
RFC 6787 MRCPv2 November 2012
A short Speech-Incomplete-Timeout may lead to an utterance being
broken up inappropriately.
The Speech-Incomplete-Timeout is usually longer than the Speech-
Complete-Timeout to allow users to pause mid-utterance (for example,
to breathe). This header field MAY occur in RECOGNIZE, SET-PARAMS,
or GET-PARAMS.
9.4.17. DTMF-Interdigit-Timeout
This header field specifies the inter-digit timeout value to use when
recognizing DTMF input. The value is in milliseconds. The value for
this header field ranges from 0 to an implementation-specific maximum
value. The default value is 5 seconds. This header field MAY occur
in RECOGNIZE, SET-PARAMS, or GET-PARAMS.
dtmf-interdigit-timeout = "DTMF-Interdigit-Timeout" ":"
1*19DIGIT CRLF
9.4.18. DTMF-Term-Timeout
This header field specifies the terminating timeout to use when
recognizing DTMF input. The DTMF-Term-Timeout applies only when no
additional input is allowed by the grammar; otherwise, the
DTMF-Interdigit-Timeout applies. The value is in milliseconds. The
value for this header field ranges from 0 to an implementation-
specific maximum value. The default value is 10 seconds. This
header field MAY occur in RECOGNIZE, SET-PARAMS, or GET-PARAMS.
dtmf-term-timeout = "DTMF-Term-Timeout" ":" 1*19DIGIT CRLF
9.4.19. DTMF-Term-Char
This header field specifies the terminating DTMF character for DTMF
input recognition. The default value is NULL, which is indicated by
an empty header field value. This header field MAY occur in
RECOGNIZE, SET-PARAMS, or GET-PARAMS.
dtmf-term-char = "DTMF-Term-Char" ":" VCHAR CRLF
9.4.20. Failed-URI
When a recognizer needs to fetch or access a URI and the access
fails, the server SHOULD provide the failed URI in this header field
in the method response, unless there are multiple URI failures, in
which case one of the failed URIs MUST be provided in this header
field in the method response.
Burnett & Shanmugham Standards Track [Page 89]
RFC 6787 MRCPv2 November 2012
failed-uri = "Failed-URI" ":" absoluteURI CRLF
9.4.21. Failed-URI-Cause
When a recognizer method needs a recognizer to fetch or access a URI
and the access fails, the server MUST provide the URI-specific or
protocol-specific response code for the URI in the Failed-URI header
field through this header field in the method response. The value
encoding is UTF-8 (RFC 3629 [RFC3629]) to accommodate any access
protocol, some of which might have a response string instead of a
numeric response code.
failed-uri-cause = "Failed-URI-Cause" ":" 1*UTFCHAR CRLF
9.4.22. Save-Waveform
This header field allows the client to request the recognizer
resource to save the audio input to the recognizer. The recognizer
resource MUST then attempt to record the recognized audio, without
endpointing, and make it available to the client in the form of a URI
returned in the Waveform-URI header field in the RECOGNITION-COMPLETE
event. If there was an error in recording the stream or the audio
content is otherwise not available, the recognizer MUST return an
empty Waveform-URI header field. The default value for this field is
"false". This header field MAY occur in RECOGNIZE, SET-PARAMS, or
GET-PARAMS. See the discussion on the sensitivity of saved waveforms
in Section 12.
save-waveform = "Save-Waveform" ":" BOOLEAN CRLF
9.4.23. New-Audio-Channel
This header field MAY be specified in a RECOGNIZE request and allows
the client to tell the server that, from this point on, further input
audio comes from a different audio source, channel, or speaker. If
the recognizer resource had collected any input statistics or
adaptation state, the recognizer resource MUST do what is appropriate
for the specific recognition technology, which includes but is not
limited to discarding any collected input statistics or adaptation
state before starting the RECOGNIZE request. Note that if there are
multiple resources that are sharing a media stream and are collecting
or using this data, and the client issues this header field to one of
the resources, the reset operation applies to all resources that use
the shared media stream. This helps in a number of use cases,
including where the client wishes to reuse an open recognition
session with an existing media session for multiple telephone calls.
Burnett & Shanmugham Standards Track [Page 90]
RFC 6787 MRCPv2 November 2012
new-audio-channel = "New-Audio-Channel" ":" BOOLEAN
CRLF
9.4.24. Speech-Language
This header field specifies the language of recognition grammar data
within a session or request, if it is not specified within the data.
The value of this header field MUST follow RFC 5646 [RFC5646] for its
values. This MAY occur in DEFINE-GRAMMAR, RECOGNIZE, SET-PARAMS, or
GET-PARAMS requests.
speech-language = "Speech-Language" ":" 1*VCHAR CRLF
9.4.25. Ver-Buffer-Utterance
This header field lets the client request the server to buffer the
utterance associated with this recognition request into a buffer
available to a co-resident verifier resource. The buffer is shared
across resources within a session and is allocated when a verifier
resource is added to this session. The client MUST NOT send this
header field unless a verifier resource is instantiated for the
session. The buffer is released when the verifier resource is
released from the session.
9.4.26. Recognition-Mode
This header field specifies what mode the RECOGNIZE method will
operate in. The value choices are "normal" or "hotword". If the
value is "normal", the RECOGNIZE starts matching speech and DTMF to
the grammars specified in the RECOGNIZE request. If any portion of
the speech does not match the grammar, the RECOGNIZE command
completes with a no-match status. Timers may be active to detect
speech in the audio (see Section 9.4.14), so the RECOGNIZE method may
complete because of a timeout waiting for speech. If the value of
this header field is "hotword", the RECOGNIZE method operates in
hotword mode, where it only looks for the particular keywords or DTMF
sequences specified in the grammar and ignores silence or other
speech in the audio stream. The default value for this header field
is "normal". This header field MAY occur on the RECOGNIZE method.
recognition-mode = "Recognition-Mode" ":"
"normal" / "hotword" CRLF
Burnett & Shanmugham Standards Track [Page 91]
RFC 6787 MRCPv2 November 2012
9.4.27. Cancel-If-Queue
This header field specifies what will happen if the client attempts
to invoke another RECOGNIZE method when this RECOGNIZE request is
already in progress for the resource. The value for this header
field is a Boolean. A value of "true" means the server MUST
terminate this RECOGNIZE request, with a Completion-Cause of
"cancelled", if the client issues another RECOGNIZE request for the
same resource. A value of "false" for this header field indicates to
the server that this RECOGNIZE request will continue to completion,
and if the client issues more RECOGNIZE requests to the same
resource, they are queued. When the currently active RECOGNIZE
request is stopped or completes with a successful match, the first
RECOGNIZE method in the queue becomes active. If the current
RECOGNIZE fails, all RECOGNIZE methods in the pending queue are
cancelled, and each generates a RECOGNITION-COMPLETE event with a
Completion-Cause of "cancelled". This header field MUST be present
in every RECOGNIZE request. There is no default value.
cancel-if-queue = "Cancel-If-Queue" ":" BOOLEAN CRLF
9.4.28. Hotword-Max-Duration
This header field MAY be sent in a hotword mode RECOGNIZE request.
It specifies the maximum length of an utterance (in seconds) that
will be considered for hotword recognition. This header field, along
with Hotword-Min-Duration, can be used to tune performance by
preventing the recognizer from evaluating utterances that are too
short or too long to be one of the hotwords in the grammar(s). The
value is in milliseconds. The default is implementation dependent.
If present in a RECOGNIZE request specifying a mode other than
"hotword", the header field is ignored.
hotword-max-duration = "Hotword-Max-Duration" ":" 1*19DIGIT
CRLF
9.4.29. Hotword-Min-Duration
This header field MAY be sent in a hotword mode RECOGNIZE request.
It specifies the minimum length of an utterance (in seconds) that
will be considered for hotword recognition. This header field, along
with Hotword-Max-Duration, can be used to tune performance by
preventing the recognizer from evaluating utterances that are too
short or too long to be one of the hotwords in the grammar(s). The
value is in milliseconds. The default value is implementation
dependent. If present in a RECOGNIZE request specifying a mode other
than "hotword", the header field is ignored.
Burnett & Shanmugham Standards Track [Page 92]
RFC 6787 MRCPv2 November 2012
hotword-min-duration = "Hotword-Min-Duration" ":" 1*19DIGIT CRLF
9.4.30. Interpret-Text
The value of this header field is used to provide a pointer to the
text for which a natural language interpretation is desired. The
value is either a URI or text. If the value is a URI, it MUST be a
Content-ID that refers to an entity of type 'text/plain' in the body
of the message. Otherwise, the server MUST treat the value as the
text to be interpreted. This header field MUST be used when invoking
the INTERPRET method.
interpret-text = "Interpret-Text" ":" 1*VCHAR CRLF
9.4.31. DTMF-Buffer-Time
This header field MAY be specified in a GET-PARAMS or SET-PARAMS
method and is used to specify the amount of time, in milliseconds, of
the type-ahead buffer for the recognizer. This is the buffer that
collects DTMF digits as they are pressed even when there is no
RECOGNIZE command active. When a subsequent RECOGNIZE method is
received, it MUST look to this buffer to match the RECOGNIZE request.
If the digits in the buffer are not sufficient, then it can continue
to listen to more digits to match the grammar. The default size of
this DTMF buffer is platform specific.
dtmf-buffer-time = "DTMF-Buffer-Time" ":" 1*19DIGIT CRLF
9.4.32. Clear-DTMF-Buffer
This header field MAY be specified in a RECOGNIZE method and is used
to tell the recognizer to clear the DTMF type-ahead buffer before
starting the RECOGNIZE. The default value of this header field is
"false", which does not clear the type-ahead buffer before starting
the RECOGNIZE method. If this header field is specified to be
"true", then the RECOGNIZE will clear the DTMF buffer before starting
recognition. This means digits pressed by the caller before the
RECOGNIZE command was issued are discarded.
clear-dtmf-buffer = "Clear-DTMF-Buffer" ":" BOOLEAN CRLF
9.4.33. Early-No-Match
This header field MAY be specified in a RECOGNIZE method and is used
to tell the recognizer that it MUST NOT wait for the end of speech
before processing the collected speech to match active grammars. A
value of "true" indicates the recognizer MUST do early matching. The
default value for this header field if not specified is "false". If
Burnett & Shanmugham Standards Track [Page 93]
RFC 6787 MRCPv2 November 2012
the recognizer does not support the processing of the collected audio
before the end of speech, this header field can be safely ignored.
early-no-match = "Early-No-Match" ":" BOOLEAN CRLF
9.4.34. Num-Min-Consistent-Pronunciations
This header field MAY be specified in a START-PHRASE-ENROLLMENT,
SET-PARAMS, or GET-PARAMS method and is used to specify the minimum
number of consistent pronunciations that must be obtained to voice
enroll a new phrase. The minimum value is 1. The default value is
implementation specific and MAY be greater than 1.
num-min-consistent-pronunciations =
"Num-Min-Consistent-Pronunciations" ":" 1*19DIGIT CRLF
9.4.35. Consistency-Threshold
This header field MAY be sent as part of the START-PHRASE-ENROLLMENT,
SET-PARAMS, or GET-PARAMS method. Used during voice enrollment, this
header field specifies how similar to a previously enrolled
pronunciation of the same phrase an utterance needs to be in order to
be considered "consistent". The higher the threshold, the closer the
match between an utterance and previous pronunciations must be for
the pronunciation to be considered consistent. The range for this
threshold is a float value between 0.0 and 1.0. The default value
for this header field is implementation specific.
consistency-threshold = "Consistency-Threshold" ":" FLOAT CRLF
9.4.36. Clash-Threshold
This header field MAY be sent as part of the START-PHRASE-ENROLLMENT,
SET-PARAMS, or GET-PARAMS method. Used during voice enrollment, this
header field specifies how similar the pronunciations of two
different phrases can be before they are considered to be clashing.
For example, pronunciations of phrases such as "John Smith" and "Jon
Smits" may be so similar that they are difficult to distinguish
correctly. A smaller threshold reduces the number of clashes
detected. The range for this threshold is a float value between 0.0
and 1.0. The default value for this header field is implementation
specific. Clash testing can be turned off completely by setting the
Clash-Threshold header field value to 0.
clash-threshold = "Clash-Threshold" ":" FLOAT CRLF
Burnett & Shanmugham Standards Track [Page 94]
RFC 6787 MRCPv2 November 2012
9.4.37. Personal-Grammar-URI
This header field specifies the speaker-trained grammar to be used or
referenced during enrollment operations. Phrases are added to this
grammar during enrollment. For example, a contact list for user
"Jeff" could be stored at the Personal-Grammar-URI
"http://myserver.example.com/myenrollmentdb/jeff-list". The
generated grammar syntax MAY be implementation specific. There is no
default value for this header field. This header field MAY be sent
as part of the START-PHRASE-ENROLLMENT, SET-PARAMS, or GET-PARAMS
method.
personal-grammar-uri = "Personal-Grammar-URI" ":" uri CRLF
9.4.38. Enroll-Utterance
This header field MAY be specified in the RECOGNIZE method. If this
header field is set to "true" and an Enrollment is active, the
RECOGNIZE command MUST add the collected utterance to the personal
grammar that is being enrolled. The way in which this occurs is
engine specific and may be an area of future standardization. The
default value for this header field is "false".
enroll-utterance = "Enroll-Utterance" ":" BOOLEAN CRLF
9.4.39. Phrase-Id
This header field in a request identifies a phrase in an existing
personal grammar for which enrollment is desired. It is also
returned to the client in the RECOGNIZE complete event. This header
field MAY occur in START-PHRASE-ENROLLMENT, MODIFY-PHRASE, or DELETE-
PHRASE requests. There is no default value for this header field.
phrase-id = "Phrase-ID" ":" 1*VCHAR CRLF
9.4.40. Phrase-NL
This string specifies the interpreted text to be returned when the
phrase is recognized. This header field MAY occur in START-PHRASE-
ENROLLMENT and MODIFY-PHRASE requests. There is no default value for
this header field.
phrase-nl = "Phrase-NL" ":" 1*UTFCHAR CRLF
Burnett & Shanmugham Standards Track [Page 95]
RFC 6787 MRCPv2 November 2012
9.4.41. Weight
The value of this header field represents the occurrence likelihood
of a phrase in an enrolled grammar. When using grammar enrollment,
the system is essentially constructing a grammar segment consisting
of a list of possible match phrases. This can be thought of to be
similar to the dynamic construction of a tag in the W3C
grammar specification. Each enrolled-phrase becomes an item in the
list that can be matched against spoken input similar to the -
within a
list. This header field allows you to assign a
weight to the phrase (i.e., - entry) in the
list that
is enrolled. Grammar weights are normalized to a sum of one at
grammar compilation time, so a weight value of 1 for each phrase in
an enrolled grammar list indicates all items in that list have the
same weight. This header field MAY occur in START-PHRASE-ENROLLMENT
and MODIFY-PHRASE requests. The default value for this header field
is implementation specific.
weight = "Weight" ":" FLOAT CRLF
9.4.42. Save-Best-Waveform
This header field allows the client to request the recognizer
resource to save the audio stream for the best repetition of the
phrase that was used during the enrollment session. The recognizer
MUST attempt to record the recognized audio and make it available to
the client in the form of a URI returned in the Waveform-URI header
field in the response to the END-PHRASE-ENROLLMENT method. If there
was an error in recording the stream or the audio data is otherwise
not available, the recognizer MUST return an empty Waveform-URI
header field. This header field MAY occur in the START-PHRASE-
ENROLLMENT, SET-PARAMS, and GET-PARAMS methods.
save-best-waveform = "Save-Best-Waveform" ":" BOOLEAN CRLF
9.4.43. New-Phrase-Id
This header field replaces the ID used to identify the phrase in a
personal grammar. The recognizer returns the new ID when using an
enrollment grammar. This header field MAY occur in MODIFY-PHRASE
requests.
new-phrase-id = "New-Phrase-ID" ":" 1*VCHAR CRLF
Burnett & Shanmugham Standards Track [Page 96]
RFC 6787 MRCPv2 November 2012
9.4.44. Confusable-Phrases-URI
This header field specifies a grammar that defines invalid phrases
for enrollment. For example, typical applications do not allow an
enrolled phrase that is also a command word. This header field MAY
occur in RECOGNIZE requests that are part of an enrollment session.
confusable-phrases-uri = "Confusable-Phrases-URI" ":" uri CRLF
9.4.45. Abort-Phrase-Enrollment
This header field MAY be specified in the END-PHRASE-ENROLLMENT
method to abort the phrase enrollment, rather than committing the
phrase to the personal grammar.
abort-phrase-enrollment = "Abort-Phrase-Enrollment" ":"
BOOLEAN CRLF
9.5. Recognizer Message Body
A recognizer message can carry additional data associated with the
request, response, or event. The client MAY provide the grammar to
be recognized in DEFINE-GRAMMAR or RECOGNIZE requests. When one or
more grammars are specified using the DEFINE-GRAMMAR method, the
server MUST attempt to fetch, compile, and optimize the grammar
before returning a response to the DEFINE-GRAMMAR method. A
RECOGNIZE request MUST completely specify the grammars to be active
during the recognition operation, except when the RECOGNIZE method is
being used to enroll a grammar. During grammar enrollment, such
grammars are OPTIONAL. The server resource sends the recognition
results in the RECOGNITION-COMPLETE event and the GET-RESULT
response. Grammars and recognition results are carried in the
message body of the corresponding MRCPv2 messages.
9.5.1. Recognizer Grammar Data
Recognizer grammar data from the client to the server can be provided
inline or by reference. Either way, grammar data is carried as typed
media entities in the message body of the RECOGNIZE or DEFINE-GRAMMAR
request. All MRCPv2 servers MUST accept grammars in the XML form
(media type 'application/srgs+xml') of the W3C's XML-based Speech
Grammar Markup Format (SRGS) [W3C.REC-speech-grammar-20040316] and
MAY accept grammars in other formats. Examples include but are not
limited to:
o the ABNF form (media type 'application/srgs') of SRGS
Burnett & Shanmugham Standards Track [Page 97]
RFC 6787 MRCPv2 November 2012
o Sun's Java Speech Grammar Format (JSGF)
[refs.javaSpeechGrammarFormat]
Additionally, MRCPv2 servers MAY support the Semantic Interpretation
for Speech Recognition (SISR)
[W3C.REC-semantic-interpretation-20070405] specification.
When a grammar is specified inline in the request, the client MUST
provide a Content-ID for that grammar as part of the content header
fields. If there is no space on the server to store the inline
grammar, the request MUST return with a Completion-Cause code of 016
"grammar-definition-failure". Otherwise, the server MUST associate
the inline grammar block with that Content-ID and MUST store it on
the server for the duration of the session. However, if the Content-
ID is redefined later in the session through a subsequent DEFINE-
GRAMMAR, the inline grammar previously associated with the Content-ID
MUST be freed. If the Content-ID is redefined through a subsequent
DEFINE-GRAMMAR with an empty message body (i.e., no grammar
definition), then in addition to freeing any grammar previously
associated with the Content-ID, the server MUST clear all bindings
and associations to the Content-ID. Unless and until subsequently
redefined, this URI MUST be interpreted by the server as one that has
never been set.
Grammars that have been associated with a Content-ID can be
referenced through the 'session' URI scheme (see Section 13.6). For
example:
session:help@root-level.store
Grammar data MAY be specified using external URI references. To do
so, the client uses a body of media type 'text/uri-list' (see RFC
2483 [RFC2483] ) to list the one or more URIs that point to the
grammar data. The client can use a body of media type 'text/grammar-
ref-list' (see Section 13.5.1) if it wants to assign weights to the
list of grammar URI. All MRCPv2 servers MUST support grammar access
using the 'http' and 'https' URI schemes.
If the grammar data the client wishes to be used on a request
consists of a mix of URI and inline grammar data, the client uses the
'multipart/mixed' media type to enclose the 'text/uri-list',
'application/srgs', or 'application/srgs+xml' content entities. The
character set and encoding used in the grammar data are specified
using to standard media type definitions.
When more than one grammar URI or inline grammar block is specified
in a message body of the RECOGNIZE request, the server interprets
this as a list of grammar alternatives to match against.
Burnett & Shanmugham Standards Track [Page 98]
RFC 6787 MRCPv2 November 2012
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
Robert
- Robert
- Robert
SRGS Grammar Example
Burnett & Shanmugham Standards Track [Page 99]
RFC 6787 MRCPv2 November 2012
Content-Type:text/uri-list
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
Grammar Reference Example
Content-Type:multipart/mixed; boundary="break"
--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:
Content-Length:...
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
Burnett & Shanmugham Standards Track [Page 100]
RFC 6787 MRCPv2 November 2012
Robert
- Robert
- Robert
--break--
Mixed Grammar Reference Example
9.5.2. Recognizer Result Data
Recognition results are returned to the client in the message body of
the RECOGNITION-COMPLETE event or the GET-RESULT response message as
described in Section 6.3. Element and attribute descriptions for the
recognition portion of the NLSML format are provided in Section 9.6
with a normative definition of the schema in Section 16.1.
Content-Type:application/nlsml+xml
Content-Length:...
yes
Result Example
9.5.3. Enrollment Result Data
Enrollment results are returned to the client in the message body of
the RECOGNITION-COMPLETE event as described in Section 6.3. Element
and attribute descriptions for the enrollment portion of the NLSML
Burnett & Shanmugham Standards Track [Page 101]
RFC 6787 MRCPv2 November 2012
format are provided in Section 9.7 with a normative definition of the
schema in Section 16.2.
9.5.4. Recognizer Context Block
When a client changes servers while operating on the behalf of the
same incoming communication session, this header field allows the
client to collect a block of opaque data from one server and provide
it to another server. This capability is desirable if the client
needs different language support or because the server issued a
redirect. Here, the first recognizer resource may have collected
acoustic and other data during its execution of recognition methods.
After a server switch, communicating this data may allow the
recognizer resource on the new server to provide better recognition.
This block of data is implementation specific and MUST be carried as
media type 'application/octets' in the body of the message.
This block of data is communicated in the SET-PARAMS and GET-PARAMS
method/response messages. In the GET-PARAMS method, if an empty
Recognizer-Context-Block header field is present, then the recognizer
SHOULD return its vendor-specific context block, if any, in the
message body as an entity of media type 'application/octets' with a
specific Content-ID. The Content-ID value MUST also be specified in
the Recognizer-Context-Block header field in the GET-PARAMS response.
The SET-PARAMS request wishing to provide this vendor-specific data
MUST send it in the message body as a typed entity with the same
Content-ID that it received from the GET-PARAMS. The Content-ID MUST
also be sent in the Recognizer-Context-Block header field of the
SET-PARAMS message.
Each speech recognition implementation choosing to use this mechanism
to hand off recognizer context data among servers MUST distinguish
its implementation-specific block of data from other implementations
by choosing a Content-ID that is recognizable among the participating
servers and unlikely to collide with values chosen by another
implementation.
9.6. Recognizer Results
The recognizer portion of NLSML (see Section 6.3.1) represents
information automatically extracted from a user's utterances by a
semantic interpretation component, where "utterance" is to be taken
in the general sense of a meaningful user input in any modality
supported by the MRCPv2 implementation.
Burnett & Shanmugham Standards Track [Page 102]
RFC 6787 MRCPv2 November 2012
9.6.1. Markup Functions
MRCPv2 recognizer resources employ the Natural Language Semantics
Markup Language (NLSML) to interpret natural language speech input
and to format the interpretation for consumption by an MRCPv2 client.
The elements of the markup fall into the following general functional
categories: interpretation, side information, and multi-modal
integration.
9.6.1.1. Interpretation
Elements and attributes represent the semantics of a user's
utterance, including the , , and
elements. The element contains the full result of
processing one utterance. It MAY contain multiple
elements if the interpretation of the utterance results in multiple
alternative meanings due to uncertainty in speech recognition or
natural language understanding. There are at least two reasons for
providing multiple interpretations:
1. The client application might have additional information, for
example, information from a database, that would allow it to
select a preferred interpretation from among the possible
interpretations returned from the semantic interpreter.
2. A client-based dialog manager (e.g., VoiceXML
[W3C.REC-voicexml20-20040316]) that was unable to select between
several competing interpretations could use this information to
go back to the user and find out what was intended. For example,
it could issue a SPEAK request to a synthesizer resource to emit
"Did you say 'Boston' or 'Austin'?"
9.6.1.2. Side Information
These are elements and attributes representing additional information
about the interpretation, over and above the interpretation itself.
Side information includes:
1. Whether an interpretation was achieved (the element)
and the system's confidence in an interpretation (the
"confidence" attribute of ).
2. Alternative interpretations ()
3. Input formats and Automatic Speech Recognition (ASR) information:
the can contain multiple elements, each of
which is taken to be an alternative. Similarly,
yes
This example includes only the minimum required information. There
is an overall element, which includes one interpretation and
an input element. The interpretation contains the application-
specific element "", which is the semantically interpreted
result.
Burnett & Shanmugham Standards Track [Page 104]
RFC 6787 MRCPv2 November 2012
9.6.3. Elements and Attributes
9.6.3.1. Root Element
The root element of the markup is . The element
includes one or more elements. Multiple
interpretations can result from ambiguities in the input or in the
semantic interpretation. If the "grammar" attribute does not apply
to all of the interpretations in the result, it can be overridden for
individual interpretations at the level.
Attributes:
1. grammar: The grammar or recognition rule matched by this result.
The format of the grammar attribute will match the rule reference
semantics defined in the grammar specification. Specifically,
the rule reference is in the external XML form for grammar rule
references. The markup interpreter needs to know the grammar
rule that is matched by the utterance because multiple rules may
be simultaneously active. The value is the grammar URI used by
the markup interpreter to specify the grammar. The grammar can
be overridden by a grammar attribute in the
element if the input was ambiguous as to which grammar it
matched. If all interpretation elements within the result
element contain their own grammar attributes, the attribute can
be dropped from the result element.
....
9.6.3.2. Element
An element contains a single semantic
interpretation.
Attributes:
1. confidence: A float value from 0.0-1.0 indicating the semantic
analyzer's confidence in this interpretation. A value of 1.0
indicates maximum confidence. The values are implementation
dependent but are intended to align with the value interpretation
for the confidence MRCPv2 header field defined in Section 9.4.1.
This attribute is OPTIONAL.
Burnett & Shanmugham Standards Track [Page 105]
RFC 6787 MRCPv2 November 2012
2. grammar: The grammar or recognition rule matched by this
interpretation (if needed to override the grammar specification
at the level.) This attribute is only needed
under if it is necessary to override a grammar
that was defined at the level. Note that the grammar
attribute for the interpretation element is optional if and only
if the grammar attribute is specified in the element.
Interpretations MUST be sorted best-first by some measure of
"goodness". The goodness measure is "confidence" if present;
otherwise, it is some implementation-specific indication of quality.
The grammar is expected to be specified most frequently at the
level. However, it can be overridden at the
level because it is possible that different
interpretations may match different grammar rules.
The element includes an optional
element containing the interpretation of the utterance.
...
9.6.3.3. Element
The element contains the interpretation of the utterance.
When the Semantic Interpretation for Speech Recognition format is
used, the element contains the XML serialization of the
result using the approach defined in that specification. When there
is semantic markup in the grammar that does not create semantic
objects, but instead only does a semantic translation of a portion of
the input, such as translating "coke" to "coca-cola", the instance
contains the whole input but with the translation applied. The NLSML
looks like the markup in Figure 2 below. If there are no semantic
objects created, nor any semantic translation, the instance value is
the same as the input value.
Attributes:
1. confidence: Each element of the instance MAY have a confidence
attribute, defined in the NLSML namespace. The confidence
attribute contains a float value in the range from 0.0-1.0
reflecting the system's confidence in the analysis of that slot.
A value of 1.0 indicates maximum confidence. The values are
implementation dependent, but are intended to align with the
Burnett & Shanmugham Standards Track [Page 106]
RFC 6787 MRCPv2 November 2012
value interpretation for the MRCPv2 header field Confidence-
Threshold defined in Section 9.4.1. This attribute is OPTIONAL.
123 Maple Street
Mill Valley
CA
90952
I would like to buy a coca-cola
). Optional "timestamp-
start" and "timestamp-end" attributes indicate the start and end
times of a spoken utterance, in ISO 8601 format [ISO.8601.1988].
Attributes:
1. timestamp-start: The time at which the input began. (optional)
2. timestamp-end: The time at which the input ended. (optional)
3. mode: The modality of the input, for example, speech, DTMF, etc.
(optional)
4. confidence: The confidence of the recognizer in the correctness
of the input in the range 0.0 to 1.0. (optional)
Burnett & Shanmugham Standards Track [Page 107]
RFC 6787 MRCPv2 November 2012
Note that it may not make sense for temporally overlapping inputs to
have the same mode; however, this constraint is not expected to be
enforced by implementations.
When there is no time zone designator, ISO 8601 time representations
default to local time.
There are three possible formats for the and
elements, which describe situations in which the speech
recognizer received input that it was unable to process or did
not receive any input at all, respectively.
9.6.3.5. Element
The element under
I want to go to New York
9.6.3.6. Element
indicates that there was no input -- a timeout occurred in
the speech recognizer due to silence.
If there are multiple levels of inputs, the most natural place for
and elements to appear is under the highest level
of , and under the appropriate level of
for . So, means "no input at
all" and means "no match in speech modality" or "no match
in DTMF modality". For example, to represent garbled speech combined
with DTMF "1 2 3 4", the markup would be:
could be represented as an attribute of input,
cannot, since it could potentially include PCDATA content
with the best match. For parallelism, is also an element.
9.7. Enrollment Results
All enrollment elements are contained within a single
element under . The elements are
described below and have the schema defined in Section 16.2. The
following elements are defined:
Burnett & Shanmugham Standards Track [Page 109]
RFC 6787 MRCPv2 November 2012
1. num-clashes
2. num-good-repetitions
3. num-repetitions-still-needed
4. consistency-status
5. clash-phrase-ids
6. transcriptions
7. confusable-phrases
9.7.1. Element
The element contains the number of clashes that this
pronunciation has with other pronunciations in an active enrollment
session. The associated Clash-Threshold header field determines the
sensitivity of the clash measurement. Note that clash testing can be
turned off completely by setting the Clash-Threshold header field
value to 0.
9.7.2. Element
The element contains the number of consistent
pronunciations obtained so far in an active enrollment session.
9.7.3. Element
The element contains the number of
consistent pronunciations that must still be obtained before the new
phrase can be added to the enrollment grammar. The number of
consistent pronunciations required is specified by the client in the
request header field Num-Min-Consistent-Pronunciations. The returned
value must be 0 before the client can successfully commit a phrase to
the grammar by ending the enrollment session.
9.7.4. Element
The element is used to indicate how consistent
the repetitions are when learning a new phrase. It can have the
values of consistent, inconsistent, and undecided.
Burnett & Shanmugham Standards Track [Page 110]
RFC 6787 MRCPv2 November 2012
9.7.5. Element
The element contains the phrase IDs of clashing
pronunciation(s), if any. This element is absent if there are no
clashes.
9.7.6. Element
The element contains the transcriptions returned in
the last repetition of the phrase being enrolled.
9.7.7. Element
The element contains a list of phrases from a
command grammar that are confusable with the phrase being added to
the personal grammar. This element MAY be absent if there are no
confusable phrases.
9.8. DEFINE-GRAMMAR
The DEFINE-GRAMMAR method, from the client to the server, provides
one or more grammars and requests the server to access, fetch, and
compile the grammars as needed. The DEFINE-GRAMMAR method
implementation MUST do a fetch of all external URIs that are part of
that operation. If caching is implemented, this URI fetching MUST
conform to the cache control hints and parameter header fields
associated with the method in deciding whether the URIs should be
fetched from cache or from the external server. If these hints/
parameters are not specified in the method, the values set for the
session using SET-PARAMS/GET-PARAMS apply. If it was not set for the
session, their default values apply.
If the server resource is in the recognition state, the DEFINE-
GRAMMAR request MUST respond with a failure status.
If the resource is in the idle state and is able to successfully
process the supplied grammars, the server MUST return a success code
status and the request-state MUST be COMPLETE.
If the recognizer resource could not define the grammar for some
reason (for example, if the download failed, the grammar failed to
compile, or the grammar was in an unsupported form), the MRCPv2
response for the DEFINE-GRAMMAR method MUST contain a failure status-
code of 407 and contain a Completion-Cause header field describing
the failure reason.
C->S:MRCP/2.0 ... DEFINE-GRAMMAR 543257
Channel-Identifier:32AECB23433801@speechrecog
Burnett & Shanmugham Standards Track [Page 111]
RFC 6787 MRCPv2 November 2012
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
S->C:MRCP/2.0 ... 543257 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
C->S:MRCP/2.0 ... DEFINE-GRAMMAR 543258
Channel-Identifier:32AECB23433801@speechrecog
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
I need help
Burnett & Shanmugham Standards Track [Page 112]
RFC 6787 MRCPv2 November 2012
S->C:MRCP/2.0 ... 543258 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
C->S:MRCP/2.0 ... DEFINE-GRAMMAR 543259
Channel-Identifier:32AECB23433801@speechrecog
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
please move the window
open a file
- open
open
- close
close
- delete
delete
- move
move
Burnett & Shanmugham Standards Track [Page 113]
RFC 6787 MRCPv2 November 2012
-
- the
- a
- window
- file
- menu
S->C:MRCP/2.0 ... 543259 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
C->S:MRCP/2.0 ... RECOGNIZE 543260
Channel-Identifier:32AECB23433801@speechrecog
N-Best-List-Length:2
Content-Type:text/uri-list
Content-Length:...
session:request1@form-level.store
session:request2@field-level.store
session:helpgramar@root-level.store
S->C:MRCP/2.0 ... 543260 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C:MRCP/2.0 ... START-OF-INPUT 543260 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C:MRCP/2.0 ... RECOGNITION-COMPLETE 543260 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
Waveform-URI:;
size=124535;duration=2340
Content-Type:application/x-nlsml
Content-Length:...
Burnett & Shanmugham Standards Track [Page 114]
RFC 6787 MRCPv2 November 2012
Andre Roy
Define Grammar Example
9.9. RECOGNIZE
The RECOGNIZE method from the client to the server requests the
recognizer to start recognition and provides it with one or more
grammar references for grammars to match against the input media.
The RECOGNIZE method can carry header fields to control the
sensitivity, confidence level, and the level of detail in results
provided by the recognizer. These header field values override the
current values set by a previous SET-PARAMS method.
The RECOGNIZE method can request the recognizer resource to operate
in normal or hotword mode as specified by the Recognition-Mode header
field. The default value is "normal". If the resource could not
start a recognition, the server MUST respond with a failure status-
code of 407 and a Completion-Cause header field in the response
describing the cause of failure.
The RECOGNIZE request uses the message body to specify the grammars
applicable to the request. The active grammar(s) for the request can
be specified in one of three ways. If the client needs to explicitly
control grammar weights for the recognition operation, it MUST employ
method 3 below. The order of these grammars specifies the precedence
of the grammars that is used when more than one grammar in the list
matches the speech; in this case, the grammar with the higher
precedence is returned as a match. This precedence capability is
useful in applications like VoiceXML browsers to order grammars
specified at the dialog, document, and root level of a VoiceXML
application.
1. The grammar MAY be placed directly in the message body as typed
content. If more than one grammar is included in the body, the
order of inclusion controls the corresponding precedence for the
Burnett & Shanmugham Standards Track [Page 115]
RFC 6787 MRCPv2 November 2012
grammars during recognition, with earlier grammars in the body
having a higher precedence than later ones.
2. The body MAY contain a list of grammar URIs specified in content
of media type 'text/uri-list' [RFC2483]. The order of the URIs
determines the corresponding precedence for the grammars during
recognition, with highest precedence first and decreasing for
each URI thereafter.
3. The body MAY contain a list of grammar URIs specified in content
of media type 'text/grammar-ref-list'. This type defines a list
of grammar URIs and allows each grammar URI to be assigned a
weight in the list. This weight has the same meaning as the
weights described in Section 2.4.1 of the Speech Grammar Markup
Format (SRGS) [W3C.REC-speech-grammar-20040316].
In addition to performing recognition on the input, the recognizer
MUST also enroll the collected utterance in a personal grammar if the
Enroll-Utterance header field is set to true and an Enrollment is
active (via an earlier execution of the START-PHRASE-ENROLLMENT
method). If so, and if the RECOGNIZE request contains a Content-ID
header field, then the resulting grammar (which includes the personal
grammar as a sub-grammar) can be referenced through the 'session' URI
scheme (see Section 13.6).
If the resource was able to successfully start the recognition, the
server MUST return a success status-code and a request-state of
IN-PROGRESS. This means that the recognizer is active and that the
client MUST be prepared to receive further events with this request-
id.
If the resource was able to queue the request, the server MUST return
a success code and request-state of PENDING. This means that the
recognizer is currently active with another request and that this
request has been queued for processing.
If the resource could not start a recognition, the server MUST
respond with a failure status-code of 407 and a Completion-Cause
header field in the response describing the cause of failure.
For the recognizer resource, RECOGNIZE and INTERPRET are the only
requests that return a request-state of IN-PROGRESS, meaning that
recognition is in progress. When the recognition completes by
matching one of the grammar alternatives or by a timeout without a
match or for some other reason, the recognizer resource MUST send the
client a RECOGNITION-COMPLETE event (or INTERPRETATION-COMPLETE, if
INTERPRET was the request) with the result of the recognition and a
request-state of COMPLETE.
Burnett & Shanmugham Standards Track [Page 116]
RFC 6787 MRCPv2 November 2012
Large grammars can take a long time for the server to compile. For
grammars that are used repeatedly, the client can improve server
performance by issuing a DEFINE-GRAMMAR request with the grammar
ahead of time. In such a case, the client can issue the RECOGNIZE
request and reference the grammar through the 'session' URI scheme
(see Section 13.6). This also applies in general if the client wants
to repeat recognition with a previous inline grammar.
The RECOGNIZE method implementation MUST do a fetch of all external
URIs that are part of that operation. If caching is implemented,
this URI fetching MUST conform to the cache control hints and
parameter header fields associated with the method in deciding
whether it should be fetched from cache or from the external server.
If these hints/parameters are not specified in the method, the values
set for the session using SET-PARAMS/GET-PARAMS apply. If it was not
set for the session, their default values apply.
Note that since the audio and the messages are carried over separate
communication paths there may be a race condition between the start
of the flow of audio and the receipt of the RECOGNIZE method. For
example, if an audio flow is started by the client at the same time
as the RECOGNIZE method is sent, either the audio or the RECOGNIZE
can arrive at the recognizer first. As another example, the client
may choose to continuously send audio to the server and signal the
server to recognize using the RECOGNIZE method. Mechanisms to
resolve this condition are outside the scope of this specification.
The recognizer can expect the media to start flowing when it receives
the RECOGNIZE request, but it MUST NOT buffer anything it receives
beforehand in order to preserve the semantics that application
authors expect with respect to the input timers.
When a RECOGNIZE method has been received, the recognition is
initiated on the stream. The No-Input-Timer MUST be started at this
time if the Start-Input-Timers header field is specified as "true".
If this header field is set to "false", the No-Input-Timer MUST be
started when it receives the START-INPUT-TIMERS method from the
client. The Recognition-Timeout MUST be started when the recognition
resource detects speech or a DTMF digit in the media stream.
For recognition when not in hotword mode:
When the recognizer resource detects speech or a DTMF digit in the
media stream, it MUST send the START-OF-INPUT event. When enough
speech has been collected for the server to process, the recognizer
can try to match the collected speech with the active grammars. If
the speech collected at this point fully matches with any of the
active grammars, the Speech-Complete-Timer is started. If it matches
partially with one or more of the active grammars, with more speech
Burnett & Shanmugham Standards Track [Page 117]
RFC 6787 MRCPv2 November 2012
needed before a full match is achieved, then the Speech-Incomplete-
Timer is started.
1. When the No-Input-Timer expires, the recognizer MUST complete
with a Completion-Cause code of "no-input-timeout".
2. The recognizer MUST support detecting a no-match condition upon
detecting end of speech. The recognizer MAY support detecting a
no-match condition before waiting for end-of-speech. If this is
supported, this capability is enabled by setting the Early-No-
Match header field to "true". Upon detecting a no-match
condition, the RECOGNIZE MUST return with "no-match".
3. When the Speech-Incomplete-Timer expires, the recognizer SHOULD
complete with a Completion-Cause code of "partial-match", unless
the recognizer cannot differentiate a partial-match, in which
case it MUST return a Completion-Cause code of "no-match". The
recognizer MAY return results for the partially matched grammar.
4. When the Speech-Complete-Timer expires, the recognizer MUST
complete with a Completion-Cause code of "success".
5. When the Recognition-Timeout expires, one of the following MUST
happen:
5.1. If there was a partial-match, the recognizer SHOULD
complete with a Completion-Cause code of "partial-match-
maxtime", unless the recognizer cannot differentiate a
partial-match, in which case it MUST complete with a
Completion-Cause code of "no-match-maxtime". The recognizer
MAY return results for the partially matched grammar.
5.2. If there was a full-match, the recognizer MUST complete
with a Completion-Cause code of "success-maxtime".
5.3. If there was a no match, the recognizer MUST complete with
a Completion-Cause code of "no-match-maxtime".
For recognition in hotword mode:
Note that for recognition in hotword mode the START-OF-INPUT event is
not generated when speech or a DTMF digit is detected.
1. When the No-Input-Timer expires, the recognizer MUST complete
with a Completion-Cause code of "no-input-timeout".
2. If at any point a match occurs, the RECOGNIZE MUST complete with
a Completion-Cause code of "success".
Burnett & Shanmugham Standards Track [Page 118]
RFC 6787 MRCPv2 November 2012
3. When the Recognition-Timeout expires and there is not a match,
the RECOGNIZE MUST complete with a Completion-Cause code of
"hotword-maxtime".
4. When the Recognition-Timeout expires and there is a match, the
RECOGNIZE MUST complete with a Completion-Cause code of "success-
maxtime".
5. When the Recognition-Timeout is running but the detected speech/
DTMF has not resulted in a match, the Recognition-Timeout MUST be
stopped and reset. It MUST then be restarted when speech/DTMF is
again detected.
Below is a complete example of using RECOGNIZE. It shows the call to
RECOGNIZE, the IN-PROGRESS and START-OF-INPUT status messages, and
the final RECOGNITION-COMPLETE message containing the result.
C->S:MRCP/2.0 ... RECOGNIZE 543257
Channel-Identifier:32AECB23433801@speechrecog
Confidence-Threshold:0.9
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
Burnett & Shanmugham Standards Track [Page 119]
RFC 6787 MRCPv2 November 2012
S->C: MRCP/2.0 ... 543257 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C:MRCP/2.0 ... START-OF-INPUT 543257 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C:MRCP/2.0 ... RECOGNITION-COMPLETE 543257 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
Waveform-URI:;
size=424252;duration=2543
Content-Type:application/nlsml+xml
Content-Length:...
Andre Roy
Below is an example of calling RECOGNIZE with a different grammar.
No status or completion messages are shown in this example, although
they would of course occur in normal usage.
Burnett & Shanmugham Standards Track [Page 120]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... RECOGNIZE 543257
Channel-Identifier:32AECB23433801@speechrecog
Confidence-Threshold:0.9
Fetch-Timeout:20
Content-Type:application/srgs+xml
Content-Length:...
-
-
-
9.10. STOP
The STOP method from the client to the server tells the resource to
stop recognition if a request is active. If a RECOGNIZE request is
active and the STOP request successfully terminated it, then the
response header section contains an Active-Request-Id-List header
field containing the request-id of the RECOGNIZE request that was
terminated. In this case, no RECOGNITION-COMPLETE event is sent for
the terminated request. If there was no recognition active, then the
response MUST NOT contain an Active-Request-Id-List header field.
Either way, the response MUST contain a status-code of 200 "Success".
Burnett & Shanmugham Standards Track [Page 121]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... RECOGNIZE 543257
Channel-Identifier:32AECB23433801@speechrecog
Confidence-Threshold:0.9
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
S->C: MRCP/2.0 ... 543257 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
C->S: MRCP/2.0 ... STOP 543258 200
Channel-Identifier:32AECB23433801@speechrecog
S->C: MRCP/2.0 ... 543258 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Active-Request-Id-List:543257
9.11. GET-RESULT
The GET-RESULT method from the client to the server MAY be issued
when the recognizer resource is in the recognized state. This
request allows the client to retrieve results for a completed
recognition. This is useful if the client decides it wants more
alternatives or more information. When the server receives this
Burnett & Shanmugham Standards Track [Page 122]
RFC 6787 MRCPv2 November 2012
request, it re-computes and returns the results according to the
recognition constraints provided in the GET-RESULT request.
The GET-RESULT request can specify constraints such as a different
confidence-threshold or n-best-list-length. This capability is
OPTIONAL for MRCPv2 servers and the automatic speech recognition
engine in the server MUST return a status of unsupported feature if
not supported.
C->S: MRCP/2.0 ... GET-RESULT 543257
Channel-Identifier:32AECB23433801@speechrecog
Confidence-Threshold:0.9
S->C: MRCP/2.0 ... 543257 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Content-Type:application/nlsml+xml
Content-Length:...
Andre Roy
9.12. START-OF-INPUT
This is an event from the server to the client indicating that the
recognizer resource has detected speech or a DTMF digit in the media
stream. This event is useful in implementing kill-on-barge-in
scenarios when a synthesizer resource is in a different session from
the recognizer resource and hence is not aware of an incoming audio
source (see Section 8.4.2). In these cases, it is up to the client
to act as an intermediary and respond to this event by issuing a
BARGE-IN-OCCURRED event to the synthesizer resource. The recognizer
resource also MUST send a Proxy-Sync-Id header field with a unique
value for this event.
This event MUST be generated by the server, irrespective of whether
or not the synthesizer and recognizer are on the same server.
Burnett & Shanmugham Standards Track [Page 123]
RFC 6787 MRCPv2 November 2012
9.13. START-INPUT-TIMERS
This request is sent from the client to the recognizer resource when
it knows that a kill-on-barge-in prompt has finished playing (see
Section 8.4.2). This is useful in the scenario when the recognition
and synthesizer engines are not in the same session. When a kill-on-
barge-in prompt is being played, the client may want a RECOGNIZE
request to be simultaneously active so that it can detect and
implement kill-on-barge-in. But at the same time the client doesn't
want the recognizer to start the no-input timers until the prompt is
finished. The Start-Input-Timers header field in the RECOGNIZE
request allows the client to say whether or not the timers should be
started immediately. If not, the recognizer resource MUST NOT start
the timers until the client sends a START-INPUT-TIMERS method to the
recognizer.
9.14. RECOGNITION-COMPLETE
This is an event from the recognizer resource to the client
indicating that the recognition completed. The recognition result is
sent in the body of the MRCPv2 message. The request-state field MUST
be COMPLETE indicating that this is the last event with that request-
id and that the request with that request-id is now complete. The
server MUST maintain the recognizer context containing the results
and the audio waveform input of that recognition until the next
RECOGNIZE request is issued for that resource or the session
terminates. If the server returns a URI to the audio waveform, it
MUST do so in a Waveform-URI header field in the RECOGNITION-COMPLETE
event. The client can use this URI to retrieve or playback the
audio.
Note, if an enrollment session was active, the RECOGNITION-COMPLETE
event can contain either recognition or enrollment results depending
on what was spoken. The following example shows a complete exchange
with a recognition result.
C->S: MRCP/2.0 ... RECOGNIZE 543257
Channel-Identifier:32AECB23433801@speechrecog
Confidence-Threshold:0.9
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
Burnett & Shanmugham Standards Track [Page 124]
RFC 6787 MRCPv2 November 2012
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
S->C: MRCP/2.0 ... 543257 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C: MRCP/2.0 ... START-OF-INPUT 543257 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C: MRCP/2.0 ... RECOGNITION-COMPLETE 543257 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
Waveform-URI:;
size=342456;duration=25435
Content-Type:application/nlsml+xml
Content-Length:...
Andre Roy
If the result were instead an enrollment result, the final message
from the server above could have been:
Burnett & Shanmugham Standards Track [Page 125]
RFC 6787 MRCPv2 November 2012
S->C: MRCP/2.0 ... RECOGNITION-COMPLETE 543257 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
Content-Type:application/nlsml+xml
Content-Length:...
2
1
1
consistent
- Jeff
- Andre
- m ay b r ow k er
- m ax r aa k ah
-
call
10
9.15. START-PHRASE-ENROLLMENT
The START-PHRASE-ENROLLMENT method from the client to the server
starts a new phrase enrollment session during which the client can
call RECOGNIZE multiple times to enroll a new utterance in a grammar.
An enrollment session consists of a set of calls to RECOGNIZE in
which the caller speaks a phrase several times so the system can
"learn" it. The phrase is then added to a personal grammar (speaker-
trained grammar), so that the system can recognize it later.
Only one phrase enrollment session can be active at a time for a
resource. The Personal-Grammar-URI identifies the grammar that is
used during enrollment to store the personal list of phrases. Once
RECOGNIZE is called, the result is returned in a RECOGNITION-COMPLETE
event and will contain either an enrollment result OR a recognition
result for a regular recognition.
Burnett & Shanmugham Standards Track [Page 126]
RFC 6787 MRCPv2 November 2012
Calling END-PHRASE-ENROLLMENT ends the ongoing phrase enrollment
session, which is typically done after a sequence of successful calls
to RECOGNIZE. This method can be called to commit the new phrase to
the personal grammar or to abort the phrase enrollment session.
The grammar to contain the new enrolled phrase, specified by
Personal-Grammar-URI, is created if it does not exist. Also, the
personal grammar MUST ONLY contain phrases added via a phrase
enrollment session.
The Phrase-ID passed to this method is used to identify this phrase
in the grammar and will be returned as the speech input when doing a
RECOGNIZE on the grammar. The Phrase-NL similarly is returned in a
RECOGNITION-COMPLETE event in the same manner as other Natural
Language (NL) in a grammar. The tag-format of this NL is
implementation specific.
If the client has specified Save-Best-Waveform as true, then the
response after ending the phrase enrollment session MUST contain the
location/URI of a recording of the best repetition of the learned
phrase.
C->S: MRCP/2.0 ... START-PHRASE-ENROLLMENT 543258
Channel-Identifier:32AECB23433801@speechrecog
Num-Min-Consistent-Pronunciations:2
Consistency-Threshold:30
Clash-Threshold:12
Personal-Grammar-URI:
Phrase-Id:
Phrase-NL:
Weight:1
Save-Best-Waveform:true
S->C: MRCP/2.0 ... 543258 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
9.16. ENROLLMENT-ROLLBACK
The ENROLLMENT-ROLLBACK method discards the last live utterance from
the RECOGNIZE operation. The client can invoke this method when the
caller provides undesirable input such as non-speech noises, side-
speech, commands, utterance from the RECOGNIZE grammar, etc. Note
that this method does not provide a stack of rollback states.
Executing ENROLLMENT-ROLLBACK twice in succession without an
intervening recognition operation has no effect the second time.
Burnett & Shanmugham Standards Track [Page 127]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... ENROLLMENT-ROLLBACK 543261
Channel-Identifier:32AECB23433801@speechrecog
S->C: MRCP/2.0 ... 543261 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
9.17. END-PHRASE-ENROLLMENT
The client MAY call the END-PHRASE-ENROLLMENT method ONLY during an
active phrase enrollment session. It MUST NOT be called during an
ongoing RECOGNIZE operation. To commit the new phrase in the
grammar, the client MAY call this method once successive calls to
RECOGNIZE have succeeded and Num-Repetitions-Still-Needed has been
returned as 0 in the RECOGNITION-COMPLETE event. Alternatively, the
client MAY abort the phrase enrollment session by calling this method
with the Abort-Phrase-Enrollment header field.
If the client has specified Save-Best-Waveform as "true" in the
START-PHRASE-ENROLLMENT request, then the response MUST contain a
Waveform-URI header whose value is the location/URI of a recording of
the best repetition of the learned phrase.
C->S: MRCP/2.0 ... END-PHRASE-ENROLLMENT 543262
Channel-Identifier:32AECB23433801@speechrecog
S->C: MRCP/2.0 ... 543262 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Waveform-URI:
;size=242453;duration=25432
9.18. MODIFY-PHRASE
The MODIFY-PHRASE method sent from the client to the server is used
to change the phrase ID, NL phrase, and/or weight for a given phrase
in a personal grammar.
If no fields are supplied, then calling this method has no effect.
Burnett & Shanmugham Standards Track [Page 128]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... MODIFY-PHRASE 543265
Channel-Identifier:32AECB23433801@speechrecog
Personal-Grammar-URI:
Phrase-Id:
New-Phrase-Id:
Phrase-NL:
Weight:1
S->C: MRCP/2.0 ... 543265 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
9.19. DELETE-PHRASE
The DELETE-PHRASE method sent from the client to the server is used
to delete a phase that is in a personal grammar and was added through
voice enrollment or text enrollment. If the specified phrase does
not exist, this method has no effect.
C->S: MRCP/2.0 ... DELETE-PHRASE 543266
Channel-Identifier:32AECB23433801@speechrecog
Personal-Grammar-URI:
Phrase-Id:
S->C: MRCP/2.0 ... 543266 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
9.20. INTERPRET
The INTERPRET method from the client to the server takes as input an
Interpret-Text header field containing the text for which the
semantic interpretation is desired, and returns, via the
INTERPRETATION-COMPLETE event, an interpretation result that is very
similar to the one returned from a RECOGNIZE method invocation. Only
portions of the result relevant to acoustic matching are excluded
from the result. The Interpret-Text header field MUST be included in
the INTERPRET request.
Recognizer grammar data is treated in the same way as it is when
issuing a RECOGNIZE method call.
If a RECOGNIZE, RECORD, or another INTERPRET operation is already in
progress for the resource, the server MUST reject the request with a
response having a status-code of 402 "Method not valid in this
state", and a COMPLETE request state.
C->S: MRCP/2.0 ... INTERPRET 543266
Channel-Identifier:32AECB23433801@speechrecog
Interpret-Text:may I speak to Andre Roy
Burnett & Shanmugham Standards Track [Page 129]
RFC 6787 MRCPv2 November 2012
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
S->C: MRCP/2.0 ... 543266 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C: MRCP/2.0 ... INTERPRETATION-COMPLETE 543266 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
Content-Type:application/nlsml+xml
Content-Length:...
Andre Roy
Burnett & Shanmugham Standards Track [Page 130]
RFC 6787 MRCPv2 November 2012
9.21. INTERPRETATION-COMPLETE
This event from the recognizer resource to the client indicates that
the INTERPRET operation is complete. The interpretation result is
sent in the body of the MRCP message. The request state MUST be set
to COMPLETE.
The Completion-Cause header field MUST be included in this event and
MUST be set to an appropriate value from the list of cause codes.
C->S: MRCP/2.0 ... INTERPRET 543266
Channel-Identifier:32AECB23433801@speechrecog
Interpret-Text:may I speak to Andre Roy
Content-Type:application/srgs+xml
Content-ID:
Content-Length:...
- oui
- yes
may I speak to
- Michel Tremblay
- Andre Roy
S->C: MRCP/2.0 ... 543266 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speechrecog
S->C: MRCP/2.0 ... INTERPRETATION-COMPLETE 543266 200 COMPLETE
Channel-Identifier:32AECB23433801@speechrecog
Completion-Cause:000 success
Content-Type:application/nlsml+xml
Content-Length:...
Burnett & Shanmugham Standards Track [Page 131]
RFC 6787 MRCPv2 November 2012
Andre Roy
9.22. DTMF Detection
Digits received as DTMF tones are delivered to the recognition
resource in the MRCPv2 server in the RTP stream according to RFC 4733
[RFC4733]. The Automatic Speech Recognizer (ASR) MUST support RFC
4733 to recognize digits, and it MAY support recognizing DTMF tones
[Q.23] in the audio.
10. Recorder Resource
This resource captures received audio and video and stores it as
content pointed to by a URI. The main usages of recorders are
1. to capture speech audio that may be submitted for recognition at
a later time, and
2. recording voice or video mails.
Both these applications require functionality above and beyond those
specified by protocols such as RTSP [RFC2326]. This includes audio
endpointing (i.e., detecting speech or silence). The support for
video is OPTIONAL and is mainly capturing video mails that may
require the speech or audio processing mentioned above.
A recorder MUST provide endpointing capabilities for suppressing
silence at the beginning and end of a recording, and it MAY also
suppress silence in the middle of a recording. If such suppression
is done, the recorder MUST maintain timing metadata to indicate the
actual time stamps of the recorded media.
See the discussion on the sensitivity of saved waveforms in
Section 12.
Burnett & Shanmugham Standards Track [Page 132]
RFC 6787 MRCPv2 November 2012
10.1. Recorder State Machine
Idle Recording
State State
| |
|---------RECORD------->|
| |
|<------STOP------------|
| |
|<--RECORD-COMPLETE-----|
| |
| |--------|
| START-OF-INPUT |
| |------->|
| |
| |--------|
| START-INPUT-TIMERS |
| |------->|
| |
Recorder State Machine
10.2. Recorder Methods
The recorder resource supports the following methods.
recorder-method = "RECORD"
/ "STOP"
/ "START-INPUT-TIMERS"
10.3. Recorder Events
The recorder resource can generate the following events.
recorder-event = "START-OF-INPUT"
/ "RECORD-COMPLETE"
10.4. Recorder Header Fields
Method invocations for the recorder resource can contain resource-
specific header fields containing request options and information to
augment the Method, Response, or Event message it is associated with.
Burnett & Shanmugham Standards Track [Page 133]
RFC 6787 MRCPv2 November 2012
recorder-header = sensitivity-level
/ no-input-timeout
/ completion-cause
/ completion-reason
/ failed-uri
/ failed-uri-cause
/ record-uri
/ media-type
/ max-time
/ trim-length
/ final-silence
/ capture-on-speech
/ ver-buffer-utterance
/ start-input-timers
/ new-audio-channel
10.4.1. Sensitivity-Level
To filter out background noise and not mistake it for speech, the
recorder can support a variable level of sound sensitivity. The
Sensitivity-Level header field is a float value between 0.0 and 1.0
and allows the client to set the sensitivity level for the recorder.
This header field MAY occur in RECORD, SET-PARAMS, or GET-PARAMS. A
higher value for this header field means higher sensitivity. The
default value for this header field is implementation specific.
sensitivity-level = "Sensitivity-Level" ":" FLOAT CRLF
10.4.2. No-Input-Timeout
When recording is started and there is no speech detected for a
certain period of time, the recorder can send a RECORD-COMPLETE event
to the client and terminate the record operation. The No-Input-
Timeout header field can set this timeout value. The value is in
milliseconds. This header field MAY occur in RECORD, SET-PARAMS, or
GET-PARAMS. The value for this header field ranges from 0 to an
implementation-specific maximum value. The default value for this
header field is implementation specific.
no-input-timeout = "No-Input-Timeout" ":" 1*19DIGIT CRLF
10.4.3. Completion-Cause
This header field MUST be part of a RECORD-COMPLETE event from the
recorder resource to the client. This indicates the reason behind
the RECORD method completion. This header field MUST be sent in the
RECORD responses if they return with a failure status and a COMPLETE
state. In the ABNF below, the 'cause-code' contains a numerical
Burnett & Shanmugham Standards Track [Page 134]
RFC 6787 MRCPv2 November 2012
value selected from the Cause-Code column of the following table.
The 'cause-name' contains the corresponding token selected from the
Cause-Name column.
completion-cause = "Completion-Cause" ":" cause-code SP
cause-name CRLF
cause-code = 3DIGIT
cause-name = *VCHAR
+------------+-----------------------+------------------------------+
| Cause-Code | Cause-Name | Description |
+------------+-----------------------+------------------------------+
| 000 | success-silence | RECORD completed with a |
| | | silence at the end. |
| 001 | success-maxtime | RECORD completed after |
| | | reaching maximum recording |
| | | time specified in record |
| | | method. |
| 002 | no-input-timeout | RECORD failed due to no |
| | | input. |
| 003 | uri-failure | Failure accessing the record |
| | | URI. |
| 004 | error | RECORD request terminated |
| | | prematurely due to a |
| | | recorder error. |
+------------+-----------------------+------------------------------+
10.4.4. Completion-Reason
This header field MAY be present in a RECORD-COMPLETE event coming
from the recorder resource to the client. It contains the reason
text behind the RECORD request completion. This header field
communicates text describing the reason for the failure.
The completion reason text is provided for client use in logs and for
debugging and instrumentation purposes. Clients MUST NOT interpret
the completion reason text.
completion-reason = "Completion-Reason" ":"
quoted-string CRLF
10.4.5. Failed-URI
When a recorder method needs to post the audio to a URI and access to
the URI fails, the server MUST provide the failed URI in this header
field in the method response.
failed-uri = "Failed-URI" ":" absoluteURI CRLF
Burnett & Shanmugham Standards Track [Page 135]
RFC 6787 MRCPv2 November 2012
10.4.6. Failed-URI-Cause
When a recorder method needs to post the audio to a URI and access to
the URI fails, the server MAY provide the URI-specific or protocol-
specific response code through this header field in the method
response. The value encoding is UTF-8 (RFC 3629 [RFC3629]) to
accommodate any access protocol -- some access protocols might have a
response string instead of a numeric response code.
failed-uri-cause = "Failed-URI-Cause" ":" 1*UTFCHAR
CRLF
10.4.7. Record-URI
When a recorder method contains this header field, the server MUST
capture the audio and store it. If the header field is present but
specified with no value, the server MUST store the content locally
and generate a URI that points to it. This URI is then returned in
either the STOP response or the RECORD-COMPLETE event. If the header
field in the RECORD method specifies a URI, the server MUST attempt
to capture and store the audio at that location. If this header
field is not specified in the RECORD request, the server MUST capture
the audio, MUST encode it, and MUST send it in the STOP response or
the RECORD-COMPLETE event as a message body. In this case, the
response carrying the audio content MUST include a Content ID (cid)
[RFC2392] value in this header pointing to the Content-ID in the
message body.
The server MUST also return the size in octets and the duration in
milliseconds of the recorded audio waveform as parameters associated
with the header field.
Implementations MUST support 'http' [RFC2616], 'https' [RFC2818],
'file' [RFC3986], and 'cid' [RFC2392] schemes in the URI. Note that
implementations already exist that support other schemes.
record-uri = "Record-URI" ":" ["<" uri ">"
";" "size" "=" 1*19DIGIT
";" "duration" "=" 1*19DIGIT] CRLF
10.4.8. Media-Type
A RECORD method MUST contain this header field, which specifies to
the server the media type of the captured audio or video.
media-type = "Media-Type" ":" media-type-value
CRLF
Burnett & Shanmugham Standards Track [Page 136]
RFC 6787 MRCPv2 November 2012
10.4.9. Max-Time
When recording is started, this specifies the maximum length of the
recording in milliseconds, calculated from the time the actual
capture and store begins and is not necessarily the time the RECORD
method is received. It specifies the duration before silence
suppression, if any, has been applied by the recorder resource.
After this time, the recording stops and the server MUST return a
RECORD-COMPLETE event to the client having a request-state of
COMPLETE. This header field MAY occur in RECORD, SET-PARAMS, or GET-
PARAMS. The value for this header field ranges from 0 to an
implementation-specific maximum value. A value of 0 means infinity,
and hence the recording continues until one or more of the other stop
conditions are met. The default value for this header field is 0.
max-time = "Max-Time" ":" 1*19DIGIT CRLF
10.4.10. Trim-Length
This header field MAY be sent on a STOP method and specifies the
length of audio to be trimmed from the end of the recording after the
stop. The length is interpreted to be in milliseconds. The default
value for this header field is 0.
trim-length = "Trim-Length" ":" 1*19DIGIT CRLF
10.4.11. Final-Silence
When the recorder is started and the actual capture begins, this
header field specifies the length of silence in the audio that is to
be interpreted as the end of the recording. This header field MAY
occur in RECORD, SET-PARAMS, or GET-PARAMS. The value for this
header field ranges from 0 to an implementation-specific maximum
value and is interpreted to be in milliseconds. A value of 0 means
infinity, and hence the recording will continue until one of the
other stop conditions are met. The default value for this header
field is implementation specific.
final-silence = "Final-Silence" ":" 1*19DIGIT CRLF
10.4.12. Capture-On-Speech
If "false", the recorder MUST start capturing immediately when
started. If "true", the recorder MUST wait for the endpointing
functionality to detect speech before it starts capturing. This
header field MAY occur in the RECORD, SET-PARAMS, or GET-PARAMS. The
value for this header field is a Boolean. The default value for this
header field is "false".
Burnett & Shanmugham Standards Track [Page 137]
RFC 6787 MRCPv2 November 2012
capture-on-speech = "Capture-On-Speech " ":" BOOLEAN CRLF
10.4.13. Ver-Buffer-Utterance
This header field is the same as the one described for the verifier
resource (see Section 11.4.14). This tells the server to buffer the
utterance associated with this recording request into the
verification buffer. Sending this header field is permitted only if
the verification buffer is for the session. This buffer is shared
across resources within a session. It gets instantiated when a
verifier resource is added to this session and is released when the
verifier resource is released from the session.
10.4.14. Start-Input-Timers
This header field MAY be sent as part of the RECORD request. A value
of "false" tells the recorder resource to start the operation, but
not to start the no-input timer until the client sends a START-INPUT-
TIMERS request to the recorder resource. This is useful in the
scenario when the recorder and synthesizer resources are not part of
the same session. When a kill-on-barge-in prompt is being played,
the client may want the RECORD request to be simultaneously active so
that it can detect and implement kill-on-barge-in (see
Section 8.4.2). But at the same time, the client doesn't want the
recorder resource to start the no-input timers until the prompt is
finished. The default value is "true".
start-input-timers = "Start-Input-Timers" ":"
BOOLEAN CRLF
10.4.15. New-Audio-Channel
This header field is the same as the one described for the recognizer
resource (see Section 9.4.23).
10.5. Recorder Message Body
If the RECORD request did not have a Record-URI header field, the
STOP response or the RECORD-COMPLETE event MUST contain a message
body carrying the captured audio. In this case, the message carrying
the audio content has a Record-URI header field with a Content ID
value pointing to the message body entity that contains the recorded
audio. See Section 10.4.7 for details.
Burnett & Shanmugham Standards Track [Page 138]
RFC 6787 MRCPv2 November 2012
10.6. RECORD
The RECORD request places the recorder resource in the recording
state. Depending on the header fields specified in the RECORD
method, the resource may start recording the audio immediately or
wait for the endpointing functionality to detect speech in the audio.
The audio is then made available to the client either in the message
body or as specified by Record-URI.
The server MUST support the 'https' URI scheme and MAY support other
schemes. Note that, due to the sensitive nature of voice recordings,
any protocols used for dereferencing SHOULD employ integrity and
confidentiality, unless other means, such as use of a controlled
environment (see Section 4.2), are employed.
If a RECORD operation is already in progress, invoking this method
causes the server to issue a response having a status-code of 402
"Method not valid in this state" and a request-state of COMPLETE.
If the Record-URI is not valid, a status-code of 404 "Illegal Value
for Header Field" is returned in the response. If it is impossible
for the server to create the requested stored content, a status-code
of 407 "Method or Operation Failed" is returned.
If the type specified in the Media-Type header field is not
supported, the server MUST respond with a status-code of 409
"Unsupported Header Field Value" with the Media-Type header field in
its response.
When the recording operation is initiated, the response indicates an
IN-PROGRESS request state. The server MAY generate a subsequent
START-OF-INPUT event when speech is detected. Upon completion of the
recording operation, the server generates a RECORD-COMPLETE event.
Burnett & Shanmugham Standards Track [Page 139]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... RECORD 543257
Channel-Identifier:32AECB23433802@recorder
Record-URI:
Media-Type:audio/wav
Capture-On-Speech:true
Final-Silence:300
Max-Time:6000
S->C: MRCP/2.0 ... 543257 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@recorder
S->C: MRCP/2.0 ... START-OF-INPUT 543257 IN-PROGRESS
Channel-Identifier:32AECB23433802@recorder
S->C: MRCP/2.0 ... RECORD-COMPLETE 543257 COMPLETE
Channel-Identifier:32AECB23433802@recorder
Completion-Cause:000 success-silence
Record-URI:;
size=242552;duration=25645
RECORD Example
10.7. STOP
The STOP method moves the recorder from the recording state back to
the idle state. If a RECORD request is active and the STOP request
successfully terminates it, then the STOP response MUST contain an
Active-Request-Id-List header field containing the RECORD request-id
that was terminated. In this case, no RECORD-COMPLETE event is sent
for the terminated request. If there was no recording active, then
the response MUST NOT contain an Active-Request-Id-List header field.
If the recording was a success, the STOP response MUST contain a
Record-URI header field pointing to the recorded audio content or to
a typed entity in the body of the STOP response containing the
recorded audio. The STOP method MAY have a Trim-Length header field,
in which case the specified length of audio is trimmed from the end
of the recording after the stop. In any case, the response MUST
contain a status-code of 200 "Success".
Burnett & Shanmugham Standards Track [Page 140]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... RECORD 543257
Channel-Identifier:32AECB23433802@recorder
Record-URI:
Capture-On-Speech:true
Final-Silence:300
Max-Time:6000
S->C: MRCP/2.0 ... 543257 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@recorder
S->C: MRCP/2.0 ... START-OF-INPUT 543257 IN-PROGRESS
Channel-Identifier:32AECB23433802@recorder
C->S: MRCP/2.0 ... STOP 543257
Channel-Identifier:32AECB23433802@recorder
Trim-Length:200
S->C: MRCP/2.0 ... 543257 200 COMPLETE
Channel-Identifier:32AECB23433802@recorder
Record-URI:;
size=324253;duration=24561
Active-Request-Id-List:543257
STOP Example
10.8. RECORD-COMPLETE
If the recording completes due to no input, silence after speech, or
reaching the max-time, the server MUST generate the RECORD-COMPLETE
event to the client with a request-state of COMPLETE. If the
recording was a success, the RECORD-COMPLETE event contains a Record-
URI header field pointing to the recorded audio file on the server or
to a typed entity in the message body containing the recorded audio.
Burnett & Shanmugham Standards Track [Page 141]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... RECORD 543257
Channel-Identifier:32AECB23433802@recorder
Record-URI:
Capture-On-Speech:true
Final-Silence:300
Max-Time:6000
S->C: MRCP/2.0 ... 543257 200 IN-PROGRESS
Channel-Identifier:32AECB23433802@recorder
S->C: MRCP/2.0 ... START-OF-INPUT 543257 IN-PROGRESS
Channel-Identifier:32AECB23433802@recorder
S->C: MRCP/2.0 ... RECORD-COMPLETE 543257 COMPLETE
Channel-Identifier:32AECB23433802@recorder
Completion-Cause:000 success
Record-URI:;
size=325325;duration=24652
RECORD-COMPLETE Example
10.9. START-INPUT-TIMERS
This request is sent from the client to the recorder resource when it
discovers that a kill-on-barge-in prompt has finished playing (see
Section 8.4.2). This is useful in the scenario when the recorder and
synthesizer resources are not in the same MRCPv2 session. When a
kill-on-barge-in prompt is being played, the client wants the RECORD
request to be simultaneously active so that it can detect and
implement kill-on-barge-in. But at the same time, the client doesn't
want the recorder resource to start the no-input timers until the
prompt is finished. The Start-Input-Timers header field in the
RECORD request allows the client to say if the timers should be
started or not. In the above case, the recorder resource does not
start the timers until the client sends a START-INPUT-TIMERS method
to the recorder.
10.10. START-OF-INPUT
The START-OF-INPUT event is returned from the server to the client
once the server has detected speech. This event is always returned
by the recorder resource when speech has been detected. The recorder
resource also MUST send a Proxy-Sync-Id header field with a unique
value for this event.
S->C: MRCP/2.0 ... START-OF-INPUT 543259 IN-PROGRESS
Channel-Identifier:32AECB23433801@recorder
Proxy-Sync-Id:987654321
Burnett & Shanmugham Standards Track [Page 142]
RFC 6787 MRCPv2 November 2012
11. Speaker Verification and Identification
This section describes the methods, responses and events employed by
MRCPv2 for doing speaker verification/identification.
Speaker verification is a voice authentication methodology that can
be used to identify the speaker in order to grant the user access to
sensitive information and transactions. Because speech is a
biometric, a number of essential security considerations related to
biometric authentication technologies apply to its implementation and
usage. Implementers should carefully read Section 12 in this
document and the corresponding section of the SPEECHSC requirements
[RFC4313]. Implementers and deployers of this technology are
strongly encouraged to check the state of the art for any new risks
and solutions that might have been developed.
In speaker verification, a recorded utterance is compared to a
previously stored voiceprint, which is in turn associated with a
claimed identity for that user. Verification typically consists of
two phases: a designation phase to establish the claimed identity of
the caller and an execution phase in which a voiceprint is either
created (training) or used to authenticate the claimed identity
(verification).
Speaker identification is the process of associating an unknown
speaker with a member in a population. It does not employ a claim of
identity. When an individual claims to belong to a group (e.g., one
of the owners of a joint bank account) a group authentication is
performed. This is generally implemented as a kind of verification
involving comparison with more than one voice model. It is sometimes
called 'multi-verification'. If the individual speaker can be
identified from the group, this may be useful for applications where
multiple users share the same access privileges to some data or
application. Speaker identification and group authentication are
also done in two phases, a designation phase and an execution phase.
Note that, from a functionality standpoint, identification can be
thought of as a special case of group authentication (if the
individual is identified) where the group is the entire population,
although the implementation of speaker identification may be
different from the way group authentication is performed. To
accommodate single-voiceprint verification, verification against
multiple voiceprints, group authentication, and identification, this
specification provides a single set of methods that can take a list
of identifiers, called "voiceprint identifiers", and return a list of
identifiers, with a score for each that represents how well the input
speech matched each identifier. The input and output lists of
identifiers do not have to match, allowing a vendor-specific group
identifier to be used as input to indicate that identification is to
Burnett & Shanmugham Standards Track [Page 143]
RFC 6787 MRCPv2 November 2012
be performed. In this specification, the terms "identification" and
"multi-verification" are used to indicate that the input represents a
group (potentially the entire population) and that results for
multiple voiceprints may be returned.
It is possible for a verifier resource to share the same session with
a recognizer resource or to operate independently. In order to share
the same session, the verifier and recognizer resources MUST be
allocated from within the same SIP dialog. Otherwise, an independent
verifier resource, running on the same physical server or a separate
one, will be set up. Note that, in addition to allowing both
resources to be allocated in the same INVITE, it is possible to
allocate one initially and the other later via a re-INVITE.
Some of the speaker verification methods, described below, apply only
to a specific mode of operation.
The verifier resource has a verification buffer associated with it
(see Section 11.4.14). This allows the storage of speech utterances
for the purposes of verification, identification, or training from
the buffered speech. This buffer is owned by the verifier resource,
but other input resources (such as the recognizer resource or
recorder resource) may write to it. This allows the speech received
as part of a recognition or recording operation to be later used for
verification, identification, or training. Access to the buffer is
limited to one operation at time. Hence, when the resource is doing
read, write, or delete operations, such as a RECOGNIZE with
ver-buffer-utterance turned on, another operation involving the
buffer fails with a status-code of 402. The verification buffer can
be cleared by a CLEAR-BUFFER request from the client and is freed
when the verifier resource is deallocated or the session with the
server terminates.
The verification buffer is different from collecting waveforms and
processing them using either the real-time audio stream or stored
audio, because this buffering mechanism does not simply accumulate
speech to a buffer. The verification buffer MAY contain additional
information gathered by the recognizer resource that serves to
improve verification performance.
11.1. Speaker Verification State Machine
Speaker verification may operate in a training or a verification
session. Starting one of these sessions does not change the state of
the verifier resource, i.e., it remains idle. Once a verification or
training session is started, then utterances are trained or verified
by calling the VERIFY or VERIFY-FROM-BUFFER method. The state of the
Burnett & Shanmugham Standards Track [Page 144]
RFC 6787 MRCPv2 November 2012
verifier resources goes from IDLE to VERIFYING state each time VERIFY
or VERIFY-FROM-BUFFER is called.
Idle Session Opened Verifying/Training
State State State
| | |
|--START-SESSION--->| |
| | |
| |----------| |
| | START-SESSION |
| |<---------| |
| | |
|<--END-SESSION-----| |
| | |
| |---------VERIFY--------->|
| | |
| |---VERIFY-FROM-BUFFER--->|
| | |
| |----------| |
| | VERIFY-ROLLBACK |
| |<---------| |
| | |
| | |--------|
| | GET-INTERMEDIATE-RESULT |
| | |------->|
| | |
| | |--------|
| | START-INPUT-TIMERS |
| | |------->|
| | |
| | |--------|
| | START-OF-INPUT |
| | |------->|
| | |
| |<-VERIFICATION-COMPLETE--|
| | |
| |<--------STOP------------|
| | |
| |----------| |
| | STOP |
| |<---------| |
| | |
|----------| | |
| STOP | |
|<---------| | |
| |----------| |
| | CLEAR-BUFFER |
| |<---------| |
Burnett & Shanmugham Standards Track [Page 145]
RFC 6787 MRCPv2 November 2012
| | |
|----------| | |
| CLEAR-BUFFER | |
|<---------| | |
| | |
| |----------| |
| | QUERY-VOICEPRINT |
| |<---------| |
| | |
|----------| | |
| QUERY-VOICEPRINT | |
|<---------| | |
| | |
| |----------| |
| | DELETE-VOICEPRINT |
| |<---------| |
| | |
|----------| | |
| DELETE-VOICEPRINT | |
|<---------| | |
Verifier Resource State Machine
11.2. Speaker Verification Methods
The verifier resource supports the following methods.
verifier-method = "START-SESSION"
/ "END-SESSION"
/ "QUERY-VOICEPRINT"
/ "DELETE-VOICEPRINT"
/ "VERIFY"
/ "VERIFY-FROM-BUFFER"
/ "VERIFY-ROLLBACK"
/ "STOP"
/ "CLEAR-BUFFER"
/ "START-INPUT-TIMERS"
/ "GET-INTERMEDIATE-RESULT"
These methods allow the client to control the mode and target of
verification or identification operations within the context of a
session. All the verification input operations that occur within a
session can be used to create, update, or validate against the
voiceprint specified during the session. At the beginning of each
session, the verifier resource is reset to the state it had prior to
any previous verification session.
Burnett & Shanmugham Standards Track [Page 146]
RFC 6787 MRCPv2 November 2012
Verification/identification operations can be executed against live
or buffered audio. The verifier resource provides methods for
collecting and evaluating live audio data, and methods for
controlling the verifier resource and adjusting its configured
behavior.
There are no dedicated methods for collecting buffered audio data.
This is accomplished by calling VERIFY, RECOGNIZE, or RECORD as
appropriate for the resource, with the header field
Ver-Buffer-Utterance. Then, when the following method is called,
verification is performed using the set of buffered audio.
1. VERIFY-FROM-BUFFER
The following methods are used for verification of live audio
utterances:
1. VERIFY
2. START-INPUT-TIMERS
The following methods are used for configuring the verifier resource
and for establishing resource states:
1. START-SESSION
2. END-SESSION
3. QUERY-VOICEPRINT
4. DELETE-VOICEPRINT
5. VERIFY-ROLLBACK
6. STOP
7. CLEAR-BUFFER
The following method allows the polling of a verification in progress
for intermediate results.
1. GET-INTERMEDIATE-RESULT
11.3. Verification Events
The verifier resource generates the following events.
Burnett & Shanmugham Standards Track [Page 147]
RFC 6787 MRCPv2 November 2012
verifier-event = "VERIFICATION-COMPLETE"
/ "START-OF-INPUT"
11.4. Verification Header Fields
A verifier resource message can contain header fields containing
request options and information to augment the Request, Response, or
Event message it is associated with.
verification-header = repository-uri
/ voiceprint-identifier
/ verification-mode
/ adapt-model
/ abort-model
/ min-verification-score
/ num-min-verification-phrases
/ num-max-verification-phrases
/ no-input-timeout
/ save-waveform
/ media-type
/ waveform-uri
/ voiceprint-exists
/ ver-buffer-utterance
/ input-waveform-uri
/ completion-cause
/ completion-reason
/ speech-complete-timeout
/ new-audio-channel
/ abort-verification
/ start-input-timers
11.4.1. Repository-URI
This header field specifies the voiceprint repository to be used or
referenced during speaker verification or identification operations.
This header field is required in the START-SESSION, QUERY-VOICEPRINT,
and DELETE-VOICEPRINT methods.
repository-uri = "Repository-URI" ":" uri CRLF
11.4.2. Voiceprint-Identifier
This header field specifies the claimed identity for verification
applications. The claimed identity MAY be used to specify an
existing voiceprint or to establish a new voiceprint. This header
field MUST be present in the QUERY-VOICEPRINT and DELETE-VOICEPRINT
methods. The Voiceprint-Identifier MUST be present in the START-
SESSION method for verification operations. For identification or
Burnett & Shanmugham Standards Track [Page 148]
RFC 6787 MRCPv2 November 2012
multi-verification operations, this header field MAY contain a list
of voiceprint identifiers separated by semicolons. For
identification operations, the client MAY also specify a voiceprint
group identifier instead of a list of voiceprint identifiers.
voiceprint-identifier = "Voiceprint-Identifier" ":"
vid *[";" vid] CRLF
vid = 1*VCHAR ["." 1*VCHAR]
11.4.3. Verification-Mode
This header field specifies the mode of the verifier resource and is
set by the START-SESSION method. Acceptable values indicate whether
the verification session will train a voiceprint ("train") or verify/
identify using an existing voiceprint ("verify").
Training and verification sessions both require the voiceprint
Repository-URI to be specified in the START-SESSION. In many usage
scenarios, however, the system does not know the speaker's claimed
identity until a recognition operation has, for example, recognized
an account number to which the user desires access. In order to
allow the first few utterances of a dialog to be both recognized and
verified, the verifier resource on the MRCPv2 server retains a
buffer. In this buffer, the MRCPv2 server accumulates recognized
utterances. The client can later execute a verification method and
apply the buffered utterances to the current verification session.
Some voice user interfaces may require additional user input that
should not be subject to verification. For example, the user's input
may have been recognized with low confidence and thus require a
confirmation cycle. In such cases, the client SHOULD NOT execute the
VERIFY or VERIFY-FROM-BUFFER methods to collect and analyze the
caller's input. A separate recognizer resource can analyze the
caller's response without any participation by the verifier resource.
Once the following conditions have been met:
1. the voiceprint identity has been successfully established through
the Voiceprint-Identifier header fields of the START-SESSION
method, and
2. the verification mode has been set to one of "train" or "verify",
the verifier resource can begin providing verification information
during verification operations. If the verifier resource does not
reach one of the two major states ("train" or "verify") , it MUST
report an error condition in the MRCPv2 status code to indicate why
the verifier resource is not ready for the corresponding usage.
Burnett & Shanmugham Standards Track [Page 149]
RFC 6787 MRCPv2 November 2012
The value of verification-mode is persistent within a verification
session. If the client attempts to change the mode during a
verification session, the verifier resource reports an error and the
mode retains its current value.
verification-mode = "Verification-Mode" ":"
verification-mode-string
verification-mode-string = "train"
/ "verify"
11.4.4. Adapt-Model
This header field indicates the desired behavior of the verifier
resource after a successful verification operation. If the value of
this header field is "true", the server SHOULD use audio collected
during the verification session to update the voiceprint to account
for ongoing changes in a speaker's incoming speech characteristics,
unless local policy prohibits updating the voiceprint. If the value
is "false" (the default), the server MUST NOT update the voiceprint.
This header field MAY occur in the START-SESSION method.
adapt-model = "Adapt-Model" ":" BOOLEAN CRLF
11.4.5. Abort-Model
The Abort-Model header field indicates the desired behavior of the
verifier resource upon session termination. If the value of this
header field is "true", the server MUST discard any pending changes
to a voiceprint due to verification training or verification
adaptation. If the value is "false" (the default), the server MUST
commit any pending changes for a training session or a successful
verification session to the voiceprint repository. A value of "true"
for Abort-Model overrides a value of "true" for the Adapt-Model
header field. This header field MAY occur in the END-SESSION method.
abort-model = "Abort-Model" ":" BOOLEAN CRLF
11.4.6. Min-Verification-Score
The Min-Verification-Score header field, when used with a verifier
resource through a SET-PARAMS, GET-PARAMS, or START-SESSION method,
determines the minimum verification score for which a verification
decision of "accepted" may be declared by the server. This is a
float value between -1.0 and 1.0. The default value for this header
field is implementation specific.
Burnett & Shanmugham Standards Track [Page 150]
RFC 6787 MRCPv2 November 2012
min-verification-score = "Min-Verification-Score" ":"
[ %x2D ] FLOAT CRLF
11.4.7. Num-Min-Verification-Phrases
The Num-Min-Verification-Phrases header field is used to specify the
minimum number of valid utterances before a positive decision is
given for verification. The value for this header field is an
integer and the default value is 1. The verifier resource MUST NOT
declare a verification 'accepted' unless Num-Min-Verification-Phrases
valid utterances have been received. The minimum value is 1. This
header field MAY occur in START-SESSION, SET-PARAMS, or GET-PARAMS.
num-min-verification-phrases = "Num-Min-Verification-Phrases" ":"
1*19DIGIT CRLF
11.4.8. Num-Max-Verification-Phrases
The Num-Max-Verification-Phrases header field is used to specify the
number of valid utterances required before a decision is forced for
verification. The verifier resource MUST NOT return a decision of
'undecided' once Num-Max-Verification-Phrases have been collected and
used to determine a verification score. The value for this header
field is an integer and the minimum value is 1. The default value is
implementation specific. This header field MAY occur in START-
SESSION, SET-PARAMS, or GET-PARAMS.
num-max-verification-phrases = "Num-Max-Verification-Phrases" ":"
1*19DIGIT CRLF
11.4.9. No-Input-Timeout
The No-Input-Timeout header field sets the length of time from the
start of the verification timers (see START-INPUT-TIMERS) until the
VERIFICATION-COMPLETE server event message declares that no input has
been received (i.e., has a Completion-Cause of no-input-timeout).
The value is in milliseconds. This header field MAY occur in VERIFY,
SET-PARAMS, or GET-PARAMS. The value for this header field ranges
from 0 to an implementation-specific maximum value. The default
value for this header field is implementation specific.
no-input-timeout = "No-Input-Timeout" ":" 1*19DIGIT CRLF
11.4.10. Save-Waveform
This header field allows the client to request that the verifier
resource save the audio stream that was used for verification/
identification. The verifier resource MUST attempt to record the
Burnett & Shanmugham Standards Track [Page 151]
RFC 6787 MRCPv2 November 2012
audio and make it available to the client in the form of a URI
returned in the Waveform-URI header field in the VERIFICATION-
COMPLETE event. If there was an error in recording the stream, or
the audio content is otherwise not available, the verifier resource
MUST return an empty Waveform-URI header field. The default value
for this header field is "false". This header field MAY appear in
the VERIFY method. Note that this header field does not appear in
the VERIFY-FROM-BUFFER method since it only controls whether or not
to save the waveform for live verification/identification operations.
save-waveform = "Save-Waveform" ":" BOOLEAN CRLF
11.4.11. Media-Type
This header field MAY be specified in the SET-PARAMS, GET-PARAMS, or
the VERIFY methods and tells the server resource the media type of
the captured audio or video such as the one captured and returned by
the Waveform-URI header field.
media-type = "Media-Type" ":" media-type-value
CRLF
11.4.12. Waveform-URI
If the Save-Waveform header field is set to "true", the verifier
resource MUST attempt to record the incoming audio stream of the
verification into a file and provide a URI for the client to access
it. This header field MUST be present in the VERIFICATION-COMPLETE
event if the Save-Waveform header field was set to true by the
client. The value of the header field MUST be empty if there was
some error condition preventing the server from recording.
Otherwise, the URI generated by the server MUST be globally unique
across the server and all its verification sessions. The content
MUST be available via the URI until the verification session ends.
Since the Save-Waveform header field applies only to live
verification/identification operations, the server can return the
Waveform-URI only in the VERIFICATION-COMPLETE event for live
verification/identification operations.
The server MUST also return the size in octets and the duration in
milliseconds of the recorded audio waveform as parameters associated
with the header field.
waveform-uri = "Waveform-URI" ":" ["<" uri ">"
";" "size" "=" 1*19DIGIT
";" "duration" "=" 1*19DIGIT] CRLF
Burnett & Shanmugham Standards Track [Page 152]
RFC 6787 MRCPv2 November 2012
11.4.13. Voiceprint-Exists
This header field MUST be returned in QUERY-VOICEPRINT and DELETE-
VOICEPRINT responses. This is the status of the voiceprint specified
in the QUERY-VOICEPRINT method. For the DELETE-VOICEPRINT method,
this header field indicates the status of the voiceprint at the
moment the method execution started.
voiceprint-exists = "Voiceprint-Exists" ":" BOOLEAN CRLF
11.4.14. Ver-Buffer-Utterance
This header field is used to indicate that this utterance could be
later considered for speaker verification. This way, a client can
request the server to buffer utterances while doing regular
recognition or verification activities, and speaker verification can
later be requested on the buffered utterances. This header field is
optional in the RECOGNIZE, VERIFY, and RECORD methods. The default
value for this header field is "false".
ver-buffer-utterance = "Ver-Buffer-Utterance" ":" BOOLEAN
CRLF
11.4.15. Input-Waveform-URI
This header field specifies stored audio content that the client
requests the server to fetch and process according to the current
verification mode, either to train the voiceprint or verify a claimed
identity. This header field enables the client to implement the
buffering use case where the recognizer and verifier resources are in
different sessions and the verification buffer technique cannot be
used. It MAY be specified on the VERIFY request.
input-waveform-uri = "Input-Waveform-URI" ":" uri CRLF
11.4.16. Completion-Cause
This header field MUST be part of a VERIFICATION-COMPLETE event from
the verifier resource to the client. This indicates the cause of
VERIFY or VERIFY-FROM-BUFFER method completion. This header field
MUST be sent in the VERIFY, VERIFY-FROM-BUFFER, and QUERY-VOICEPRINT
responses, if they return with a failure status and a COMPLETE state.
In the ABNF below, the 'cause-code' contains a numerical value
selected from the Cause-Code column of the following table. The
'cause-name' contains the corresponding token selected from the
Cause-Name column.
Burnett & Shanmugham Standards Track [Page 153]
RFC 6787 MRCPv2 November 2012
completion-cause = "Completion-Cause" ":" cause-code SP
cause-name CRLF
cause-code = 3DIGIT
cause-name = *VCHAR
Burnett & Shanmugham Standards Track [Page 154]
RFC 6787 MRCPv2 November 2012
+------------+--------------------------+---------------------------+
| Cause-Code | Cause-Name | Description |
+------------+--------------------------+---------------------------+
| 000 | success | VERIFY or VERIFY-FROM- |
| | | BUFFER request completed |
| | | successfully. The verify |
| | | decision can be |
| | | "accepted", "rejected", |
| | | or "undecided". |
| 001 | error | VERIFY or VERIFY-FROM- |
| | | BUFFER request terminated |
| | | prematurely due to a |
| | | verifier resource or |
| | | system error. |
| 002 | no-input-timeout | VERIFY request completed |
| | | with no result due to a |
| | | no-input-timeout. |
| 003 | too-much-speech-timeout | VERIFY request completed |
| | | with no result due to too |
| | | much speech. |
| 004 | speech-too-early | VERIFY request completed |
| | | with no result due to |
| | | speech too soon. |
| 005 | buffer-empty | VERIFY-FROM-BUFFER |
| | | request completed with no |
| | | result due to empty |
| | | buffer. |
| 006 | out-of-sequence | Verification operation |
| | | failed due to out-of- |
| | | sequence method |
| | | invocations, for example, |
| | | calling VERIFY before |
| | | QUERY-VOICEPRINT. |
| 007 | repository-uri-failure | Failure accessing |
| | | Repository URI. |
| 008 | repository-uri-missing | Repository-URI is not |
| | | specified. |
| 009 | voiceprint-id-missing | Voiceprint-Identifier is |
| | | not specified. |
| 010 | voiceprint-id-not-exist | Voiceprint-Identifier |
| | | does not exist in the |
| | | voiceprint repository. |
| 011 | speech-not-usable | VERIFY request completed |
| | | with no result because |
| | | the speech was not usable |
| | | (too noisy, too short, |
| | | etc.) |
+------------+--------------------------+---------------------------+
Burnett & Shanmugham Standards Track [Page 155]
RFC 6787 MRCPv2 November 2012
11.4.17. Completion-Reason
This header field MAY be specified in a VERIFICATION-COMPLETE event
coming from the verifier resource to the client. It contains the
reason text behind the VERIFY request completion. This header field
communicates text describing the reason for the failure.
The completion reason text is provided for client use in logs and for
debugging and instrumentation purposes. Clients MUST NOT interpret
the completion reason text.
completion-reason = "Completion-Reason" ":"
quoted-string CRLF
11.4.18. Speech-Complete-Timeout
This header field is the same as the one described for the Recognizer
resource. See Section 9.4.15. This header field MAY occur in
VERIFY, SET-PARAMS, or GET-PARAMS.
11.4.19. New-Audio-Channel
This header field is the same as the one described for the Recognizer
resource. See Section 9.4.23. This header field MAY be specified in
a VERIFY request.
11.4.20. Abort-Verification
This header field MUST be sent in a STOP request to indicate whether
or not to abort a VERIFY method in progress. A value of "true"
requests the server to discard the results. A value of "false"
requests the server to return in the STOP response the verification
results obtained up to the point it received the STOP request.
abort-verification = "Abort-Verification " ":" BOOLEAN CRLF
11.4.21. Start-Input-Timers
This header field MAY be sent as part of a VERIFY request. A value
of "false" tells the verifier resource to start the VERIFY operation
but not to start the no-input timer yet. The verifier resource MUST
NOT start the timers until the client sends a START-INPUT-TIMERS
request to the resource. This is useful in the scenario when the
verifier and synthesizer resources are not part of the same session.
In this scenario, when a kill-on-barge-in prompt is being played, the
client may want the VERIFY request to be simultaneously active so
that it can detect and implement kill-on-barge-in (see
Section 8.4.2). But at the same time, the client doesn't want the
Burnett & Shanmugham Standards Track [Page 156]
RFC 6787 MRCPv2 November 2012
verifier resource to start the no-input timers until the prompt is
finished. The default value is "true".
start-input-timers = "Start-Input-Timers" ":"
BOOLEAN CRLF
11.5. Verification Message Body
A verification response or event message can carry additional data as
described in the following subsection.
11.5.1. Verification Result Data
Verification results are returned to the client in the message body
of the VERIFICATION-COMPLETE event or the GET-INTERMEDIATE-RESULT
response message as described in Section 6.3. Element and attribute
descriptions for the verification portion of the NLSML format are
provided in Section 11.5.2 with a normative definition of the schema
in Section 16.3.
11.5.2. Verification Result Elements
All verification elements are contained within a single
element under . The elements are
described below and have the schema defined in Section 16.2. The
following elements are defined:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
Burnett & Shanmugham Standards Track [Page 157]
RFC 6787 MRCPv2 November 2012
11.5.2.1. Element
This element in the verification results provides information on how
the speech data matched a single voiceprint. The result data
returned MAY have more than one such entity in the case of
identification or multi-verification. Each element and
the XML data within the element describe verification result
information for how well the speech data matched that particular
voiceprint. The list of element data are ordered
according to their cumulative verification match scores, with the
highest score first.
11.5.2.2. Element
Within each element there MUST be a element
with the cumulative scores of how well multiple utterances matched
the voiceprint.
11.5.2.3. Element
The first element MAY contain an element
with the incremental scores of how well the last utterance matched
the voiceprint.
11.5.2.4. Element
This element is found within the or
element within the verification results. Its value indicates the
verification decision. It can have the values of "accepted",
"rejected", or "undecided".
11.5.2.5. Element
This element MAY occur within either the or
elements within the first element. Its
value indicates the size in milliseconds, respectively, of the last
utterance or the cumulated set of utterances.
11.5.2.6. Element
This element is found within the or
element within the verification results. Its value indicates the
apparent type of device used by the caller as determined by the
verifier resource. It can have the values of "cellular-phone",
"electret-phone", "carbon-button-phone", or "unknown".
Burnett & Shanmugham Standards Track [Page 158]
RFC 6787 MRCPv2 November 2012
11.5.2.7. Element
This element is found within the or
element within the verification results. Its value indicates the
apparent gender of the speaker as determined by the verifier
resource. It can have the values of "male", "female", or "unknown".
11.5.2.8. Element
This element is found within the first element within
the verification results. When verification is trying to confirm the
voiceprint, this indicates if the voiceprint has been adapted as a
consequence of analyzing the source utterances. It is not returned
during verification training. The value can be "true" or "false".
11.5.2.9. Element
This element is found within the or
element within the verification results. Its value indicates the
score of the last utterance as determined by verification.
During verification, the higher the score, the more likely it is that
the speaker is the same one as the one who spoke the voiceprint
utterances. During training, the higher the score, the more likely
the speaker is to have spoken all of the analyzed utterances. The
value is a floating point between -1.0 and 1.0. If there are no such
utterances, the score is -1. Note that the verification score is not
a probability value.
11.5.2.10. Element
MRCPv2 servers MAY send verification results that contain
implementation-specific data that augment the information provided by
the MRCPv2-defined elements. Such data might be useful to clients
who have private knowledge of how to interpret these schema
extensions. Implementation-specific additions to the verification
results schema MUST belong to the vendor's own namespace. In the
result structure, either they MUST be indicated by a namespace prefix
declared within the result, or they MUST be children of an element
identified as belonging to the respective namespace.
The following example shows the results of three voiceprints. Note
that the first one has crossed the verification score threshold, and
the speaker has been accepted. The voiceprint was also adapted with
the most recent utterance.
Burnett & Shanmugham Standards Track [Page 159]
RFC 6787 MRCPv2 November 2012
true
500
cellular-phone
male
accepted
0.98514
10000
cellular-phone
male
accepted
0.96725
0.93410
0.74209
Verification Results Example 1
In this next example, the verifier has enough information to decide
to reject the speaker.
Burnett & Shanmugham Standards Track [Page 160]
RFC 6787 MRCPv2 November 2012
500
cellular-phone
male
0.88514
high
sadness
10000
cellular-phone
male
rejected
0.9345
Verification Results Example 2
11.6. START-SESSION
The START-SESSION method starts a speaker verification or speaker
identification session. Execution of this method places the verifier
resource into its initial state. If this method is called during an
ongoing verification session, the previous session is implicitly
aborted. If this method is invoked when VERIFY or VERIFY-FROM-BUFFER
is active, the method fails and the server returns a status-code of
402.
Upon completion of the START-SESSION method, the verifier resource
MUST have terminated any ongoing verification session and cleared any
voiceprint designation.
A verification session is associated with the voiceprint repository
to be used during the session. This is specified through the
Repository-URI header field (see Section 11.4.1).
The START-SESSION method also establishes, through the Voiceprint-
Identifier header field, which voiceprints are to be matched or
trained during the verification session. If this is an
Burnett & Shanmugham Standards Track [Page 161]
RFC 6787 MRCPv2 November 2012
Identification session or if the client wants to do Multi-
Verification, the Voiceprint-Identifier header field contains a list
of semicolon-separated voiceprint identifiers.
The Adapt-Model header field MAY also be present in the START-SESSION
request to indicate whether or not to adapt a voiceprint based on
data collected during the session (if the voiceprint verification
phase succeeds). By default, the voiceprint model MUST NOT be
adapted with data from a verification session.
The START-SESSION also determines whether the session is for a train
or verify of a voiceprint. Hence, the Verification-Mode header field
MUST be sent in every START-SESSION request. The value of the
Verification-Mode header field MUST be one of either "train" or
"verify".
Before a verification/identification session is started, the client
may only request that VERIFY-ROLLBACK and generic SET-PARAMS and
GET-PARAMS operations be performed on the verifier resource. The
server MUST return status-code 402 "Method not valid in this state"
for all other verification operations.
A verifier resource MUST NOT have more than a single session active
at one time.
C->S: MRCP/2.0 ... START-SESSION 314161
Channel-Identifier:32AECB23433801@speakverify
Repository-URI:http://www.example.com/voiceprintdbase/
Voiceprint-Mode:verify
Voiceprint-Identifier:johnsmith.voiceprint
Adapt-Model:true
S->C: MRCP/2.0 ... 314161 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
11.7. END-SESSION
The END-SESSION method terminates an ongoing verification session and
releases the verification voiceprint resources. The session may
terminate in one of three ways:
1. abort - the voiceprint adaptation or creation may be aborted so
that the voiceprint remains unchanged (or is not created).
2. commit - when terminating a voiceprint training session, the new
voiceprint is committed to the repository.
Burnett & Shanmugham Standards Track [Page 162]
RFC 6787 MRCPv2 November 2012
3. adapt - an existing voiceprint is modified using a successful
verification.
The Abort-Model header field MAY be included in the END-SESSION to
control whether or not to abort any pending changes to the
voiceprint. The default behavior is to commit (not abort) any
pending changes to the designated voiceprint.
The END-SESSION method may be safely executed multiple times without
first executing the START-SESSION method. Any additional executions
of this method without an intervening use of the START-SESSION method
have no effect on the verifier resource.
The following example assumes there is either a training session or a
verification session in progress.
C->S: MRCP/2.0 ... END-SESSION 314174
Channel-Identifier:32AECB23433801@speakverify
Abort-Model:true
S->C: MRCP/2.0 ... 314174 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
11.8. QUERY-VOICEPRINT
The QUERY-VOICEPRINT method is used to get status information on a
particular voiceprint and can be used by the client to ascertain if a
voiceprint or repository exists and if it contains trained
voiceprints.
The response to the QUERY-VOICEPRINT request contains an indication
of the status of the designated voiceprint in the Voiceprint-Exists
header field, allowing the client to determine whether to use the
current voiceprint for verification, train a new voiceprint, or
choose a different voiceprint.
A voiceprint is completely specified by providing a repository
location and a voiceprint identifier. The particular voiceprint or
identity within the repository is specified by a string identifier
that is unique within the repository. The Voiceprint-Identifier
header field carries this unique voiceprint identifier within a given
repository.
The following example assumes a verification session is in progress
and the voiceprint exists in the voiceprint repository.
Burnett & Shanmugham Standards Track [Page 163]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... QUERY-VOICEPRINT 314168
Channel-Identifier:32AECB23433801@speakverify
Repository-URI:http://www.example.com/voiceprints/
Voiceprint-Identifier:johnsmith.voiceprint
S->C: MRCP/2.0 ... 314168 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
Repository-URI:http://www.example.com/voiceprints/
Voiceprint-Identifier:johnsmith.voiceprint
Voiceprint-Exists:true
The following example assumes that the URI provided in the
Repository-URI header field is a bad URI.
C->S: MRCP/2.0 ... QUERY-VOICEPRINT 314168
Channel-Identifier:32AECB23433801@speakverify
Repository-URI:http://www.example.com/bad-uri/
Voiceprint-Identifier:johnsmith.voiceprint
S->C: MRCP/2.0 ... 314168 405 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
Repository-URI:http://www.example.com/bad-uri/
Voiceprint-Identifier:johnsmith.voiceprint
Completion-Cause:007 repository-uri-failure
11.9. DELETE-VOICEPRINT
The DELETE-VOICEPRINT method removes a voiceprint from a repository.
This method MUST carry the Repository-URI and Voiceprint-Identifier
header fields.
An MRCPv2 server MUST reject a DELETE-VOICEPRINT request with a 401
status code unless the MRCPv2 client has been authenticated and
authorized. Note that MRCPv2 does not have a standard mechanism for
this. See Section 12.8.
If the corresponding voiceprint does not exist, the DELETE-VOICEPRINT
method MUST return a 200 status code.
The following example demonstrates a DELETE-VOICEPRINT operation to
remove a specific voiceprint.
Burnett & Shanmugham Standards Track [Page 164]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... DELETE-VOICEPRINT 314168
Channel-Identifier:32AECB23433801@speakverify
Repository-URI:http://www.example.com/bad-uri/
Voiceprint-Identifier:johnsmith.voiceprint
S->C: MRCP/2.0 ... 314168 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
11.10. VERIFY
The VERIFY method is used to request that the verifier resource
either train/adapt the voiceprint or verify/identify a claimed
identity. If the voiceprint is new or was deleted by a previous
DELETE-VOICEPRINT method, the VERIFY method trains the voiceprint.
If the voiceprint already exists, it is adapted and not retrained by
the VERIFY command.
C->S: MRCP/2.0 ... VERIFY 543260
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 543260 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speakverify
When the VERIFY request completes, the MRCPv2 server MUST send a
VERIFICATION-COMPLETE event to the client.
11.11. VERIFY-FROM-BUFFER
The VERIFY-FROM-BUFFER method directs the verifier resource to verify
buffered audio against a voiceprint. Only one VERIFY or VERIFY-FROM-
BUFFER method may be active for a verifier resource at a time.
The buffered audio is not consumed by this method and thus VERIFY-
FROM-BUFFER may be invoked multiple times by the client to attempt
verification against different voiceprints.
For the VERIFY-FROM-BUFFER method, the server MAY optionally return
an IN-PROGRESS response before the VERIFICATION-COMPLETE event.
When the VERIFY-FROM-BUFFER method is invoked and the verification
buffer is in use by another resource sharing it, the server MUST
return an IN-PROGRESS response and wait until the buffer is available
to it. The verification buffer is owned by the verifier resource but
is shared with write access from other input resources on the same
session. Hence, it is considered to be in use if there is a read or
write operation such as a RECORD or RECOGNIZE with the
Ver-Buffer-Utterance header field set to "true" on a resource that
shares this buffer. Note that if a RECORD or RECOGNIZE method
Burnett & Shanmugham Standards Track [Page 165]
RFC 6787 MRCPv2 November 2012
returns with a failure cause code, the VERIFY-FROM-BUFFER request
waiting to process that buffer MUST also fail with a Completion-Cause
of 005 (buffer-empty).
The following example illustrates the usage of some buffering
methods. In this scenario, the client first performed a live
verification, but the utterance had been rejected. In the meantime,
the utterance is also saved to the audio buffer. Then, another
voiceprint is used to do verification against the audio buffer and
the utterance is accepted. For the example, we assume both
Num-Min-Verification-Phrases and Num-Max-Verification-Phrases are 1.
C->S: MRCP/2.0 ... START-SESSION 314161
Channel-Identifier:32AECB23433801@speakverify
Verification-Mode:verify
Adapt-Model:true
Repository-URI:http://www.example.com/voiceprints
Voiceprint-Identifier:johnsmith.voiceprint
S->C: MRCP/2.0 ... 314161 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
C->S: MRCP/2.0 ... VERIFY 314162
Channel-Identifier:32AECB23433801@speakverify
Ver-buffer-utterance:true
S->C: MRCP/2.0 ... 314162 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... VERIFICATION-COMPLETE 314162 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
Completion-Cause:000 success
Content-Type:application/nlsml+xml
Content-Length:...
500
cellular-phone
female
rejected
0.05465
Burnett & Shanmugham Standards Track [Page 166]
RFC 6787 MRCPv2 November 2012
500
cellular-phone
female
rejected
0.05465
C->S: MRCP/2.0 ... QUERY-VOICEPRINT 314163
Channel-Identifier:32AECB23433801@speakverify
Repository-URI:http://www.example.com/voiceprints/
Voiceprint-Identifier:johnsmith
S->C: MRCP/2.0 ... 314163 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
Repository-URI:http://www.example.com/voiceprints/
Voiceprint-Identifier:johnsmith.voiceprint
Voiceprint-Exists:true
C->S: MRCP/2.0 ... START-SESSION 314164
Channel-Identifier:32AECB23433801@speakverify
Verification-Mode:verify
Adapt-Model:true
Repository-URI:http://www.example.com/voiceprints
Voiceprint-Identifier:marysmith.voiceprint
S->C: MRCP/2.0 ... 314164 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
C->S: MRCP/2.0 ... VERIFY-FROM-BUFFER 314165
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 314165 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... VERIFICATION-COMPLETE 314165 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
Completion-Cause:000 success
Content-Type:application/nlsml+xml
Content-Length:...
Burnett & Shanmugham Standards Track [Page 167]
RFC 6787 MRCPv2 November 2012
1000
cellular-phone
female
accepted
0.98
1000
cellular-phone
female
accepted
0.98
C->S: MRCP/2.0 ... END-SESSION 314166
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 314166 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
VERIFY-FROM-BUFFER Example
11.12. VERIFY-ROLLBACK
The VERIFY-ROLLBACK method discards the last buffered utterance or
discards the last live utterances (when the mode is "train" or
"verify"). The client will likely want to invoke this method when
the user provides undesirable input such as non-speech noises, side-
speech, out-of-grammar utterances, commands, etc. Note that this
method does not provide a stack of rollback states. Executing
VERIFY-ROLLBACK twice in succession without an intervening
recognition operation has no effect on the second attempt.
C->S: MRCP/2.0 ... VERIFY-ROLLBACK 314165
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 314165 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
VERIFY-ROLLBACK Example
Burnett & Shanmugham Standards Track [Page 168]
RFC 6787 MRCPv2 November 2012
11.13. STOP
The STOP method from the client to the server tells the verifier
resource to stop the VERIFY or VERIFY-FROM-BUFFER request if one is
active. If such a request is active and the STOP request
successfully terminated it, then the response header section contains
an Active-Request-Id-List header field containing the request-id of
the VERIFY or VERIFY-FROM-BUFFER request that was terminated. In
this case, no VERIFICATION-COMPLETE event is sent for the terminated
request. If there was no verify request active, then the response
MUST NOT contain an Active-Request-Id-List header field. Either way,
the response MUST contain a status-code of 200 "Success".
The STOP method can carry an Abort-Verification header field, which
specifies if the verification result until that point should be
discarded or returned. If this header field is not present or if the
value is "true", the verification result is discarded and the STOP
response does not contain any result data. If the header field is
present and its value is "false", the STOP response MUST contain a
Completion-Cause header field and carry the Verification result data
in its body.
An aborted VERIFY request does an automatic rollback and hence does
not affect the cumulative score. A VERIFY request that was stopped
with no Abort-Verification header field or with the Abort-
Verification header field set to "false" does affect cumulative
scores and would need to be explicitly rolled back if the client does
not want the verification result considered in the cumulative scores.
The following example assumes a voiceprint identity has already been
established.
C->S: MRCP/2.0 ... VERIFY 314177
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 314177 200 IN-PROGRESS
Channel-Identifier:32AECB23433801@speakverify
C->S: MRCP/2.0 ... STOP 314178
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 314178 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
Active-Request-Id-List:314177
STOP Verification Example
Burnett & Shanmugham Standards Track [Page 169]
RFC 6787 MRCPv2 November 2012
11.14. START-INPUT-TIMERS
This request is sent from the client to the verifier resource to
start the no-input timer, usually once the client has ascertained
that any audio prompts to the user have played to completion.
C->S: MRCP/2.0 ... START-INPUT-TIMERS 543260
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 543260 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
11.15. VERIFICATION-COMPLETE
The VERIFICATION-COMPLETE event follows a call to VERIFY or VERIFY-
FROM-BUFFER and is used to communicate the verification results to
the client. The event message body contains only verification
results.
S->C: MRCP/2.0 ... VERIFICATION-COMPLETE 543259 COMPLETE
Completion-Cause:000 success
Content-Type:application/nlsml+xml
Content-Length:...
500
cellular-phone
male
accepted
0.85
1500
cellular-phone
male
accepted
0.75
Burnett & Shanmugham Standards Track [Page 170]
RFC 6787 MRCPv2 November 2012
11.16. START-OF-INPUT
The START-OF-INPUT event is returned from the server to the client
once the server has detected speech. This event is always returned
by the verifier resource when speech has been detected, irrespective
of whether or not the recognizer and verifier resources share the
same session.
S->C: MRCP/2.0 ... START-OF-INPUT 543259 IN-PROGRESS
Channel-Identifier:32AECB23433801@speakverify
11.17. CLEAR-BUFFER
The CLEAR-BUFFER method can be used to clear the verification buffer.
This buffer is used to buffer speech during recognition, record, or
verification operations that may later be used by VERIFY-FROM-BUFFER.
As noted before, the buffer associated with the verifier resource is
shared by other input resources like recognizers and recorders.
Hence, a CLEAR-BUFFER request fails if the verification buffer is in
use. This can happen when any one of the input resources that share
this buffer has an active read or write operation such as RECORD,
RECOGNIZE, or VERIFY with the Ver-Buffer-Utterance header field set
to "true".
C->S: MRCP/2.0 ... CLEAR-BUFFER 543260
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 543260 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
11.18. GET-INTERMEDIATE-RESULT
A client can use the GET-INTERMEDIATE-RESULT method to poll for
intermediate results of a verification request that is in progress.
Invoking this method does not change the state of the resource. The
verifier resource collects the accumulated verification results and
returns the information in the method response. The message body in
the response to a GET-INTERMEDIATE-RESULT REQUEST contains only
verification results. The method response MUST NOT contain a
Completion-Cause header field as the request is not yet complete. If
the resource does not have a verification in progress, the response
has a 402 failure status-code and no result in the body.
Burnett & Shanmugham Standards Track [Page 171]
RFC 6787 MRCPv2 November 2012
C->S: MRCP/2.0 ... GET-INTERMEDIATE-RESULT 543260
Channel-Identifier:32AECB23433801@speakverify
S->C: MRCP/2.0 ... 543260 200 COMPLETE
Channel-Identifier:32AECB23433801@speakverify
Content-Type:application/nlsml+xml
Content-Length:...
50
cellular-phone
female
undecided
0.85
150
cellular-phone
female
undecided
0.65
12. Security Considerations
MRCPv2 is designed to comply with the security-related requirements
documented in the SPEECHSC requirements [RFC4313]. Implementers and
users of MRCPv2 are strongly encouraged to read the Security
Considerations section of [RFC4313], because that document contains
discussion of a number of important security issues associated with
the utilization of speech as biometric authentication technology, and
on the threats against systems which store recorded speech, contain
large corpora of voiceprints, and send and receive sensitive
information based on voice input to a recognizer or speech output
from a synthesizer. Specific security measures employed by MRCPv2
are summarized in the following subsections. See the corresponding
sections of this specification for how the security-related machinery
is invoked by individual protocol operations.
Burnett & Shanmugham Standards Track [Page 172]
RFC 6787 MRCPv2 November 2012
12.1. Rendezvous and Session Establishment
MRCPv2 control sessions are established as media sessions described
by SDP within the context of a SIP dialog. In order to ensure secure
rendezvous between MRCPv2 clients and servers, the following are
required:
1. The SIP implementation in MRCPv2 clients and servers MUST support
SIP digest authentication [RFC3261] and SHOULD employ it.
2. The SIP implementation in MRCPv2 clients and servers MUST support
'sips' URIs and SHOULD employ 'sips' URIs; this includes that
clients and servers SHOULD set up TLS [RFC5246] connections.
3. If media stream cryptographic keying is done through SDP (e.g.
using [RFC4568]), the MRCPv2 clients and servers MUST employ the
'sips' URI.
4. When TLS is used for SIP, the client MUST verify the identity of
the server to which it connects, following the rules and
guidelines defined in [RFC5922].
12.2. Control Channel Protection
Sensitive data is carried over the MRCPv2 control channel. This
includes things like the output of speech recognition operations,
speaker verification results, input to text-to-speech conversion,
personally identifying grammars, etc. For this reason, MRCPv2
servers must be properly authenticated, and the control channel must
permit the use of both confidentiality and integrity for the data.
To ensure control channel protection, MRCPv2 clients and servers MUST
support TLS and SHOULD utilize it by default unless alternative
control channel protection is used. When TLS is used, the client
MUST verify the identity of the server to which it connects,
following the rules and guidelines defined in [RFC4572]. If there
are multiple TLS-protected channels between the client and the
server, the server MUST NOT send a response to the client over a
channel for which the TLS identities of the server or client differ
from the channel over which the server received the corresponding
request. Alternative control-channel protection MAY be used if
desired (e.g., Security Architecture for the Internet Protocol
(IPsec) [RFC4301]).
12.3. Media Session Protection
Sensitive data is also carried on media sessions terminating on
MRCPv2 servers (the other end of a media channel may or may not be on
the MRCPv2 client). This data includes the user's spoken utterances
Burnett & Shanmugham Standards Track [Page 173]
RFC 6787 MRCPv2 November 2012
and the output of text-to-speech operations. MRCPv2 servers MUST
support a security mechanism for protection of audio media sessions.
MRCPv2 clients that originate or consume audio similarly MUST support
a security mechanism for protection of the audio. One such mechanism
is the Secure Real-time Transport Protocol (SRTP) [RFC3711].
12.4. Indirect Content Access
MCRPv2 employs content indirection extensively. Content may be
fetched and/or stored based on URI addressing on systems other than
the MRCPv2 client or server. Not all of the stored content is
necessarily sensitive (e.g., XML schemas), but the majority generally
needs protection, and some indirect content, such as voice recordings
and voiceprints, is extremely sensitive and must always be protected.
MRCPv2 clients and servers MUST implement HTTPS for indirect content
access and SHOULD employ secure access for all sensitive indirect
content. Other secure URI schemes such as Secure FTP (FTPS)
[RFC4217] MAY also be used. See Section 6.2.15 for the header fields
used to transfer cookie information between the MRCPv2 client and
server if needed for authentication.
Access to URIs provided by servers introduces risks that need to be
considered. Although RFC 6454 [RFC6454] discusses and focuses on a
same-origin policy, which MRCPv2 does not restrict URIs to, it still
provides an excellent description of the pitfalls of blindly
following server-provided URIs in Section 3 of the RFC. Servers also
need to be aware that clients could provide URIs to sites designed to
tie up the server in long or otherwise problematic document fetches.
MRCPv2 servers, and the services they access, MUST always be prepared
for the possibility of such a denial-of-service attack.
MRCPv2 makes no inherent assumptions about the lifetime and access
controls associated with a URI. For example, if neither
authentication nor scheme-specific access controls are used, a leak
of the URI is equivalent to a leak of the content. Moreover, MRCPv2
makes no specific demands on the lifetime of a URI. If a server
offers a URI and the client takes a long, long time to access that
URI, the server may have removed the resource in the interim time
period. MRCPv2 deals with this case by using the URI access scheme's
'resource not found' error, such as 404 for HTTPS. How long a server
should keep a dynamic resource available is highly application and
context dependent. However, the server SHOULD keep the resource
available for a reasonable amount of time to make it likely the
client will have the resource available when the client needs the
resource. Conversely, to mitigate state exhaustion attacks, MRCPv2
servers are not obligated to keep resources and resource state in
perpetuity. The server SHOULD delete dynamically generated resources
associated with an MRCPv2 session when the session ends.
Burnett & Shanmugham Standards Track [Page 174]
RFC 6787 MRCPv2 November 2012
One method to avoid resource leakage is for the server to use
difficult-to-guess, one-time resource URIs. In this instance, there
can be only a single access to the underlying resource using the
given URI. A downside to this approach is if an attacker uses the
URI before the client uses the URI, then the client is denied the
resource. Other methods would be to adopt a mechanism similar to the
URLAUTH IMAP extension [RFC4467], where the server sets cryptographic
checks on URI usage, as well as capabilities for expiration,
revocation, and so on. Specifying such a mechanism is beyond the
scope of this document.
12.5. Protection of Stored Media
MRCPv2 applications often require the use of stored media. Voice
recordings are both stored (e.g., for diagnosis and system tuning),
and fetched (for replaying utterances into multiple MRCPv2
resources). Voiceprints are fundamental to the speaker
identification and verification functions. This data can be
extremely sensitive and can present substantial privacy and
impersonation risks if stolen. Systems employing MRCPv2 SHOULD be
deployed in ways that minimize these risks. The SPEECHSC
requirements RFC [RFC4313] contains a more extensive discussion of
these risks and ways they may be mitigated.
12.6. DTMF and Recognition Buffers
DTMF buffers and recognition buffers may grow large enough to exceed
the capabilities of a server, and the server MUST be prepared to
gracefully handle resource consumption. A server MAY respond with
the appropriate recognition incomplete if the server is in danger of
running out of resources.
12.7. Client-Set Server Parameters
In MRCPv2, there are some tasks, such as URI resource fetches, that
the server does on behalf of the client. To control this behavior,
MRCPv2 has a number of server parameters that a client can configure.
With one such parameter, Fetch-Timeout (Section 6.2.12), a malicious
client could set a very large value and then request the server to
fetch a non-existent document. It is RECOMMENDED that servers be
cautious about accepting long timeout values or abnormally large
values for other client-set parameters.
12.8. DELETE-VOICEPRINT and Authorization
Since this specification does not mandate a specific mechanism for
authentication and authorization when requesting DELETE-VOICEPRINT
(Section 11.9), there is a risk that an MRCPv2 server may not do such
Burnett & Shanmugham Standards Track [Page 175]
RFC 6787 MRCPv2 November 2012
a check for authentication and authorization. In practice, each
provider of voice biometric solutions does insist on its own
authentication and authorization mechanism, outside of this
specification, so this is not likely to be a major problem. If in
the future voice biometric providers standardize on such a mechanism,
then a future version of MRCP can mandate it.
13. IANA Considerations
13.1. New Registries
This section describes the name spaces (registries) for MRCPv2 that
IANA has created and now maintains. Assignment/registration policies
are described in RFC 5226 [RFC5226].
13.1.1. MRCPv2 Resource Types
IANA has created a new name space of "MRCPv2 Resource Types". All
maintenance within and additions to the contents of this name space
MUST be according to the "Standards Action" registration policy. The
initial contents of the registry, defined in Section 4.2, are given
below:
Resource type Resource description Reference
------------- -------------------- ---------
speechrecog Speech Recognizer [RFC6787]
dtmfrecog DTMF Recognizer [RFC6787]
speechsynth Speech Synthesizer [RFC6787]
basicsynth Basic Synthesizer [RFC6787]
speakverify Speaker Verifier [RFC6787]
recorder Speech Recorder [RFC6787]
13.1.2. MRCPv2 Methods and Events
IANA has created a new name space of "MRCPv2 Methods and Events".
All maintenance within and additions to the contents of this name
space MUST be according to the "Standards Action" registration
policy. The initial contents of the registry, defined by the
"method-name" and "event-name" BNF in Section 15 and explained in
Sections 5.2 and 5.5, are given below.
Burnett & Shanmugham Standards Track [Page 176]
RFC 6787 MRCPv2 November 2012
Name Resource type Method/Event Reference
---- ------------- ------------ ---------
SET-PARAMS Generic Method [RFC6787]
GET-PARAMS Generic Method [RFC6787]
SPEAK Synthesizer Method [RFC6787]
STOP Synthesizer Method [RFC6787]
PAUSE Synthesizer Method [RFC6787]
RESUME Synthesizer Method [RFC6787]
BARGE-IN-OCCURRED Synthesizer Method [RFC6787]
CONTROL Synthesizer Method [RFC6787]
DEFINE-LEXICON Synthesizer Method [RFC6787]
DEFINE-GRAMMAR Recognizer Method [RFC6787]
RECOGNIZE Recognizer Method [RFC6787]
INTERPRET Recognizer Method [RFC6787]
GET-RESULT Recognizer Method [RFC6787]
START-INPUT-TIMERS Recognizer Method [RFC6787]
STOP Recognizer Method [RFC6787]
START-PHRASE-ENROLLMENT Recognizer Method [RFC6787]
ENROLLMENT-ROLLBACK Recognizer Method [RFC6787]
END-PHRASE-ENROLLMENT Recognizer Method [RFC6787]
MODIFY-PHRASE Recognizer Method [RFC6787]
DELETE-PHRASE Recognizer Method [RFC6787]
RECORD Recorder Method [RFC6787]
STOP Recorder Method [RFC6787]
START-INPUT-TIMERS Recorder Method [RFC6787]
START-SESSION Verifier Method [RFC6787]
END-SESSION Verifier Method [RFC6787]
QUERY-VOICEPRINT Verifier Method [RFC6787]
DELETE-VOICEPRINT Verifier Method [RFC6787]
VERIFY Verifier Method [RFC6787]
VERIFY-FROM-BUFFER Verifier Method [RFC6787]
VERIFY-ROLLBACK Verifier Method [RFC6787]
STOP Verifier Method [RFC6787]
START-INPUT-TIMERS Verifier Method [RFC6787]
GET-INTERMEDIATE-RESULT Verifier Method [RFC6787]
SPEECH-MARKER Synthesizer Event [RFC6787]
SPEAK-COMPLETE Synthesizer Event [RFC6787]
START-OF-INPUT Recognizer Event [RFC6787]
RECOGNITION-COMPLETE Recognizer Event [RFC6787]
INTERPRETATION-COMPLETE Recognizer Event [RFC6787]
START-OF-INPUT Recorder Event [RFC6787]
RECORD-COMPLETE Recorder Event [RFC6787]
VERIFICATION-COMPLETE Verifier Event [RFC6787]
START-OF-INPUT Verifier Event [RFC6787]
Burnett & Shanmugham Standards Track [Page 177]
RFC 6787 MRCPv2 November 2012
13.1.3. MRCPv2 Header Fields
IANA has created a new name space of "MRCPv2 Header Fields". All
maintenance within and additions to the contents of this name space
MUST be according to the "Standards Action" registration policy. The
initial contents of the registry, defined by the "message-header" BNF
in Section 15 and explained in Section 5.1, are given below. Note
that the values permitted for the "Vendor-Specific-Parameters"
parameter are managed according to a different policy. See
Section 13.1.6.
Name Resource type Reference
---- ------------- ---------
Channel-Identifier Generic [RFC6787]
Accept Generic [RFC2616]
Active-Request-Id-List Generic [RFC6787]
Proxy-Sync-Id Generic [RFC6787]
Accept-Charset Generic [RFC2616]
Content-Type Generic [RFC6787]
Content-ID Generic
[RFC2392], [RFC2046], and [RFC5322]
Content-Base Generic [RFC6787]
Content-Encoding Generic [RFC6787]
Content-Location Generic [RFC6787]
Content-Length Generic [RFC6787]
Fetch-Timeout Generic [RFC6787]
Cache-Control Generic [RFC6787]
Logging-Tag Generic [RFC6787]
Set-Cookie Generic [RFC6787]
Vendor-Specific Generic [RFC6787]
Jump-Size Synthesizer [RFC6787]
Kill-On-Barge-In Synthesizer [RFC6787]
Speaker-Profile Synthesizer [RFC6787]
Completion-Cause Synthesizer [RFC6787]
Completion-Reason Synthesizer [RFC6787]
Voice-Parameter Synthesizer [RFC6787]
Prosody-Parameter Synthesizer [RFC6787]
Speech-Marker Synthesizer [RFC6787]
Speech-Language Synthesizer [RFC6787]
Fetch-Hint Synthesizer [RFC6787]
Audio-Fetch-Hint Synthesizer [RFC6787]
Failed-URI Synthesizer [RFC6787]
Failed-URI-Cause Synthesizer [RFC6787]
Speak-Restart Synthesizer [RFC6787]
Speak-Length Synthesizer [RFC6787]
Load-Lexicon Synthesizer [RFC6787]
Lexicon-Search-Order Synthesizer [RFC6787]
Confidence-Threshold Recognizer [RFC6787]
Burnett & Shanmugham Standards Track [Page 178]
RFC 6787 MRCPv2 November 2012
Sensitivity-Level Recognizer [RFC6787]
Speed-Vs-Accuracy Recognizer [RFC6787]
N-Best-List-Length Recognizer [RFC6787]
Input-Type Recognizer [RFC6787]
No-Input-Timeout Recognizer [RFC6787]
Recognition-Timeout Recognizer [RFC6787]
Waveform-URI Recognizer [RFC6787]
Input-Waveform-URI Recognizer [RFC6787]
Completion-Cause Recognizer [RFC6787]
Completion-Reason Recognizer [RFC6787]
Recognizer-Context-Block Recognizer [RFC6787]
Start-Input-Timers Recognizer [RFC6787]
Speech-Complete-Timeout Recognizer [RFC6787]
Speech-Incomplete-Timeout Recognizer [RFC6787]
Dtmf-Interdigit-Timeout Recognizer [RFC6787]
Dtmf-Term-Timeout Recognizer [RFC6787]
Dtmf-Term-Char Recognizer [RFC6787]
Failed-URI Recognizer [RFC6787]
Failed-URI-Cause Recognizer [RFC6787]
Save-Waveform Recognizer [RFC6787]
Media-Type Recognizer [RFC6787]
New-Audio-Channel Recognizer [RFC6787]
Speech-Language Recognizer [RFC6787]
Ver-Buffer-Utterance Recognizer [RFC6787]
Recognition-Mode Recognizer [RFC6787]
Cancel-If-Queue Recognizer [RFC6787]
Hotword-Max-Duration Recognizer [RFC6787]
Hotword-Min-Duration Recognizer [RFC6787]
Interpret-Text Recognizer [RFC6787]
Dtmf-Buffer-Time Recognizer [RFC6787]
Clear-Dtmf-Buffer Recognizer [RFC6787]
Early-No-Match Recognizer [RFC6787]
Num-Min-Consistent-Pronunciations Recognizer [RFC6787]
Consistency-Threshold Recognizer [RFC6787]
Clash-Threshold Recognizer [RFC6787]
Personal-Grammar-URI Recognizer [RFC6787]
Enroll-Utterance Recognizer [RFC6787]
Phrase-ID Recognizer [RFC6787]
Phrase-NL Recognizer [RFC6787]
Weight Recognizer [RFC6787]
Save-Best-Waveform Recognizer [RFC6787]
New-Phrase-ID Recognizer [RFC6787]
Confusable-Phrases-URI Recognizer [RFC6787]
Abort-Phrase-Enrollment Recognizer [RFC6787]
Sensitivity-Level Recorder [RFC6787]
No-Input-Timeout Recorder [RFC6787]
Completion-Cause Recorder [RFC6787]
Completion-Reason Recorder [RFC6787]
Burnett & Shanmugham Standards Track [Page 179]
RFC 6787 MRCPv2 November 2012
Failed-URI Recorder [RFC6787]
Failed-URI-Cause Recorder [RFC6787]
Record-URI Recorder [RFC6787]
Media-Type Recorder [RFC6787]
Max-Time Recorder [RFC6787]
Trim-Length Recorder [RFC6787]
Final-Silence Recorder [RFC6787]
Capture-On-Speech Recorder [RFC6787]
Ver-Buffer-Utterance Recorder [RFC6787]
Start-Input-Timers Recorder [RFC6787]
New-Audio-Channel Recorder [RFC6787]
Repository-URI Verifier [RFC6787]
Voiceprint-Identifier Verifier [RFC6787]
Verification-Mode Verifier [RFC6787]
Adapt-Model Verifier [RFC6787]
Abort-Model Verifier [RFC6787]
Min-Verification-Score Verifier [RFC6787]
Num-Min-Verification-Phrases Verifier [RFC6787]
Num-Max-Verification-Phrases Verifier [RFC6787]
No-Input-Timeout Verifier [RFC6787]
Save-Waveform Verifier [RFC6787]
Media-Type Verifier [RFC6787]
Waveform-URI Verifier [RFC6787]
Voiceprint-Exists Verifier [RFC6787]
Ver-Buffer-Utterance Verifier [RFC6787]
Input-Waveform-URI Verifier [RFC6787]
Completion-Cause Verifier [RFC6787]
Completion-Reason Verifier [RFC6787]
Speech-Complete-Timeout Verifier [RFC6787]
New-Audio-Channel Verifier [RFC6787]
Abort-Verification Verifier [RFC6787]
Start-Input-Timers Verifier [RFC6787]
Input-Type Verifier [RFC6787]
13.1.4. MRCPv2 Status Codes
IANA has created a new name space of "MRCPv2 Status Codes" with the
initial values that are defined in Section 5.4. All maintenance
within and additions to the contents of this name space MUST be
according to the "Specification Required with Expert Review"
registration policy.
13.1.5. Grammar Reference List Parameters
IANA has created a new name space of "Grammar Reference List
Parameters". All maintenance within and additions to the contents of
this name space MUST be according to the "Specification Required with
Burnett & Shanmugham Standards Track [Page 180]
RFC 6787 MRCPv2 November 2012
Expert Review" registration policy. There is only one initial
parameter as shown below.
Name Reference
---- -------------
weight [RFC6787]
13.1.6. MRCPv2 Vendor-Specific Parameters
IANA has created a new name space of "MRCPv2 Vendor-Specific
Parameters". All maintenance within and additions to the contents of
this name space MUST be according to the "Hierarchical Allocation"
registration policy as follows. Each name (corresponding to the
"vendor-av-pair-name" ABNF production) MUST satisfy the syntax
requirements of Internet Domain Names as described in Section 2.3.1
of RFC 1035 [RFC1035] (and as updated or obsoleted by successive
RFCs), with one exception, the order of the domain names is reversed.
For example, a vendor-specific parameter "foo" by example.com would
have the form "com.example.foo". The first, or top-level domain, is
restricted to exactly the set of Top-Level Internet Domains defined
by IANA and will be updated by IANA when and only when that set
changes. The second-level and all subdomains within the parameter
name MUST be allocated according to the "First Come First Served"
policy. It is RECOMMENDED that assignment requests adhere to the
existing allocations of Internet domain names to organizations,
institutions, corporations, etc.
The registry contains a list of vendor-registered parameters, where
each defined parameter is associated with a contact person and
includes an optional reference to the definition of the parameter,
preferably an RFC. The registry is initially empty.
13.2. NLSML-Related Registrations
13.2.1. 'application/nlsml+xml' Media Type Registration
IANA has registered the following media type according to the process
defined in RFC 4288 [RFC4288].
To: ietf-types@iana.org
Subject: Registration of media type application/nlsml+xml
MIME media type name: application
MIME subtype name: nlsml+xml
Required parameters: none
Burnett & Shanmugham Standards Track [Page 181]
RFC 6787 MRCPv2 November 2012
Optional parameters:
charset: All of the considerations described in RFC 3023
[RFC3023] also apply to the application/nlsml+xml media type.
Encoding considerations: All of the considerations described in RFC
3023 also apply to the 'application/nlsml+xml' media type.
Security considerations: As with HTML, NLSML documents contain links
to other data stores (grammars, verifier resources, etc.). Unlike
HTML, however, the data stores are not treated as media to be
rendered. Nevertheless, linked files may themselves have security
considerations, which would be those of the individual registered
types. Additionally, this media type has all of the security
considerations described in RFC 3023.
Interoperability considerations: Although an NLSML document is
itself a complete XML document, for a fuller interpretation of the
content a receiver of an NLSML document may wish to access
resources linked to by the document. The inability of an NLSML
processor to access or process such linked resources could result
in different behavior by the ultimate consumer of the data.
Published specification: RFC 6787
Applications that use this media type: MRCPv2 clients and servers
Additional information: none
Magic number(s): There is no single initial octet sequence that is
always present for NLSML files.
Person & email address to contact for further information:
Sarvi Shanmugham, sarvi@cisco.com
Intended usage: This media type is expected to be used only in
conjunction with MRCPv2.
13.3. NLSML XML Schema Registration
IANA has registered and now maintains the following XML Schema.
Information provided follows the template in RFC 3688 [RFC3688].
XML element type: schema
URI: urn:ietf:params:xml:schema:nlsml
Registrant Contact: IESG
Burnett & Shanmugham Standards Track [Page 182]
RFC 6787 MRCPv2 November 2012
XML: See Section 16.1.
13.4. MRCPv2 XML Namespace Registration
IANA has registered and now maintains the following XML Name space.
Information provided follows the template in RFC 3688 [RFC3688].
XML element type: ns
URI: urn:ietf:params:xml:ns:mrcpv2
Registrant Contact: IESG
XML: RFC 6787
13.5. Text Media Type Registrations
IANA has registered the following text media type according to the
process defined in RFC 4288 [RFC4288].
13.5.1. text/grammar-ref-list
To: ietf-types@iana.org
Subject: Registration of media type text/grammar-ref-list
MIME media type name: text
MIME subtype name: text/grammar-ref-list
Required parameters: none
Optional parameters: none
Encoding considerations: Depending on the transfer protocol, a
transfer encoding may be necessary to deal with very long lines.
Security considerations: This media type contains URIs that may
represent references to external resources. As these resources
are assumed to be speech recognition grammars, similar
considerations as for the media types 'application/srgs' and
'application/srgs+xml' apply.
Interoperability considerations: '>' must be percent encoded in URIs
according to RFC 3986 [RFC3986].
Published specification: The RECOGNIZE method of the MRCP protocol
performs a recognition operation that matches input against a set
Burnett & Shanmugham Standards Track [Page 183]
RFC 6787 MRCPv2 November 2012
of grammars. When matching against more than one grammar, it is
sometimes necessary to use different weights for the individual
grammars. These weights are not a property of the grammar
resource itself but qualify the reference to that grammar for the
particular recognition operation initiated by the RECOGNIZE
method. The format of the proposed 'text/grammar-ref-list' media
type is as follows:
body = *reference
reference = "<" uri ">" [parameters] CRLF
parameters = ";" parameter *(";" parameter)
parameter = attribute "=" value
This specification currently only defines a 'weight' parameter,
but new parameters MAY be added through the "Grammar Reference
List Parameters" IANA registry established through this
specification. Example:
;weight="0.85"
;weight="0.9"
;weight="0.75"
Applications that use this media type: MRCPv2 clients and servers
Additional information: none
Magic number(s): none
Person & email address to contact for further information:
Sarvi Shanmugham, sarvi@cisco.com
Intended usage: This media type is expected to be used only in
conjunction with MRCPv2.
13.6. 'session' URI Scheme Registration
IANA has registered the following new URI scheme. The information
below follows the template given in RFC 4395 [RFC4395].
URI scheme name: session
Status: Permanent
URI scheme syntax: The syntax of this scheme is identical to that
defined for the "cid" scheme in Section 2 of RFC 2392 [RFC2392].
Burnett & Shanmugham Standards Track [Page 184]
RFC 6787 MRCPv2 November 2012
URI scheme semantics: The URI is intended to identify a data
resource previously given to the network computing resource. The
purpose of this scheme is to permit access to the specific
resource for the lifetime of the session with the entity storing
the resource. The media type of the resource CAN vary. There is
no explicit mechanism for communication of the media type. This
scheme is currently widely used internally by existing
implementations, and the registration is intended to provide
information in the rare (and unfortunate) case that the scheme is
used elsewhere. The scheme SHOULD NOT be used for open Internet
protocols.
Encoding considerations: There are no other encoding considerations
for the 'session' URIs not described in RFC 3986 [RFC3986]
Applications/protocols that use this URI scheme name: This scheme
name is used by MRCPv2 clients and servers.
Interoperability considerations: Note that none of the resources are
accessible after the MCRPv2 session ends, hence the name of the
scheme. For clients who establish one MRCPv2 session only for the
entire speech application being implemented, this is sufficient,
but clients who create, terminate, and recreate MRCP sessions for
performance or scalability reasons will lose access to resources
established in the earlier session(s).
Security considerations: Generic security considerations for URIs
described in RFC 3986 [RFC3986] apply to this scheme as well. The
URIs defined here provide an identification mechanism only. Given
that the communication channel between client and server is
secure, that the server correctly accesses the resource associated
with the URI, and that the server ensures session-only lifetime
and access for each URI, the only additional security issues are
those of the types of media referred to by the URI.
Contact: Sarvi Shanmugham, sarvi@cisco.com
Author/Change controller: IESG, iesg@ietf.org
References: This specification, particularly Sections 6.2.7, 8.5.2,
9.5.1, and 9.9.
13.7. SDP Parameter Registrations
IANA has registered the following SDP parameter values. The
information for each follows the template given in RFC 4566
[RFC4566], Appendix B.
Burnett & Shanmugham Standards Track [Page 185]
RFC 6787 MRCPv2 November 2012
13.7.1. Sub-Registry "proto"
"TCP/MRCPv2" value of the "proto" parameter
Contact name, email address, and telephone number: Sarvi Shanmugham,
sarvi@cisco.com, +1.408.902.3875
Name being registered (as it will appear in SDP): TCP/MRCPv2
Long-form name in English: MCRPv2 over TCP
Type of name: proto
Explanation of name: This name represents the MCRPv2 protocol
carried over TCP.
Reference to specification of name: RFC 6787
"TCP/TLS/MRCPv2" value of the "proto" parameter
Contact name, email address, and telephone number: Sarvi Shanmugham,
sarvi@cisco.com, +1.408.902.3875
Name being registered (as it will appear in SDP): TCP/TLS/MRCPv2
Long-form name in English: MCRPv2 over TLS over TCP
Type of name: proto
Explanation of name: This name represents the MCRPv2 protocol
carried over TLS over TCP.
Reference to specification of name: RFC 6787
13.7.2. Sub-Registry "att-field (media-level)"
"resource" value of the "att-field" parameter
Contact name, email address, and telephone number: Sarvi Shanmugham,
sarvi@cisco.com, +1.408.902.3875
Attribute name (as it will appear in SDP): resource
Long-form attribute name in English: MRCPv2 resource type
Type of attribute: media-level
Subject to charset attribute? no
Burnett & Shanmugham Standards Track [Page 186]
RFC 6787 MRCPv2 November 2012
Explanation of attribute: See Section 4.2 of RFC 6787 for
description and examples.
Specification of appropriate attribute values: See section
Section 13.1.1 of RFC 6787.
"channel" value of the "att-field" parameter
Contact name, email address, and telephone number: Sarvi Shanmugham,
sarvi@cisco.com, +1.408.902.3875
Attribute name (as it will appear in SDP): channel
Long-form attribute name in English: MRCPv2 resource channel
identifier
Type of attribute: media-level
Subject to charset attribute? no
Explanation of attribute: See Section 4.2 of RFC 6787 for
description and examples.
Specification of appropriate attribute values: See Section 4.2 and
the "channel-id" ABNF production rules of RFC 6787.
"cmid" value of the "att-field" parameter
Contact name, email address, and telephone number: Sarvi Shanmugham,
sarvi@cisco.com, +1.408.902.3875
Attribute name (as it will appear in SDP): cmid
Long-form attribute name in English: MRCPv2 resource channel media
identifier
Type of attribute: media-level
Subject to charset attribute? no
Explanation of attribute: See Section 4.4 of RFC 6787 for
description and examples.
Specification of appropriate attribute values: See Section 4.4 and
the "cmid-attribute" ABNF production rules of RFC 6787.
Burnett & Shanmugham Standards Track [Page 187]
RFC 6787 MRCPv2 November 2012
14. Examples
14.1. Message Flow
The following is an example of a typical MRCPv2 session of speech
synthesis and recognition between a client and a server. Although
the SDP "s=" attribute in these examples has a text description value
to assist in understanding the examples, please keep in mind that RFC
3264 [RFC3264] recommends that messages actually put on the wire use
a space or a dash.
The figure below illustrates opening a session to the MRCPv2 server.
This exchange does not allocate a resource or setup media. It simply
establishes a SIP session with the MRCPv2 server.
C->S:
INVITE sip:mresources@example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bg1
Max-Forwards:6
To:MediaServer
From:sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:323123 INVITE
Contact:
Content-Type:application/sdp
Content-Length:...
v=0
o=sarvi 2614933546 2614933546 IN IP4 192.0.2.12
s=Set up MRCPv2 control and audio
i=Initial contact
c=IN IP4 192.0.2.12
S->C:
SIP/2.0 200 OK
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bg1;received=192.0.32.10
To:MediaServer ;tag=62784
From:sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:323123 INVITE
Contact:
Content-Type:application/sdp
Content-Length:...
v=0
Burnett & Shanmugham Standards Track [Page 188]
RFC 6787 MRCPv2 November 2012
o=- 3000000001 3000000001 IN IP4 192.0.2.11
s=Set up MRCPv2 control and audio
i=Initial contact
c=IN IP4 192.0.2.11
C->S:
ACK sip:mresources@server.example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bg2
Max-Forwards:6
To:MediaServer ;tag=62784
From:Sarvi ;tag=1928301774
Call-ID:a84b4c76e66710
CSeq:323123 ACK
Content-Length:0
The client requests the server to create a synthesizer resource
control channel to do speech synthesis. This also adds a media
stream to send the generated speech. Note that, in this example, the
client requests a new MRCPv2 TCP stream between the client and the
server. In the following requests, the client will ask to use the
existing connection.
C->S:
INVITE sip:mresources@server.example.com SIP/2.0
Via:SIP/2.0/TCP client.atlanta.example.com:5060;
branch=z9hG4bK74bg3
Max-Forwards:6
To:MediaServer ;tag=62784
From:sarvi