===============
rtorrent-notify
===============

Description
-----------

rtorrent-notify aims to be a very simple tool to notify users of rtorrent-related events.
It can actually be used for other kind of events, being mostly generic.

Running
-------

If installed, you can run ``rtorrent-notify``.
Otherwise, you can start it with ``python -m rtorrentnotify``.

Upgrading
---------

If you upgrade from rtorrent2rss, the event database will get erased because of format incompatibilities.

Requirements
------------

- PyRSS2Gen
- argparse (or Python 2.7)
- An `irkerd <http://www.catb.org/esr/irker/>`_ server running on localhost (optional, only if you want IRC notifications)

Configuration
-------------

Add this to your .rtorrent.rc::

    system.method.set_key = event.download.finished,rtnfy_finished,"execute=rtorrent-notify,FINISH,$d.get_base_path="
    system.method.set_key = event.download.inserted_new,rtnfy_inserted,"execute=~/rtorrent-notify/rtorrent-notify,INSERT,$d.get_name="

For older versions of rtorrent (pre 0.8.4)::

    on_finished = rtnfy_finished,"execute=rtorrent-notify,FINISH,$d.get_base_path="
    on_start = rtnfy_started,"execute=rtorrent-notify,START,$d.get_name="

Unless you specify their location, the files (``rtorrent-notify.db`` and ``rtorrent-notify.xml``) will be written in the home directory. Start ``rtorrent-notify -h`` for more details.

``FINISH`` and ``START`` are just strings, you can change them.

Some tips:

- There are other events you might be interested in. As there is no documentation, you can try to grep for ``event.`` in rtorrent's source code.
- ``get_base_path`` doesn't work with the "inserted" event, you can use ``get_name`` instead.
- You will find a list of properties to use in ``ui/download.cc``

Complete help for the rtorrent-notify command is available by running ``rtorrent-notify -h``.

Examples
--------

Advanced usage with some options would be::

    "execute=rtorrent-notify,-r,~/public_html/feed.xml,-n,irc://chat.freenode.net/mynick,FINISH,$d.get_base_path="

- The target RSS feed is changed from the default.
- This also sends a notification to the freenode nick ``mynick``. ``-n`` is used instead of -i ``irc://chat.freenode.net/mynick,isnick`` as the ``,`` character is already used by rtorrent's config.
- Notifications to channels could be sent by ``-i irc://chat.freenode.net/mychannel``.
