xeps/xep-0118.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>User Tune</title>
  <abstract>This document defines an XMPP protocol extension for communicating information about the music to which a user is listening.</abstract>
  &LEGALNOTICE;
  <number>0118</number>
  <status>Draft</status>
  <type>Standards Track</type>
  <jig>Standards JIG</jig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0060</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>tune</shortname>
  <schemaloc>
    <url>http://www.xmpp.org/schemas/tune.xsd</url>
  </schemaloc>
  &stpeter;
  <revision>
    <version>1.0</version>
    <date>2004-11-12</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
  </revision>
  <revision>
    <version>0.10</version>
    <date>2004-10-29</date>
    <initials>psa</initials>
    <remark>Added example with URL.</remark>
  </revision>
  <revision>
    <version>0.9</version>
    <date>2004-10-27</date>
    <initials>psa</initials>
    <remark>Changed recommendation to not include the &lt;length/&gt; element if the track time is unknown.</remark>
  </revision>
  <revision>
    <version>0.8</version>
    <date>2004-10-26</date>
    <initials>psa</initials>
    <remark>Added implementation notes; clarified nature of &lt;source/&gt; and &lt;track/&gt; elements; if length is unknown, set to zero.</remark>
  </revision>
  <revision>
    <version>0.7</version>
    <date>2004-05-20</date>
    <initials>psa</initials>
    <remark>Changed &lt;length/&gt; datatype from xs:duration to xs:unsignedShort.</remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2004-04-25</date>
    <initials>psa</initials>
    <remark>Corrected several errors; added reference to XEP-0033.</remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2004-02-19</date>
    <initials>psa</initials>
    <remark>Reverted from infobits to tune elements.</remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2003-12-14</date>
    <initials>psa</initials>
    <remark>Slight modifications to track changes to infobits JEPs.</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2003-10-23</date>
    <initials>psa</initials>
    <remark>Replaced tune elements with infobits.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2003-09-10</date>
    <initials>psa</initials>
    <remark>Added "stop" function via empty &lt;tune/&gt; element.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2003-09-08</date>
    <initials>psa</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>This document defines a protocol for communicating information about the music to which a user is listening. Such information may be seen as a kind of "extended presence", and users may want to communicate such information to their contacts on the network as a fun add-on to traditional IM applications or to provide integration with common music-player applications.</p>
</section1>
<section1 topic='Protocol' anchor='protocol'>
  <section2 topic='Container Element and Child Elements' anchor='protocol-elements'>
    <p>Information about tunes is provided by the user and propagated on the network by the user's client. The information container for tune data is a &lt;tune/&gt; element that is qualified by the 'http://jabber.org/protocol/tune' namespace. The tune information itself is provided as the XML character data of the following children of the &lt;tune/&gt; element:</p>
    <table caption='Child Elements'>
      <tr>
        <th>Element</th>
        <th>Description</th>
        <th>Example</th>
        <th>Datatype</th>
      </tr>
      <tr>
        <td>artist</td>
        <td>The artist or performer of the song or piece</td>
        <td>Yes</td>
        <td>xs:string</td>
      </tr>
      <tr>
        <td>title</td>
        <td>The title of the song or piece</td>
        <td>Heart of the Sunrise</td>
        <td>xs:string</td>
      </tr>
      <tr>
        <td>source</td>
        <td>The collection (e.g., album) or other source (e.g., a band website that hosts streams or audio files)</td>
        <td>Yessongs</td>
        <td>xs:string</td>
      </tr>
      <tr>
        <td>track</td>
        <td>A unique identifier for the tune; e.g., the track number within a collection or the specific URI for the object (e.g., a stream or audio file)</td>
        <td>3</td>
        <td>xs:string</td>
      </tr>
      <tr>
        <td>length</td>
        <td>The duration of the song or piece in seconds</td>
        <td>686</td>
        <td>xs:unsignedShort</td>
      </tr>
    </table>
    <p>NOTE: The datatypes specified above are defined in &w3xmlschema2;.</p>
  </section2>
  <section2 topic='Transport Mechanism' anchor='protocol-transport'>
    <p>Tune information SHOULD be communicated and transported by means of the &xep0060; protocol. Because tune information is not pure presence information and can change independently of the user's availability, it SHOULD NOT be provided as an extension to &PRESENCE;.</p>
    <example caption='User Publishes Tune Information'><![CDATA[
<iq type='set'
    from='stpeter@jabber.org/work'
    to='pubsub.jabber.org'
    id='tunes123'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='generic/tunes/stpeter@jabber.org'>
      <item id='current'>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Yes</artist>
          <title>Heart of the Sunrise</title>
          <source>Yessongs</source>
          <track>3</track>
          <length>686</length>
        </tune>
      </item>
    </publish>
  </pubsub>
</iq>
    ]]></example>
    <p>The tune information is then delivered to all subscribers:</p>
    <example caption='Tune Information is Delivered to All Subscribers'><![CDATA[
<message
    from='pubsub.jabber.org'
    to='maineboy@jabber.org'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='generic/tunes/stpeter@jabber.org'>
      <item id='current'>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Yes</artist>
          <title>Heart of the Sunrise</title>
          <source>Yessongs</source>
          <track>3</track>
          <length>686</length>
        </tune>
      </item>
    </items>
  </event>
</message>
.
.
.
    ]]></example>
    <p>As mentioned in XEP-0060, the stanza containing the event notification or payload MAY also include 'replyto' data (as specified by the &xep0033; protocol) to provide an explicit association between the published data and the user:</p>
    <example caption="Event notification with extended stanza addressing"><![CDATA[
<message
    from='pubsub.jabber.org'
    to='maineboy@jabber.org'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='generic/tunes/stpeter@jabber.org'>
      <item id='current'>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Yes</artist>
          <title>Heart of the Sunrise</title>
          <source>Yessongs</source>
          <track>3</track>
          <length>686</length>
        </tune>
      </item>
    </items>
  </event>
  <addresses xmlns='http://jabber.org/protocol/address'>
    <address type='replyto' jid='juliet@capulet.com'/>
  </addresses>
</message>
    ]]></example>
    <p>Naturally, further extensions could be included, e.g., using &xep0066; to specify a URL where one could buy the recording.</p>
    <example caption="Tune info with URL"><![CDATA[
<message
    from='pubsub.jabber.org'
    to='maineboy@jabber.org'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='generic/tunes/stpeter@jabber.org'>
      <item id='current'>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Yes</artist>
          <title>Heart of the Sunrise</title>
          <source>Yessongs</source>
          <track>3</track>
          <length>686</length>
	  <x xmlns='jabber:x:oob'>
	    <url>http://www.amazon.com/exec/obidos/ASIN/B000002J1Y</url>
	  </x>
        </tune>
      </item>
    </items>
  </event>
</message>
    ]]></example>
  </section2>
  <section2 topic='Stop Command' anchor='protocol-stop'>
    <p>In order to indicate that the user is no longer listening to any tunes, the user's client SHOULD send an empty &lt;tune/&gt; element, which can be considered a "stop command" for user tunes:</p>
    <example caption='User Publishes "Stop Playing" Information'><![CDATA[
<iq type='set'
    from='stpeter@jabber.org/work'
    to='pubsub.jabber.org'
    id='tunes345'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='generic/tunes/stpeter@jabber.org'>
      <item id='current'>
        <tune xmlns='http://jabber.org/protocol/tune'/>
      </item>
    </publish>
  </pubsub>
</iq>
    ]]></example>
    <example caption='Empty Tune Information is Delivered to All Subscribers'><![CDATA[
<message
    from='pubsub.jabber.org'
    to='maineboy@jabber.org'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='generic/tunes/stpeter@jabber.org'>
      <item id='current'>
        <tune xmlns='http://jabber.org/protocol/tune'/>
      </item>
    </items>
  </event>
</message>
.
.
.
    ]]></example>
  </section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
  <p>To prevent a large number of updates when a user is skipping through tracks, an implementation may wait several seconds before publishing new tune information.</p>
  <p>If the length is unknown (e.g., the user is listening to a stream), the &lt;length/&gt; element SHOULD NOT be included.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>This protocol introduces no security considerations above and beyond those defined in <cite>Publish-Subscribe</cite> (XEP-0060).</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>The &REGISTRAR; includes 'http://jabber.org/protocol/tune' in its registry of protocol namespaces.</p>
  </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='http://jabber.org/protocol/tune'
    xmlns='http://jabber.org/protocol/tune'
    elementFormDefault='qualified'>

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

  <xs:element name='tune'>
    <xs:complexType>
      <xs:sequence minOccurs='0'>
        <xs:element name='artist' type='xs:string' minOccurs='0'/>
        <xs:element name='title' type='xs:string' minOccurs='0'/>
        <xs:element name='source' type='xs:string' minOccurs='0'/>
        <xs:element name='track' type='xs:string' minOccurs='0'/>
        <xs:element name='length' type='xs:unsignedShort' minOccurs='0'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

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