SANE WebAssembly (sane-wasm)

A project to bring the SANE API to Node.js and the Web using WebAssembly.

It supports USB scanners on browser environments through the WebUSB API and on Node.js using node-usb.

This works by compiling all SANE backends (and required dependencies) to WebAssembly using Emscripten. The other key piece is @RReverser's bridge from libusb to WebUSB (article/article/code/code) for direct USB access.

Right now, it includes all backends that have support for at least one USB device. No external backends are included at the moment.

WebScan

Check webscan.goncalomb.com (source) for a demo of sane-wasm. This is a React application that uses sane-wasm for document/image scanning directly in the browser. It exposes all scanning options for full control.

Usage

The pre-compiled WebAssembly package for sane-wasm is published on NPM:

https://www.npmjs.com/package/sane-wasm

For Web environments (e.g. Webpack, Vite, etc.)

npm install sane-wasm
Copy

Cross-origin isolation (COOP+COEP) is required for multithreading which uses Web Workers and SharedArrayBuffer. This is not optional.

See examples/webpack/ for a working example.

For Node.js

npm install sane-wasm usb
Copy

The usb package (node-usb) is required to provide USB functionality.

See examples/node/ for a working example.

Building

A pre-configured Docker image is used for building and debugging. Most npm run ... commands use Docker.

Build SANE and test page

git clone https://github.com/goncalomb/sane-wasm.git
cd sane-wasm
npm run debug
Copy

Check the test page at: http://localhost:6931/libsane.html.

Other commands

npm run clean  # clean build artifacts and dependencies
npm run build  # run full clean build (SANE + TypeScript)
npm run debug  # run debug build (SANE only) and start the test server
npm run emrun  # start the test server
npm run test   # run the tests
Copy

Non-Docker builds and build.sh

Building without Docker is possible but untested. It requires Emscripten and all the tools to build the dependencies, see Dockerfile.

The ./build.sh script controls the build and has other options for debugging:

usage: build.sh [options]
  --with-docker  run with docker (preferred)
  --clean        clean 'deps' and 'build' directories
  --no-build     don't actually build
  --debug        enable debug flags
  --emrun        run emrun development server
  --shell        run debug shell (depends on --with-docker)
Copy

API

API documentation is available at: https://goncalomb.github.io/sane-wasm/.

Most of the SANE API is exposed as-is, check the SANE Standard.

Some safeguards are in place to avoid API misuse and prevent memory leaks. It's important to understand the SANE API and follow the Code Flow to avoid issues.

Differences with the SANE API

The most important difference with the underlying SANE API is that device handles are not exposed. This means that sane_open() does not return a device handle. A single handle is managed by the internal code. This effectively means that only one device can be accessed at a time. This was a design decision made to simplify the API and prevent other issues.

Other differences include:

• function arguments and return values are adapted for javascript (see docs)
• extra sane-wasm constants: SANE_WASM_COMMIT, SANE_WASM_VERSION, and SANE_WASM_BACKENDS
• values of type SANE_Fixed are automatically converted to/from Number
• extra sane_get_state() function exclusive to sane-wasm
• sane_control_option() is split into 3 separate functions:
  • sane_control_option_get_value()
  • sane_control_option_set_value()
  • sane_control_option_set_auto()
• sane_set_io_mode() is not available on sane-wasm
• sane_get_select_fd() is no available on sane-wasm

Extra TypeScript classes (utilities)

• src/options.ts to manage scanner options
• src/readers.ts for image acquisition and decoding

License

Because of the weird state of SANE's licensing (GPL + linking exception, on some backends), see backends/LICENSE. I'm releasing this project with dual licensing GNU GPLv2 + GNU LGPLv2.1. IANAL, you choose.