Task Operations

Adding DownloadsCopy Anchor Link

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). The reverse also applies: addMedia, addMetalink, addNzb, changePosition, getServers, forcePause/forcePauseAll, forceRemove, the routing-rule methods, and setBtPeerBlocklist exist only over JSON-RPC.

addUriCopy Anchor Link

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" }
);

addTorrentCopy Anchor Link

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" });

addMagnetCopy Anchor Link

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",
});

addEd2kCopy Anchor Link

Download using the ED2K protocol.

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

addM3u8Copy Anchor Link

Download an M3U8/HLS stream.

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

addFtpCopy Anchor Link

Download from an FTP/SFTP server.

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

Task OptionsCopy Anchor Link

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:

Controlling DownloadsCopy Anchor Link

pauseCopy Anchor Link

Pause an active download.

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

unpauseCopy Anchor Link

Resume a paused download, or retry an errored one.

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

removeCopy Anchor Link

Remove a download. Active downloads are stopped first.

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

pauseAll / unpauseAllCopy Anchor Link

Pause or resume all downloads at once.

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

ExampleCopy Anchor Link

import risuko from "@risuko/risuko-js";

const { addUri, pause, unpause, remove } = risuko;

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

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

Editing a running taskCopy Anchor Link

updateTaskCopy Anchor Link

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. On an active task, any change to the URI list, dir, or out stops the worker, relocates any .part file when possible, and starts it again. Changing one of these options does the same: split, max-download-limit, header, all-proxy, proxy, no-proxy, user-agent, referer, cookie, max-connection-per-server, min-split-size, checksum, ftp-user, ftp-passwd, sftp-private-key, sftp-private-key-passphrase.
• Torrent tasks reject URI, dir, and out changes. trackers appends extra announce URLs (comma or newline separated) and is persisted on bt-tracker; it is rejected on non-torrent tasks.
• Startup-only option keys are rejected on the patch: rpc-listen-port, rpc-secret, pbh-enable, pbh-listen-port, pbh-rpc-secret, listen-port, dht-listen-port, ed2k-port, ed2k-enable-kad, ed2k-kad-port, bt-max-peers-per-torrent, bt-max-outstanding-per-peer, bt-ban-corrupt-peers, bt-ban-corrupt-strikes, bt-enable-upnp, bt-upnp-lease, bt-enable-lsd, bt-encryption-policy, and bt-listen-v6. The desktop Edit… dialog uses this API.

QueriesCopy Anchor Link

tellStatusCopy Anchor Link

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 FieldsCopy Anchor Link

BitTorrent tasks include additional fields such as infoHash, infoHashV2 (v2 and hybrid torrents), metaVersion, bittorrent (the torrent name is nested at bittorrent.info.name, alongside comment and announceList), seeder, numSeeders, pieceLength, and numPieces. ED2K tasks include ed2kLink, numPeers, and ed2kKad; M3U8 tasks include m3u8Link; Usenet tasks include usenet, usenetStage, usenetWarning, and usenetRepairFailure. Multi-connection HTTP downloads include chunkProgress, an array of { completedLength, totalLength } per chunk.

tellActiveCopy Anchor Link

Get all active downloads.

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

tellWaitingCopy Anchor Link

Get waiting and paused downloads with pagination.

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

tellStoppedCopy Anchor Link

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

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

getGlobalStatCopy Anchor Link

Get global transfer statistics.

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

const stat = await getGlobalStat();
// { downloadSpeed, uploadSpeed, numActive, numWaiting, numStopped, numStoppedTotal,
//   numCompleted, numStoppedError, numScheduled, numPaused }
// numWaiting counts waiting, paused, and scheduled downloads (numPaused and
// numScheduled count those subsets); numStoppedError is
// numStopped minus numCompleted; all values are strings

getFilesCopy Anchor Link

Get the file list for a download.

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

getPeersCopy Anchor Link

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.

getUrisCopy Anchor Link

Get the URI list for a download.

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