<abstract>This document defines a framework for initiating and managing peer-to-peer multimedia sessions (e.g., voice and video chat) between two Jabber/XMPP endpoints in a way that is interoperable with existing Internet standards.</abstract>
<remark><p>Simplified signalling process and state chart; Removed session-redirect action (use redirect error instead); removed content-decline action; removed transport-* actions (except transport-info for ICE negotiation); removed description-* actions; simplified syntax to allow only one transport per content type; corrected syntax of creator attribute to be either initiator or responder (not JIDs); added profile attribute to content element in order to specify RTP profile in use.</p></remark>
<remark><p>Added creator attribute to content element for prevention of race condition; modified spec to use provisional namespace before advancement to Draft (per XEP-0053).</p></remark>
<remark><p>Made several corrections to the state machines and examples.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2006-09-08</date>
<initials>ram/psa</initials>
<remark><p>Further cleaned up state machines and state-related actions.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2006-08-23</date>
<initials>ram/psa</initials>
<remark><p>Changed channels to components in line with ICE; changed various action names for consistency; added session-extend and session-reduce actions to add and remove description/transport pairs; added description-modify action; added sender attribute to specify directionality.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2006-07-17</date>
<initials>psa</initials>
<remark><p>Added implementation note about handling multiple content types.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2006-07-12</date>
<initials>se/psa</initials>
<remark><p>Changed media type to content type.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2006-03-20</date>
<initials>psa/jb</initials>
<remark><p>Further clarified state machine diagrams; specified that session accept must include agreed-upon media format and transport description; moved deployment notes to appropriate transport spec.</p></remark>
<remark><p>Provided more detail about modify scenarios; defined media-specific and transport-specific actions and adjusted state machine accordingly.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2006-02-13</date>
<initials>psa/jb</initials>
<remark><p>Per agreement among the co-authors, moved transport definition to separate specification, simplified state machine, and made other associated changes to the text, examples, and schemas; also harmonized redirect, decline, and terminate processes.</p></remark>
<remark><p>Restructured document flow; provided example of burst mode.</p></remark>
</revision>
<revision>
<version>0.0.8</version>
<date>2005-12-05</date>
<initials>psa/sl/jb</initials>
<remark><p>Distinguished between dribble mode and burst mode, including mode attribute, service discovery features, and implementation notes; provided detailed resource discovery examples; corrected state chart; specified session termination; specified error conditions; specified semantics of informational messages; began to define security considerations; added Joe Beda as co-author.</p></remark>
</revision>
<revision>
<version>0.0.7</version>
<date>2005-11-08</date>
<initials>psa</initials>
<remark><p>Added more detail to basic session flow; harmonized candidate negotiation process with ICE.</p></remark>
<p>The purpose of Jingle is to enable one-to-one, peer-to-peer media sessions between XMPP entities, with the negotiation occurring over XMPP and the media being exchanged outside the XMPP band using technologies such as the Real-time Transport Protocol (RTP; &rfc3550;), the User Datagram Protocol (UDP; &rfc0768;), and &ice;.</p>
<p>One target application for Jingle is simple voice chat (see &xep0167;). We stress the word "simple". The purpose of Jingle is not to build a full-fledged telephony application that supports call waiting, call forwarding, call transfer, hold music, IVR systems, find-me-follow-me functionality, conference calls, and the like. These features are of interest to some user populations, but building in support for these features would introduce unnecessary complexity into a technology that is designed for basic multimedia interaction.</p>
<p>The purpose of Jingle is not to supplant or replace technologies based on Session Initiation Protocol (SIP; &rfc3261;). Because dual-stack XMPP+SIP clients are difficult to build, Jingle was designed as a pure XMPP signalling protocol. However, Jingle is at the same time designed to interwork with SIP so that the millions of deployed XMPP clients can be added onto existing Voice over Internet Protocol (VoIP) networks, rather than limiting XMPP users to a separate and distinct network.</p>
<p>Jingle is designed in a modular way so that developers can easily add support for multimedia session types other than voice chat, such as video chat (see &xep0180;), application sharing, file sharing, collaborative editing, whiteboarding, and torrent broadcasting. The transport methods are also modular, so that Jingle implementations can use any appropriate media transport (including proprietary methods not standardized through the XMPP Standards Foundation).</p>
<li>Make it possible to add, modify, and remove content types from an existing session.</li>
<li>Make it relatively easy to implement support for the protocol in standard Jabber/XMPP clients.</li>
<li>Where communication with non-XMPP entities is needed, push as much complexity as possible onto server-side gateways between the XMPP network and the non-XMPP network.</li>
</ol>
<p>This document defines the signalling protocol only. Additional documents specify the following:</p>
<li><p>Various content description formats (audio, video, etc.) and, where possible, mapping those types to the Session Description Protocol (SDP; see &rfc4566;); examples include <cite>XEP-0167</cite> and <cite>XEP-0180</cite>.</p></li>
<li><p>Procedures for mapping the Jingle signalling protocol to existing signalling standards such as the IETF's Session Initiation Protocol (SIP) and the ITU's H.323 protocol (see &h323;); these documents are forthcoming.</p></li>
<td>A number of pairs of negotiated content transport methods and content description formats connecting two entities. It is delimited in time by an initiate request and session ending events. During the lifetime of a session, pairs of content descriptions and content transport methods can be added or removed. A session consists of at least one active negotiated content type at a time.</td>
<td>The format of the content type being established, which formally declares one purpose of the session (e.g., "voice" or "video"). This is the 'what' of the session (i.e., the bits to be transferred), such as the acceptable codecs when establishing a voice conversation. In Jingle XML syntax the content type is the namespace of the &DESCRIPTION; element.</td>
<td>The method for establishing data stream(s) between entities. Possible transports might include ICE-TCP, Raw UDP, inband data, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The content transport method defines how to transfer bits from one host to another. Each transport method must specify whether it is lossy (thus suitable for applications where some packet loss is tolerable) or reliable (thus suitable for applications where packet loss is not tolerable).</td>
<td>A component is a numbered stream of data which needs to be transmitted between the endpoints for a given content type in the context of a given session. It is up to the transport to negotiate the details of each component. Depending on the content type and the content description, one content description may require multiple components to be communicated (e.g., the audio content type might use two components: one to transmit an RTP stream and another to transmit RTCP timing information).</td>
<p>This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for content description formats and content transport methods, which are specified in separate documents; however, for the sake of completeness, this document also includes examples for all of the actions related to description formats and transport methods.</p>
<li>One user (the "initator") sends to another user (the "receiver") a session request with one content type, which includes at least one content type.</li>
<li>If the receiver wants to proceed, it provisionally accepts the request by sending an IQ result.</li>
<li>Both the initiator and receive start exchanging possible transport candidates as quickly as possible (these are sent in quick succession before further negotiation in order to minimize the time required before media data can flow).</li>
<li>These candidates are checked for connectivity.</li>
<li>As soon as the receiver finds a candidate over which media can flow, the receiver sends to the initiator a "session-accept" action.</li>
<li>The parties start sending media over the negotiated candidate.</li>
<p>If the parties later discover a better candidate, they perform a "content-modify" negotiation and then switch to the better candidate. Naturally they can also modify various other parameters related to the session (e.g., adding video to a voice chat).</p>
<td>Add one or more new content types to the session. This action MUST NOT be sent while the session is in the PENDING state. When a party sends a content-add, it MUST ignore any actions received from the other party until it receives acknowledgement of the content-add. <note>In the event that a session contains two unidirectional streams of the same type because a content-add was issued simultaneously by both parties, it is RECOMMENDED that participants close the duplicate stream in favour of that created by the session initiator, which should be made bidirectional with a 'content-modify' action by the responder.</note></td>
<td>Change an existing content type. The recipient MUST NOT reply to a content-modify action with another content-modify action.</td>
</tr>
<tr>
<td>content-remove</td>
<td>Remove one or more content types from the session. <note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content description that is received after a 'content-remove' action has been sent but before the action has been acknowledged by the peer.</note></td>
</tr>
<tr>
<td>session-accept</td>
<td>Definitively accept a session negotiation. Implicitly this action also serves as a content-accept (which in turn serves as a description-accept and transport-accept).</td>
</tr>
<tr>
<td>session-info</td>
<td>Send session-level information / messages, such as (for Jingle audio) a ringing message.</td>
</tr>
<tr>
<td>session-initiate</td>
<td>Request negotiation of a new Jingle session.</td>
</tr>
<tr>
<td>session-terminate</td>
<td>End an existing session.</td>
</tr>
<tr>
<td>transport-info</td>
<td>Exchange transport candidates; it is mainly used in <cite>XEP-0176</cite> but may be used in other transport specifications.</td>
<p>In order to initiate a Jingle session, the initiator must determine which of the receiver's XMPP resources is best for the desired content description format. There are several possible scenarios:</p>
<ol>
<li><p>If the intended responder shares presence with the initiator (see &xmppim;) and has only one available resource, this task SHOULD be completed using &xep0030; or the presence-based profile of service discovery specified in &xep0115;. <note>Naturally, instead of sending service discovery requests to every contact in a user's roster, it is more efficient to use <cite>Entity Capabilities</cite>, whereby support for Jingle and various Jingle content description formats and content transport methods is determined for a client version in general (rather than on a per-JID basis) and then cached. Refer to <cite>XEP-0115</cite> for details.</note></p></li>
<li><p>If the intended responder shares presence with the initiator and has more than one available resource but only one of the resources supports Jingle and the desired content description format, the initiator SHOULD MUST initiate the Jingle signalling with that resource.</p></li>
<li><p>If the intended responder shares presence with the initiator and has more than one available resource but more than one of the resources supports Jingle and the desired content description format, the initiator SHOULD use &xep0168; in order to determine which is the best resource with which to initiate the desired Jingle session.</p></li>
<li><p>If the intended responder does not share presence with the initiator, the initiator SHOULD first send a &xep0155; request to the responder in order to initiate the exchange of XMPP stanzas. The request SHOULD include a RAP routing hint as specified in <cite>XEP-0168</cite> and the &MESSAGE; stanza containing the request SHOULD be of type "headline" so that (typically) it is not stored offline for later delivery.</p></li>
<p>Once the initiator has discovered which of the receiver's XMPP resources is ideal for the desired content description format, it sends a session initiation request to the receiver. This request is an IQ-set containing a &JINGLE; element qualified by the 'http://www.xmpp.org/extensions/xep-0166.html#ns' namespace. The &JINGLE; element MUST possess the 'action', 'initiator', and 'sid' attributes (the latter two uniquely identify the session). For initiation, the 'action' attribute MUST have a value of "session-initiate" and the &JINGLE; element MUST contain one or more &CONTENT; elements, each of which defines a content type to be transferred during the session; each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired content description format and one &TRANSPORT; child element that specifies a potential content transport method. If either party wishes to propose the use of multiple transport methods for the same content description, it must send multiple &CONTENT; elements.</p>
<p>Note: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; elements are out of scope for this specification, but are defined in related specifications.</p>
<p>The attributes of the &JINGLE; element are as follows:</p>
<ul>
<li>The 'action' attribute is REQUIRED; it specifies a Jingle action as listed in this document (e.g., "session-initiate").</li>
<li>The 'initiator' attribute is the full JID of the entity that has initiated the session flow (which may be different from the 'from' address on the IQ-set).</li>
<li>The OPTIONAL 'reasoncode' attribute specifies a machine-readable purpose for the action being sent (e.g., "connectivity-error" for a session-terminate action).</li>
<li>The OPTIONAL 'reasontext' attribute specifies a human-readable purpose for the action being sent (e.g., "Sorry, gotta go!" for a session-terminate action).</li>
<li>The 'responder' attribute (see examples below) is the full JID of the entity that has replied to the initiation (which may be different from the 'to' address on the IQ-set).</li>
<li>The 'sid' attribute is a random session identifier generated by the initiator; this SHOULD match the XML Nmtoken production <note>See <<linkurl='http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken'>http://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Nmtoken</link>></note> so that XML character escaping is not needed for characters such as &. (Note: the 'sid' attribute effectively maps to the SIP "Call-ID" parameter.)</li>
</ul>
<p>The attributes of the &CONTENT; element are as follows:</p>
<li>The 'creator' attribute is REQUIRED; it specifies which party originally generated the content description (used to prevent race conditions regarding modifications).</li>
<li>The 'name' attribute is REQUIRED; it specifies a unique name or identifier for the content type (this identifier is opaque and does not have semantic meaning).</li>
<li>The 'profile' attribute is RECOMMENDED; for some content types, it specifies the profile in use (e.g., "RTP/AVP" in the context of the Real-time Transport Protocol).</li>
<li>The 'senders' attribute is RECOMMENDED; it specifies which entities in the session will be generating content; the allowable values are "initiator", "recipient", or "both" (where "both" is the default).</li>
<p>Note: In order to expedite session establishment, the initiator MAY send transport candidates (e.g., for negotiation of the ICE transport) immediately after sending the "session-initiate" message and before receiving acknowledgement from the receiver (i.e., the initiator MUST consider the session to be live even before receiving acknowledgement). Given in-order delivery, the receiver should receive such "transport-info" messages after receiving the "session-initiate" message (if not, it is appropriate for the receiver to return <unknown-session/> errors since it according to its state machine the session does not exist).</p>
<p>If the initiator is unknown to the receiver (e.g., via presence subscription) and the receiver has a policy of not communicating via Jingle with unknown entities, it SHOULD return a &unavailable; error.</p>
<examplecaption="Initiator Unknown to Receiver"><