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`	Proxy URL	`"http://proxy:8080"`
`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

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"`, `"torrent"`, `"ed2k"`, `"m3u8"`, `"ftp"`, `"media"`, ...
`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 (name, comment, announce list), 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>[]>;

getUris

Get the URI list for a download.

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

Task Operations

On this page