Transmission RPC Ruby

Build Status Code Climate Dependency Status Coverage Status

Transmission RPC Ruby is a Ruby library to communicate with Transmission RPC (bittorrent client). This library is based on this spec and currently supports RPC versions >= 14

Installation

gem install transmission-rpc-ruby

Then require it

require 'transmission'

Getting started

To get started with this gem you need to decide if you are using this library to connect to one or multiple transmission daemons. Both is possible

Single connection

Just set up a single configuration with will be used throughout any library calls

Transmission::Config.set host: 'some.host', port: 9091, ssl: false, credentials: {username: 'transmission', password: '********'}

torrents = Transmission::Model::Torrent.all

Multiple connections

Introducing the Transmission::RPC class, which represent all the raw rpc connection requests.

rpc = Transmission::RPC.new host: 'some.host', port: 9091, ssl: false, credentials: {username: 'transmission', password: '********'}

torrents = Transmission::Model::Torrent.all connector: rpc

This Object can be passed to the Transmission::Model classes. Examples are shown below.

Configuration options

Both Transmission::Config and Transmission::RPC take the same arguments, these are the default settings:

{
  host: 'localhost',
  port: 9091
  path: '/transmission/rpc',
  ssl: false,
  credentials: {username: 'transmission', password: '********'},
  session_id: ''
}

Torrents

To work with torrents you need use the Transmission::Model::Torrent class

Get all torrents

torrents = Transmission::Model::Torrent.all

If only a few fields are required

torrents = Transmission::Model::Torrent.all fields: ['id']

Find a torrent

id = 1
torrent = Transmission::Model::Torrent.find id

If only a few fields are required

torrent = Transmission::Model::Torrent.find id, fields: ['id']

Add a torrent

filename = 'http://example.com/torrent.torrent'
torrent = Transmission::Model::Torrent.add filename: filename

NOTE: you can also specify a magnet link instead

Torrent instance methods

id = 1
torrent = Transmission::Model::Torrent.find(id)

torrent.start!
torrent.start_now!
torrent.stop!
torrent.verify!
torrent.re_announce!

torrent.move_up!
torrent.move_down!
torrent.move_top!
torrent.move_bottom!

You can access the torrent accessors & mutators via instance methods too

# uploadLimited
torrent.upload_limited
torrent.upload_limited = true

torrent.save!

The save! method will update the torrent on your remote transmission daemon.

To find all the torrent accessors & mutators visit spec

Session

To find out more about the current session use the Transmission::Model::Session class.

Get session

session = Transmission::Model::Session.get

If only a few fields are required

session = Transmission::Model::Session.get fields: ['version']

If used with a connector

options = {}
rpc = Transmission::RPC.new options

session = Transmission::Model::Session.get connector: rpc

Change session

Like the Transmission::Model::Torrent class, you change some session properties

session = Transmission::Model::Session.get

# alt-speed-enabled
session.alt_speed_enabled
session.alt_speed_enabled = true

session.save!

To find all the session accessors & mutators visit spec

Session Stats

You can also retrieve some session stats by using the Transmission::Model::SessionStats class

session_stats = Transmission::Model::SessionStats.get

# activeTorrentCount
session_stats.active_torrent_count

For session stats there are no mutators. To find out more about the accessors visit the spec

RPC Connector

If it is not desired to use any of the Transmission::Model classes you can use the RPC connector

Examples

rpc = Transmission::RPC.new host: 'some.host', port: 9091, ssl: false, credentials: {username: 'transmission', password: '********'}

session_body = rpc.get_session

ids = [1, 2, 3]

torrent_bodies = rpc.get_torrent ids
rpc.start_torrents ids

For more methods check out lib/transmission/rpc.rb

Contribute

Please help make this gem awesome! If you have any suggestions or feedback either create an issue or PR. Just make sure you run the tests before.