1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-10-31 15:35:07 -04:00
xeps/xep-0118.xml
Peter Saint-Andre ff7d1dc5c9 1.1
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@912 4b5297f7-1745-476d-ba37-a9c6900126ab
2007-06-04 19:18:39 +00:00

281 lines
10 KiB
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>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0163</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>tune</shortname>
<schemaloc>
<url>http://www.xmpp.org/schemas/tune.xsd</url>
</schemaloc>
&stpeter;
<revision>
<version>1.1</version>
<date>2007-06-04</date>
<initials>psa</initials>
<remark><p>Removed non-PEP examples; added uri element.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2004-11-12</date>
<initials>psa</initials>
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
</revision>
<revision>
<version>0.10</version>
<date>2004-10-29</date>
<initials>psa</initials>
<remark><p>Added example with URL.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2004-10-27</date>
<initials>psa</initials>
<remark><p>Changed recommendation to not include the &lt;length/&gt; element if the track time is unknown.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2004-10-26</date>
<initials>psa</initials>
<remark><p>Added implementation notes; clarified nature of &lt;source/&gt; and &lt;track/&gt; elements; if length is unknown, set to zero.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2004-05-20</date>
<initials>psa</initials>
<remark><p>Changed &lt;length/&gt; datatype from xs:duration to xs:unsignedShort.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2004-04-25</date>
<initials>psa</initials>
<remark><p>Corrected several errors; added reference to XEP-0033.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2004-02-19</date>
<initials>psa</initials>
<remark><p>Reverted from infobits to tune elements.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-12-14</date>
<initials>psa</initials>
<remark><p>Slight modifications to track changes to infobits specifications.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-10-23</date>
<initials>psa</initials>
<remark><p>Replaced tune elements with infobits.</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-09-10</date>
<initials>psa</initials>
<remark><p>Added "stop" function via empty &lt;tune/&gt; element.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-09-08</date>
<initials>psa</initials>
<remark><p>Initial version.</p></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>length</td>
<td>The duration of the song or piece in seconds</td>
<td>686</td>
<td>xs:unsignedShort</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>title</td>
<td>The title of the song or piece</td>
<td>Heart of the Sunrise</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>uri</td>
<td>A URI or URL pointing to information about the song, collection, or artist</td>
<td>http://www.yesworld.com/lyrics/Fragile.html#9</td>
<td>xs:anyURI</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; subset specified in &xep0163;. 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/14793c64-0f94-11dc-9430-000bcd821bfb'
id='tunes123'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='http://jabber.org/protocol/tune'>
<item>
<tune xmlns='http://jabber.org/protocol/tune'>
<artist>Yes</artist>
<length>686</length>
<source>Yessongs</source>
<title>Heart of the Sunrise</title>
<track>3</track>
<uri>http://www.yesworld.com/lyrics/Fragile.html#9</uri>
</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='stpeter@jabber.org'
to='maineboy@jabber.org'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='http://jabber.org/protocol/tune'>
<item id='bffe6584-0f9c-11dc-84ba-001143d5d5db'>
<tune xmlns='http://jabber.org/protocol/tune'>
<artist>Yes</artist>
<length>686</length>
<source>Yessongs</source>
<title>Heart of the Sunrise</title>
<track>3</track>
<uri>http://www.yesworld.com/lyrics/Fragile.html#9</uri>
</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/14793c64-0f94-11dc-9430-000bcd821bfb'
id='tunes345'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='http://jabber.org/protocol/tune'>
<item>
<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='stpeter@jabber.org'
to='maineboy@jabber.org'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='http://jabber.org/protocol/tune'>
<item id='cbbb3f5a-0f9c-11dc-afe0-001143d5d5db'>
<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 SHOULD 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='length' type='xs:unsignedShort' minOccurs='0'/>
<xs:element name='source' type='xs:string' minOccurs='0'/>
<xs:element name='title' type='xs:string' minOccurs='0'/>
<xs:element name='track' type='xs:string' minOccurs='0'/>
<xs:element name='uri' type='xs:anyURI' minOccurs='0'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>