xeps/xep-0339.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>Source-Specific Media Attributes in Jingle</title>
  <abstract>This specification provides an XML mapping for translating the RFC 5766 Source-Specific Media Attributes from SDP to Jingle</abstract>
  &LEGALNOTICE;
  <number>0339</number>
  <status>Draft</status>
  <lastcall>2020-05-19</lastcall>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XEP-0166</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  &fippo;
  <revision>
    <version>1.0.1</version>
    <date>2021-10-23</date>
    <initials>egp</initials>
    <remark><p>Add a XML Schema, and fix an example lacking a namespace.</p></remark>
  </revision>
  <revision>
    <version>1.0.0</version>
    <date>2020-05-26</date>
    <initials>XEP Editor (jsc)</initials>
    <remark><p>Move to Draft as per Council vote from 2020-05-20.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2017-09-11</date>
    <initials>XEP Editor (jwi)</initials>
    <remark>Defer due to lack of activity.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2015-11-09</date>
    <initials>ph</initials>
    <remark><p>remove obsolete mslabel and label lines.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2014-01-08</date>
    <initials>psa</initials>
    <remark><p>Initial published version approved by the XMPP Council.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2013-11-25</date>
    <initials>ph</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic="Introduction" anchor="intro">
  <p>&rfc5576; provides a mechanism to describe attributes of individual media sources (identified by their synchronization source) within a media stream. A mapping to Jingle as an extension to &xep0167; is defined in this document.</p>
</section1>
<section1 topic='Mapping to Session Description Protocol' anchor='sdp'>
  <section2 topic='The ssrc attribute' anchor='sdp-ssrc'>
    <p>The SDP format defined in <cite>RFC 5576</cite> is shown below.</p>
    <code>
a=ssrc:&lt;ssrc-id&gt; &lt;attribute&gt;
a=ssrc:&lt;ssrc-id&gt; &lt;attribute&gt;:&lt;value&gt;
    </code>
    <p>This maps to Jingle as a &lt;source/&gt; element qualified by the 'urn:xmpp:jingle:apps:rtp:ssma:0' namespace. Since 'ssrc' is a media attribute in SDP, the &lt;source/&gt; element is included as child of the Jingle &lt;description/&gt; element.</p>
    <code><![CDATA[
<source ssrc='ssrc-id' xmlns='urn:xmpp:jingle:apps:rtp:ssma:0'>
    <parameter name='attribute'/>
    <parameter name='attribute' value='value'/>
</source>
]]></code>
    <p>Each ssrc-id maps to a &lt;source/&gt; element whose 'ssrc' attribute is set to the ssrc-id. The associated attributes map to &lt;parameter/&gt; children with 'name' and 'value' attributes. If there is no value in the SDP, the value parameter shall be omitted.</p>
    <p>An example follows:</p>
    <code>
a=ssrc:1656081975 cname:Yv/wvbCdsDW2Prgd
a=ssrc:1656081975 msid:MLTJKIHilGn71fNQoszkQ4jlPTuS5vJyKVIv MLTJKIHilGn71fNQoszkQ4jlPTuS5vJyKVIva0</code>
    <code><![CDATA[
<source ssrc='1656081975' xmlns='urn:xmpp:jingle:apps:rtp:ssma:0'>
    <parameter name='cname' value='Yv/wvbCdsDW2Prgd'/>
    <parameter name='msid' value='MLTJKIHilGn71fNQoszkQ4jlPTuS5vJyKVIv MLTJKIHilGn71fNQoszkQ4jlPTuS5vJyKVIva0'/>
</source>]]></code>
  </section2>
  <section2 topic='The ssrc-group attribute' anchor='sdp-ssrc-group'>
    <p>The SDP format defined in <cite>RFC 5576</cite> is shown below.</p>
    <code>
a=ssrc-group:&lt;semantics&gt; &lt;ssrc-id&gt; ...</code>
    <p>This maps to Jingle as a &lt;ssrc-group/&gt; element qualified by the 'urn:xmpp:jingle:apps:rtp:ssma:0' namespace. Like the &lt;source/&gt; element, this is included as child of the Jingle &lt;description/&gt; element. The SDP 'semantics' parameter is mapped to the semantics attribute (for consistency with &xep0338;) and the list of ssrc-ids is mapped to &lt;source/&gt; elements whole 'ssrc' attribute is set to the ssrc-id.</p>
    <code><![CDATA[
<ssrc-group xmlns='urn:xmpp:jingle:apps:rtp:ssma:0' semantics='semantics'>
   <source ssrc='ssrc-id'/>
   [...]
</ssrc-group>]]></code>
  </section2>
</section1>
<section1 topic='Example' anchor='example'>
  <p>A minimal example follows:</p>
    <code>
m=video 1 RTP/SAVPF 100 116 117
a=rtpmap:100 VP8/90000
a=ssrc-group:FID 2301230316 386328120
a=ssrc:2301230316 cname:T5qvrIZj42v//eYQ
a=ssrc:386328120 cname:uEYgNtStZyTF74sM
a=ssrc-group:FID 3139499595 2613715171
a=ssrc:3139499595 cname:re8jhxkly9bxzuxr
a=ssrc:2613715171 cname:f83avsiw6n1m7vi
    </code>
    <p>This is mapped to Jingle as follows:</p>
    <code><![CDATA[
<content xmlns='http://jabber.org/protocols/jingle' creator='initiator' name='webcam'>
  <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
    <payload-type id='100' name='VP8' clockrate='90000'/>
    <ssrc-group xmlns='urn:xmpp:jingle:apps:rtp:ssma:0' semantics='FID'>
      <source ssrc='2301230316'/>
      <source ssrc='386328120'/>
    </ssrc-group>
    <ssrc-group xmlns='urn:xmpp:jingle:apps:rtp:ssma:0' semantics='FID'>
      <source ssrc='3139499595'/>
      <source ssrc='2613715171'/>
    </ssrc-group>
    <source ssrc='2301230316' xmlns='urn:xmpp:jingle:apps:rtp:ssma:0'>
      <parameter name='cname' value='T5qvrIZj42v//eYQ'/>
    </source>
    <source ssrc='386328120' xmlns='urn:xmpp:jingle:apps:rtp:ssma:0'>
      <parameter name='cname' value='uEYgNtStZyTF74sM'/>
    </source>
    <source ssrc='3139499595' xmlns='urn:xmpp:jingle:apps:rtp:ssma:0'>
      <parameter name='cname' value='re8jhxkly9bxzuxr'/>
    </source>
    <source ssrc='2613715171' xmlns='urn:xmpp:jingle:apps:rtp:ssma:0'>
      <parameter name='cname' value='f83avsiw6n1m7vi'/>
    </source>
  </description>
</content>
]]></code>
</section1>
<section1 topic='Determining Support' anchor='disco'>
  <p>If an entity supports source specific media attributes as described in <cite>RFC 5576</cite>, it MUST advertise that fact in its responses to &xep0030; information ("disco#info") requests by returning a feature of 'urn:ietf:rfc:5576':</p>
  <example caption='A disco#info query'><![CDATA[
<iq type='get'
    from='calvin@usrobots.lit/lab'
    to='herbie@usrobots.lit/home'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
  <example caption='A disco#info response'><![CDATA[
<iq type='result'
    from='herbie@usrobots.lit/home'
    to='calvin@usrobots.lit/lab'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:jingle:1'/>
    <feature var='urn:ietf:rfc:5576'/>
  </query>
</iq>
]]></example>
  <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>
<!--
<section1 topic='Acknowledgements' anchor='acks'>
</section1>
-->
<section1 topic='Security Considerations' anchor='security'>
  <p>This document introduces no additional security considerations above and beyond those defined in the documents on which it depends.</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='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:jingle:apps:rtp:ssma:0</li>
    </ul>
    <p>The &REGISTRAR; includes the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:jingle:apps:rtp:ssma:0'
    xmlns='urn:xmpp:jingle:apps:rtp:ssma:0'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0339: http://www.xmpp.org/extensions/xep-0339.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='ssrc-group'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='source'
                    minOccurs='0'
                    maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='semantics' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='LS'/>
            <xs:enumeration value='FID'/>
            <xs:enumeration value='SRF'/>
            <xs:enumeration value='ANAT'/>
            <xs:enumeration value='FEC'/>
            <xs:enumeration value='DDP'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <xs:element name='source'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='parameter'
                    minOccurs='0'
                    maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='ssrc' type='xs:unsignedInt' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='parameter'>
    <xs:complexType>
      <xs:attribute name='name' type='xs:string' use='required'/>
      <xs:attribute name='value' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

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