RTCWeb JSEP XMPP/Jingle Mapping

In draft , it is mentioned that there are several options for the signalling mechanisms: ROAP (see ), SIP or XMPP/Jingle. This document focuses on XMPP/Jingle and tries to explain how to use JSEP and XMPP/Jingle to exchange session descriptions.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

In , it shows the overall architecture. In the figure, "Browser" is synonymous with "User Agent", and "Web Application" is synonymous with "JavaScript".

+----------------------+ | Web | | | | Server | +----------------------+ / \ / \ Jingle / \ Jingle / \ / \ / \ +-------------+ +--------------+ | Web | | Web | | Application | | Application | + ----------- + + ------------ + ^ ^ | SDP | SDP | | V (JSEP) V (JSEP) +-------------+ +--------------+ | Offerer | | Answerer | | | <====== Media =======> | | | Browser | | Browser | +-------------+ +--------------+

In , it shows the basic Jingle session flow.

| | ack | |<----------------------------| | session-accept | |<----------------------------| | ack | |---------------------------->| | RTCWeb Media Session | |<===========================>| | session-terminate | |<----------------------------| | ack | |---------------------------->| | | ]]>

In , it shows the overall Jingle session management.

To initiate a session, the initiator can create an offer, and send the offer to the recipient by using Jingle "session-initiate" action. The JSEP APIs are defined in and . JSEP API: OffererJS->OffererUA: pc = new PeerConnection(); OffererJS->OffererUA: pc.addStream(localStream, null); OffererJS->OffererUA: offer = pc.createOffer(null); Jingle message: OffererJS->AnswererJS: ]]>. After receiving the Jingle "session-initiate" action, the recipient can parse the session information, and apply the supplied offer as the remote description. JSEP API: AnswererJS->AnswererUA: pc.setRemoteDescription("offer",offer);

If the recipient accepts a session, it can create an answer and send back the answer by using Jingle "session-accept" action. JSEP API: AnswererJS->AnswererUA: peer.addStream(localStream, null); AnswererJS->AnswererUA: answer = peer.createAnswer(offer, null); Jingle message: AnswererJS->OffererJS: ]]>. After receiving the Jingle "session-accept" action, the initiator can parse the received answer and apply the supplied answer to the remote description. JSEP API: OffererJS->OffererUA: pc.setRemoteDescription("answer", answer);

To terminate a session, the initiator can close the peer connection with the recipient by using Jingle "session-terminate" action. JSEP API: OffererJS->OffererUA: pc.close(); Jingle message: OffererJS->AnswererJS: ]]>. After receiving the Jingle "session-terminate" action, the recipient can close the peer connection. JSEP API: AnswererJS->AnswererUA: peer.close();

To add media (e.g.video) to an existing session, the initiator can use Jingle "content-add" action. JSEP API: OffererJS->OffererUA: pc.addStream(videoStream); OffererJS->OffererUA: offer = pc.createOffer(null); Jingle message: OffererJS->AnswererJS: ]]>. After receiving the Jingle "content-add" action, the recipient can parse the received offer and set the remote description. JSEP API: AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);

To modify media (e.g.change audio to video) to an existing session, the initiator can either use Jingle "content-modify" action, or use combined Jingle "content-remove" action and "content-add" action. JSEP API: OffererJS->OffererUA: pc.removeStream(audioStream); OffererJS->OffererUA: pc.addStream(videoStream); Jingle message: OffererJS->AnswererJS: ]]>. After receiving the Jingle "content-modify" action, the recipient can parse the received offer and set the remote description. JSEP API: AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);

To remove media (e.g.video) to an existing session, the initiator can use Jingle "content-remove" action. JSEP API: OffererJS->OffererUA: pc.removeStream(audioStream); Jingle message: OffererJS->AnswererJS: ]]>. After receiving the Jingle "content-remove" action, the recipient can parse the received offer and set the remote description. JSEP API: AnswererJS->AnswererUA: peer.setRemoteDescription("offer", offer);

If the recipient accepts the "content-add" action to an existing session from the initiator, recipient can create an answer and send back the answer by using Jingle "content-accept" action. JSEP API: AnswererJS: offer = parseContentAdd(xmpp); AnswererJS->AnswererUA: peer.createAnswer(offer,null); Jingle message: AnswererJS->OffererJS: ]]>. After receiving the Jingle "content-accept" action, the initiator can parse the received answer and apply the received answer to the remote description. JSEP API: OffererJS->OffererUA: peer.setRemoteDescription("answer", answer);

If the recipient rejects the "content-add" action to an existing session from the initiator, recipient can send back answer by using Jingle "content-reject" action. JSEP API: AnswererJS: offer = parseContentAdd(xmpp); AnswererJS->AnswererUA: peer.createAnswer(offer,null); Jingle message: AnswererJS->OffererJS: ]]>. After receiving the Jingle "content-reject" action, the initiator can parse the received answer and apply the received answer to the remote description. JSEP API: OffererJS->OffererUA: peer.setRemoteDescription("answer", answer);

To perform the ICE process, the initiator can start gathering or update ICE address, and exchange the ICE candidates with the recipient by using Jingle "transport-info" action. JSEP API: OffererJS->OffererUA: pc.startIce(); OffererJS->OffererUA: pc.updateIce(); Jingle message: OffererJS->AnswererJS: ]]>. AnswererJS->OffererJS: ]]>. After receiving the Jingle "transport-info" action, the recipient can parse the received ICE candidates and add remote candidate to the ICE Agent. JSEP API: AnswererJS->AnswererUA: pc.addIceCandidate(candidate);

To send informational hints about parameters related to an existing session, for example, add new video sources to a call that already has video, the initiator can indicate that by using Jingle "description-info" action. JSEP API: OffererJS->OffererUA: pc.addStream(offererVideoStream2); OffererJS->OffererUA: offer = pc.createOffer(null); Jingle message: OffererJS->AnswererJS: ]]>. After receiving the Jingle "description-info" action, the recipient parses the description information and sends back the acknowledgement by using IQ stanza of "result" type. There is no mapped JSEP API for Jingle "description-info" action.

To acknowledge the description information to an existing session from the initiator, recipient can send back answer by using IQ stanza of "result" type. See . Jingle message: AnswererJS->OffererJS: ]]>. After receiving the Jingle IQ stanza of "result" type, the recipient can use the remote offer as an answer in the remote description. JSEP API: AnswererJS->AnswererUA: peer.setRemoteDescription("answer", offer);

If there are errors occurred during an existing session, the recipient can send back answer by using IQ stanza of "error" type. See . JSEP API: AnswererJS->AnswererUA: peer.RTCPeerConnectionErrorCallback; Jingle message: AnswererJS->OffererJS: ]]>. After receiving the Jingle IQ stanza of "error" type, the initiate can choose to close the peer connection due to the errors. JSEP API: OffererJS->OffererUA: pc.close();

TBD 1: do we have usage for the following actions: "security-info", "session-info"? TBD 2: do we need to redefine a transport method? If yes, we can use "transport-replace", "transport-accept", "transport-reject".

When Offerer Javascript uses JSEP API to interact with Offerer User Agent, it needs to map the JSEP API to Jingle message, to send it Answerer JavaScript. In , it shows the mapping table from JSEP APIs to Jingle messages.

When Answerer Javascript receives Jingle message, it needs to map it to JSEP API, and interacts with ANswerer User Agent. In , it shows the mapping table from JSEP APIs to Jingle messages.

In order to perform the media negotiation, PeerConnection SDP Messages need to be converted into Jingle message and vice-versa. The session description information included in Jingle message can be mapped to SDP as defined in section 6 of . For example, consider a payload of 16-bit linear-encoded stereo audio sampled at 16KHz associated with dynamic payload-type 96:

]]>

That Jingle-formatted information would be mapped to SDP as follows: m=audio 9999 RTP/AVP 96a=rtpmap:96 speex/16000

In , OffererJS uses Jingle "session-initiate" action to initiate a session with AnswererJS, and uses Jingle "transport-info" to exchange ICE candidates with AnswererJS. Then AnswererJS accepts the session using Jingle "session-accept" action. After the media session, OffererJS uses "session-terminate" action to terminate the session, and AnswererJS acknowledges with IQ stanza of "result" type.

| |-------------------------------------->| | | | | |-------------------------------------->| | | | | |<--------------------------------------| | | | | |<--------------------------------------| | | | Media Session | |<=====================================>| | | | | |-------------------------------------->| | | | | |<--------------------------------------| | | ]]> Message details go here...

In , OffererJS uses Jingle "content-add" action to add video media to an existing session. AnswererJS accepts that by using Jingle "content-accept" action. For simplicity, candidate exchange is not shown.

| |-------------------------------------->| | | | | |<--------------------------------------| | | | Media Session | |<=====================================>| | | ]]> Message details go here...

In , OffererJS uses Jingle "description-info" action to add new video sources at the same time to a call that already has video. AnswererJS also uses Jingle "description-info" action to indicate the new sources to the remote side. After that, they uses IQ stanza of "result" type to acknowledge each other.

| |-------------------------------------->| | | | | |<--------------------------------------| | | | | |-------------------------------------->| | | | | |<--------------------------------------| | | | Media Session | |<=====================================>| | | ]]> Message details go here...

TBD.

This document requires no actions from IANA.

The author would like to thank Kiran Kumar, Bert greevenbosch, Justin Uberti for the reviews and feedbacks.