katoss

Katoss allows you to download TV Show episode torrent files from different torrent provider platforms along with matched subtitles from several databases.

It may be linked to a Sick Beard / SickRage manager API to search 'Wanted' episodes.

KATOSS was originally an acronym for KickAss Torrents + OpenSubtitles Search. Today, it also supports ExtraTorrent, isoHunt torrents, Rarbg torrents and Addic7ed subtitles providers.

Requirements

Katoss needs Node.js to run.

To be able to download subtitles from OpenSubtitles database, you need to register as a user on www.opensubtitles.org and request a personal user agent string following these directions: How to request a new user agent.

Installation

Method 1

The easiest way to install katoss is by downloading the latest release archive from https://github.com/same31/katoss/releases/latest.

Method 2 for developers

1. Clone this repository: git clone https://github.com/same31/katoss.git
2. Type npm install to install the dependencies.
3. Rename (or copy) the katoss/sampleConfig.json configuration file to katoss/config.json and edit it to configure katoss.

Configuration

See the katoss/sampleConfig.json for a sample configuration file.

• subtitlesProviders: (optional) The list of supported subtitles databases, ordered by preference. Valid values are opensubtitles and addic7ed. The default value is opensubtitles.
• torrentProviders: (optional) The list of supported torrent platforms, ordered by preference. Valid values are kickass, extratorrent, isohunt, and rarbg. The default value is extratorrent.
• openSubtitlesUserAgent: (optional) Your personal Open Subtitles user agent string, required if opensubtitles is in your list of subtitles providers, see How to request a new user agent.
• outputPath: (optional) The path where to downloads torrent and subtitles files, default is directory from where the script is launched.
• qualityOrder: The list of allowed qualities to download, ordered by preference. Valid values are 2160p, 1080p, 720p, 480p and unknown.
• distributionOrder: The list of allowed distribution releases to download, ordered by preference. Valid values are BluRay, WEB-DL, HDTV and unknown.
• priority: (optional) Torrent results will be ordered by this priority list. Valid values are quality, language, distribution and HEVC. Use the last option to include x265 HEVC releases. The default priority list is quality, language, distribution. That means release quality will prevail over preferred subtitles language found which will also prevails over the preferred release distribution and x265 HEVC releases will be ignored.
• ignoredWords: (optional) Torrent releases containing a word in this list will be ignored. Note: To ignore x265 HEVC releases, you have to exclude HEVC option from priority config key.
• languages: Subtitles language(s) to search (3 characters code), ordered by preference. Example: ["fre", "eng"].
• showLanguages: (optional) Subtitles languages to search by show, will override the languages key.
• sickBeard: (optional) Configuration used when connecting to a Sick Beard API.
  • apiKey: Your Sick Beard API key.
  • protocol: (optional) The protocol used to connect to the Sick Beard server, default is http.
  • host: (optional) The host used to connect to the Sick Beard server, default is 127.0.0.1.
  • port: (optional) The port used to connect to the Sick Beard server, default is 80.
• kodi: (optional) Configuration used when connecting to a KODI server.
  • protocol: (optional) The protocol used to connect to the KODI server, default is http.
  • host: (optional) The host used to connect to the KODI server, default is 127.0.0.1.
  • port: (optional) The port used to connect to the KODI server, default is 8080.

Usage

Search can be performed by providing a JSON search file or using a Sick Beard API.

Search with a JSON file

1. Rename (or copy) the file utils/sampleSearch.json to utils/search.json.
2. Edit the Sample TV Show title by the desired TV show title.
3. Under the seasons key, write a season number followed by the list of episodes to search and download.
4. Repeat for each desired season and TV show.
5. Run node utils/searchJSONFile.js to search and download torrent and subtitles files.

Search using a Sick Beard API

1. Fill in the sickBeard part into the configuration file.
2. In the Sick Beard admin page, go to Post-processing and enter /<path to node bin>/node /<path to katoss>/utils/postProcessSickBeard.js into the Extra scripts field.
3. Run node utils/searchSickBeard.js to search and download the episodes marked as Wanted.

Search in order to replace low quality episodes

Run node utils/searchSickBeard.js --replace-low-quality to search and download the episodes marked as Downloaded and which quality does not match the first of the qualityOrder in the configuration file.

Note: It will not search for 2160p releases when using this option as it would search for nearly your entire library.

About

Torrent providers

Kickass Torrents

ExtraTorrent

isoHunt torrents

Rarbg torrents

Subtitles providers

Open Subtitles

Addic7ed

License

MIT. Feel free to modify and distribute.