Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bittorrent/btc

Command-line BitTorrent remote control (btc)
https://github.com/bittorrent/btc

Last synced: about 1 month ago
JSON representation

Command-line BitTorrent remote control (btc)

Awesome Lists containing this project

README 

        
BTC

===



This project enables you to control uTorrent from the command line.



License

-------



BTC is released under the [MIT](http://www.opensource.org/licenses/mit-license.php) license.



Installation

------------



BTC requires python 2.6.x or 2.7.x and can be installed using pip:



    $ pip install -U https://github.com/bittorrent/btc/tarball/master



If you were to make changes to the source code, which is welcome, you

can fork the git repository on Github and install a development setup

doing:



    $ python setup.py develop



You can then use pull requests if you want your changes to be

integrated.



Configuration

-------------



Located in your home folder, the settings file should be named `.btc`.

This file has to hold a valid JSON dictionary. In order to have BTC

talk to uTorrent we need to set `host`, `port`, `username` and

`password` settings properly. All these settings have default values

so an empty settings file will be equivalent to:



    {

      "host": "127.0.0.1",

      "port": 8080,

      "username": "admin",

      "password": ""

    }



In order to keep this file clean you can use `btc set` to change

settings.



    $ btc set host 192.168.1.10

    $ btc set port 8889



If you want to remove a setting and get the default back, you can use

the `--delete` option to get rid of it.



    $ btc set --delete host



Finally if you want to use a configuration file named differently you

can set then environment variable `BTC_CONFIG_FILE` to another

absolute path.



Usage

-----



BTC is made to behave in a way that might surprise you at first.  It

is made to be piped into itself. What does it mean? When you pipe a

command into another, say you type `ls | grep bittorrent`, the output

of `ls` is going to be used as the input of `grep` and `grep` will

output only the lines with the word `bittorrent`. BTC leverages this

mecanism as its core way of processing data and requesting

actions. Everything beggins with the `list` command.



    $ btc list

    [

      {

        "name": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "sid": "5deab0a",

        "dl_rate": 0,

        "done": 815997472,

        "peers_connected": 0,

        "seeds_connected": 0,

        "size": 815997472,

        "state": "SEEDING",

        "ul_rate": 0

      },

      {

        "name": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",

        "hash": "779E32E8D82521A3472FE6F93C0B29984A7FB411",

        "sid": "5d6264e",

        "dl_rate": 0,

        "done": 477507449,

        "peers_connected": 0,

        "seeds_connected": 0,

        "size": 477507449,

        "state": "SEEDING",

        "ul_rate": 0

      }

    ]



This command queries uTorrent for the list of all its torrents, and

BTC outputs them, using JSON format, as a list of dictionaries each

dictionary being a torrent. Each torrent is reported with its name and

hash but other information such as `peers_connected` or current

`state` and so on. This is nice, but what next? This command can then

be piped to other commands in order to filter the information you want

and have BTC perform the operations you want on your uTorrent

client. Let's say you want to stop the torrent named with all these

'A's.



    $ btc list "A*" | btc stop



This torrent is not going to be seeded anymore by uTorrent. Don't

worry, you can restart it using the `start` command. This is the right

moment to mention that `btc list` takes an optional argument which

filters all the torrents by name allowing glob syntax. The

`--case-sensitive` or the shorter `-s` options can be used to enforce

case sensitivity. Some of you might think that it is a lot more

complicated than doing `btc stop "A*"`. Fair enough, but what if you

only want to stop torrents with a `dl_rate` of zero?



    $ btc list | btc filter --key dl_rate --numeric-equals 0 | btc stop



As simple as that. The `filter` command is here to help you select the

entries you want and reject the other ones. It can be used to filter

anything BTC outputs, not only torrents, but we will see that

afterwards. The `filter` command can have multiple arguments (see `btc

filter --help`) such as `--nth N` which select the N-th entry in a

list or `--first N` which takes the N first entries of the

list. Given a key supplied with `--key` each entry is going to be

selected if:



    $ btc list | btc filter --key KEY "X*"  # it matches a string, supporting glob syntax

    $ btc list | btc filter --key KEY --numeric-equals X  # its numeric value equals X

    $ btc list | btc filter --key KEY --numeric-differs X # its numeric value differs from X

    $ btc list | btc filter --key KEY --less X    # its numeric value is less than X

    $ btc list | btc filter --key KEY --greater X # its numeric value is greater than X

    $ btc list | btc filter --key KEY --true      # it is the boolean value true

    $ btc list | btc filter --key KEY --false     # it is the boolean value false

    ...



Multiple filter commands can be piped one after the other for the

output to match exactly what you want.



What about files? A torrent can have multiple files and you can list

them using the `files` command. Hence for one or many torrents

outputed by `btc list`, `btc files` lists the files inside this or

these torrents.



    $ btc list "A*" | btc files

    [

      {

        "name": "audio_1.mp3",

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "sid": "5deab0a",

        "fileid": 0,

        "downloaded": 6579667,

        "priority": 2,

        "size": 6579667

      },

      {

        "name": "image_1.jpeg",

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "sid": "5deab0a",

        "fileid": 1,

        "downloaded": 384077,

        "priority": 2,

        "size": 384077

      },

      {

        "name": "video_6.mpg",

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "sid": "5deab0a",

        "fileid": 2,

        "downloaded": 809033728,

        "priority": 2,

        "size": 809033728

      }

    ]



This lists all the files of the torrent(s) given in input. The

`filter` command can be used here again to select some of these

files. But let's introduce the `sort` command. It allows you to sort

the results by simply piping them to `btc sort`. By default, giving it

no arguments, it is going to sort the entries by name. Another key can

also be specified with the option `--key` if you were to sort by size

for instance. You can also reverse the sort by using the option

`--reverse`.



    $ btc list | btc files | btc sort

    [

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "audio_1.mp3",

        "priority": 2,

        "downloaded": 6579667,

        "sid": "5deab0a",

        "size": 6579667,

        "fileid": 0

      },

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "image_1.jpeg",

        "priority": 2,

        "downloaded": 384077,

        "sid": "5deab0a",

        "size": 384077,

        "fileid": 1

      },

      {

        "hash": "779E32E8D82521A3472FE6F93C0B29984A7FB411",

        "name": "image_2.jpg",

        "priority": 2,

        "downloaded": 3386455,

        "sid": "5d6264e",

        "size": 3386455,

        "fileid": 0

      },

      {

        "hash": "779E32E8D82521A3472FE6F93C0B29984A7FB411",

        "name": "video_14.avi",

        "priority": 2,

        "downloaded": 474120994,

        "sid": "5d6264e",

        "size": 474120994,

        "fileid": 1

      },

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "video_6.mpg",

        "priority": 2,

        "downloaded": 809033728,

        "sid": "5deab0a",

        "size": 809033728,

        "fileid": 2

      }

    ]



    $ btc list | btc files | btc sort --key size

    [

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "image_1.jpeg",

        "priority": 2,

        "downloaded": 384077,

        "sid": "5deab0a",

        "size": 384077,

        "fileid": 1

      },

      {

        "hash": "779E32E8D82521A3472FE6F93C0B29984A7FB411",

        "name": "image_2.jpg",

        "priority": 2,

        "downloaded": 3386455,

        "sid": "5d6264e",

        "size": 3386455,

        "fileid": 0

      },

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "audio_1.mp3",

        "priority": 2,

        "downloaded": 6579667,

        "sid": "5deab0a",

        "size": 6579667,

        "fileid": 0

      },

      {

        "hash": "779E32E8D82521A3472FE6F93C0B29984A7FB411",

        "name": "video_14.avi",

        "priority": 2,

        "downloaded": 474120994,

        "sid": "5d6264e",

        "size": 474120994,

        "fileid": 1

      },

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "video_6.mpg",

        "priority": 2,

        "downloaded": 809033728,

        "sid": "5deab0a",

        "size": 809033728,

        "fileid": 2

      }

    ]



    $ btc list | btc files | btc sort --key size --reverse

    [

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "video_6.mpg",

        "priority": 2,

        "downloaded": 809033728,

        "sid": "5deab0a",

        "size": 809033728,

        "fileid": 2

      },

      {

        "hash": "779E32E8D82521A3472FE6F93C0B29984A7FB411",

        "name": "video_14.avi",

        "priority": 2,

        "downloaded": 474120994,

        "sid": "5d6264e",

        "size": 474120994,

        "fileid": 1

      },

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "audio_1.mp3",

        "priority": 2,

        "downloaded": 6579667,

        "sid": "5deab0a",

        "size": 6579667,

        "fileid": 0

      },

      {

        "hash": "779E32E8D82521A3472FE6F93C0B29984A7FB411",

        "name": "image_2.jpg",

        "priority": 2,

        "downloaded": 3386455,

        "sid": "5d6264e",

        "size": 3386455,

        "fileid": 0

      },

      {

        "hash": "45097EB957FD45EE657A442B16F702251CBB8E35",

        "name": "image_1.jpeg",

        "priority": 2,

        "downloaded": 384077,

        "sid": "5deab0a",

        "size": 384077,

        "fileid": 1

      }

    ]



You can also download on your disk some files using the `download`

command. Piping a list of files to `btc download` will download them

to the directory from which BTC is run. To change the output directory

you can use the `--directory` option. If you are dealing with a single

file you can also rename it using the `--output` option. Last but not

least, if uTorrent is running on Windows you need to add the

`--windows` option so that the backslashes will be converted to

forward slashes.



    $ btc list | btc files | btc download

    downloading: ./audio_1.mp3

    downloading: ./image_1.jpeg

    downloading: ./image_2.jpg

    downloading: ./video_14.avi

    downloading: ./video_6.mpg



    $ btc list | btc files | btc download --directory /tmp

    downloading: /tmp/audio_1.mp3

    downloading: /tmp/image_1.jpeg

    downloading: /tmp/image_2.jpg

    downloading: /tmp/video_14.avi

    downloading: /tmp/video_6.mpg



    $ btc list | btc files | btc filter --nth 1 | btc download --output /tmp/file

    downloading: /tmp/file



Want to stream? No problem, use `btc stream`. With files as input it

will run a stream command with the appropriate streaming url. By

default it outputing the stream urls to your terminal. You can provide

a streaming command using the `--command` option.



    $ btc list | btc files | btc stream

    btc stream: warning: no stream command specified, outputing streaming links

    audio_1.mp3: http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=0&service=DOWNLOAD&qos=0&disposition=inline

    image_1.jpeg: http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=1&service=DOWNLOAD&qos=0&disposition=inline

    image_2.jpg: http://admin:@127.0.0.1:8080/proxy?sid=5d6264e&file=0&service=DOWNLOAD&qos=0&disposition=inline

    video_14.avi: http://admin:@127.0.0.1:8080/proxy?sid=5d6264e&file=1&service=DOWNLOAD&qos=0&disposition=inline

    video_6.mpg: http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=2&service=DOWNLOAD&qos=0&disposition=inline

    $ btc list | btc files | btc filter --nth 1 | btc stream --command mplayer

    running: mplayer http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=0&service=DOWNLOAD&qos=0&disposition=inline

    $ btc list | btc files | btc stream --command mplayer

    running: mplayer http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=0&service=DOWNLOAD&qos=0&disposition=inline

    running: mplayer http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=1&service=DOWNLOAD&qos=0&disposition=inline

    running: mplayer http://admin:@127.0.0.1:8080/proxy?sid=5d6264e&file=0&service=DOWNLOAD&qos=0&disposition=inline

    running: mplayer http://admin:@127.0.0.1:8080/proxy?sid=5d6264e&file=1&service=DOWNLOAD&qos=0&disposition=inline

    running: mplayer http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=2&service=DOWNLOAD&qos=0&disposition=inline



If you want to play all the files using a single instance of the

command you may use the option `--together` which has the following

behavior:



    $ btc list | btc files | btc stream --command mplayer --together

    running: mplayer http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=0&service=DOWNLOAD&qos=0&disposition=inline http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=1&service=DOWNLOAD&qos=0&disposition=inline http://admin:@127.0.0.1:8080/proxy?sid=5d6264e&file=0&service=DOWNLOAD&qos=0&disposition=inline http://admin:@127.0.0.1:8080/proxy?sid=5d6264e&file=1&service=DOWNLOAD&qos=0&disposition=inline http://admin:@127.0.0.1:8080/proxy?sid=5deab0a&file=2&service=DOWNLOAD&qos=0&disposition=inline



Here is the way to add a torrent by url or using a file on your

computer:



    $ btc add http://www.clearbits.net/get/547-home-2009.torrent

    $ btc add "home project - home 2009.torrent"



And then you can remove the torrent from your downloads keeping or not

the torrent file and dropping or not the data:



    $ btc list "Home Project - Home 2009" | btc remove

    $ btc list "Home Project - Home 2009" | btc remove --keep-torrent

    $ btc list "Home Project - Home 2009" | btc remove --drop-data

    $ btc list "Home Project - Home 2009" | btc remove --keep-torrent --drop-data



Finally the `wait` command simply waits for a torrent to complete. You

can use that to run a command when the torrent is complete, shutdown

for instance...



    $ btc list "Home Project - Home 2009" | btc wait && shutdown