Options
Read and modify engine and per-task options at runtime.
Per-Task Options
getOption
Get the options for a specific download task. Returns only the keys set on the task itself (at add time or via changeOption); global options are not merged in.
function getOption(gid: string): Promise<Record<string, unknown>>;const gid = await addUri(["https://example.com/file.zip"], { split: "8" });
const options = await getOption(gid);
console.log(options.split); // "8"
console.log(options.dir); // undefined unless set per-taskchangeOption
Change options for a running task. Only some options can be changed after a download starts.
function changeOption(
gid: string,
options: Record<string, unknown>
): Promise<void>;// Stop a seeding torrent immediately
await changeOption(gid, { "seed-time": "0" });Changeable Options
changeOption merges the provided keys into the task's option map, so any key can be stored. These keys affect a running task:
| Key | Effect on a running task |
|---|---|
seed-time, seed-ratio, keep-seeding | Per-task seeding goals. They override the global values on every progress tick (unset keys fall back to the globals). seed-time and seed-ratio accept numbers or numeric strings; keep-seeding accepts a boolean or "true" / "false" |
seed-time = 0 | While a torrent is seeding and the effective seed-ratio is 0 or absent, seeding stops immediately and risuko.onDownloadComplete is emitted |
select-file | Torrents only: applied to the live torrent immediately. 1-based file indices with aria2-style ranges ("1-3,7"); padding files are not counted, and an empty string selects every file. Deselected files that share pieces with selected ones are kept as part files. See File selection |
max-download-limit | Stored on the task; the per-task speed limiter is built when a worker starts, so the new limit applies the next time the task is restarted (e.g. pause then unpause) |
Other options are stored on the task and used the next time a relevant action runs (for example, dir/out when the task is restarted). To change URIs, the save path, or trackers on an existing task, use updateTask instead.
Global Options
getGlobalOption
Get the current global engine options.
function getGlobalOption(): Promise<Record<string, unknown>>;const global = await getGlobalOption();
console.log(global["max-concurrent-downloads"]);
console.log(global["max-overall-download-limit"]);changeGlobalOption
Change global engine options. These affect new downloads and some aspects of running downloads.
Changes are held in memory only and are lost when the engine stops. To persist a setting, write it to system.json or user.json in the config directory before calling startEngine.
function changeGlobalOption(
options: Record<string, unknown>
): Promise<void>;// Limit to 3 concurrent downloads
await changeGlobalOption({ "max-concurrent-downloads": "3" });
// Set global speed limit to 10 MB/s
await changeGlobalOption({ "max-overall-download-limit": "10485760" });Global Option Reference
Defaults come from src-tauri/risuko-engine/src/config/defaults.rs and are stored as JSON numbers/strings; changeGlobalOption accepts either form. Speed-limit values also accept K (×1024) and M (×1048576) suffixes, e.g. "512K" or "10M".
| Key | Default | Description |
|---|---|---|
dir | OS Downloads dir | Default download directory |
max-concurrent-downloads | 5 | Maximum active non-torrent download workers. Queue reconciliation can preempt lower-priority non-torrent workers back to waiting; BitTorrent tasks are managed separately |
max-overall-download-limit | 0 | One overall download budget (bytes/s, 0 = unlimited) shared by HTTP/FTP/SFTP/HLS, BitTorrent, ED2K, and Usenet; running downloads are retuned immediately |
max-overall-upload-limit | 0 | Overall upload cap (bytes/s, 0 = unlimited), enforced for BitTorrent uploads and applied immediately |
bt-upload-rate-limit | 0 | BitTorrent upload cap (bytes/s, accepts 512K-style values, applied immediately). The effective cap is the smaller non-zero of this and max-overall-upload-limit |
split | 16 | Default number of HTTP connections for new downloads and M3U8 segment workers |
seed-ratio | 0 | Stop seeding once the upload/download ratio reaches this value (0 = no ratio goal; checked every second) |
seed-time | 0 | Stop seeding after this many minutes (0 = no time goal). With both seed-ratio and seed-time at 0 and keep-seeding off, torrents complete without seeding |
keep-seeding | false | Seed until stopped manually, ignoring seed-ratio/seed-time |
user-agent | Chrome UA string | Default user agent string |
all-proxy | "" | Default HTTP-profile proxy URL |
p2p-proxy | "" | Default P2P TCP proxy URL. Via the Node API the value is stored but the P2P route is not rebuilt; restart the engine to apply it |
p2p-udp-proxy | "" | Optional P2P UDP proxy; empty reuses p2p-proxy |
pbh-enable | false | Start the PeerBanHelper Aria2Next RPC listener (read at startEngine only) |
pbh-listen-port | 16801 | PeerBanHelper RPC port (read at startEngine only) |
doh-enable | false | Resolve DNS over HTTPS (only active when doh-url is set). Hot-reloaded when any doh-* key changes |
doh-url | "" | DoH endpoint URL; must be https:// |
doh-bootstrap | "" | Comma/space/newline-separated IPs for reaching the endpoint host without system DNS |
doh-fallback | true | Fall back to the system resolver when a DoH query fails (timeout, network error, SERVFAIL); an NXDOMAIN or NODATA answer does not fall back |
nzb-body-timeout | 30 | Maximum idle time in seconds between chunks while fetching an NZB URL body |
rpc-listen-port | 16800 | RPC server port (read at startEngine only) |
rpc-host, rpc-listen-port, rpc-secret, pbh-enable, pbh-listen-port, pbh-rpc-secret, listen-port, dht-listen-port, ed2k-enable-kad, ed2k-kad-port, ed2k-port, and most bt-* keys are read once at startEngine; changing them with changeGlobalOption has no effect until the engine is restarted. The same applies to p2p-proxy / p2p-udp-proxy through the Node API: only the desktop app rebuilds the P2P route when its settings are saved.