naria2

Convenient BitTorrent Client based on the aria2 JSON RPC Interface and aria2c CLI application with Web UI.

• Download aria2 prebuilt binary according to your architecture and platform
• Convenient BitTorrent downloading API
• Event bus used for watching progress, state change, error handling
• Vite plugin which helps you develop aria2 client application
• Web UI for aria2c and naria2c

Introduction blog post 构建一个易用的 aria2 客户端包和 CLI 应用 in Chinese.

Cross-platform aria2c

It is used in the same way as aria2c.

$ npm i -g naria2c

$ naria2c --version
naria2c/0.0.26
--------------
...

$ naria2c --help

You can also launch a Web UI to manage aria2 using the --ui option. This feature is provided by this package, not the original aria2.

$ naria2c --ui
...
10/29 21:22:46 [NOTICE] WebUI is listening on the http://127.0.0.1:6801?port=6800&secret=123456
...

Quickstart

Browser

npm i naria2

Using WebSocket:

import { createClient } from 'naria2'

const client = await createClient(
  new WebSocket('ws://localhost:6800/jsonrpc')
)

Using HTTP:

import { createClient } from 'naria2'
import { createHTTP } from 'naria2/transport'

const client = await createClient(
  createHTTP('http://localhost:6800/jsonrpc')
)

Node.js standalone

If you want to use naria2 in the Node.js standalone, you can install @naria2/node. It has included a prebuilt aria2 binary according to your architecture, so that there is no need to install a aria2 on your own.

npm i naria2 @naria2/node

You can use the createChildProcess API to spawn an aria2 child process, and connect to it in WebScoket under the hood.

import { createClient } from 'naria2'
import { createChildProcess } from '@naria2/node'

const client = await createClient(createChildProcess())

Warning

You should close the client on your own, otherwise the aria2 process may not be killed even if your program finished or crashed.

See my blog post (in Chinese) or The Death of a Node.js Process (in English) on how to handle the exit of a Node.js process.

Usage

import { createClient } from 'naria2'
import { createChildProcess } from '@naria2/node'

// Initialize a client
const client = await createClient(createChildProcess())

// Start downloading a magnet
const torrent = await client.downloadUri('...')

// Wait for torrent download finished
await torrent.watchTorrent(
  // Watch metadata progress
  (task) => {
    console.log(`Downloading [MEATADATA]`)
  },
  // Watch torrent progress
  (task) => {
    console.log(`Downloading torrent`)
  },
  // Wait for the target event being fired
  // 'bt-complete': downloading finished
  // 'complete':    seeding finished
  'bt-complete'
)

// Shutdown client
await client.shutdown()

You can find detailed examples using Node.js here: examples/magnet.mjs, examples/torrent.mjs, examples/http.mjs.

Due to the implementation of aria2, the downloading progress of a magnet uri includes two steps:

1. Download the torrent metadata which contains a special file name with prefix [METADATA];
2. Download the torrent content itself.

So that, in the above code, the first callback is to wait for downloading metadata, and then the second callback is to wait for downloading the followed by task which is the torrent content itself.

Credits

• aria2: A lightweight multi-protocol & multi-source, cross platform download utility operated in command-line
• maria2: Modern & Simple RPC Library for aria2c made by @hydrati
• aria2-static-builds and Motrix: Build aria2 binaries for different platforms

License

MIT License © 2024 XLor