Custom sources - tylergibbs2/Tsundoku GitHub Wiki

Tsundoku will attempt to load all sources in the sources/ directory (data/sources/ if Docker). You will likely be able to get a good grasp on how sources work by looking at the ones included out of the box.

Sources take the form of JSON files. The root object is required to have four keys, name, version, url, and rssItemKeyMapping.

The name and version keys are only used for logging purposes within Tsundoku. You're free to name these fields whatever you like. The URL key defines the URL that will be used to retrieve the RSS feed.

rssItemKeyMapping is slightly more complex. This field is an object with two keys, filename and torrent. These two keys define how Tsundoku can retrieve the filename and the torrent from an item in the RSS feed.

{
  "name": "Nyaa.si",
  "version": "1.0.0",
  "url": "https://nyaa.si/?page=rss&c=1_2",
  "rssItemKeyMapping": {
    "filename": "$.title",
    "torrent": "$.link"
  }
}

If you take a look at this sample RSS feed (from Nyaa), you can see that it contains some metadata at the top, and then it starts to list the items in the feed. In the rssItemKeyMapping field, it lists $.link to retrieve the torrent. In this case, the $ is referring to any particular item, kind of like a placeholder. The .link part is denoting that the torrent can be retrieved from the <link> field of the item. Tsundoku is intelligent enough to be able to retrieve torrents from either .torrent links or magnet URLs, so when you're writing your custom source feel free to point it to either.

<rss xmlns:atom="http://www.w3.org/2005/Atom" xmlns:nyaa="https://nyaa.si/xmlns/nyaa" version="2.0">
  <channel>
  <title>Nyaa - Home - Torrent File RSS</title>
  <description>RSS Feed for Home</description>
  <link>https://nyaa.si/</link>
  <atom:link href="https://nyaa.si/?page=rss" rel="self" type="application/rss+xml"/>
  <item>
    <title>Bleach.S17E13.Thousand-Year.Blood.War.The.Blade.is.Me.1080p.DSNP.WEB-DL.AAC2.0.H.264-NTb</title>
    <link>https://nyaa.si/download/...</link>
    <guid isPermaLink="true">https://nyaa.si/view/...</guid>
    <pubDate>Mon, 26 Dec 2022 16:47:05 -0000</pubDate>
    <nyaa:seeders>270</nyaa:seeders>
    <nyaa:leechers>1646</nyaa:leechers>
    <nyaa:downloads>162</nyaa:downloads>
    <nyaa:infoHash>...</nyaa:infoHash>
    <nyaa:categoryId>1_2</nyaa:categoryId>
    <nyaa:category>Anime - English-translated</nyaa:category>
    <nyaa:size>1.1 GiB</nyaa:size>
    <nyaa:comments>2</nyaa:comments>
    <nyaa:trusted>No</nyaa:trusted>
    <nyaa:remake>No</nyaa:remake>
    <description>
      <![CDATA[ <a href="https://nyaa.si/view/...">#...| Bleach.S17E13.Thousand-Year.Blood.War.The.Blade.is.Me.1080p.DSNP.WEB-DL.AAC2.0.H.264-NTb</a> | 1.1 GiB | Anime - English-translated | ...]]>
    </description>
  </item>

  ...

  </channel>
</rss>