Skip to content

Latest commit

 

History

History
406 lines (358 loc) · 14.2 KB

README.md

File metadata and controls

406 lines (358 loc) · 14.2 KB
Raw

BTC

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

License

BTC is released under the MIT 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