aria2.js

JavaScript library for aria2, "The next generation download utility."

• Introduction
• Getting started
• Usage
  • open
  • close
  • call
  • multicall
  • batch
  • listNotifications
  • listMethods
  • events

Introduction

aria2.js controls aria2 via its JSON-RPC interface and features

• Node.js and browsers support
• multiple transports
  • HTTP
  • WebSocket
• promise API
• no 3rd party dependency

See aria2 methods and aria2 notifications.

↑

Getting started

Start aria2 with rpc, example:

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

Install aria2.js

npm install aria2

↑

Usage

import Aria2 from "aria2";

const aria2 = new Aria2(options);

In the browser you can also use node_modules/aria2/bundle.js directly in <script> and window.Aria2.

Aria2 extends EventTarget.

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 WebSocket is open (via the open method) aria2.js will use the WebSocket 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.

await aria2.open();
console.log("open");

↑

close

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

await aria2.close();
console.log("closed");

↑

call

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

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 throw 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 the same as 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.addEventListener(notification, ({detail}) => {
    console.log("aria2", notification, detail);
  }});
});

↑

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.addEventListener("open", () => {
  console.log("aria2", "OPEN");
});

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

// emitted when error occur.
aria2.addEventListener("error", ({ error }) => {
  console.error("aria2", "error", error);
});

// emitted for every data sent.
aria2.addEventListener("input", ({ data }) => {
  console.log("aria2", "IN");
  console.dir(data);
});

// emitted for every data received.
aria2.addEventListener("output", ({ data }) => {
  console.log("aria2", "OUT");
  console.dir(data);
});

// emitted for every notification received.
aria2.addEventListener("notification", ({ method, params }) => {
  console.log("aria2", "notification", { method, params });
});

Additionally, every aria2 notifications is also emitted as an event. Only available when using WebSocket, see open.

aria2.addEventListener("onDownloadStart", ({params: [guid]}) => {
  console.log("aria2 onDownloadStart", guid);
});

↑