git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1424 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-11-27 19:46:25 +00:00
parent 38020c4a0c
commit 5abc78599f
1 changed files with 65 additions and 48 deletions

View File

@ -27,6 +27,12 @@
<surname>Chen</surname>
<email>Milton.Chen@vseelab.com</email>
</author>
<revision>
<version>0.10</version>
<date>2007-11-27</date>
<initials>psa</initials>
<remark><p>Further editorial review.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2007-11-15</date>
@ -118,8 +124,8 @@
</section1>
<section1 topic='Application Format' anchor='format'>
<p>A Jingle video session is described by a content type that contains one application format and one transport method. The application format consists of one or more encodings contained within a wrapper &DESCRIPTION; element qualified by the 'http://www.xmpp.org/extensions/xep-0180.html#ns' namespace &NSNOTE;. 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. In Jingle Video, 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>
<example caption="Video application format"><![CDATA[
<p>A Jingle video session is described by a content type that contains one application format and one transport method. The application format consists of one or more encodings contained within a wrapper &lt;description/&gt; element qualified by the 'http://www.xmpp.org/extensions/xep-0180.html#ns' namespace &NSNOTE;. In the language of <cite>RFC 4566</cite> each encoding is a payload-type; therefore, each &lt;payload-type/&gt; element specifies an encoding that can be used for the audio stream, as illustrated in the following example.</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'/>
@ -132,9 +138,10 @@
</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 &CONTENT; element SHOULD possess a 'profile' attribute that specifies the exact protocol in use as would be encapsulated in SDP (e.g., "RTP/AVP" or "UDP/TLS/RTP/AVP").</p>
<p>The encodings SHOULD be provided in order of preference by placing the most-preferred &PAYLOADTYPE; element as the first child of the &DESCRIPTION; element (etc.).</p>
<p>The defined attributes of the &PAYLOADTYPE; element are as follows:</p>
<table caption='Video Description Attributes'>
<p>The allowable attributes of the &PAYLOADTYPE; element are as follows:</p>
<table caption='Payload-Type Attributes'>
<tr>
<th>Attribute</th>
<th>Description</th>
@ -202,7 +209,8 @@
<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 &rtptheora;, 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, where the &lt;parameter/&gt; element is a child of the &PAYLOADTYPE; element:</p>
<p>In Jingle Video, the 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 payload IDs are represented in the 'id' attribute.</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 &rtpspeex;, the "cng", "mode", 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>
@ -210,11 +218,11 @@
</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>
<p>When the initiator sends a session-initiate stanza to the responder, 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"><![CDATA[
<iq from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='jinglevideo1'
<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'
@ -236,30 +244,30 @@
</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> and illustrated &xep0167;. In addition, the receiver must determine if it supports any of the payload types advertised by the initiator; if it supports none of the offered payload types, it must reject the session by returning a &notacceptable; error with a Jingle-Video-specific condition of &lt;unsupported-codecs/&gt;:</p>
<example caption="Receiver does not support any of the codecs"><![CDATA[
<iq type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='jingleaudio1'>
<p>Upon receiving the session-initiate stanza, the responder determines whether it can proceed with the negotiation. The general Jingle error cases are specified in <cite>XEP-0166</cite> and illustrated &xep0167;. In addition, the responder must determine if it supports any of the payload types advertised by the initiator; if it supports none of the offered payload types, it must reject the session by returning a &notacceptable; error with a Jingle-Video-specific condition of &lt;unsupported-codecs/&gt;:</p>
<example caption="Responder does not support any of the codecs"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='jingleaudio1'
to='romeo@montague.net/orchard'
type='error'>
<error type='cancel'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<unsupported-codecs xmlns='http://www.xmpp.org/extensions/xep-0180.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'
<p>If there is no error, the responder acknowledges the session initiation request:</p>
<example caption="Responder acknowledges session-initiate request"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='jinglevideo1'
to='romeo@montague.net/orchard'
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 specified by the initiator. The order of the &PAYLOADTYPE; elements indicates the receiver's preferences, with the most-preferred types first.</p>
<example caption="Receiver accepts content type"><![CDATA[
<iq from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='jinglevideo2'
<p>The responder 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 responder sends MAY include any payload types (not a subset of the payload types sent by the initiator) but SHOULD retain the ID numbers specified by the initiator. The order of the &PAYLOADTYPE; elements indicates the responder's preferences, with the most-preferred types first.</p>
<example caption="Responder 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'
@ -274,7 +282,7 @@
</payload-type>
<payload-type id='32' name='MPV' clockrate='90000'/>
<payload-type id='33' name='MP2T' clockrate='90000'/>
</description>
</description>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
</content>
</jingle>
@ -282,29 +290,37 @@
]]></example>
<p>The initiator acknowledges the 'content-accept' with an empty IQ result:</p>
<example caption="Initiator acknowledges modified application type"><![CDATA[
<iq from='romeo@montegue.net/orchard'
to='juliet@capulet.com/balcony'
id='jinglevideo2'
<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'>
<p>After successful transport negotiation (not shown here), the responder then accepts the session:</p>
<example caption="Responder definitively accepts the session"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='accept1'
to='romeo@montague.net/orchard'
type='set'>
<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-0180.html#ns'/>
<description xmlns='http://www.xmpp.org/extensions/xep-0180.html#ns'>
<payload-type id='96' name='theora' height='720' width='1280'>
<parameter name='delivery-method' value='inline'/>
<parameter name='configuration' 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'>
<candidate component='2'
foundation='1'
generation='0'
ip='192.0.2.3'
generation='0'
ip='192.0.2.3'
network='1'
port='45664'
priority='1107821052'
@ -319,9 +335,9 @@
]]></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'
<iq from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='accept1'
type='result' />
]]></example>
<p>Note: Because a "session-accept" action implicitly indicates acceptance of the application format (i.e., "content-accept"), it is not necessary to send a separate "content-accept" action. This flow is shown for completeness only.</p>
@ -364,7 +380,7 @@ a=fmtp:98 width=352;height=288;
<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;
a=fmtp:96 sampling=YCbCr-4:2:2; width=1280; height=720;
delivery-method=inline; configuration=somebase16string;
]]></example>
</section1>
@ -388,17 +404,17 @@ delivery-method=inline; configuration=somebase16string;
<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 &NSNOTE;.</p>
<example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.net/orchard'
<iq from='romeo@montague.net/orchard'
id='disco1'
to='juliet@capulet.com/balcony'
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'
<iq from='juliet@capulet.com/balcony'
id='disco1'
to='romeo@montague.net/orchard'
to='romeo@montague.net/orchard'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
@ -408,10 +424,11 @@ delivery-method=inline; configuration=somebase16string;
</query>
</iq>
]]></example>
<p>Naturally, support may also be discovered via the dynamic, presence-based profile of service discovery defined in &xep0115;.</p>
</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". No informational message payload elements have yet been defined, but they may be specified in a future version of this document.</p>
<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". No informational message payload elements have yet been defined for Jingle Video via RTP, but they may be specified in a future version of this document.</p>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
@ -470,11 +487,11 @@ delivery-method=inline; configuration=somebase16string;
<xs:element ref='parameter'/>
</xs:sequence>
<xs:attribute name='channels' type='xs:integer' use='optional' default='1'/>
<xs:attribute name='clockrate' type='xs:short' use='optional'/>
<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'/>