0.6-pre2

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@134 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0167.xml

@@ -10,7 +10,7 @@
   <abstract>This document defines a content description format for Jingle audio sessions.</abstract>
   &LEGALNOTICE;
   <number>0167</number>
-  <status>Experimental</status>
+  <status>Proposed</status>
   <type>Standards Track</type>
   <jig>Standards JIG</jig>
   <approver>Council</approver>
@@ -27,8 +27,8 @@
   <revision>
     <version>0.6</version>
     <date>2006-10-30</date>
-    <initials>psa</initials>
+    <initials>psa/se</initials>
-    <remark><p>Revised schema to allow child elements of the payload-type element; added Speex examples.</p></remark>
+    <remark><p>Specified how to include SDP parameters and codec-specific parameters; added Speex examples.</p></remark>
   </revision>
   <revision>
     <version>0.5</version>
@@ -91,8 +91,46 @@
   </ol>
 </section1>
 <section1 topic='Content Description Format' anchor='format'>
-  <p>A Jingle audio session is described by one or more encodings contained within a wrapper &lt;description/&gt; element. In the language of <cite>RFC 4566</cite> these encodings are payload-types; therefore, each &lt;payload-type/&gt; element specifies an encoding that can be used for the audio stream. In Jingle Audio, these encodings are used in the context of RTP. 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 'id' attribute is REQUIRED. The 'name' attribute is RECOMMENDED for static payload types, and REQUIRED for dynamic payload types. The 'clockrate' attribute is RECOMMENDED and should specify the sampling frequency in hertz. The 'channels' attribute is RECOMMENDED and should specify the number of channels; if omitted, it MUST be assumed to contain one channel.</p>
+  <p>A Jingle audio session is described by one or more encodings contained within a wrapper &lt;description/&gt; element. In the language of <cite>RFC 4566</cite> these encodings are payload-types; therefore, each &lt;payload-type/&gt; element specifies an encoding that can be used for the audio stream. In Jingle Audio, these encodings are used in the context of RTP. 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>.</p>
-<p>The encodings SHOULD be provided in order of preference.</p>
+  <p>The allowable attributes are as follows:</p>
+  <table>
+    <tr>
+      <th>Attribute</th>
+      <th>Description</th>
+      <th>Inclusion</th>
+    </tr>
+    <tr>
+      <td>channels</td>
+      <td>The number of channels; if omitted, it MUST be assumed to contain one channel</td>
+      <td>RECOMMENDED</td>
+    </tr>
+    <tr>
+      <td>clockrate</td>
+      <td>The sampling frequency in Hert</td>
+      <td>RECOMMENDED</td>
+    </tr>
+    <tr>
+      <td>id</td>
+      <td>The payload identifier</td>
+      <td>REQUIRED</td>
+    </tr>
+    <tr>
+      <td>maxptime</td>
+      <td>Maximum packet time as specified in RFC 4566</td>
+      <td>OPTIONAL</td>
+    </tr>
+    <tr>
+      <td>name</td>
+      <td>The appropriate subtype of the audio MIME type</td>
+      <td>RECOMMENDED for static payload types, REQUIRED for dynamic payload types</td>
+    </tr>
+    <tr>
+      <td>ptime</td>
+      <td>Packet time as specified in RFC 4566</td>
+      <td>OPTIONAL</td>
+    </tr>
+  </table>
+  <p>The encodings SHOULD be provided in order of preference.</p>
   <example caption="Audio Description Format"><![CDATA[
     <description xmlns='http://jabber.org/protocol/jingle/description/audio'>
       <payload-type id='96' name='SPEEX' clockrate='16000'/>
@@ -111,7 +149,11 @@
     </description>
   ]]></example>
   <p>The &lt;description/&gt; element is intended to be a child of a &JINGLE; element as specified in <cite>XEP-0166</cite>.</p>
-  <p>Each &lt;payload-type/&gt; element MAY contain a child element that specifies more detailed information. For example, as described in <cite>draft-ietf-avt-rtp-speex</cite>, the "ptime", "sr", "ebw", "vbr", "eng", and "mode" parameters may be specified in relation to usage of the Speex <note>See &lt;<link url='http://www.speex.org/'>http://www.speex.org/</link>&gt;.</note> codec. XML representation of such parameters shall be provided in separate specifications or in a registry to be maintained by the XMPP Registrar.</p>
+  <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-speex</cite> <note>This Internet-Draft has expired; see &lt;<link url='http://www.watersprings.org/pub/id/draft-ietf-avt-rtp-speex-00.txt'>http://www.watersprings.org/pub/id/draft-ietf-avt-rtp-speex-00.txt</link>&gt; for an archived version.</note>, the "ebw", "eng", "mode", "sr", and "vbr" parameters may be specified in relation to usage of the Speex <note>See &lt;<link url='http://www.speex.org/'>http://www.speex.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>The parameter names are 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='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: Session Description Protocol</cite> (SDP). The generic format for the media field is as follows:</p>
@@ -135,6 +177,19 @@ m=audio 9999 RTP/AVP 13
 m=audio 9999 RTP/AVP 96
 a=rtpmap:96 SPEEX/16000
   ]]></example>
+  <p>As noted, if additional parameters are to be specified, they shall be represented as attributes of the &lt;payload-type/&gt; element or 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='SPEEX' clockrate='16000' ptime='40'>
+  <parameter name='vbr' value='on'/>
+  <parameter name='cng' value='on'/>
+</payload-type>
+  ]]></example>
+  <example caption="SDP Mapping of Dynamic Payload-Type With Parameters"><![CDATA[
+m=audio 9999 RTP/AVP 96
+a=rtpmap:96 SPEEX/16000
+a=ptime:40
+a=fmtp:96 vbr=on;cng=on
+  ]]></example>
 </section1>
 <section1 topic='Service Discovery' anchor='disco'>
   <p>If an entity supports the Jingle audio content description format, it MUST advertise that fact by returning a feature of "http://jabber.org/protocol/jingle/description/audio" in response to &xep0030; information requests.</p>
@@ -308,24 +363,43 @@ a=rtpmap:96 SPEEX/16000
 
   <xs:element name='description'>
     <xs:complexType>
-      <xs:sequence>
+      <xs:sequence minOccurs='0' maxOccurs='unbounded'/>
-        <xs:element ref='payload-type' minOccurs='0' maxOccurs='unbounded'/>
+        <xs:element ref='payload-type'/>
       </xs:sequence>
     </xs:complexType>
   </xs:element>
 
   <xs:element name='payload-type'>
     <xs:complexType>
-      <xs:sequence minOccurs='0' maxOccurs='1'>
+      <xs:sequence minOccurs='0' maxOccurs='unbounded'>
-        <xs:any namespace='##other'/>
+        <xs:element ref='parameter'/>
       </xs:choice>
       <xs:attribute name='channels' type='xs:byte' use='optional' default='1'/>
       <xs:attribute name='clockrate' type='xs:short' use='optional'/>
       <xs:attribute name='id' type='xs:unsignedByte' use='required'/>
+      <xs:attribute name='maxptime' type='xs:short' use='optional'/>
       <xs:attribute name='name' type='xs:string' use='optional'/>
+      <xs:attribute name='ptime' type='xs:short' use='optional'/>
     </xs:complexType>
   </xs:element>
 
+  <xs:element name='parameter'>
+    <xs:complexType>
+      <xs:simpleContent>
+        <xs:extension base='empty'>
+          <xs:attribute name='name' type='xs:string' use='required'/>
+          <xs:attribute name='value' type='xs:string' use='required'/>
+        </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>