Torrent RSS feeds

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>

link

The link tag contains the torrent link as its body.

Example

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

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:

.. parsed-literal

	**<?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:

.. parsed-literal

	**<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>**

Copyright

This document has been placed in the public domain.

..

Local Variables:

mode: indented-text

indent-tabs-mode: nil

sentence-end-double-space: t

fill-column: 70

coding: utf-8

End: