gallerydl-api

A robust, fully-typed Node.js wrapper for gallery-dl.

This package automatically downloads and manages the correct gallery-dl executable for the host operating system during installation. It eliminates the need for a global Python or gallery-dl dependency.

macOS note: gallery-dl does not publish a standalone macOS executable. On darwin, the installer falls back to a system-wide install found on PATH (pip install gallery-dl or brew install gallery-dl); if none is found, install falls back gracefully with a warning instead of failing.

Installation

npm install gallerydl-api

Usage Guide

The API is fully Promise-based and returns strictly typed objects.

1. Fetching Gallery Metadata

The getGalleryInfo method retrieves directory metadata and every file gallery-dl would fetch for a URL, without downloading anything.

import gallerydl from 'gallerydl-api';

async function fetchMetadata() {
  const info = await gallerydl.getGalleryInfo('https://en.wikipedia.org/wiki/Cat');

  console.log(info.directory.category); // wikipedia
  console.log(info.files.length);       // number of images on the page
  console.log(info.files[0].url);       // direct file URL
}

JSON Output Structure Example:

{
  "directory": {
    "category": "wikipedia",
    "subcategory": "article",
    "page": "Cat",
    "count": 1
  },
  "files": [
    {
      "url": "https://upload.wikimedia.org/wikipedia/commons/4/41/202104_Cat.svg",
      "category": "wikipedia",
      "extension": "svg",
      "filename": "202104_Cat",
      "date": "2021-04-05 07:56:57"
    }
  ],
  "queue": []
}

2. Downloading Galleries with Progress Tracking

The download method downloads a gallery/post to disk while providing one progress event per file. gallery-dl reports file-level (not byte-level) progress, which maps naturally onto how galleries are structured — many files per URL.

import gallerydl from 'gallerydl-api';

async function downloadGallery() {
  await gallerydl.download(
    'https://en.wikipedia.org/wiki/Cat',
    (progress) => {
      // Example: { index: 3, path: './wikipedia/Cat/202104_Cat.svg', status: 'downloaded' }
      console.log(`[${progress.index}] ${progress.status}: ${progress.path}`);
    },
    { args: ['-D', './downloads'] }
  );
}

3. Listing Files Only

The getFiles method is a convenience shortcut for (await getGalleryInfo(url)).files.

import gallerydl from 'gallerydl-api';

const files = await gallerydl.getFiles('https://en.wikipedia.org/wiki/Cat');
const svgs = files.filter(f => f.extension === 'svg');

4. Global Options (cookies, proxy, rate limiting, download archive)

Pass a second argument to the GalleryDl constructor to apply options to every call automatically — no need to repeat them via args each time.

import { GalleryDl } from 'gallerydl-api';

const gallerydl = new GalleryDl(undefined, {
  cookies: './cookies.txt',            // or: cookiesFromBrowser: 'firefox'
  proxy: 'socks5://127.0.0.1:1080',
  rateLimit: '2M',                     // cap bandwidth at 2MB/s
  retries: 10,
  destination: './downloads',
  downloadArchive: './archive.sqlite3', // skip files already downloaded before
  options: ['extractor.pixiv.ugoira=false'],
});

5. Resolving Direct File URLs

Skip the download entirely and get the raw, direct URL(s) for every file in a gallery — useful for proxying or handing off to another downloader.

import gallerydl from 'gallerydl-api';

const urls = await gallerydl.getDirectUrls('https://en.wikipedia.org/wiki/Cat');
console.log(urls[0]); // https://upload.wikimedia.org/...

6. Fast, Field-Only Metadata

getFields skips the full --dump-json extraction and only prints the fields you ask for, for the first file — much faster when scraping a single field across many URLs.

import gallerydl from 'gallerydl-api';

const { extension, filename } = await gallerydl.getFields(
  'https://en.wikipedia.org/wiki/Cat',
  ['extension', 'filename']
);

7. Cancelling In-Flight Requests

Every method that spawns gallery-dl accepts an AbortSignal via options.signal.

import gallerydl from 'gallerydl-api';

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await gallerydl.download(url, onProgress, { args: ['-D', './downloads'], signal: controller.signal });

8. Typed Errors

Failures are classified into specific error subclasses so callers can branch on why gallery-dl failed instead of parsing stderr themselves.

import gallerydl, {
  UnsupportedUrlError,
  NotFoundError,
  AuthenticationError,
  RateLimitedError,
  NetworkError,
} from 'gallerydl-api';

try {
  await gallerydl.getGalleryInfo(url);
} catch (err) {
  if (err instanceof AuthenticationError) {
    // needs cookies/login
  } else if (err instanceof NetworkError) {
    // retry later
  }
  throw err;
}

9. Watching a Gallery for New Files

Polls a gallery/feed URL and calls onNewFile only for files that appeared after the watch started.

import gallerydl from 'gallerydl-api';

const stop = gallerydl.watchGallery(
  'https://example.com/user/gallery',
  (file) => console.log('New file:', file.filename),
  { intervalMs: 5 * 60_000 }
);

// later, to stop polling:
stop();

10. Batch Scraping and Downloading with Bounded Concurrency

Both metadata fetching and downloading support processing many URLs at once without spawning unlimited processes. Each URL resolves independently — one failure doesn't sink the batch.

import gallerydl from 'gallerydl-api';

const infoResults = await gallerydl.batchGetGalleryInfo(urls, { concurrency: 3, delayMs: 250 });
for (const r of infoResults) {
  if (r.status === 'fulfilled') console.log(r.url, r.value.files.length);
  else console.warn(r.url, r.reason.message);
}

await gallerydl.batchDownload(urls, (url, progress) => {
  console.log(url, progress.status, progress.path);
}, { concurrency: 3 });

11. Checking for / Applying Updates

checkForUpdate mirrors gallery-dl -U and only checks; updateBinary actually re-downloads and replaces the managed binary (gallery-dl itself has no in-place self-update flag).

import gallerydl from 'gallerydl-api';

const status = await gallerydl.checkForUpdate();
if (status.updateAvailable) {
  const newVersion = await gallerydl.updateBinary();
  console.log('Updated to', newVersion);
}

API Reference

• new GalleryDl(binaryPath?: string, globalOptions?: GlobalOptions) Creates a wrapper instance. globalOptions (cookies, proxy, rate limiting, etc.) apply to every call made through it.

• gallerydl.checkForUpdate(): Promise<UpdateCheckResult> Checks whether a newer gallery-dl release exists, without installing it.

• gallerydl.updateBinary(): Promise<string> Downloads the latest gallery-dl release and replaces the managed binary. Returns the new version tag.

• gallerydl.version(): Promise<string> Returns the version string of the underlying gallery-dl binary.

• gallerydl.getGalleryInfo(url: string, options?: GalleryDlOptions): Promise<GalleryInfo> Fetches directory metadata, every file, and any queued child URLs for a gallery/post — without downloading.

• gallerydl.getFiles(url: string, options?: GalleryDlOptions): Promise<GalleryFile[]> Fetches just the list of files for a URL.

• gallerydl.getDirectUrls(url: string, options?: GalleryDlOptions): Promise<string[]> Resolves the direct, downloadable URL(s) for a gallery without downloading it.

• gallerydl.getFields(url: string, fields: string[], options?: GalleryDlOptions): Promise<Record<string, string>> Fetches only the requested metadata fields for the first file — faster than a full getGalleryInfo call.

• gallerydl.download(url: string, onProgress?: (progress: DownloadProgress) => void, options?: GalleryDlOptions): Promise<void> Downloads a gallery/post and emits one progress event per file (downloaded or skipped).

• gallerydl.batchGetGalleryInfo(urls: string[], options?: BatchOptions): Promise<BatchResult<GalleryInfo>[]> Fetches metadata for many URLs with bounded concurrency; each URL resolves independently.

• gallerydl.batchDownload(urls: string[], onProgress?: (url: string, progress: DownloadProgress) => void, options?: BatchOptions): Promise<BatchResult<void>[]> Downloads many URLs with bounded concurrency; each URL resolves independently.

• gallerydl.watchGallery(url: string, onNewFile: (file: GalleryFile) => void, options?: WatchGalleryOptions): () => void Polls a gallery/feed and invokes onNewFile for files discovered after the watch started. Returns a stop function.

• gallerydl.exec(args: string[], signal?: AbortSignal): Promise<string> Executes gallery-dl with arbitrary arguments and returns raw stdout.

License

MIT