<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 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>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 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 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>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>
<p>This section provides a friendly introduction to Jingle.</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 takes place outside of XMPP. The simplest session flow is as follows:</p>
<p>Naturally, more complex scenarios are probable; 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 (see <cite>XEP-0167</cite>) initiated by Romeo, where the transport is &xep0177;.</p>
<p>The parties then begin to exchange media. In this case they would exchange audio using the Speex codec at a clockrate of 8000 since that is the highest-priority codec for the responder (as determined by the XML order of the &PAYLOADTYPE; children).</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 Audio via RTP</cite> and <cite>Jingle Video via RTP</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>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>
</tr>
<tr>
<td>Component</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 may be needed (e.g., two components might be needed, 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 an initiate request and session ending events. 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 lossy (thus suitable for applications where some packet loss is tolerable) or reliable (thus suitable for applications where packet loss is not tolerable).</td>
<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>Both the initiator and responder 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>
<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. The sender MUST specify only the added content-type(s), not the added content-type(s) plus the existing content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. 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 sender SHOULD specify only the aspects for which a modification is desired (e.g., if a party wishes to change only the profile then it would send an empty <content/> element with a modified value for the 'profile' attribute; if a party wishes to change only the transport, then it would send a <content/> element that contains only a <transport/> child; etc.). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. The recipient MUST NOT reply to a content-modify action with another content-modify action. <note>If both parties send modify messages at the same time, the modify message from the session initiator MUST trump the modify message from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
<td>Remove one or more content types from the session. The sender MUST specify only the removed content-type(s), not the removed content-type(s) plus the remaining content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. <note>The recipient SHOULD NOT send a content-accept with the new content type definition after receiving a content-remove.</note><note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content type that is received after a 'content-remove' action has been sent but before the action has been acknowledged by the peer.</note><note>If the content-remove results in zero content types for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content types is void).</note></td>
<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 must 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 'http://www.xmpp.org/extensions/xep-0166.html#ns' namespace &NSNOTE;, 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 send multiple &CONTENT; elements.</p>
<p>Note: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; elements are out of scope for this specification, 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" message 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, the responder should receive such "transport-info" messages after receiving the "session-initiate" message (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 may 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 reasoncode 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 SHOULD 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>Note: In the session-accept stanza, the &JINGLE; element MUST contain one or more <content/> elements, each of which MUST contain one <description/> element and one <transport/> element. The &JINGLE; element SHOULD possess a 'responder' attribute that explicitly specifies the full JID of the responding entity; after sending acknowledgement of the session-accept, the initiator SHOULD send all future commmunications about this Jingle session to the JID provided in the 'responder' attribute and note the new JID in the user interface.</p>
<p>The initiator then acknowledges the responder's definitive acceptance, after which the parties can exchange media over the negotiated connection.</p>
<p>Once a session is in the ACTIVE state, it may 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 MAY 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 "terminate" action to the other party.</p>
<p>The party that terminates the session SHOULD include a 'reasoncode' attribute that specifies why the session is being terminated. Examples follow.</p>
<p>One reason for terminating the session is that the terminating party is busy; in this case, the recommended reasoncode is "busy".</p>
<examplecaption="Terminating the session (busy)"><