Task Operations

Adding Downloads

All add* functions return a GID (Global ID) string that identifies the download task.

addUri, addTorrent, and addEd2k have corresponding JSON-RPC methods. addMagnet, addM3u8, and addFtp are available only through the Node.js bindings — they call the engine manager directly (not via RPC).

addUri

Download from one or more HTTP/HTTPS URLs. Multiple URLs are treated as mirrors for the same file.

function addUri(
  uris: string[],
  options?: Record<string, unknown>
): Promise<string>;

const gid = await addUri(
  ["https://mirror1.example.com/file.zip", "https://mirror2.example.com/file.zip"],
  { split: "16", dir: "/downloads", out: "file.zip" }
);

addTorrent

Download from a .torrent file. Pass the raw file contents as a Buffer.

function addTorrent(
  data: Buffer,
  options?: Record<string, unknown>
): Promise<string>;

import { readFile } from "node:fs/promises";

const torrentData = await readFile("./ubuntu.torrent");
const gid = await addTorrent(torrentData, { dir: "/downloads" });

addMagnet

Download from a magnet link.

function addMagnet(
  uri: string,
  options?: Record<string, unknown>
): Promise<string>;

const gid = await addMagnet("magnet:?xt=urn:btih:abc123...", {
  dir: "/downloads",
  "seed-ratio": "1.0",
});

addEd2k

Download using the ED2K protocol.

function addEd2k(
  uri: string,
  options?: Record<string, unknown>
): Promise<string>;

addM3u8

Download an M3U8/HLS stream.

function addM3u8(
  uri: string,
  options?: Record<string, unknown>
): Promise<string>;

addFtp

Download from an FTP/SFTP server.

function addFtp(
  uri: string,
  options?: Record<string, unknown>
): Promise<string>;

Task Options

Options are passed as a flat object. String values follow the aria2 convention; numeric and boolean keys also accept plain numbers and booleans. Common options:

Key	Description	Example
`dir`	Download directory	`"/downloads"`
`out`	Output filename	`"file.zip"`
`risuko-start-at`	Scheduling timestamp in Unix seconds. The engine honors it for non-torrent tasks, but the Node.js package does not expose a `tellScheduled` helper	`1783459200`
`split`	Number of connections	`"16"`
`header`	HTTP headers (array of strings, or one newline-separated string)	`["Cookie: foo=bar"]`
`user-agent`	User agent string	`"MyApp/1.0"`
`all-proxy`	HTTP-profile proxy URL	`"http://proxy:8080"`
`p2p-proxy`	P2P TCP proxy URL (BitTorrent / eD2K / Gnutella)	`"socks5h://127.0.0.1:1080"`
`referer`	HTTP referer	`"https://example.com"`
`seed-ratio`	BT seed ratio	`"1.0"`
`seed-time`	BT seed time (minutes)	`"60"`
`max-download-limit`	Speed limit in bytes/s; `K` and `M` suffixes allowed, `0` = unlimited	`"1M"`

Controlling Downloads

pause

Pause an active download.

function pause(gid: string): Promise<void>;

unpause

Resume a paused download.

function unpause(gid: string): Promise<void>;

remove

Remove a download. Active downloads are stopped first.

function remove(gid: string): Promise<void>;

pauseAll / unpauseAll

Pause or resume all downloads at once.

function pauseAll(): Promise<void>;
function unpauseAll(): Promise<void>;

Example

import { addUri, pause, unpause, remove } from "@risuko/risuko-js";

const gid = await addUri(["https://example.com/file.zip"]);

await pause(gid);     // Pause
await unpause(gid);   // Resume
await remove(gid);    // Remove

Editing a running task

updateTask

Apply a structured patch to an existing task. Unlike changeOption, this can replace URIs, move the save path, rename the output, and append BitTorrent trackers, and it will restart an active worker when those fields require it.

function updateTask(
  gid: string,
  patch: {
    uris?: string[];
    dir?: string;
    out?: string;
    trackers?: string[];
    options?: Record<string, unknown>;
  }
): Promise<{
  restarted: boolean;
  trackersAdded: number;
  progressPreserved: boolean;
}>;

const outcome = await updateTask(gid, {
  uris: ["https://mirror.example.com/file.zip"],
  dir: "/downloads",
  options: { split: "8" },
});
console.log(outcome.restarted, outcome.progressPreserved);

At least one of uris, dir, out, trackers, or options must be set.
Finished tasks (complete / removed) cannot be edited; errored tasks can.
HTTP, media, m3u8, FTP, and similar tasks accept URI, directory, and filename changes. Thunder links in uris are decoded to HTTP. Changing the primary URI, dir, or out on an active task stops the worker, relocates any .part file when possible, and starts it again.
Torrent tasks reject URI, dir, and out changes. trackers appends extra announce URLs (comma or newline separated) and is persisted on bt-tracker.
Startup-only option keys (rpc-*, pbh-*, listen ports, most bt-*) are rejected on the patch. The desktop Edit… dialog uses this API.

Queries

tellStatus

Get the status of a specific download. Optionally filter which fields to return.

function tellStatus(
  gid: string,
  keys?: string[]
): Promise<Record<string, unknown>>;

const status = await tellStatus(gid);
// { gid, status, totalLength, completedLength, downloadSpeed, ... }

// Request specific fields only
const partial = await tellStatus(gid, ["status", "completedLength"]);

Status Fields

Field	Type	Description
`gid`	`string`	Global ID
`status`	`string`	`"active"`, `"waiting"`, `"paused"`, `"scheduled"`, `"complete"`, `"removed"`, `"error"`
`kind`	`string`	Protocol family: `"http"`, `"media"`, `"torrent"`, `"ed2k"`, `"m3u8"`, `"ftp"`, `"metalink"`, `"usenet"`, `"adc"`, `"gnutella"`, `"g2"`, or `"gift"`
`totalLength`	`string`	Total file size in bytes
`completedLength`	`string`	Downloaded bytes
`downloadSpeed`	`string`	Current download speed (bytes/s)
`uploadSpeed`	`string`	Current upload speed (bytes/s)
`files`	`object[]`	Array of file information
`connections`	`string`	Number of connections
`dir`	`string`	Download directory
`createdAt`	`string`	Creation time (ms since epoch)
`startAt`	`string`	Scheduled start time in Unix seconds, present only for scheduled tasks
`scheduleMissed`	`boolean`	Present and `true` when a scheduled task missed its 5-minute grace window
`errorCode`	`string`	Error code (if status is `"error"`)
`errorMessage`	`string`	Error description

BitTorrent tasks include additional fields such as infoHash, bittorrent (the torrent name is nested at bittorrent.info.name, alongside comment and announceList), seeder, and numSeeders. Multi-connection HTTP downloads include chunkProgress, an array of { completedLength, totalLength } per chunk.

tellActive

Get all active downloads.

function tellActive(
  keys?: string[]
): Promise<Record<string, unknown>[]>;

tellWaiting

Get waiting and paused downloads with pagination.

function tellWaiting(
  offset: number,
  num: number,
  keys?: string[]
): Promise<Record<string, unknown>[]>;

tellStopped

Get stopped downloads (complete, error, removed) with pagination.

function tellStopped(
  offset: number,
  num: number,
  keys?: string[]
): Promise<Record<string, unknown>[]>;

getGlobalStat

Get global transfer statistics.

function getGlobalStat(): Promise<Record<string, unknown>>;

const stat = await getGlobalStat();
// { downloadSpeed, uploadSpeed, numActive, numWaiting, numStopped, numStoppedTotal }
// numWaiting counts waiting, paused, and scheduled downloads; all values are strings

getFiles

Get the file list for a download.

function getFiles(gid: string): Promise<Record<string, unknown>[]>;

getPeers

Get connected peers for a BitTorrent download. Returns an empty array for non-BitTorrent tasks or unknown GIDs.

function getPeers(gid: string): Promise<Record<string, unknown>[]>;

Each peer object includes aria2-compatible fields (ip, port, amChoking, peerChoking, seeder) plus Aria2Next-style extras used by PeerBanHelper: peerId, peerClientName, percent, amInterested, peerInterested, downloadSpeed, uploadSpeed, downloaded, uploaded, progress, incoming, snubbed, handshaking, optimisticUnchoke, and bitfield.

getUris

Get the URI list for a download.

function getUris(gid: string): Promise<Record<string, unknown>[]>;

Task Operations

On this page