BEP:36
Title:Torrent RSS feeds
Version: 9c5c1dd1b372016e05af84fb34fccac6752ef54a
Last-Modified:Thu Jul 21 10:45:38 2016 -0400
Author: Arvid Norberg <arvid@bittorrent.com>
Status: Draft
Type:Standards Track
Created:9-October-2012
Post-History:14-Oct-1012: Change enclosure/size to refer to the .torrent file, rather than torrent content

Abstract

It has become common practice to publish RSS feeds linking to content by using torrent files. This BEP attempts to document and standardize how to format such RSS feeds.

Terminology

For the purpose of the BEP, the term torrent link will be used to identify any kind of URL identifying a torrent. This may be either an HTTP or HTTPS URL pointing to a .torrent file or a magnet link identifying a torrent info-hash.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Client support

This section will document which RSS formats currently are supported by bittorrent clients.

client RSS 2.0 Atom
uTorrent Yes No
Azureus Yes No
Deluge Yes Yes
qBittorrent Yes No
KTorrent Yes Yes
libtorrent Yes Yes
Catch Yes No

RSS 2.0 are feeds based on the rss/channel/item tags.

Atom are feeds based on the feed/entry tags.

The following table indicates which tags are supported for items in a feed. Only tags that identify the torrent are included, since those are the key tags. The ttl tag is used by the server to indicate how frequently subscribers should refresh the feed.

client <ttl> <enclosure> <media:content> <media:hash> <link> <torrent> <guid>
uTorrent Yes Yes Yes Yes Yes Yes Yes
Azureus [3] Yes Yes No No Yes No No
Deluge [4] Yes Yes No No No No No
qBittorrent No Yes No No No No No
KTorrent ? Yes No No No No No
libtorrent Yes Yes Yes No Yes No No
Catch [1] No Yes No No No No No
[1] Source at http://code.google.com/p/catch/source/browse/trunk/FeedChecker.m
[2] Azureus tolerates HTML in descriptions, but strips mark-up
[3] Based on org.kmallan.azureus.rssfeed.Scheduler.java from http://azureus.sourceforge.net/plugin_details.php?plugin=rssfeed , version 1.3.6
[4] Uses YaRSS2 https://github.com/bendikro/deluge-yarss-plugin/blob/master/yarss2/lib/feedparser.py

By far the most well supported format for feeds among bittorrent clients are RSS (as opposed to Atom) and the enclosure tag for torrent content.

enclosure

The enclosure tag MUST have a type attribute set to "application/x-bittorrent" and MUST store the torrent link in a url attribute. It MAY have a length attribute, which should indicate the size of the .torrent file, in bytes.

Example:

<enclosure type="application/x-bittorrent" length="12216" url="http://featuredcontent.utorrent.com/torrents/WillisEarlBeal-BitTorrent.torrent"/>

media:content

The media content tag is really the "content" tag under the namespace http://search.yahoo.com/mrss/. Most bittorrent clients don't support XML namespaces in their generic form. Most clients that support the media:content tag assume that the namespace is called media in the feed, and will not recognize the tag otherwise.

For more information see the media RSS specification.

The media::content tag includes metadata as attributes. The ones relevant to bittorrent clients are url which is the torrent link, and filesize which is the size of the torrent's content (in bytes).

Example:

<media:content url="http://featuredcontent.utorrent.com/torrents/WillisEarlBeal-BitTorrent.torrent" fileSize="12216320"/>

media:hash

The media hash tag provides the info hash of the torrent hex encoded.

Example:

<media:hash algo="sha1"><8c056e06fbc16d2a2be79cefbf3e4ddc15396abe/media:hash>

torrent

The torrent tag can be used instead of magnet links or to complement another tag which has a torrent link in it. The torrent tag only provides two attributes, infohash and contentlength, which are supposed to be the hex encoded info-hash of the torrent and the size of the torrent's content respectively.

Although uTorrent doesn't support any other tags, magneturi and filename typically occur in this tag, containing the magnet link and name of the torrent respectively

Example:

<torrent>
        <infohash>"8c056e06fbc16d2a2be79cefbf3e4ddc15396abe</infohash>
        <contentlength>600162597</contentlength>
</torrent>

For more information, see the xmlns.

guid

Sometimes the torrent link is encoded as the GUID in RSS feeds.

Example:

<guid>http://featuredcontent.utorrent.com/torrents/WillisEarlBeal-BitTorrent.torrent</guid>

However, for the most part, clients expect the GUID to simply be a unique identifier for this piece of content and is only used to avoid downloading duplicates. uTorrent is an exception in that it also looks for torrent links in the guid tag.

conclusions

Even though this section may look like a comparison of clients, its main point is that there are currently a very large number of ways of representing torrents in RSS feeds, and clients support some and not others.

The main take away from the client support is that there is a distinct need for a standardization document like this, to make torrent RSS feeds less of a black art, and to provide clear recommendations for torrent feed providers.

Torrent RSS feeds

The proposed standard RSS feed format for torrents is an RSS 2.0 feed using the enclosure tag for torrent content.

The ttl tag SHOULD be supported and honored. The definition of the value inside the ttl tag is the number of seconds to wait until the client should refresh the feed the next time.

The enclosure tag MUST include a type attribute set to application/x-bittorrent and MUST include a url attribute containing the torrent link.

If an enclosure tag matching the above mentioned specifications, it SHOULD take priority over any other tag found in the RSS item.

The title tag SHOULD be used for the name of the torrent.

The description tag MAY be used for a description of the content. If a description tag is available, it SHOULD NOT contain any markup. It should be plain text.

Clients often need to identify whether a torrent has already been downloaded or not just by inspecting the item. For this reason, RSS feeds SHOULD include a guid field. If practical, the guid SHOULD be the info-hash of the torrent. That way, GUIDs would match across different feeds.

Example:

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
        <channel>
                <title> Featured content </title>
                <link> http://featuredcontent.utorrent.com/ </link>
                <item>
                        <title> WillisEarlBeal-BitTorrent </title>
                        <description>
                                The Principles of a Protagonist Bundle

                                Chicago native Willis Earl Beal came from humble musical beginnings- he
                                began as a street performer of sorts that was prone to leaving homemade
                                novels, artwork and CD-Rs across America to promote his work, suggesting
                                a desire to be heard. Thereafter, he relocated to Albuquerque, NM where
                                he continued his practice of 'gifting' as he simultaneously recorded a
                                set of songs on a discarded karaoke machine that would become Acousmatic
                                Sorcery, his Hot Charity/XL Recordings debut.
                        </description>
                        <guid> e380a6c5ae0fb15f296d29964a56250780b05ad7 </guid>
                        <enclosure
                                url="http://featuredcontent.utorrent.com/torrents/WillisEarlBeal-BitTorrent.torrent"
                                type="application/x-bittorrent" />
                </item>
        </channel>
</rss>

extended torrent attributes

For torrent sites providing listings of torrents along with more detailed statistics, the recommended tags are the ones defined by eztv.

Example:

<torrent>
        <filename> WillisEarlBeal-BitTorrent </filename>
        <contentlength> 28571661 </contentlength>
        <magneturi> magnet:?xt=urn:btih:e380a6c5ae0fb15f296d29964a56250780b05ad7&dn=WillisEarlBean </magneturi>
        <trackers>
                <group order="ordered">
                        <tracker seeds="359" peers="3961">
                                udp://tracker.openbittorrent.com:80/announce
                        </tracker>
                </group>
                <group order="random">
                        <tracker seeds="365" peers="4451">
                                http://tracker.publicbt.com/announce
                        </tracker>
                        <tracker seeds="367" peers="4434">
                                udp://tracker.publicbt.com:80/announce
                        </tracker>
                        <tracker seeds="565" peers="6406">
                                udp://tracker.istole.it:80/announce
                        </tracker>
                        <tracker seeds="0" peers="0">
                                http://tracker.hexagon.cc:2710/announce
                        </tracker>
                </group>
        </trackers>
</torrent>