bittorrent-client

Simple, robust, streaming bittorrent client.

bittorrent-client

This module is deprecated. Please use the webtorrent module instead, which has an equivalent API.

Simple, robust, torrent client that exposes files as streams so you can access file content before a torrent has finished downloading. This module is used by WebTorrent and heavily inspired by the excellent design of torrent-stream by @mafintosh.

  • insanely fast
  • pure javascript (no native dependencies)
  • exposes individual files as streams to access file content before torrent is finished
    • sequentially requests pieces from peers (when necessary)
    • otherwise, uses rarest-first piece strategy
  • download multiple torrents simultaneously, efficiently
  • supports advanced torrent client features
  • comprehensive test suite (completely offline, so it's reliable and fast)
npm install bittorrent-client

Access files inside a torrent as node.js readable streams.

The client automatically connects to the DHT to fetch torrent metadata (if necessary) and to discover new peers. If the magnet uri or .torrent file contains tracker urls, the client automatically connects to trackers to discover new peers.

var BitTorrentClient = require('bittorrent-client')
 
var client = new BitTorrentClient()
 
// "Pride and Prejudice" by Jane Austen 
client.add('magnet:?xt=urn:btih:1e69917fbaa2c767bca463a96b5572785c6d8a12')
 
client.on('torrent', function (torrent) {
  // torrent metadata has been fetched 
  console.log(torrent.name)
 
  torrent.files.forEach(function (file) {
    console.log(file.name)
    // get a readable stream of the file content 
    var stream = file.createReadStream()
  })
})

You can pass start and end options to createReadStream to stream only a slice of a file.

// get a stream containing bytess 100-1000 inclusive 
var stream = file.createReadStream({
  start: 100
  end: 1000
})

By default, no files are downloaded until you call file.createReadStream. If you want to download a particular file without creating a stream, call file.select and file.deselect.

To download multiple torrents simulataneous, just reuse the same instance of Client. This will improve the download speed, conserve system resources, and allow internal state like the DHT routing table to be re-used.

// Sintel movie in 4K 
var magnet = 'magnet:?xt=urn:btih:489a21c45f7eb13ad75b3b9bfa0132b1be035f62'
 
client.add(magnet, function (errtorrent) {
  if (!err) {
    // torrent metadata has been fetched 
    console.log(torrent.name)
  }
})

You can also download from a local torrent file, or a URL to a torrent.

var fs = require('fs')
 
var file = fs.readFileSync('/path/to/file.torrent')
client.add(file)
 
var url = 'http://releases.ubuntu.com/14.04/ubuntu-14.04-server-amd64.iso.torrent'
client.add(url)

Create a new bittorrent-client instance.

If opts is specified, then the default options (shown below) will be overridden.

{
  maxPeers: 100,          // Max number of peers to connect to (per torrent) 
  peerId: '',             // Wire protocol peer ID (otherwise, randomly generated) 
  nodeId: '',             // DHT protocol node ID (otherwise, randomly generated) 
  tracker: true,          // Whether or not to enable trackers 
  dht: true,              // Whether or not to enable DHT 
  verify: true            // Verify previously stored data before starting 
}

Aliased as client.download.

Start downloading a torrent. Aliased as client.download.

torrentId can be any of the following:

  • info hash (as a hex string or Buffer)
  • magnet uri (as a utf8 string)
  • .torrent file (as a Buffer)
  • parsed torrent (from parse-torrent)
  • http/https url to a .torrent file (string)
  • filesystem path to a .torrent file (string)

If ontorrent is specified, then it will be called when this torrent is ready to be used (i.e. metadata is available). Note: this is distinct from the 'torrent' event which will fire for all torrents.

If you want access to the torrent object immediately in order to listen to events as the metadata is fetched from the network, then use the return value of client.add. If you just want the file data, then use ontorrent or the 'torrent' event.

Start seeding a new torrent.

input can be any of the following:

  • path to the file or folder on filesystem (string)
  • W3C File object (from an <input> or drag and drop)
  • W3C FileList object (basically an array of File objects)
  • Array of File objects

If opts is specified, it should contain the following types of options:

  • options for create-torrent (to allow configuration of the .torrent file that is created)
  • options for client.add (see above)

If onseed is specified, it will be called when the client has begun seeding the file.

Emitted when a torrent is ready to be used (i.e. metadata is available and storage is ready). See the torrent section for more info on what methods a torrent has.

Remove a torrent from the client. Destroy all connections to peers and delete all saved file data. Optional callback is called when file data has been removed.

Destroy the client, including all torrents and connections to peers.

Listen for incoming peers on the specified port. Port defaults to 6881

An array of all torrents in the client.

Return the torrent with the given torrentId. Easier than searching through the client.torrents array by hand for the torrent you want.

Aggregate seed ratio for all torrents in the client.

An array of all files in the torrent. See the file section for more info on what methods the file has.

The attached bittorrent-swarm instance.

Alias for client.remove(torrent).

Adds a peer to the underlying bittorrent-swarm instance.

Selects a range of pieces to prioritize starting with start and ending with end (both inclusive) at the given priority. notify is an optional callback to be called when the selection is updated with new data.

Deprioritizes a range of previously selected pieces.

Marks a range of pieces as critical priority to be downloaded ASAP. From start to end (both inclusive).

File name, as specified by the torrent. Example: 'some-filename.txt'

File path, as specified by the torrent. Example: 'some-folder/some-filename.txt'

File length (in bytes), as specified by the torrent. Example: 12345

Selects the file to be downloaded, but at a lower priority than files with streams. Useful if you know you need the file at a later stage.

Deselects the file, which means it won't be downloaded unless someone creates a stream for it.

Create a readable stream to the file. Pieces needed by the stream will be prioritized highly and fetched from the swarm first.

You can pass opts to stream only a slice of a file.

{
  start: startByte,
  end: endByte
}

Both start and end are inclusive.

MIT. Copyright (c) Feross Aboukhadijeh.