Task Routing

Risuko can decide where a download goes (and how it is labelled) by matching the inferred output filename against an ordered list of glob rules. This is useful for sorting videos, music, archives, or specific projects into dedicated folders without configuring every task by hand.

How a Task Is RoutedCopy Anchor Link

When a new task is created, the engine picks a filename hint:

• HTTP, FTP/SFTP, M3U8, media, torrent, and magnet tasks use the task's out option if set. Otherwise HTTP/FTP use the last URI path segment, M3U8 uses the playlist basename with a .ts extension, torrent and magnet tasks use the placeholders download.torrent / download.magnet, and media tasks use an empty hint, so these last three don't route by content filename.
• Other protocols ignore out. ED2K uses the filename embedded in the link, Metalink the first file's name, NZB the NZB title (then the first file's name, then usenet), and ADC, Gnutella, G2, and giFT the name parsed from the URI.

A trailing .part on the hint is ignored, so desktop tasks (whose out carries a .part suffix while downloading) match on their final name. Desktop magnet links without a rename get a download-<hash> name and so don't route by content filename. The engine then walks the configured rules:

1. Custom routing rules — the first enabled rule whose case-insensitive glob pattern matches the filename wins. The matching rule's dir becomes the download directory, and its label is exposed as the task's tag.
2. Legacy category fallback — if no rule matches, the engine resolves the filename to a built-in category (music, video, image, document, compressed, program) and looks it up in file-category-dirs.
3. Default — falls back to the global dir setting.

A rule whose dir is empty after trimming is skipped even when its pattern matches — its label is not applied, and evaluation continues with the remaining rules and fallbacks.

Rule ShapeCopy Anchor Link

Stored in the user config under task-routing-rules:

{
  "id": "rule-videos",
  "label": "Videos",
  "pattern": "*.mkv",
  "dir": "/Users/me/Downloads/Videos",
  "enabled": true
}

All fields except enabled are required when adding a rule over RPC.

Managing RulesCopy Anchor Link

Desktop AppCopy Anchor Link

Open Preferences → Basic → Task Routing Rules to add, edit, toggle, and remove rules. Changes are saved with the preferences form but the engine reads the rules only at startup, so they take effect after the engine restarts.

RPCCopy Anchor Link

The same operations are exposed over JSON-RPC for headless setups:

Each method is also reachable under the aria2. prefix. When rpc-secret is set, prepend token:<secret> as the first param.

Rule changes made over RPC update the running engine only — they are not written back to user.json, so they are lost on restart. To persist rules, manage them from the desktop app or set task-routing-rules in the user config directly.

curl -X POST http://localhost:16800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "risuko.resolveRouting",
    "params": ["awesome-show.S01E03.1080p.mkv"]
  }'

Glob CheatsheetCopy Anchor Link

Patterns use the glob crate's syntax, matched case-insensitively against the whole basename:

Brace alternation (*.{mp4,mkv}) is not supported by the glob crate — create one rule per extension instead. Empty or whitespace-only patterns never match, and invalid patterns are skipped silently rather than aborting routing.