<abstract>This specification defines an XMPP protocol extension for initiating and managing peer-to-peer media sessions between two XMPP entities in a way that is interoperable with existing Internet standards. The protocol provides a pluggable model that enables the core session management semantics (compatible with SIP) to be used for a wide variety of application types (e.g., voice chat, video chat, file transfer) and with a wide variety of transport methods (e.g., TCP, UDP, ICE, application-specific transports).</abstract>
<remark><p>Specified handling of duplicate name attributes on content element; clarified recommended usage of Jingle when exchanging multiple content-types; declared the principle that application types ought not to be mixed beyond necessity within a single session; clarified use of the reason element in cases other than termination.</p></remark>
<remark><p>Per a vote of the XMPP Council, advanced specification from Experimental to Draft; also required inclusion of the creator attribute per list consensus.</p></remark>
<remark><p>Specified tie-breaking for session-initiate action; incremented errors namespace to match core namespace; clarified some ambiguities in the text, examples, and state machine.</p></remark>
<li>Added the concept of a security precondition to the Jingle framework, where preconditions are defined in separate specifications (just as application types and transport methods are).</li>
<li>Defined a new Jingle action of security-info.</li>
<li>Incremented the namespace to urn:xmpp:jingle:1 in order to reflect the addition of security preconditions and the security-info action.</li>
<li>Clarified a number of points about the overall session flow and state machine.</li>
<li>Added Jingle reasons for failed-application, failed-transport, and incompatible-parameters.</li>
<remark><p>Clarified the definitions and conformance requirements for datagram and streaming transports; tightened the security requirements regarding the initiator and responder attributes; updated examples to reflect changes to XEP-0176.</p></remark>
<li>Added cancel, expired, gone, security-error, and timeout reason conditions.</li>
<li>Changed XMPP error condition for Jingle <unknown-session/> condition from <bad-request/> to <item-not-found/>.</li>
<li>Changed XMPP error condition for Jingle tie breaks from <unexpected-request/> to <conflict/> and defined Jingle-specific condition of <tie-break/>.</li>
<remark><p>Added content-reject action to mirror content-accept for replies to content-add; also added transport-reject action to mirror transport-accept for replies to transport-replace.</p></remark>
<li>Changed "reliable" vs. "lossy" to "streaming" vs. "datagram", since reliability or dependability is orthogonal to the streaming nature of the transport.</li>
<li>Added "transport-replace" action (answered by "transport-accept").</li>
<li>Removed <condition/> element as container for Jingle condition elements inside <reason/>, since it introduced an unnecessary layer of indirection.</li>
<li>Modified state machine to allow content removal during PENDING state.</li>
<li>Noted that a session can have more than one content instance of the same type.</li>
<li>Noted that the 'name' attribute is unique to a creator.</li>
<li>Changed examples to once again use voice chat instead of file transfer.</li>
<remark><p>Updated examples to track changes to XEP-0167 and retraction of XEP-0180; corrected definition of name attribute to allow semantic meaning.</p></remark>
<remark><p>More clearly specified the content-replace action (essentially similar to content-add); specified that content-accept shall be sent in response to content-replace; removed content-modify and content-accept from PENDING state; adjusted text regarding initial session negotiation.</p></remark>
<remark><p>Added content-replace action; modified reasoncode and reasontext to use elements instead of attributes; added sid element to handle alternative-session condition; modified examples to use file transfer instead of voice chat; moved profile element to XEP-0167 and XEP-0180.</p></remark>
<remark><p>Removed content-accept after content-remove; removed errors for unsupported-content and unsupported-transports since they are handled via session-terminate; clarified handling of responder attribute.</p></remark>
<remark><p>Modified session flows for busy, unsupported application formats, and unsupported transport methods to enable separation between Jingle core and distinct modules for applications and transports; moved resource determination recommendations to XEP-208.</p></remark>
<remark><p>Added scenario for handling of busy state, including Jingle-specific error code and modified error flow (no longer an instance of decline).</p></remark>
<remark><p>Added scenarios for various session flows; clarified handling of content-add, content-modify, and content-remove actions; clarified rules for codec priority.</p></remark>
<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, where the negotiation occurs over the XMPP signalling channel and the media is exchanged over a data channel that is usually a dedicated non-XMPP transport. Jingle is designed in a modular way:</p>
<ul>
<li><p>Developers can easily plug in support for a wide variety of application types, such as voice and video chat (see &xep0167;), file transfer (see &xep0234;), application sharing, collaborative editing, whiteboarding, and secure transmission of end-to-end XML streams (see &xep0247;).</p></li>
<li><p>The transport methods are also pluggable, so that Jingle implementations can use any appropriate datagram transport such as User Datagram Protocol (UDP; &rfc0768;) as negotiated via &xep0177; or &xep0176;, or any appropriate streaming transport such as Transmission Control Protocol (TCP; &rfc0793;), &xep0065; as negotiated via &xep0260;, and &xep0047; as negotiated via &xep0261;.</p></li>
<li><p>This modular approach also extends to the security preconditions that need to be met before application data can be exchanged over a given transport, such as negotiation of Transport Layer Security (TLS; &rfc5246;) for streaming transports and negotiation of Datagram Transport Layer Security (DTLS; &rfc4347;) for datagram transports.</p></li>
</ul>
<p>It is expected that most application types, transport methods, and security preconditions will be documented in specifications produced by the &XSF; or the &IETF;; however, developers can also define proprietary methods for custom functionality.</p>
<p>Although Jingle provides a general framework for session management, the original target application for Jingle was simple voice and video chat. We stress the word "simple". The purpose of Jingle was 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 adding support for them to the core Jingle layer would introduce unnecessary complexity into a technology that is designed for simple but generalized session negotiation.</p>
<p>Furthermore, Jingle is not intended to supplant or replace existing Internet technologies based on the 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>In essence, Jingle enables two XMPP entities (e.g., romeo@montague.lit and juliet@capulet.lit) to set up, manage, and tear down a multimedia session. The negotiation takes place over XMPP, and the media transfer typically takes place outside of XMPP. A simplified session flow would be as follows: <note>Naturally, more complex scenarios are possible; such scenarios are described in other specifications, such as <cite>Jingle RTP Sessions</cite> for voice and video chat.</note></p>
<p>To illustrate the basic flow, we show a truncated example with a "stub" application format and transport method (skipping non-essential steps to enforce the most essential concepts and ignoring security preconditions for now).</p>
<p>In this example, the initiator (romeo@montague.lit/orchard) sends a session initiation offer to the responder (juliet@capulet.lit/balcony), where the session is defined as the exchange of "stub" media over a "stub" transport.</p>
<p>After the responding client acknowledges receipt of the session-initiate message (not shown here), it prompts the responding user (if any) to choose whether she wants to proceed with the session (however, it does not need to prompt the user if for example she has configured her client to automatically accept session requests from this particular initiator). If she wants to proceed she selects the appropriate interface element and her client sends a session-accept message to the initiator.</p>
<p>The initiating client acknowledges receipt of the session-accept message (not shown here) and the parties can exchange "stub" media data over the "stub" transport.</p>
<p>The initiating client acknowledges receipt of the session-terminate message (not shown here) and the session is ended.</p>
<p>We now "fill in the blanks" for the &DESCRIPTION; and &TRANSPORT; elements with a more complex example: a voice chat session, where the application type is a Jingle RTP session (with several different codec possibilities) and the transport method is ICE-UDP.</p>
<p>Upon receiving the session-initiate message, the responder determines whether it can proceed with the negotiation. If there is no error, the responder acknowledges the session initiation request.</p>
<p>When the responding user affirms that she would like to proceed with the session, the responding client sends a session-accept message to the initiator (including in this example the subset of offered codecs that the responding client supports and one or more transport candidates generated by the responder).</p>
<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 application formats (audio, video, etc.) and, where possible, mapping of those types to the Session Description Protocol (SDP; see &rfc4566;); examples include <cite>Jingle RTP Sessions</cite> and <cite>Jingle File Transfer</cite>.</p></li>
<li><p>Various transport methods; examples include <cite>Jingle ICE-UDP Transport Method</cite>, <cite>Jingle Raw UDP Transport Method</cite>, <cite>Jingle In-Band Bytestreams Transport Method</cite>, and <cite>Jingle SOCKS5 Bytestreams Transport Method</cite>.</p></li>
<li><p>Various methods of securing the transport before using it to send application data; the only method defined so far is Transport Layer Security as described in &xtls;.</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 &H.323;); see for example &xmppsipmedia;.</p></li>
<dd>The data format of the content type being established, which formally declares one purpose of the session (e.g., "audio" 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 application format is the namespace of the &DESCRIPTION; element.</dd>
</di>
<di>
<dt>Component</dt>
<dd>A numbered stream of data that 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, multiple components might be needed (e.g., one to transmit an RTP stream and another to transmit RTCP timing information).</dd>
</di>
<di>
<dt>Content Type</dt>
<dd>A pair formed by the combination of one application format and one transport method.</dd>
</di>
<di>
<dt>Session</dt>
<dd>One or more content types negotiated between two entities. It is delimited in time by a session-initiate action and a session-terminate action. During the lifetime of a session, content types can be added or removed. A session consists of at least one content type at a time.</dd>
</di>
<di>
<dt>Transport Method</dt>
<dd>The method for establishing data stream(s) between entities. Possible transports might include ICE-UDP, ICE-TCP, Raw UDP, In-Band Bytestreams, SOCKS5 Bytestreams, etc. This is the 'how' of the session. In Jingle XML syntax this is the namespace of the &TRANSPORT; element. The transport method defines how to transfer bits from one host to another. Each transport method MUST specify whether it is "datagram" or "streaming" as described in the <linkurl='#transports'>Transport Types</link> section of this document.</dd>
<li>Single-dashed lines (---) represent Jingle stanzas that are sent via the XMPP signalling channel.</li>
<li>Double-dashed lines (===) represent media packets that are sent via the data channel, which typically is not an XMPP channel (although the <cite>Jingle In-Band Bytestreams Transport Method</cite> is an exception) but instead is a direct or mediated channel between the endpoints.</li>
<p>This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for application formats and transport methods, which are specified in separate documents.</p>
<li>One user (the "initiator") sends to another user (the "responder") a session-initiate message containing at least one content definition, each of which defines one application type, one transport method, and optionally one security precondition.</li>
<li>If the responder wishes to proceed, it sends a session-accept message to the initiator, optionally including one or more transport candidates (depending on the transport method specified in the session-initiate message).</li>
<li>The parties attempt to establish connectivity over the offered transport method as defined in the relevant specification, which might involve the exchange of transport-info messages for additional transport candidates; if connectivity cannot be established then the parties might attempt to fall back to another transport method using the transport-replace and transport-accept messages.</li>
<li>Optionally, the parties attempt to establish security for the transport method before using it to exchange application data.</li>
<li>Optionally, either party can add or remove content definitions, or change the direction of the media flow, using the content-add, content-remove, and content-modify messages.</li>
<li>Optionally, either party can send session-info messages (e.g., to inform the other party that its device is ringing).</li>
<li>As soon as the initiator and responder determine that data can flow over the negotiated transport (potentially only after a security precondition has been met), they start sending application data over the transport.</li>
<p>Even after application data is being exchanged, the parties can adjust the session definition by sending additional Jingle messages, such as content-modify, content-remove, content-add, description-info, security-info, session-info, and transport-replace.</p>
<p>Note: While it is allowed to send all actions while in the PENDING state, typically the responder will send a session-accept message as quickly as possible in order to expedite the transport negotiation; see the <linkurl='#sec'>Security Considerations</link> section of this document regarding information exposure when the responder sends transport candidates to the initiator.</p>
<p>The actions related to management of the overall Jingle session are as follows (detailed definitions are provided in the <linkurl='#def-action'>Action Attribute</link> section of this document).</p>
<p>This section defines the high-level flow of a Jingle session. More detailed descriptions are provided in the specifications for Jingle application formats and transport methods.</p>
<p>In order to initiate a Jingle session, the initiator needs to determine which of the responder's XMPP resources is best for the desired application format. Methods for doing so are out of scope for this specification. However, see the <linkurl='#support'>Determining Support</link> section of this document for relevant information.</p>
<p>Once the initiator has discovered which of the responder's XMPP resources is ideal for the desired application format, it sends a session initiation request to the responder. This request is an IQ-set containing a &JINGLE; element qualified by the 'urn:xmpp:jingle:1' namespace &VNOTE;, where the value of the 'action' attribute is "session-initiate" and where the &JINGLE; element contains one or more &CONTENT; elements. Each &CONTENT; element defines a content type to be transferred during the session, and each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired application format and one &TRANSPORT; child element that specifies a potential transport method, as well as (optionally) one <security/> element that specifies a security precondition that needs to be met before the parties can exchange application data over the negotiated transport.</p>
<p>Application types ought not to be mixed beyond necessity within a single session. Therefore the session initiation request (along with subsequent additions) will include only content-types that can be grouped together into a coherent session within a given Jingle application. For example, two parties might start an audio call but then add a video aspect to that call. If one of the parties decides to send a file to the other party as a result of discussion over the audio/video session or a text chat conversation, conceptually that is probably a separate session (unless file exchange or screen sharing or some other application type is an integral part of a broader collaboration experience and needs to be calibrated with the audio/video session).</p>
<p>Note: The syntax and semantics of the &DESCRIPTION;, &TRANSPORT;, and <security/> elements are out of scope for this document, since they are defined in related specifications. The syntax and semantics of the &JINGLE; and &CONTENT; elements are specified in this document under <linkurl='#def'>Formal Definition</link>.</p>
<p>However, after acknowledging the session initiation request, the responder might subsequently determine that it cannot proceed with negotiation of the session (e.g., because it does not support any of the offered application formats or transport methods, because a human user is busy or unable to accept the session, because a human user wishes to formally decline the session, etc.). In these cases, the responder SHOULD immediately acknowledge the session initiation request but then terminate the session with an appropriate reason as described in the <linkurl='#session-terminate'>Termination</link> section of this document.</p>
<p>If the initiator is unknown to the responder (e.g., via presence subscription as defined in &rfc3921;) and the responder has a policy of not communicating via Jingle with unknown entities, it MUST return a &unavailable; error.</p>
<p>Although in general it is preferable for the responder to send a session-accept message as soon as possible, some forms of negotiation might be necessary before the parties can agree on an acceptable set of application formats and transport methods. There are many potential parameter combinations, as defined in the relevant specifications for various application formats and transport methods.</p>
<p>As soon as possible after receiving the session-initiate message, the responder informs the initiator that she wishes to proceed with the session by sending a session-accept message.</p>
<pclass='box'>Note: After receiving and acknowledging the "session-initiate" action received from the initiator, the responding client SHOULD present an interface element that enables a human user to explicitly agree to proceeding with the session (e.g., an "Accept Incoming Call?" pop-up window including "Yes" and "No" buttons). However, the responding client SHOULD NOT return a "session-accept" action to the initiator until the responder has explicitly agreed to proceed with the session (unless the initiator is on a list of entities whose sessions are automatically accepted).</p>
<p>The initiator then acknowledges the responder's definitive acceptance.</p>
<p>The session is now in the ACTIVE state. However, this does not necessarily mean that the parties can exchange application data yet, because further negotiation might be necessary (e.g., to fall back from the offered transport method to a suitable alternative).</p>
<p>Once a session is in the ACTIVE state, it might be modified via a content-add, content-modify, content-remove, or transport-info message. Examples of such modifications are shown in the specifications for various application formats and transport methods.</p>
<p>In order to gracefully end the session (which can be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the responder or the initiator MUST send a session-terminate message to the other party.</p>
<p>The party that terminates the session SHOULD include a <reason/> element that specifies why the session is being terminated. Examples follow.</p>
<p>Probably the primary reason for terminating a session is that the session has ended successfully (e.g., because a file has been sent or a voice call has completed); in this case, the recommended condition is <success/>.</p>
<p>Another reason for terminating the session is that the terminating party wishes to formally decline the session; in this case, the recommended condition is <decline/>.</p>
<p>Another reason for terminating the session is that the terminating party already has an existing session with the other party and wishes to use that session rather than initiate a new session; in this case, the recommended condition is <alternative-session/> and the terminating party SHOULD include the session ID of the alternative session in the <sid/> element.</p>
<p>Another reason for terminating the session is that the terminating party does not support any of the offered transport methods; in this case, the recommended condition is <unsupported-transports/>.</p>
<examplecaption="Terminating the session (no offered transport method supported)"><![CDATA[
<iqfrom='juliet@capulet.lit/balcony'
id='h82bs51g'
to='romeo@montague.lit/orchard'
type='set'>
<jinglexmlns='urn:xmpp:jingle:1'
action='session-terminate'
sid='a73sjjvkla37jfea'>
<reason>
<unsupported-transports/>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party has determined that transport setup has failed in an unrecoverable fashion (e.g., all transport methods have been exhausted even after fallback and the last method attempted has failed); in this case, the recommended condition is <failed-transport/>.</p>
<examplecaption="Terminating the session (transport negotiation failed)"><