Writing a plug-in for Baretorrent

27 oct 2013

Today I ran across Baretorrent on HN. Looking around I found that the project supported some really simple extensibility. So here is how you set up a simple plugin to fix something for your personal needs or as a useful tool for others.

This info is completely based on the nice docs from the project.

The plugin consists of two files, btx.txt and main.py.

btx.txt contains some information on your application, such as guid, name and description. If we were to build, lets say, a automatic subtitle downloader, the file might look like this.

guid = E5258701-DF85-4CA9-819F-E44F065C4E55
name = subtitles
author = Christopher Käck
short_description = Downloads subtitles for files queued.
long_description = Downloads subtitles for downloads.
version = 0.1
email = christopher@kejsarmakten.se
website = http://blog.kejsarmakten.se
requires = 0.4.3

Read about the different fields in the documentation linked above.

The main.py file is a simple python 3 file which defines some methods which baretorrent will trigger on certain events.
The file contains the python standard library, libtorrent and baretorrent modules.

To make the module trigger on an event we need to declare an event listener. This is easily done in the init method. The different events are described in the documentation. In our example subtitle downloader we want to hook on the event when a new torrent is added. We put this hook in the main.py file.

def init():
    """ Called on load """ 
    baretorrent.register("torrent.added", "check_for_sub")

This tells baretorrent to call the method check_for_sub when a new torrent is added.

We then look in the docs to see what arguments are sent back to the callback function and use that info to define check_for_sub.

def check_for_sub(torrent):
    baretorrent.log("Got " + torrent.name())

If we run baretorrent from the terminal we can now see that the title of the newly added torrents are printed to the log output.

Now we can simply utilize the python language to parse a subtitle api of our choice by searching for the torrent name. Here is some pseudo-code for that.

def check_for_sub(torrent):
    baretorrent.log("Got " + torrent.name())
    url = call_subtitle_api(torrent.name())
    download_subtitle_url(url)

The complete file would look something like this.

import baretorrent

def init():
    """ Called on load """ 
    baretorrent.register("torrent.added", "check_for_sub")

def cleanup():
    """ Called on shutdown """
    pass

def uninstall():
    """ Called when plugin uninstalled """
    pass

def call_subtitle_api(name):
    # call some api or parse some website, return download url
    pass

def download_subtitle_url(url):
    # Save url to disk. Load path from config? 

def check_for_sub(torrent):
    baretorrent.log("Got " + torrent.name())
    url = call_subtitle_api(torrent.name())
    download_subtitle_url(url)
    baretorrent.log("Subtile was saved")

Now we need to package the plugin so we can publish it on our website or send it to some friends.

This is done by adding both btx.txt and main.py to a 7z file. On OS X you can do this by installing p7zip with brew

> brew install pzip
> 7z a name_of_extension.7z btx.txt main.py

When this is done you can simply install the extension by pressing Tools → Install extension.

It should look something like this, and you are done!

blog comments powered by Disqus