Transmission RPC Ruby

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

gem install transmission-rpc-ruby

Then require it

require 'transmission'

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

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

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 any of the Transmission::Model classes. Examples are shown below.

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: ''
}

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

torrents = Transmission::Model::Torrent.all

If only a few fields are required

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

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

If only a few fields are required

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

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

NOTE: you can also specify a magnet link instead

You can also ask for certain fields too

filename = 'http://example.com/torrent.torrent'
torrent = Transmission::Model::Torrent.add arguments: {filename: filename}, fields: ['id']

Or use an RPC connector instance

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

filename = 'http://example.com/torrent.torrent'
torrent = Transmission::Model::Torrent.add arguments: {filename: filename}, fields: ['id'], connector: rpc

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!

torrent.finished?
# => true

torrent.to_json
# => {"id"=>132, "name"=>"Torrent Name", ....}

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

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

# Copies torrent to new location
torrent.set_location '/some/new/path'

# Moves torrent to new location
torrent.set_location '/some/new/path', true

You can also start and stop all torrents

Transmission::Model::Torrent.start_all!

Transmission::Model::Torrent.stop_all!

If you want to change multiple torrents at once:

ids = [1, 2, 3]
torrents = Transmission::Model::Torrent.find ids

This will return a Transmission::Model::Torrent instance which takes the same methods as described before.

torrents.start!
torrents.stop!
# ...

torrents.to_json
# => [{"id"=>132, "name"=>"Torrent Name", ....}, {...}]

# uploadLimited
torrents.upload_limited = false
torrents.save!

This will change uploadLimited for all torrents with ids 1, 2 & 3.

NOTE: If using Transmission::Model::Torrent you will only be able to modify their mutators.

To find out if a torrent instance contains multiple torrents

torrents.is_multi?
# => true

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

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

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

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

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

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_torrent ids

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

Features:

• Added set_location method to torrent model (thanks @balinez)

Bugfixes:

• uninitialized constant Transmission::Model::SessionStats error fix

Features:

• ability to handle multiple torrents in one instance
• start_all! & stop_all! static class methods for torrents
• reload!, to_json, is_multi?, is_finished instance method for torrents
• to_json instance method for session & session stats

Bugfixes:

• when adding torrents the returned torrent instance will use same options for finding added torrent

Features:

• all basic torrent actions (start, stop, move up queue, etc)
• session model
• session stats model
• adding torrents

• Initial project import

• Add support for all versions of RPC
• More documentation
• Add 'torrent-rename-path' & 'torrent-set-location' & 'port-test' & 'free-space' & 'session-close' RPC methods

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.