> For the complete documentation index, see [llms.txt](https://seanime.gitbook.io/seanime-extensions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://seanime.gitbook.io/seanime-extensions/plugins/ui/downloading/downloader.md).

# Downloader

OS-agnostic API for downloading files asynchronously.

## Permission

{% hint style="warning" %}
`system` permission is required.
{% endhint %}

<pre class="language-json" data-title="my-plugin.json"><code class="lang-json">{
    //...
    "plugin": {
        "permissions": {
<strong>            "scopes": ["system"],
</strong>            "allow": {
                "writePaths": ["$DOWNLOAD/**/*"]
            }
        }
    }
}
</code></pre>

```typescript
//...

// Destination file
// Note that $DOWNLOAD is in the allow list
const filePath = $filepath.Join($osExtra.downloadDir(), "file.zip")
const downloadUrl = "http://example.com/download/file.zip"

// Start a download
const downloadID = ctx.downloader.download(downloadUrl, filePath);

// Track progress
const cancelWatch = ctx.downloader.watch(downloadID, (progress) => {
	console.log("Download progress:", 
		progress.percentage.toFixed(2), "%, ", 
		"Speed:", (progress.speed / 1024).toFixed(2), "KB/s, ",
		"Downloaded:", (progress.totalBytes / 1024).toFixed(2), "KB"
	);
	
	if (progress.status === "completed") {
		// download completed
	} else if (progress.status === "error") {
		// something went wrong
	}
});

// Cancel at any time
ctx.downloader.cancel(downloadID)
```