TransmissionNG ruby gem
Version history
1.0.0 - Initial release, compatible with RPC version 15 (latest as of 18/08/2015) 1.0.1 - Minor bugfix (regex anchor) 1.0.2 - Added a few default list attributes and fixed the name value 1.0.3 - Added peersGettingFromUs and peersSendingToUs to default list keys 1.0.4 - Fixed broken JSON back from RPC bug 1.0.5 - Switched to Mechanize for http 1.0.6 - Disable socksify when talking to Transmission 1.0.7 - Bugfix 1.0.8 - Bugfix 1.0.9 - Removed nasty regex replace for broken libtransmission 1.0.10 - Fixed typo 1.0.11 - Bugfix for tcp connection exhaustion
Description
This gem is designed to provide a clean and simple ruby interface to the Transmission RPC API.
It is optimised for simplicity and ease of use and is compatible with version 15 of the Transmission RPC API, the spec for which is currently here:
https://trac.transmissionbt.com/browser/branches/1.7x/doc/rpc-spec.txt
Installation
sudo gem install transmission-ng
Note: ensure you are running the latest transmission. On ubuntu you need to add the Transmission apt repository:
sudo add-apt-repository ppa:transmissionbt/ppa
Usage
Initialise the instance:
require 'transmission'
t = Transmission.new({
:host => '127.0.0.1',
:port => 9091,
:user => 'admin',
:pass => 'admin'
})
Get a list of torrents:
t.list => []
Change the default keys included with list items:
t.list_attributes = ['id','name']
t.list => []
Get all torrent information by id:
t.get(9) => {} or false
t.get([9,10]) => []
Get torrents with a specific attribute:
t.list_by("status","stopped") => []
t.list_by("status","=","stopped") => []
t.list_by("percentDone",">=",98) => []
t.list_by("status","!=","seeding") => []
Get torrent attributes:
t.get(9, 'isFinished') => boolean
t.get(9, 'name') => string
t.get(9, ['name','isFinished','isStalled']) => {}
For a full list of attributes please refer to the spec document here:
https://trac.transmissionbt.com/browser/trunk/extras/rpc-spec.txt
Add torrents:
t.add_magnet('magnet:?blahblah') => true
t.add_torrentfile('http://path/to/torrent.torrent') => true
torrent_data = File.open("path/to/torrent.torrent","r").read
t.add_torrentdata(torrent_data) => true
Add torrent in paused state:
t.add_magnet('magnet:?blahblah',{'paused' => true}) => true
t.add_torrentfile('http://path/to/torrent.torrent',{'paused' => true}) => true
t.add_torrentdata(torrent_data,{'paused' => true}) => true
For more parameters for the add torrent methods, please see section 3.4 of the spec at: https://trac.transmissionbt.com/browser/trunk/extras/rpc-spec.txt
Change torrent parameters:
t.set(9, {
'peer-limit' => 20,
'uploadLimited' => true
})
For a full list of attributes, please see section 3.2 of the spec at: https://trac.transmissionbt.com/browser/trunk/extras/rpc-spec.txt
Change parameters on all torrents at once:
t.set([], {
'peer-limit' => 20,
'uploadLimited' => true
})
Just as an empty "ids" value is shorthand for "all ids", using an empty array for "files-wanted", "files-unwanted", "priority-high", "priority-low", or "priority-normal" is shorthand for saying "all files". For example, to make all files high priority:
t.set(9, {
'priority-high' => []
})
Delete torrent(s):
t.delete(9) => true
t.delete([9,10]) => true
Delete torrent(s) and also remove all their local data:
t.delete(9,true) => true
t.delete([9,10],true) => true
Start torrent(s):
t.start(9) => true
t.start([9,10]) => true
Stop torrent(s):
t.stop(9) => true
t.stop([9,10]) => true
Verify torrent(s):
t.verify(9) => true
t.verify([9,10]) => true
Reannounce torrent(s):
t.reannounce(9) => true
t.reannounce([9,10]) => true
Move torrent(s) to the top of the queue:
t.queue_top(9) => true
t.queue_top([9,10]) => true
Move torrent(s) up the queue:
t.queue_up(9) => true
t.queue_up([9,10]) => true
Move torrent(s) down the queue: t.queue_down(9) => true t.queue_down([9,10]) => true
Move torrent(s) to the bottom of the queue:
t.queue_bottom(9) => true
t.queue_bottom([9,10]) => true
Set the location of a torrent:
t.set_location(9, '/path/to/files') => true
t.set_location([9,10], '/path/to/files') => true
t.set_location(9, '/path/to/files', true) => true
t.set_location([9,10], '/path/to/files', true) => true
If the third parameter is true the files will be moved to the new location, otherwise the client will simply look for the files in the new location.
Renaming a torrent's path:
t.rename_path(9, 'file/one', 'file/two') => true
For more information on the use of this function, see the transmission.h documentation of tr_torrentRenamePath(). In particular, note that if this call succeeds you'll want to update the torrent's "files" and "name" field with torrent-get.
Get the session variables:
t.session_get => {}
Set session variables:
t.session_set({
'encryption' => 'required',
'peer-port' => 31337,
'pex-enabled' => false
}) => true
Get session statistics:
t.session_stats => {}
Update the blocklist:
t.blocklist_update => true
Note: this currently doesn't work for me, might be a bug in Transmission.
Test that the external port is reachable via the internet:
t.port_test => boolean
Close the session:
t.session_close => true
Return the amount of free space at a specific directory:
t.free_space("/") => {}