From 5b60caa978940b69085682012ab7b483786e450d Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Fri, 23 Mar 2007 22:07:22 +0000 Subject: [PATCH] 0.8 git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@688 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0167.xml | 277 +++++++++++++++++++++++++++++---------------------- 1 file changed, 159 insertions(+), 118 deletions(-) diff --git a/xep-0167.xml b/xep-0167.xml index eacb6346..8120e9e5 100644 --- a/xep-0167.xml +++ b/xep-0167.xml @@ -6,8 +6,8 @@
- Jingle Audio Content Description Format - This document defines a content description format for Jingle audio sessions. + Jingle Audio via RTP + This document defines methods for negotiating Jingle audio sessions that use the Real-time Transport Protocol (RTP) for media exchange. &LEGALNOTICE; 0167 Experimental @@ -24,6 +24,13 @@ &scottlu; &stpeter; &seanegan; + &robmcqueen; + + 0.8 + 2007-03-23 + psa/ram +

Renamed to mention RTP as the associated transport; corrected negotiation flow to be consistent with SIP/SDP (each party specifies a list of the payload types it can receive); added profile attribute to content element in order to specify RTP profile in use.

 + 0.7 2006-12-21 @@ -86,7 +93,7 @@
-

&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is audio (voice) chat. This document specifies a format for describing Jingle audio sessions.

+

&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is audio chat. This document specifies a format for describing Jingle audio sessions.

The Jingle content description format defined herein is designed to meet the following requirements:

@@ -151,98 +158,111 @@ ]]> -

The <description/> element is intended to be a child of a &JINGLE; element as specified in XEP-0166. (See Protocol Namespaces regarding issuance of a permanent namespace.)

+

The <description/> element is intended to be a child of a &JINGLE; element as specified in XEP-0166.

Each <payload-type/> element MAY contain one or more child elements that specify particular parameters related to the payload. For example, as described in draft-ietf-avt-rtp-speex This Internet-Draft has expired; see <http://www.watersprings.org/pub/id/draft-ietf-avt-rtp-speex-00.txt> for an archived version., the "ebw", "eng", "mode", "sr", and "vbr" parameters may be specified in relation to usage of the Speex See <http://www.speex.org/>. codec. Where such parameters are encoded via the "fmtp" SDP attribute, they shall be represented in Jingle via the following format:

]]>

Note: The parameter names are effectively guaranteed to be unique, since &IANA; maintains a registry of SDP parameters (see <http://www.iana.org/assignments/sdp-parameters>).

 - -

Upon receiving a Jingle initiate stanza containing a Jingle Audio content description as defined in this document, a target entity iterates through the list of offered payload types, composing an appropriate Jingle Audio response description according to the following rules:

-
    -
  • If the target entity does not support the offered encoding, it MUST NOT include the encoding in its response.
    • -
  • If the target entity does support the offered encoding, it SHOULD include encoding in the response, preseriving the offered payload type.
    • -
  • If the target entity is unable to support the offered encoding with the offered payload type, it MAY provide an alternate payload type in its response. This typically will happen only when translating from other signalling protocols.
    • -
  • The target entity SHOULD preserve the order of the offered encodings, which represents the priority assigned to them by the initator.
    • -
-

If, after applying these rules, the target entity determines it does not support any of the offering encodings, the target entity MUST reject the session by sending a <unsupported-codecs/> error in response to the initiator's "initiate" message. Otherwise, it MUST provisionally accept the session by sending an empty IQ result. If the response content type differs from the one offered, the target entity MUST then propose the change in a "description-modify" message as defined in XEP-0166. If the description is identical, the target entity MUST send a "description-accept" message (either explictly, or implicitly as part of a "content-accept" message).

- -

Following is an example of this negotiation:

- + +

When the initiator sends a session-initiate stanza to the receiver, the &DESCRIPTION; element includes all of the payload types that the initiator can receive for Jingle audio (each one encapsulated in a separate &PAYLOADTYPE; element):

- - - - - - - - ... - - - - - ]]> - -

The target entity now follows the rules provided in this section and determines it can only support PCMU. It provisionally accepts the session:

- - + + + action='session-initiate' + initiator='romeo@montague.net/orchard' + sid='a73sjjvkla37jfea'> + + + + + + + + + + + + ]]> - -

It then offers the new content description in a 'description-modify' message:

- - - - - - - - - - - ]]> - -

The initiator acknowledges the 'description-modify' with an empty IQ result, and sends a 'description-accept' to accept - the new Jingle Audio content description.

- - - - - - - - - - - - +

Upon receiving the session-initiate stanza, the receiver determines whether it can provisionally accept the session and proceed with the negotiation. The general Jingle error cases are specified in XEP-0166. In addition, the receiver must determine if it supports any of the payload types advertised by the initiator; if it does not, it MUST reject the session by sending a <unsupported-codecs/> error:

+ + + + + + ]]> - -

Finally, the target acknowledges the 'description-accept'.

- - +

If there is no error, the receiver provisionally accepts the session:

+ + ]]> +

The receiver then should send a list of the payload types that it can receive via a Jingle "content-accept" (or "session-accept") action. The list that the receiver sends MAY include any payload types (not a subset of the payload types sent by the initiator) but SHOULD retain the ID numbers and order specified by the initiator.

+ + + action='content-accept' + initiator='romeo@montague.net/orchard' + sid='a73sjjvkla37jfea'> + + + + + + + + + + + + + + + ]]> +

The initiator acknowledges the 'content-accept' with an empty IQ result:

+ + ]]> +

After successful transport negotiation (not shown here), the receiver then accepts the session:

+ + + + + + + + + + + ]]> +

And the initiator acknowledges session acceptance:

+ ]]> - -

If the payload type is static (payload-type IDs 0 through 95 inclusive), it MUST be mapped to a media field defined in RFC 4566: Session Description Protocol (SDP). The generic format for the media field is as follows:

+

If the payload type is static (payload-type IDs 0 through 95 inclusive), it MUST be mapped to a media field defined in RFC 4566. The generic format for the media field is as follows:

]]> -

In the context of Jingle audio sessions, the <content> is "audio", the <port> is the preferred port for such communications (which may be determined dynamically), the <transport> is whatever transport method is negotiated via the Jingle negotiation (e.g., "RTP/AVT"), and the <fmt list> is the payload-type ID.

+

In the context of Jingle audio sessions, the <media> is "audio", the <port> is the preferred port for such communications (which may be determined dynamically), the <transport> is whatever transport method is negotiated via the Jingle negotiation (e.g., "RTP/AVT"), and the <fmt list> is the payload-type ID.

For example, consider the following static payload-type:

@@ -251,7 +271,7 @@ m= m=audio 9999 RTP/AVP 13 ]]>

If the payload type is dynamic (payload-type IDs 96 through 127 inclusive), it SHOULD be mapped to an SDP media field plus an SDP attribute field named "rtpmap".

-

For example, consider a payload of 16-bit linear-encoded stereo audio sampled at 16KHz associated with dynamic payload-type 98:

+

For example, consider a payload of 16-bit linear-encoded stereo audio sampled at 16KHz associated with dynamic payload-type 96:

]]> @@ -259,7 +279,7 @@ m=audio 9999 RTP/AVP 13 m=audio 9999 RTP/AVP 96 a=rtpmap:96 speex/16000 ]]> -

As noted, if additional parameters are to be specified, they shall be represented as attributes of the <payload-type/> element or of the child <parameter/> element, as in the following example.

+

As noted, if additional parameters are to be specified, they shall be represented as attributes of the <payload-type/> element of the child <parameter/> element, as in the following example.

@@ -273,33 +293,9 @@ a=ptime:40 a=fmtp:96 vbr=on;cng=on ]]> - -

If an entity supports the Jingle audio content description format, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0167.html#ns" (see Protocol Namespaces) in response to &xep0030; information requests.

- - - - ]]> - - - ... - - - ... - - - ]]> - -

Informational messages may be sent by either party within the context of Jingle to communicate the status of a Jingle audio session, device, or principal. The informational message MUST be an IQ-set containing a &JINGLE; element of type "description-info", where the informational message is a payload element qualified by the 'http://www.xmpp.org/extensions/xep-0167.html#ns-info' namespace; the following payload elements are defined: A <trying/> element (equivalent to the SIP 100 Trying response code) is not necessary, since each session-level action is acknowledged via XMPP IQ semantics.

+

Informational messages may be sent by either party within the context of Jingle to communicate the status of a Jingle audio session, device, or principal. The informational message MUST be an IQ-set containing a &JINGLE; element of type "session-info", where the informational message is a payload element qualified by the 'http://www.xmpp.org/extensions/xep-0167.html#ns-info' namespace; the following payload elements are defined: A <trying/> element (equivalent to the SIP 100 Trying response code) is not necessary, since each session-level action is acknowledged via XMPP IQ semantics.

@@ -330,8 +326,8 @@ a=fmtp:96 vbr=on;cng=on to='romeo@montague.net/orchard' id='busy1' type='set'> - + action='session-info' initiator='romeo@montague.net/orchard' sid='a73sjjvkla37jfea'> @@ -344,7 +340,7 @@ a=fmtp:96 vbr=on;cng=on id='hold1' type='set'> @@ -357,7 +353,7 @@ a=fmtp:96 vbr=on;cng=on id='mute1' type='set'> @@ -370,7 +366,7 @@ a=fmtp:96 vbr=on;cng=on id='ringing1' type='set'> @@ -381,7 +377,7 @@ a=fmtp:96 vbr=on;cng=on -The Jingle Audio-specific error conditions are as follows: +

The Jingle Audio-specific error conditions are as follows:

Element
@@ -394,7 +390,31 @@ The Jingle Audio-specific error conditions are as follows:
Jingle ConditionThe recipient does not support any of the offered audio encodings.
+ + +

If an entity supports Jingle audio exchanges via RTP, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0167.html#ns" &NSNOTE; in response to &xep0030; information requests.

+ + + + ]]> + + + ... + + + ... + + + ]]> @@ -405,12 +425,12 @@ The Jingle Audio-specific error conditions are as follows:

If it is necessary to send Dual Tone Multi-Frequency (DTMF) tones, it is REQUIRED to use the XML format specified &xep0181;.

-

When the Jingle Audio content is accepted, either by a 'content-accept' action or a combination of 'description-accept' and 'transport-accept' actions, both receiving and sending entities SHOULD start listening for audio as defined by the negotiated transport method and audio description. For interoperability with telephony systems, each entity SHOULD both play any audio received and send a ringing tone, at this time, before the receiver sends a 'session-accept' action.

+

When the Jingle Audio content is accepted via a 'content-accept' action, both initiator and responder SHOULD start listening for audio as defined by the negotiated transport method and audio description. For interoperability with telephony systems, each entity SHOULD both play any audio received and send a ringing tone at this time (i.e., before the receiver sends a 'session-accept' action).

 -

The description of a format for audio sessions introduces no known security vulnerabilities.

+

In order to secure the data stream, implementations SHOULD use encryption methods appropriate to the transport method and media being exchanged; for example, in the case of UDP, that would include Datagram Transport Layer Security (DTLS) as specified in &rfc4347;. &sdpdtls; defines such methods for the Session Description Protocol; the relevant RTP profile (e.g., "UDP/TLS/RTP/AVP" for transporting the RTP stream over DTLS with UDP) shall be specified as the value of the &CONTENT; element's 'profile' attribute.

 @@ -422,11 +442,11 @@ The Jingle Audio-specific error conditions are as follows:

Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-0167.html#ns" and "http://www.xmpp.org/extensions/xep-0167.html#ns-info"; upon advancement of this specification, the ®ISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.

-

The XMPP Registrar shall include "audio" in its registry of Jingle content description formats. The registry submission is as follows:

+

The XMPP Registrar shall include "audio-rtp" in its registry of Jingle content description formats. The registry submission is as follows:

- audio - Jingle sessions that support audio exchanges + audio-rtp + Jingle sessions that support audio exchange via the Real-time Transport Protocol XEP-0167 ]]> @@ -483,6 +503,27 @@ The Jingle Audio-specific error conditions are as follows: + + ]]> + + + + + + + + + + + + + + ]]>