aria2-lib

JavaScript library for Aria2. Works in Node.js and the browser.

Introduction

aria2-lib controls Aria2 via its JSON-RPC interface and features

• Node.js and browser support
• multiple transports
  • HTTP
  • WebSocket
• Promise API
• Full typing support (written in TypeScript)

See Aria2 methods and Aria2 notifications.

Getting Started

Start Aria2 with RPC, for example:

aria2c --enable-rpc --rpc-listen-all=true --rpc-allow-origin-all

Browser

npm install aria2-lib

import Aria2 from 'aria2-lib';

const aria2 = new Aria2({ WebSocket: ws, fetch: nodefetch, ...options });

You can also use node_modules/aria2-lib/browser/aria2-lib.js directly in a <script> and access the Aria2 class with window.Aria2.

Node.js

npm install aria2-lib node-fetch ws

import Aria2 from 'aria2-lib';
import ws from 'ws';
import nodefetch from 'node-fetch';

const aria2 = new Aria2({ WebSocket: ws, fetch: nodefetch, ...options });

Usage

The default options match aria2c defaults and are

{
  host: 'localhost',
  port: 6800,
  secure: false,
  secret: '',
  path: '/jsonrpc',
}

secret is optional and refers to --rpc-secret. If you define it, it will be added to every call for you.

If the web socket is open (via the open method), aria2-lib will use the web socket transport, otherwise the HTTP transport.

The 'aria2.' prefix can be omitted from both methods and notifications.

open()

aria2.open() opens the WebSocket connection. All subsequent requests will use the WebSocket transport instead of HTTP.

aria2
  .open()
  .then(() => console.log('open'))
  .catch((err) => console.log('error', err));

close()

aria2.close() closes the WebSocket connection. All subsequent requests will use the HTTP transport instead of WebSocket.

aria2
  .close()
  .then(() => console.log('closed'))
  .catch((err) => console.log('error', err));

call()

aria2.call() calls a method. Parameters are provided as arguments.

Here's an example using addUri method to download from a magnet link.

const magnet =
  'magnet:?xt=urn:btih:88594AAACBDE40EF3E2510C47374EC0AA396C08E&dn=bbb_sunflower_1080p_30fps_normal.mp4&tr=udp%3a%2f%2ftracker.openbittorrent.com%3a80%2fannounce&tr=udp%3a%2f%2ftracker.publicbt.com%3a80%2fannounce&ws=http%3a%2f%2fdistribution.bbb3d.renderfarming.net%2fvideo%2fmp4%2fbbb_sunflower_1080p_30fps_normal.mp4';
const [guid] = await aria2.call('addUri', [magnet], { dir: '/tmp' });

multicall()

aria2.multicall() is a helper for system.multicall. It returns an array of results or throws if any of the call failed.

const multicall = [
  [methodA, param1, param2],
  [methodB, param1, param2],
];

const results = await aria2.multicall(multicall);

batch()

aria2.batch() is a helper for batch. It behaves like multicall() except it returns an array of promises which gives more flexibility in handling errors.

const batch = [
  [methodA, param1, param2],
  [methodB, param1, param2],
];

const promises = await aria2.batch(batch);

listNotifications()

aria2.listNotifications() is a helper for system.listNotifications. The difference with aria2.call('listNotifications') is that it removes the 'aria2.' prefix from the results.

const notifications = await aria2.listNotifications();
/*
[
  'onDownloadStart',
  'onDownloadPause',
  'onDownloadStop',
  'onDownloadComplete',
  'onDownloadError',
  'onBtDownloadComplete'
]
*/

// notifications logger example
notifications.forEach((notification) => {
  aria2.on(notification, (params) => {
    console.log('aria2', notification, params);
  });
});

listMethods()

aria2.listMethods() is a helper for system.listMethods. The difference with aria2.call('listMethods') is that it removes the 'aria2.' prefix for the results.

const methods = await aria2.listMethods();
/*
[ 'addUri',
  [...]
  'system.listNotifications' ]

*/

Events

// emitted when the WebSocket is open.
aria2.on('open', () => {
  console.log('aria2 OPEN');
});

// emitted when the WebSocket is closed.
aria2.on('close', () => {
  console.log('aria2 CLOSE');
});

// emitted for every message sent.
aria2.on('output', (m) => {
  console.log('aria2 OUT', m);
});

// emitted for every message received.
aria2.on('input', (m) => {
  console.log('aria2 IN', m);
});

Additionally, every Aria2 notification received will be emitted as an event (with and without the 'aria2.' prefix). This is only available when using a web socket connection, see open.

aria2.on('onDownloadStart', ([guid]) => {
  console.log('aria2 onDownloadStart', guid);
});