@crowsgear/escl-protocol-scanner

한국어

Network scanner library based on eSCL/AirPrint protocol.

Note: This library only supports network-connected scanners (WiFi or LAN). USB scanners may not be supported.

Installation

npm install @crowsgear/escl-protocol-scanner
# or
yarn add @crowsgear/escl-protocol-scanner

No Python installation required! Pre-built binaries for Windows, macOS, and Linux are included. You can also specify a custom Python path. See Application (Custom Configuration) for details.

Quick Start

import { eSCLScanner } from '@crowsgear/escl-protocol-scanner';

// 1. Discover scanners (result: IDiscoveryResponse)
const result = await eSCLScanner.discoverScanners(10000);
if (result.success && result.data.length > 0) {
  console.log('Found scanners:', result.data);
}

// 2. Get scanner capabilities (result.data: IESCLScanner[])
const scanner = result.data[0]; // Select first scanner
const capabilities = await eSCLScanner.getCapabilities(scanner);
console.log('Resolutions:', capabilities?.resolutions);
console.log('Color modes:', capabilities?.colorModes);

// 3. Perform scan
const filePaths = await eSCLScanner.quickScan({
  scanner: scanner,
  dpi: 300,
  mode: 'color',
  source: 'Platen',
  documentFormat: 'image/jpeg',
  savePath: '/path/to/save',
});
console.log('Saved files:', filePaths);

API

eSCLScanner

Default instance, ready to use.

import { eSCLScanner } from '@crowsgear/escl-protocol-scanner';

// Discover scanners
const result = await eSCLScanner.discoverScanners(timeout?: number);

// Get scanner capabilities
const caps = await eSCLScanner.getCapabilities(scanner: IESCLScanner);

// Quick scan
const files = await eSCLScanner.quickScan(params: IQuickScanParams);

// Create scan job
const jobId = await eSCLScanner.createScanJob(scanner, dpi, colorMode, source, documentFormat, width?, height?);

// Get scan job status
const status = await eSCLScanner.getScanJobStatus(scanner, jobId);

// Download image
const buffer = await eSCLScanner.downloadImage(scanner, imageUrl);

Application (Custom Configuration)

Create a new instance for custom configuration.

import { Application } from '@crowsgear/escl-protocol-scanner';

const myScanner = new Application({
  timeout: 15000,
  pythonPath: '/path/to/.venv/bin/python3', // Optional: Python path
  debug: true,
});

const result = await myScanner.discoverScanners();

Note: When pythonPath is provided, it takes priority over pre-built binaries.

quickScan Parameters

interface IQuickScanParams {
  scanner: IESCLScanner;         // Scanner device
  dpi: number;                    // Resolution (e.g., 200, 300, 600)
  mode: 'bw' | 'gray' | 'color';  // Color mode
  source: 'Platen' | 'Feeder';    // Scan source (flatbed/ADF)
  documentFormat: string;         // MIME type (e.g., 'image/jpeg')
  savePath?: string;              // Save path (default: cwd)
  width?: number;                 // Scan width in mm (default: 210)
  height?: number;                // Scan height in mm (default: 297)
  timeout?: number;               // Timeout in ms
}

Types

interface IESCLScanner {
  name: string;
  host: string;
  port: number;
  model?: string;
  manufacturer?: string;
}

interface IESCLCapabilities {
  resolutions: number[];
  colorModes: ('BlackAndWhite1' | 'Grayscale8' | 'RGB24')[];
  sources: ('Platen' | 'Adf' | 'Feeder')[];
  documentFormats: string[];
  maxWidth?: number;
  maxHeight?: number;
}

interface IDiscoveryResponse {
  success: boolean;
  data: IESCLScanner[];
  error?: string;
}

Paper Size Reference

| Paper | Width (mm) | Height (mm) | |--------|------------|-------------| | A4 | 210 | 297 | | A3 | 297 | 420 | | Letter | 216 | 279 | | Legal | 216 | 356 |

Supported Scanners

Works with any network scanner or MFP that supports the eSCL (AirPrint Scan) protocol. Most modern network MFPs from Brother, Canon, Epson, HP, Ricoh, Xerox, and others support eSCL.

eSCL is a protocol designed by Apple and maintained as an industry standard by the Mopria Alliance. For a list of compatible devices, see the Apple AirPrint page. Not all devices have been fully tested. If you encounter issues with a specific device, please open an issue.

Development

For development without pre-built binaries, Python 3 with zeroconf and pillow is required.

python3 -m venv .venv
source .venv/bin/activate
pip install zeroconf pillow

import { Application } from '@crowsgear/escl-protocol-scanner';

const scanner = new Application({
  pythonPath: '/path/to/.venv/bin/python3',
});

const result = await scanner.discoverScanners();

License

MIT