@weejewel/libtorrent

Promise-based Node.js bindings for libtorrent-rasterbar. The native addon uses Node-API and supports magnet URIs and .torrent files. The public API is authored in TypeScript and published as compiled ESM with generated type declarations.

Requirements

• Node.js 20 or newer
• libtorrent-rasterbar 2.x development files
• A C++17 compiler, Python 3, and pkg-config

Install the native requirements before installing the package:

# Debian or Ubuntu
sudo apt-get install build-essential libtorrent-rasterbar-dev pkg-config python3

# macOS with Homebrew
brew install libtorrent-rasterbar boost openssl@3 pkg-config

Then install the package:

npm install @weejewel/libtorrent

The addon compiles against the locally installed libtorrent during npm install.

If macOS cannot find a libtorrent/*.hpp header, verify that Homebrew's pkg-config metadata is visible, then rebuild:

pkg-config --cflags libtorrent-rasterbar
npm run clean
npm run build

Quick start

import libtorrent from "@weejewel/libtorrent";

const session = new libtorrent.Session();

try {
  const torrent = await session.addTorrent(
    "magnet:?xt=urn:btih:...",
    { savePath: "./downloads" },
  );

  const status = await torrent.status();
  console.log(status.name, `${(status.progress * 100).toFixed(1)}%`);

  await torrent.pause();
  await torrent.resume();
} finally {
  await session.close();
}

Named exports and TypeScript declarations are included:

import { Session, Torrent, version } from "@weejewel/libtorrent";

Add a magnet URI

import libtorrent from "@weejewel/libtorrent";

const session = new libtorrent.Session({
  listenInterfaces: "0.0.0.0:6881,[::]:6881",
});

const torrent = await session.addTorrent(
  "magnet:?xt=urn:btih:...",
  { savePath: "/data/downloads" },
);

console.log(await torrent.status());
await session.close();

Add a .torrent file

addTorrent accepts an absolute or relative path, or a file: URL:

const torrent = await session.addTorrent("./movie.torrent", {
  savePath: "./downloads",
});

Track progress

while (true) {
  const status = await torrent.status();

  console.log({
    progress: `${(status.progress * 100).toFixed(1)}%`,
    downloadRate: status.downloadRate,
    uploadRate: status.uploadRate,
    peers: status.numPeers,
    state: status.state,
  });

  if (status.error) throw new Error(status.error);
  if (status.isFinished || status.isSeeding) break;
  await new Promise((resolve) => setTimeout(resolve, 1000));
}

Rates are reported in bytes per second and progress ranges from 0 to 1.

API

new Session(options?)

Creates a libtorrent session. options.listenInterfaces uses libtorrent's comma-separated endpoint syntax and defaults to 0.0.0.0:6881,[::]:6881.

await session.addTorrent(source, options?)

Adds a magnet URI or .torrent file and returns a Torrent. The destination in options.savePath is created automatically and defaults to the current working directory.

await session.torrents()

Returns the active Torrent objects.

await session.status(torrentOrId)

Returns progress, rates, transfer totals, peer counts, state, and any current libtorrent error. await torrent.status() is equivalent.

await torrent.pause() / await torrent.resume()

Pauses or resumes a torrent.

await torrent.remove()

Removes a torrent from the session. Downloaded files are not deleted.

await session.close()

Closes the native session and releases its background threads. Calling it more than once is safe.

Examples

The repository includes complete progress-reporting examples for the public Big Buck Bunny torrent:

node examples/download_big_buck_bunny_file.mjs
node examples/download_big_buck_bunny_magnet.mjs

Press Ctrl-C to close the session cleanly.

CLI

Installing the package exposes libtorrent-download:

libtorrent-download 'magnet:?xt=urn:btih:...' ./downloads
libtorrent-download ./movie.torrent ./downloads

Docker

The image includes the native runtime and exposes the default peer port:

docker build -t weejewel-libtorrent .
docker run --rm -it \
  -p 6881:6881/tcp -p 6881:6881/udp \
  -v "$PWD/downloads:/downloads" \
  weejewel-libtorrent 'magnet:?xt=urn:btih:...' /downloads

Development

npm install
npm run build
npm test
npm run test:package

Publishing

Publishing is handled by .github/workflows/publish.yml when a GitHub Release is published. The release tag must be v followed by the version in package.json, such as v1.0.0.

The workflow can also be started manually from GitHub Actions by entering the matching release tag.

The workflow uses npm Trusted Publishing with short-lived OIDC credentials, so it does not need an NPM_TOKEN. In the npm package settings for @weejewel/libtorrent, add a GitHub Actions trusted publisher with:

• Organization or user: WeeJeWel
• Repository: libtorrent
• Workflow filename: publish.yml
• Allowed action: npm publish

If the package does not exist on npm yet, publish the first version manually, then configure the trusted publisher for subsequent releases.

License

MIT

Torrent details and peers

await torrent.details() (or await session.details(torrentOrId)) returns torrent metadata, trackers, verified per-file downloaded bytes, and connected peers. Before metadata arrives, hasMetadata is false and files is empty; trackers and peers are still available. Padding files are omitted, and file progress counts verified pieces.

const details = await torrent.details();
for (const peer of details.peerList) {
  console.log(peer.ip, peer.port, peer.client, peer.progress);
  console.log(peer.downloadRate, peer.uploadRate);
}

Peer progress describes the remote peer's completion from 0 to 1. Download and upload rates are payload bytes per second received from and sent to that peer, respectively. Connecting and handshaking connections are omitted. Country lookup is left to the application. Details also include name, pieceLength, numPieces, totalSize, and isPrivate when metadata is available.