rtorrent

rtorrent#

Description#

Plugin to interact search, download and manage torrents through RTorrent.

You may prefer the built-in platypush.plugins.torrent.TorrentPlugin over this one, unless you have heavy dependencies on RTorrent, as quite some extra configuration is required to enable RTorrent’s RPC API - which is required to communicate with this integration.

Configuration:

  • Install rtorrent on your system - on Debian/Ubuntu/Raspbian:

    apt-get install rtorrent

  • Configure the rtorrent XML/RPC interface, usually by adding the following lines to your ~/.rtorrent.rc:

    # Enable XML/RPC
scgi_local = /home/user/.rpc.socket

  • Use a web server to bridge the RPC interface exposed by RTorrent over HTTP. Some configuration examples are available here. I usually use lighttpd because it’s easy to configure and it comes with a built-in SCGI module. Install the server e.g. using apt:

    apt-get install lighttpd

  • Create a base configuration file like this under e.g. ~/.config/rtorrent/lighttpd.conf:

    ### Base configuration
server.modules = (
    "mod_indexfile",
    "mod_access",
    "mod_alias",
    "mod_redirect",
)

# Make sure that all the directories exist.

# server.document-root isn't really needed, but lighttpd
# won't start if it doesn't find a document root.
server.document-root        = "/home/user/.local/share/rtorrent/html"
server.upload-dirs          = ( "/home/user/.cache/uploads" )
server.errorlog             = "/home/user/.local/log/rtorrent/error.log"
server.pid-file             = "/home/user/.local/run/lighttpd.pid"
server.username             = "your-user"
server.groupname            = "your-group"
server.port                 = 5000

index-file.names            = ( "index.html" )

### Configure the RTorrent XML/RPC endpoint
server.modules += ( "mod_scgi" )
scgi.server = (
    # Bind an endpoint called /RPC2 to your local interface
    "/RPC2" =>
      ( "127.0.0.1" =>
        (
          # Read from the RTorrent XML/RPC socket
          "socket" => "/home/user/.rpc.socket",
          "check-local" => "disable",
          "disable-time" => 0,  # don't disable scgi if connection fails
        )
      )
  )

  • Start the HTTP service, and optionally enable it as a system/user service:

    lighttpd -f ~/.config/rtorrent/lighttpd.conf

  • Start RTorrent and check that the XML/RPC interface works:

    $ xmlrpc localhost:8000 system.listMethods
# Should return a list with all the methods exposed by RTorrent.
$ xmlrpc localhost:5000 download_list
Result:
Array of 0 items:

  • It is advised to let the RTorrent instance run in e.g. screen or tmux on the server machine - it is more reliable than letting the plugin start/stop the instance, and you have an easy CLI interface to attach to manage/monitor your torrents.

  • In this example, the URL to configure in the plugin would be http://localhost:5000/RPC2.

Configuration#

rtorrent:
  # [Required]
  # HTTP URL that exposes the XML/RPC interface of RTorrent (e.g. ``http://localhost:5000/RPC2``).
  url:   # type=str

  # [Optional]
  # How often the plugin will monitor for changes in the torrent state (default: 5 seconds).
  # poll_seconds: 5.0  # type=float

  # [Optional]
  # Directory where torrents and metadata files will be downloaded
  # (default: ``~/.rtorrent/watch``).
  # download_dir: ~/.rtorrent/watch  # type=str

  # [Optional]
  # Torrent ports to listen on (default: 6881 and 6891)
  # torrent_ports: (6881, 6891)  # type=Iterable[int]

  # [Optional]
  # List of search providers to use.
  # search_providers:   # type=Union[Dict[str, dict], Iterable[platypush.plugins.torrent._search._base.TorrentSearchProvider], NoneType]

Dependencies#

Alpine

apk add rtorrent

Debian

apt install rtorrent

Fedora

yum install rtorrent

Arch Linux

pacman -S rtorrent

Triggered events#

Actions#

Module reference#

class platypush.plugins.rtorrent.RtorrentPlugin(url: str, poll_seconds: float = 5.0, download_dir: str = '~/.rtorrent/watch', **kwargs)[source]#

Bases: TorrentPlugin

Plugin to interact search, download and manage torrents through RTorrent.

You may prefer the built-in platypush.plugins.torrent.TorrentPlugin over this one, unless you have heavy dependencies on RTorrent, as quite some extra configuration is required to enable RTorrent’s RPC API - which is required to communicate with this integration.

Configuration:

  • Install rtorrent on your system - on Debian/Ubuntu/Raspbian:

    apt-get install rtorrent

  • Configure the rtorrent XML/RPC interface, usually by adding the following lines to your ~/.rtorrent.rc:

    # Enable XML/RPC
scgi_local = /home/user/.rpc.socket

  • Use a web server to bridge the RPC interface exposed by RTorrent over HTTP. Some configuration examples are available here. I usually use lighttpd because it’s easy to configure and it comes with a built-in SCGI module. Install the server e.g. using apt:

    apt-get install lighttpd

  • Create a base configuration file like this under e.g. ~/.config/rtorrent/lighttpd.conf:

    ### Base configuration
server.modules = (
    "mod_indexfile",
    "mod_access",
    "mod_alias",
    "mod_redirect",
)

# Make sure that all the directories exist.

# server.document-root isn't really needed, but lighttpd
# won't start if it doesn't find a document root.
server.document-root        = "/home/user/.local/share/rtorrent/html"
server.upload-dirs          = ( "/home/user/.cache/uploads" )
server.errorlog             = "/home/user/.local/log/rtorrent/error.log"
server.pid-file             = "/home/user/.local/run/lighttpd.pid"
server.username             = "your-user"
server.groupname            = "your-group"
server.port                 = 5000

index-file.names            = ( "index.html" )

### Configure the RTorrent XML/RPC endpoint
server.modules += ( "mod_scgi" )
scgi.server = (
    # Bind an endpoint called /RPC2 to your local interface
    "/RPC2" =>
      ( "127.0.0.1" =>
        (
          # Read from the RTorrent XML/RPC socket
          "socket" => "/home/user/.rpc.socket",
          "check-local" => "disable",
          "disable-time" => 0,  # don't disable scgi if connection fails
        )
      )
  )

  • Start the HTTP service, and optionally enable it as a system/user service:

    lighttpd -f ~/.config/rtorrent/lighttpd.conf

  • Start RTorrent and check that the XML/RPC interface works:

    $ xmlrpc localhost:8000 system.listMethods
# Should return a list with all the methods exposed by RTorrent.
$ xmlrpc localhost:5000 download_list
Result:
Array of 0 items:

  • It is advised to let the RTorrent instance run in e.g. screen or tmux on the server machine - it is more reliable than letting the plugin start/stop the instance, and you have an easy CLI interface to attach to manage/monitor your torrents.

  • In this example, the URL to configure in the plugin would be http://localhost:5000/RPC2.

__init__(url: str, poll_seconds: float = 5.0, download_dir: str = '~/.rtorrent/watch', **kwargs)[source]#
Parameters:

  • url – HTTP URL that exposes the XML/RPC interface of RTorrent (e.g. http://localhost:5000/RPC2).

  • poll_seconds – How often the plugin will monitor for changes in the torrent state (default: 5 seconds).

  • download_dir – Directory where torrents and metadata files will be downloaded (default: ~/.rtorrent/watch).

download(torrent: str, is_media: bool = False, *_, **__)[source]#

Download a torrent.

Parameters:

  • torrent –

    Torrent to download. Supported formats:

    • Magnet URLs

    • Torrent URLs

    • Local torrent files

  • is_media – Set it to true if you’re downloading a media file that you’d like to stream as soon as the first chunks are available. If so, then the events and the status method will only include media files

Returns:

The status of the torrent.

download_torrent_file(torrent: str) → str[source]#

Download a torrent link to torrent_files_dir.

Parameters:

torrent – Torrent URL, magnet link or local file.

Returns:

Path to the locally downloaded .torrent file.

execute(method: str, *args, **kwargs)[source]#

Execute a raw command over the RTorrent RPC interface.

Parameters:

  • method – Method name.

  • args – Method arguments.

  • kwargs – Method keyword-arguments.

Returns:

Anything returned by the RPC method.

list_methods() → List[str][source]#
Returns:

The list of methods exposed by the RTorrent instance

open(torrent: str) → dict[source]#

Open a loaded torrent transfer.

Parameters:

torrent – Torrent hash.

Returns:

The status of the torrent.

pause(torrent: str) → dict[source]#

Pause a torrent transfer.

Parameters:

torrent – Torrent hash.

Returns:

The status of the torrent.

quit()[source]#

Terminate all the active transfers and quit the monitor.

remove(torrent)[source]#

Stop and remove a torrent transfer (without removing the downloaded files).

Parameters:

torrent – Torrent hash.

resume(torrent) → dict[source]#

Resume a torrent transfer.

Parameters:

torrent – Torrent hash.

Returns:

The status of the torrent.

search(query: str, *args, providers: str | Iterable[str] | None = None, limit: int = 25, page: int = 1, **filters)#

Perform a search of video torrents.

Parameters:

  • query – Query string, video name or partial name

  • providers – Override the default search providers by specifying the provider names to use for this search.

  • filters – Additional filters to apply to the search, depending on what the configured search providers support. For example, category and language are supported by the PopcornTime.

  • limit – Maximum number of results to return (default: 25).

  • page – Page number (default: 1).

Returns:

[
  {
    "community_rating": 86.0,
    "country": "USA",
    "created_at": "2021-01-01T00:00:00",
    "critic_rating": 86.0,
    "description": "A description of the torrent",
    "duration": 123.45,
    "episode": 1,
    "file": "/home/user/downloads/2001_a_space_odyssey.torrent",
    "genres": [
      "Sci-Fi",
      "Adventure"
    ],
    "image": "https://example.com/image.jpg",
    "imdb_id": "tt0062622",
    "is_media": true,
    "language": "en",
    "network": "AMC",
    "num_seasons": 5,
    "overview": "Overview of the torrent, if it is a TV show",
    "peers": 123,
    "provider": "popcorntime",
    "quality": "1080p",
    "rating": 86.0,
    "season": 1,
    "seeds": 123,
    "series": "Breaking Bad",
    "series_status": "Ended",
    "size": 123456789,
    "title": "2001: A Space Odyssey",
    "trailer": "https://example.com/trailer.mp4",
    "tvdb_id": "76283",
    "type": "movies",
    "url": "magnet:?xt=urn:btih:...",
    "votes": 123,
    "year": 1968
  }
]

start_monitor()[source]#

Start monitoring the status of the RTorrent instance.

status(torrent: str = None) → dict[source]#

Get the status of the current transfers.

Parameters:

torrent – Torrent hash.

Returns:

A dictionary:

{
  "HASH1234567890": {
    "hash": "HASH1234567890",
    "name": "Your torrent name",
    "save_path": "/home/user/Downloads/Your torrent name",
    "is_active": true,
    "is_open": true,
    "completed_bytes": 666894336,
    "download_rate": 451345,
    "is_multi_file": true,
    "remaining_bytes": 1482827011,
    "size_bytes": 2149721347,
    "load_date": "2020-09-02T18:42:19",
    "peers": 0,
    "state": "paused",
    "start_date": "2020-09-02T18:42:19",
    "finish_date": null,
    "upload_rate": 143967,
    "progress": 31.0,
    "files": ["list", "of", "downloaded", "files"]
  }
}

stop(torrent) → dict[source]#

Stop a torrent transfer.

Parameters:

torrent – Torrent hash.

Returns:

The status of the torrent.

stop_monitor()[source]#

Stop monitoring the status of the RTorrent instance.