Skip to content
Developer Platform

Getting Started with the Web Downloader

The MASV Web Downloader SDK lets you embed high-speed file downloads directly in your web application. It handles chunking, retries, and progress tracking so you can focus on your integration workflow rather than the complexities of the MASV API.

This guide walks you through installation, downloader initialization, directory handle selection, and download execution.

Prerequisites

Section titled “Prerequisites”

Before you begin, make sure you have:

Installation

Section titled “Installation”

Install the MASV Web Downloader package:

Terminal window
npm install @masvio/downloader

Or with Yarn:

Terminal window
yarn add @masvio/downloader

Initialize the Downloader

Section titled “Initialize the Downloader”

Import the Downloader class and create an instance with a MASV download link and the link password (if required by the link owner):

import { Downloader } from "@masvio/downloader";


const downloader = new Downloader(masvLink, linkPassword);


await downloader.initialize();

Each Downloader instance is tied to a single download link. Create a new instance for each download attempt (pause and resume use the same instance).

The initialize() method bootstraps the downloader and loads the file list from the link. See the API Reference for full constructor details.

Listen for events

Section titled “Listen for events”

Track download progress and completion by subscribing to events. Attach callbacks before calling start():

downloader.on(Downloader.States.Downloading, () => {
  console.log("State changed: Downloading");
});


downloader.on(Downloader.States.Paused, () => {
  console.log("State changed: Paused");
});


downloader.on(Downloader.DownloaderEvents.Progress, ({ data }) => {
  console.log("Download progress:", data.performanceStats);
});


downloader.on(Downloader.DownloaderEvents.Finished, () => {
  console.log("Download complete!");
});


downloader.on(Downloader.DownloaderEvents.Error, ({ data }) => {
  console.error("Download failed:", data.errorMsg);
});

See the API Reference — Events for the full list of events and their payloads.

Select a download directory

Section titled “Select a download directory”

The Web Downloader writes files to a local directory using the browser’s File System Access API. Call showDirectoryPicker() to let the user choose a destination folder:

<button id="download">Download</button>
let directoryHandle;
const downloadButton = document.getElementById("download");


downloadButton.addEventListener("click", async () => {
  directoryHandle = await showDirectoryPicker({
    id: "masv-web-downloader",
    mode: "readwrite",
    startIn: "downloads",
  });
});

Start the download

Section titled “Start the download”

Pass the directory handle to the start() method to begin downloading all files from the link:

await downloader.start(directoryHandle);

To download only specific files, pass a file list as the second argument:

const files = await downloader.loadFiles();
const selectedFiles = files.filter((f) => f.name.endsWith(".mov"));


await downloader.start(directoryHandle, selectedFiles);

Complete example

Section titled “Complete example”

Here’s a minimal end-to-end integration:

import { Downloader } from "@masvio/downloader";


// 1. Initialize Downloader
const downloader = new Downloader(masvLink, linkPassword);
await downloader.initialize();


// 2. Listen for events
downloader.on(Downloader.DownloaderEvents.Progress, ({ data }) => {
  console.log("Progress:", data.performanceStats);
});


downloader.on(Downloader.DownloaderEvents.Finished, () => {
  console.log("Download finished");
});


downloader.on(Downloader.DownloaderEvents.Error, ({ data }) => {
  console.error("Error:", data.errorMsg);
});


// 3. Select directory and start download
const downloadButton = document.getElementById("download");
downloadButton.addEventListener("click", async () => {
  const directoryHandle = await showDirectoryPicker({
    id: "masv-web-downloader",
    mode: "readwrite",
    startIn: "downloads",
  });


  await downloader.start(directoryHandle);
});

Next steps

Section titled “Next steps”