xeps/xep-0180.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Jingle Video via RTP</title>
  <abstract>This document defines methods for negotiating Jingle video sessions that use the Real-time Transport Protocol (RTP) for media exchange.</abstract>
  &LEGALNOTICE;
  <number>0180</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0166</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>TO BE ASSIGNED</shortname>
  &stpeter;
  <author>
    <firstname>Milton</firstname>
    <surname>Chen</surname>
    <email>Milton.Chen@vseelab.com</email>
  </author>
  <revision>
    <version>0.8</version>
    <date>2007-05-23</date>
    <initials>psa</initials>
    <remark><p>Corrected examples to use video codecs; added clockrate attribute.</p></remark>
  </revision>
  <revision>
    <version>0.7</version>
    <date>2007-05-23</date>
    <initials>psa</initials>
    <remark><p>More completely specified how to include SDP parameters and codec-specific parameters (same approach as in XEP-0167); added and corrected Theora examples.</p></remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2007-04-17</date>
    <initials>psa</initials>
    <remark><p>Specified Jingle conformance, including the need to use a lossy transport and the process of sending and receiving video content.</p></remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2007-03-23</date>
    <initials>psa</initials>
    <remark><p>Added negotiation flow and SDP mapping; renamed to mention RTP as the associated transport; corrected negotiation flow to be consistent with SIP/SDP (each party specifies a list of the payload types it can receive); added profile attribute to content element in order to specify RTP profile in use.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2006-12-21</date>
    <initials>psa</initials>
    <remark><p>Modified spec to use provisional namespace before advancement to Draft (per XEP-0053).</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2006-08-23</date>
    <initials>psa</initials>
    <remark><p>Modified namespace to track XEP-0166.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2006-07-12</date>
    <initials>psa</initials>
    <remark><p>Updated to use content type instead of media type.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2006-03-23</date>
    <initials>psa/mc</initials>
    <remark><p>Initial version.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2006-03-20</date>
    <initials>psa/mc</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is video exchange. This document specifies a format for describing Jingle video sessions, where the media exchange occurs using the Real-time Transport Protocol (see &rfc3550;). Such sessions require the use of a lossy transport method such as &xep0177; or the "ice-udp" method specified in &xep0176;.</p>
</section1>

<section1 topic='Requirements' anchor='reqs'>
  <p>The Jingle content description format defined herein is designed to meet the following requirements:</p>
  <ol>
    <li>Enable negotiation of parameters necessary for video exchange.</li>
    <li>Map these parameters to Session Description Protocol (SDP; see &rfc4566;) to enable interoperability.</li>
    <li>Define informational messages related to video chat.</li>
  </ol>
</section1>

<section1 topic='Jingle Conformance' anchor='conformance'>
   <p>In accordance with Section 8 of <cite>XEP-0166</cite>, this document specifies the following information related to the Jingle Video via RTP application type:</p>
   <ol>
     <li><p>The content negotiation process is defined in the <link url='#negotiation'>Negotiating a Jingle Video Session</link> section of this document.</p></li>
     <li><p>The semantics of the &DESCRIPTION; element are defined in the <link url='#format'>Content Description Format</link> section of this document.</p></li>
     <li><p>A mapping of Jingle semantics to the Session Description Protocol is provided in the <link url='#sdp'>Mapping to Session Description Protocol</link> section of this document.</p></li>
     <li><p>A Jingle video session MUST use a lossy transport method such as &xep0177; or the "ice-udp" method specified in &xep0176;.</p></li>
     <li>
       <p>Content is to be sent and received as follows:</p>
       <ul>
         <li><p>Outbound video content shall be encoded into RTP packets and each packet shall be sent individually over the transport. Each inbound packet received over the transport is an RTP packet.</p></li>
       </ul>
     </li>
   </ol>
</section1>

<section1 topic='Content Description Format' anchor='format'>
  <p>A Jingle video session is described by one or more encodings contained within a wrapper &DESCRIPTION; element. In the language of <cite>RFC 4566</cite> these encodings are payload-types; therefore, each &lt;payload-type/&gt; child element specifies an encoding that can be used for the video stream. Such encodings are often used in the context of the Real-time Transfer Protocol (RTP; see <cite>RFC 3550</cite>) but may be used in other contexts as well. The most common encodings for the Audio/Video Profile (AVP) of RTP are listed in &rfc3551; (these "static" types are reserved from payload ID 0 through payload ID 95), although other encodings are allowed (these "dynamic" types use payload IDs 96 to 127) in accordance with the dynamic assignment rules described in Section 3 of <cite>RFC 3551</cite>. The &PAYLOADTYPE; element's 'id' attribute is REQUIRED and its 'name' attribute is RECOMMENDED. The encodings SHOULD be provided in order of preference.</p>
  <example caption="Video Description Format"><![CDATA[
    <description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
      <payload-type id='96' name='theora' clockrate='90000' height='720' width='1280'>
        <parameter name='delivery-method' value='inline'/>
        <parameter name='configutation' value='somebase16string'/>
        <parameter name='sampling' value='YCbCr-4:2:2'/>
      </payload-type>
      <payload-type id='28' name='nv' clockrate='90000'/>
      <payload-type id='25' name='CelB' clockrate='90000'/>
      <payload-type id='32' name='MPV' clockrate='90000'/>
    </description>
  ]]></example>
  <p>The &DESCRIPTION; element is intended to be a child of a &CONTENT; element as specified in <cite>XEP-0166</cite>.</p>
  <p>The defined attributes of the &PAYLOADTYPE; element are as follows:</p>
  <table caption='Video Description Attributes'>
    <tr>
      <th>Attribute</th>
      <th>Description</th>
      <th>Datatype/Units</th>
      <th>Inclusion</th>
    </tr>
    <tr>
      <td>channels</td>
      <td>The number of channels (e.g., 2 for stereoscopic video)</td>
      <td>positiveInteger (defaults to 1)</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>clockrate</td>
      <td>The sampling frequency in Hertz</td>
      <td>positiveInteger</td>
      <td>RECOMMENDED</td>
    </tr>
    <tr>
      <td>height</td>
      <td>The vertical extent of the displayed video, in pixels</td>
      <td>positiveInteger</td>
      <td>RECOMMENDED</td>
    </tr>
    <tr>
      <td>id</td>
      <td>A unique identifier for the payload type</td>
      <td>positiveInteger</td>
      <td>REQUIRED</td>
    </tr>
    <tr>
      <td>layer</td>
      <td>The relationship of a layer to the "bottom" of the stack, where 0 = bottom (the first layer)</td>
      <td>nonNegativeInteger</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>name</td>
      <td>A name for the payload type</td>
      <td>string</td>
      <td>RECOMMENDED for static payload types, REQUIRED for dynamic payload types</td>
    </tr>
    <tr>
      <td>transparent</td>
      <td>Whether or not a layer is transparent</td>
      <td>boolean</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>width</td>
      <td>The horizontal extent of the displayed video, in pixels</td>
      <td>positiveInteger</td>
      <td>RECOMMENDED</td>
    </tr>
    <tr>
      <td>x</td>
      <td>The horizontal starting point of a tile, in pixels from the origin point</td>
      <td>positiveInteger</td>
      <td>OPTIONAL</td>
    </tr>
    <tr>
      <td>y</td>
      <td>The vertical starting point of a tile, in pixels from the origin point</td>
      <td>positiveInteger</td>
      <td>OPTIONAL</td>
    </tr>
  </table>
  <p>Each &lt;payload-type/&gt; element MAY contain one or more child elements that specify particular parameters related to the payload. For example, as described in <cite>draft-ietf-avt-rtp-theora</cite> <note>This Internet-Draft has expired; see &lt;<link url='http://svn.xiph.org/trunk/theora/doc/draft-ietf-avt-rtp-theora-00.txt'>http://svn.xiph.org/trunk/theora/doc/draft-ietf-avt-rtp-theora-00.txt</link>&gt; for an archived version.</note>, the "configuration", "configuration-uri", "delivery-method", and "sampling", parameters may be specified in relation to usage of the Theora <note>See &lt;<link url='http://www.theora.org/'>http://www.theora.org/</link>&gt;.</note> codec. Where such parameters are encoded via the "fmtp" SDP attribute, they shall be represented in Jingle via the following format:</p>
  <code><![CDATA[
<parameter name='foo' value='bar'/>
  ]]></code>
  <p>Note: The parameter names are effectively guaranteed to be unique, since &IANA; maintains a registry of SDP parameters (see &lt;<link url='http://www.iana.org/assignments/sdp-parameters'>http://www.iana.org/assignments/sdp-parameters</link>&gt;).</p>
</section1>

<section1 topic='Negotiating a Jingle Video Session' anchor='negotiation'>
  <p>When the initiator sends a session-initiate stanza to the receiver, the &DESCRIPTION; element includes all of the payload types that the initiator can receive for Jingle video (each one encapsulated in a separate &PAYLOADTYPE; element):</p>
  <example caption="Initiation Example"><![CDATA[
<iq from='romeo@montague.net/orchard' 
    to='juliet@capulet.com/balcony' 
    id='jinglevideo1' 
    type='set'>
  <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'>
          action='session-initiate'
          initiator='romeo@montague.net/orchard'
          sid='v1d30k1ll3dth3r4d10st4r'>
    <content content='initiator' name='this-is-the-video-content' profile='RTP/AVP'>
      <description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
        <payload-type id='96' name='theora' clockrate='90000' height='720' width='1280'>
          <parameter name='delivery-method' value='inline'/>
          <parameter name='configutation' value='somebase16string'/>
          <parameter name='sampling' value='YCbCr-4:2:2'/>
        </payload-type>
        <payload-type id='28' name='nv' clockrate='90000'/>
        <payload-type id='25' name='CelB' clockrate='90000'/>
        <payload-type id='32' name='MPV' clockrate='90000'/>
      </description>
      <transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
    </content>
  </jingle>
</iq>
  ]]></example>
  <p>Upon receiving the session-initiate stanza, the receiver determines whether it can provisionally accept the session and proceed with the negotiation. The general Jingle error cases are specified in <cite>XEP-0166</cite>. In addition, the receiver must determine if it supports any of the payload types advertised by the initiator; if it does not, it MUST reject the session by sending a &lt;unsupported-codecs/&gt; error:</p>
  <example caption="Receiver Does Not Support Codecs"><![CDATA[
<iq type='error' 
    from='juliet@capulet.com/balcony' 
    to='romeo@montague.net/orchard' 
    id='jinglevideo1'>
  <error type='cancel'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unsupported-codecs xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns-errors'/>
  </error>
</iq>
  ]]></example>
  <p>If there is no error, the receiver provisionally accepts the session:</p>
  <example caption="Receiver Provisionally Accepts Session"><![CDATA[
  <iq from='juliet@capulet.com/balcony' 
      to='romeo@montague.net/orchard' 
      id='jinglevideo1' 
      type='result' />
  ]]></example>
  <p>The receiver then should send a list of the payload types that it can receive via a Jingle "content-accept" (or "session-accept") action. The list that the receiver sends MAY include any payload types (not a subset of the payload types sent by the initiator) but SHOULD retain the ID numbers and order specified by the initiator.</p>
  <example caption="Receiver Accepts Content Type"><![CDATA[
<iq from='juliet@capulet.com/balcony' 
    to='romeo@montague.net/orchard' 
    id='jinglevideo2' 
    type='set'>
  <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'>
          action='content-accept'
          initiator='romeo@montague.net/orchard'
          sid='v1d30k1ll3dth3r4d10st4r'>
    <content content='initiator' name='this-is-the-video-content' profile='RTP/AVP'>
      <description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'>
        <payload-type id='96' name='theora' height='720' width='1280'>
          <parameter name='delivery-method' value='inline'/>
          <parameter name='configutation' value='somebase16string'/>
          <parameter name='sampling' value='YCbCr-4:2:2'/>
        </payload-type>
        <payload-type id='32' name='MPV' clockrate='90000'/>
        <payload-type id='33' name='MP2T' clockrate='90000'/>
      </description> 
    <transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
    </content>
  </jingle>
</iq>
  ]]></example>
  <p>The initiator acknowledges the 'content-accept' with an empty IQ result:</p>
  <example caption="Initiator Acknowledges Modified Content Description"><![CDATA[
  <iq from='romeo@montegue.net/orchard' 
      to='juliet@capulet.com/balcony' 
      id='jinglevideo2' 
      type='result' />
  ]]></example>
  <p>After successful transport negotiation (not shown here), the receiver then accepts the session:</p>
  <example caption="Receiver Definitively Accepts the Session"><![CDATA[
<iq type='set' 
    from='juliet@capulet.com/balcony' 
    to='romeo@montague.net/orchard' 
    id='accept1'>
  <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
          action='session-accept'
          initiator='romeo@montague.net/orchard'
          responder='juliet@capulet.com/balcony'
          sid='v1d30k1ll3dth3r4d10st4r'>
    <content creator='initiator' name='this-is-the-video-content' profile='RTP/AVP'>
      <description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'/>
      <transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'>
        <candidate component='2'
                   foundation='1'
                   generation='0' 
                   ip='192.0.2.3' 
                   network='1'
                   port='45664'
                   priority='1107821052'
                   protocol='udp'
                   pwd='asd88fgpdd777uzjYhagZg'
                   type='srflx'
                   ufrag='8hhy'/>
      </transport>
    </content>
  </jingle>
</iq>
  ]]></example>
  <p>And the initiator acknowledges session acceptance:</p>
  <example caption="Initiator Acknowledges Session Acceptance"><![CDATA[
  <iq from='romeo@montague.net/orchard' 
      to='juliet@capulet.com/balcony' 
      id='accept1' 
      type='result' />
  ]]></example>
</section1>

<section1 topic='Mapping to Session Description Protocol' anchor='sdp'>
  <p>If the payload type is static (payload-type IDs 0 through 95 inclusive), it MUST be mapped to a media field defined in <cite>RFC 4566</cite>. The generic format for the media field is as follows:</p>
  <code><![CDATA[
m=<media> <port> <transport> <fmt list>
  ]]></code>
  <p>In the context of Jingle video sessions, the &lt;media&gt; is "video", the &lt;port&gt; is the preferred port for such communications (which may be determined dynamically), the &lt;transport&gt; is whatever transport method is negotiated via the Jingle negotiation (e.g., "RTP/AVT"), and the &lt;fmt list&gt; is the payload-type ID.</p>
  <p>For example, consider the following static payload-type:</p>
  <example caption="Jingle Format for Static Payload-Type"><![CDATA[
<payload-type id="28" name="nv"/>
  ]]></example>
  <example caption="SDP Mapping of Static Payload-Type"><![CDATA[
m=video 9000 RTP/AVP 28
  ]]></example>
  <p>If the payload type is dynamic (payload-type IDs 96 through 127 inclusive), it SHOULD be mapped to an SDP media field plus an SDP attribute field named "rtpmap".</p>
  <p>For example, consider a VC-1 payload such as that described in &rfc4425;:</p>
  <example caption="Jingle Format for Dynamic Payload-Type"><![CDATA[
<payload-type id='98' name='vc1' height='288' width='352'/>
  ]]></example>
  <example caption="SDP Mapping of Dynamic Payload-Type"><![CDATA[
m=video 49170 RTP/AVP 98
a=rtpmap:98 vc1/90000
a=fmtp:98 width=352;height=288;
  ]]></example>
  <p>As noted, if additional parameters are to be specified, they shall be represented as attributes of the &lt;payload-type/&gt; element of the child &lt;parameter/&gt; element, as in the following example.</p>
  <example caption="Jingle Format for Dynamic Payload-Type With Parameters"><![CDATA[
<payload-type id='96' name='theora' height='720' width='1280'>
  <parameter name='delivery-method' value='inline'/>
  <parameter name='configutation' value='somebase16string'/>
  <parameter name='sampling' value='YCbCr-4:2:2'/>
</payload-type>
  ]]></example>
  <example caption="SDP Mapping of Dynamic Payload-Type With Parameters"><![CDATA[
m=video 49170 RTP/AVP 98
a=rtpmap:96 theora/90000
a=fmtp:96 sampling=YCbCr-4:2:2; width=1280; height=720; 
delivery-method=inline; configuration=somebase16string;
  ]]></example>
</section1>

<section1 topic='Determining Support' anchor='support'>
  <p>If an entity supports Jingle video exchanges via RTP, it MUST advertise that fact by returning a feature of "http://www.xmpp.org/extensions/xep-0180.html#ns" in response to &xep0030; information requests.</p>
  <example caption="Service Discovery Information Request"><![CDATA[
<iq from='romeo@montague.net/orchard' 
    id='disco1'
    to='juliet@capulet.com/balcony' 
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  ]]></example>
  <example caption="Service Discovery Information Response"><![CDATA[
<iq from='juliet@capulet.com/balcony' 
    id='disco1'
    to='romeo@montague.net/orchard' 
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://www.xmpp.org/extensions/xep-0166.html#ns'/>
    <feature var='http://www.xmpp.org/extensions/xep-0180.html#ns'/>
    ...
  </query>
</iq>
  ]]></example>
</section1>

<section1 topic='Informational Messages' anchor='info'>
  <p>Informational messages may be sent by either party within the context of Jingle to communicate the status of a Jingle video session, device, or principal. The informational message MUST be an IQ-set containing a &JINGLE; element of type "session-info", where the informational message is a payload  element qualified by the 'http://www.xmpp.org/extensions/xep-0180.html#ns-info' namespace. No payload elements have yet been defined, but may be specified in a future version of this document.</p>
</section1>

<section1 topic='Implementation Notes' anchor='impl'>
  <section2 topic='Codecs' anchor='impl-codecs'>
    <p>Support for the Theora codec is RECOMMENDED.</p>
  </section2>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>In order to secure the data stream, implementations SHOULD use encryption methods appropriate to the transport method and media being exchanged; for example, in the case of UDP, that would include Datagram Transport Layer Security (DTLS) as specified in &rfc4347;. &sdpdtls; defines such methods for the Session Description Protocol; the relevant RTP profile (e.g., "UDP/TLS/RTP/AVP" for transporting the RTP stream over DTLS with UDP) shall be specified as the value of the &CONTENT; element's 'profile' attribute.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='ns'>
    <p>Until this specification advances to a status of Draft, its associated namespaces shall be "http://www.xmpp.org/extensions/xep-0180.html#ns" and "http://www.xmpp.org/extensions/xep-0180.html#ns-info"; upon advancement of this specification, the &REGISTRAR; shall issue permanent namespaces in accordance with the process defined in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Jingle Content Description Formats' anchor='registrar-content'>
    <p>The XMPP Registrar shall include "video-rtp" in its registry of Jingle content description formats. The registry submission is as follows:</p>
    <code><![CDATA[
<content>
  <name>video-rtp</name>
  <desc>Jingle sessions that support video exchange via the Real-time Transport Protocol</desc>
  <transport>lossy</transport>
  <doc>XEP-0180</doc>
</content>
    ]]></code>
  </section2>
</section1>

<section1 topic='XML Schemas' anchor='schema'>
  <section2 topic='Content Description Format' anchor='schema-content'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://www.xmpp.org/extensions/xep-0180.html#ns'
    xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'
    elementFormDefault='qualified'>

  <xs:element name='description'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='payload-type' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='payload-type'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='channels' type='xs:integer' use='optional' default='1'/>
          <xs:attribute name='height' type='xs:nonNegativeInteger' use='optional'/>
          <xs:attribute name='id' type='xs:unsignedByte' use='required'/>
          <xs:attribute name='layer' type='xs:nonNegativeInteger' use='optional'/>
          <xs:attribute name='name' type='xs:string' use='optional'/>
          <xs:attribute name='rate' type='xs:short' use='optional'/>
          <xs:attribute name='transparent' type='xs:boolean' use='optional'/>
          <xs:attribute name='width' type='xs:nonNegativeInteger' use='optional'/>
          <xs:attribute name='x' type='xs:integer' use='optional'/>
          <xs:attribute name='y' type='xs:integer' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    ]]></code>
  </section2>
</section1>
</xep>