<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 sharing) and with a wide variety of transport methods (e.g., TCP, UDP, ICE, application-specific transports).</abstract>
<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 "channel" and the media is exchanged outside the XMPP channel 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 and video chat (see &xep0167;). We stress the word "simple". The purpose of the core Jingle technology 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 adding support for them to the core Jingle layer would introduce unnecessary complexity into a technology that is designed for basic multimedia interaction.</p>
<p>In addition, the purpose of Jingle is not to supplant or replace existing Internet 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 and video chat, such as 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>
<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 generally takes place outside of XMPP. A simplified session flow would be as follows:</p>
<p>Naturally, more complex scenarios are possible; such scenarios are described in other specifications, such as <cite>XEP-0167</cite> for voice chat.</p>
<p>The simplest flow might happen as follows. The example is that of a voice chat offer, where the transport method is &xep0176; and the initiator offers several different codec possibilities.</p>
<p>Upon receiving the session-initiate stanza, the responder determines whether it can proceed with the negotiation. If there is no error, the responder acknowledges the session initiation request.</p>
<p>After successful transport negotiation (not shown here), the responder accepts the session by sending a session-accept action to the initiator (including the negotiated transport details and the subset of offered codecs that the responder supports).</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 &xep0234;.</p></li>
<li><p>Various transport methods; examples include <cite>Jingle ICE-UDP Transport</cite> and &xep0177;.</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;); see for example &xmppsipmedia;.</p></li>
<td>The data 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 application format is the namespace of the &DESCRIPTION; element.</td>
<td>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).</td>
<td>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.</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 transport method defines how to transfer bits from one host to another. Each transport method must specify whether it is datagram (thus suitable for applications where some packet loss is tolerable) or streaming (thus suitable for applications where packet loss is not tolerable).</td>
<li>Double-dashed lines (===) represent media packets that are sent via the media channel, which typically is not an XMPP channel but 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>
<p>At the most basic level, the process for initial negotiation of a Jingle session is as follows (i.e., the actions that can be generated during the PENDING state):</p>
<li>Optionally, either party can send session-info actions (to inform the other party that it is attempting transport negotiation, that its device is ringing, etc.).</li>
<p>After the initial session negotiation has been completed and the session is in the ACTIVE state, the parties can adjust the session definition by sending the content-modify, content-remove, content-add, and transport-replace actions. In addition, certain transport methods allow continued sending of transport-info actions while in the ACTIVE state. And naturally the parties can send session-info actions at any time.</p>
<p>The actions related to management of the overall Jingle session are as follows (detailed definitions are provided in under <linkurl='#def-action'>Action Attribute</link>).</p>
<ul>
<li>content-accept -- Accept a content-add action received from another party.</li>
<li>content-add -- Add one or more new content definitions to the session.</li>
<li>content-modify -- Change the directionality of media sending.</li>
<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 (and associated specifications) 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:0' 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. If either party wishes to propose the use of multiple transport methods for the same application format, it MUST include multiple &CONTENT; elements.</p>
<p>Note: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; 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>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 action and before receiving acknowledgement from the responder (i.e., the initiator MUST consider the session to be PENDING even before receiving acknowledgement). Given in-order delivery in accordance with &xmppcore;, the responder will receive such transport-info actions after receiving the session-initiate action (if not, it is appropriate for the responder to return <unknown-session/> errors since according to its state machine the session does not exist).</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; or stanza session negotiation as defined in &xep0155;) and the responder has a policy of not communicating via Jingle with unknown entities, it MUST return a &unavailable; error.</p>
<p>In general, negotiation will 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>If (after negotiation of transport methods and application formats as well as checking of transport candidates) the responder determines that it will be able to establish a connection, it sends a definitive acceptance to the initiator.</p>
<p>The initiator then acknowledges the responder's definitive acceptance, after which the parties can exchange media over the negotiated connection.</p>
<p>If one of the parties cannot find a suitable transport method or candidate, it SHOULD terminate the session as described below.</p>
</section2>
<section2topic='Modifying an Active Session'anchor='session-modify'>
<p>Once a session is in the ACTIVE state, it might be modified via a content-add, content-modify, content-remove, or transport-info action. 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 action 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 call has ended successfully; in this case, the recommended condition is "success".</p>
<examplecaption="Terminating the session (busy)"><![CDATA[
<iqfrom='juliet@capulet.lit/balcony'
id='term0'
to='romeo@montague.lit/orchard'
type='set'>
<jinglexmlns='urn:xmpp:jingle:0'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<success/>
</reason>
</jingle>
</iq>
]]></example>
<p>Another reason for terminating the session is that the terminating party is busy; in this case, the recommended condition is "busy".</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>
<examplecaption="Terminating the session (session formally declined)"><