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 (genesys is not included due to issues). No external backends are included at the moment.
Check webscan.goncalomb.com 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 to the user for full control.
The pre-compiled WebAssembly package for sane-wasm is published on NPM:
https://www.npmjs.com/package/sane-wasm?activeTab=code
npm install -D sane-wasm
The main .js will not be bundled with your application. A loader (lib/loader.js) is provided to automatically load the .js/.wasm files from a CDN (jsdelivr.com). You can configure the loader to serve the files from your server if you want.
See examples/webpack/ for a working example.
npm install sane-wasm usb
The usb package (node-usb) is required to provide USB functionality.
See examples/node/ for a working example.
As an alternative, you can add sane-wasm as a submodule to your application and integrate ./build.sh with your build process. This is not recommended as it relies on some magical/dubious code on ./build.sh to make the build work.
You can also just build sane-wasm independently and use the build artifacts...
<script src="build/libsane.js"></script>
<script>
window.LibSANE().then(lib => {
// your code
console.log(lib.sane_init());
});
</script>
const { libsane } = require('./sane-wasm');
libsane().then(lib => {
console.log(lib.sane_init());
});
import { libsane } from './sane-wasm';
const lib = await libsane();
console.log(lib.sane_init());
Building requires emscripten and all the required tools to build the dependencies.
The preferred way is just to use the pre-configured Docker image:
git clone --recurse-submodules https://github.com/goncalomb/sane-wasm.git
cd sane-wasm
./build.sh --with-docker --clean
Start the test server with:
./build.sh --with-docker --no-build --emrun
Check the test page at: http://localhost:6931/libsane.html.
The ./build.sh script 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)
To do a full build use npm run build.
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.
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.
Personally, I believe that this is an acceptable change, especially for WebAssembly where it may be easier to lose track of opened resources and crash the application. The SANE API is also somewhat unforgiving and building more safeguards around it (especially with multiple handles) is not worth the effort. Ultimately I don't see a use that requires more than one device open at a time. -goncalomb
Check API documentation at: goncalomb.github.io/sane-wasm/modules.html.
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.