instascan

HTML5 QR code scanner using your webcam

2,958

863

2,958

192

View on GitHub View on NPM

Top Related Projects

library

2,432

Multi-format 1D/2D barcode image processing library, usable in JavaScript ecosystem.

html5-qrcode

4,880

A cross platform HTML5 QR code reader. See end to end implementation at: https://scanapp.org

qr-scanner

2,415

Lightweight Javascript QR Code Scanner

jsQR

3,671

A pure javascript QR code reading library. This library takes in raw images and will locate, extract and parse any QR code found within.

Quick Overview

Instascan is a real-time webcam-based HTML5 QR code scanner. It's a JavaScript library that allows web applications to scan QR codes directly from the browser using the device's camera, without the need for any external plugins or native apps.

Pros

Easy to integrate into web applications
Works directly in the browser without additional plugins
Supports multiple cameras and real-time scanning
Lightweight and has no external dependencies

Cons

Limited to QR codes only (doesn't support other barcode formats)
Requires HTTPS for camera access in most modern browsers
May have performance issues on older devices or browsers
Not actively maintained (last commit was in 2017)

Code Examples

Basic QR code scanning:

let scanner = new Instascan.Scanner({ video: document.getElementById('preview') });
scanner.addListener('scan', function (content) {
  console.log(content);
});
Instascan.Camera.getCameras().then(function (cameras) {
  if (cameras.length > 0) {
    scanner.start(cameras[0]);
  } else {
    console.error('No cameras found.');
  }
}).catch(function (e) {
  console.error(e);
});

Scanning with multiple cameras:

let scanner = new Instascan.Scanner({ video: document.getElementById('preview') });
Instascan.Camera.getCameras().then(function (cameras) {
  if (cameras.length > 0) {
    scanner.start(cameras[0]);
    if (cameras.length > 1) {
      document.getElementById('camera-switch').addEventListener('click', function() {
        scanner.start(cameras[1]);
      });
    }
  }
}).catch(function (e) {
  console.error(e);
});

Customizing scanner options:

let opts = {
  continuous: true,
  video: document.getElementById('preview'),
  mirror: false,
  captureImage: true,
  backgroundScan: true,
  refractoryPeriod: 5000,
  scanPeriod: 1
};
let scanner = new Instascan.Scanner(opts);

Getting Started

Include the Instascan library in your HTML:

<script type="text/javascript" src="https://rawgit.com/schmich/instascan-builds/master/instascan.min.js"></script>

Add a video element to your HTML for the camera preview:

<video id="preview"></video>

Initialize the scanner and start scanning:

let scanner = new Instascan.Scanner({ video: document.getElementById('preview') });
scanner.addListener('scan', function (content) {
  alert('Scanned: ' + content);
});
Instascan.Camera.getCameras().then(function (cameras) {
  if (cameras.length > 0) {
    scanner.start(cameras[0]);
  } else {
    console.error('No cameras found.');
  }
}).catch(function (e) {
  console.error(e);
});

Competitor Comparisons

library

2,432

Multi-format 1D/2D barcode image processing library, usable in JavaScript ecosystem.

Pros of zxing-js/library

More comprehensive barcode support, including 1D and 2D formats
Active development and maintenance, with regular updates
Broader functionality beyond just QR code scanning

Cons of zxing-js/library

Larger file size and potentially higher resource usage
Steeper learning curve due to more complex API

Code Comparison

Instascan:

let scanner = new Instascan.Scanner({ video: document.getElementById('preview') });
scanner.addListener('scan', function (content) {
  console.log(content);
});
Instascan.Camera.getCameras().then(function (cameras) {
  if (cameras.length > 0) {
    scanner.start(cameras[0]);
  }
}).catch(function (e) {
  console.error(e);
});

zxing-js/library:

const codeReader = new ZXing.BrowserQRCodeReader();
codeReader.decodeFromVideoDevice(undefined, 'video', (result, err) => {
  if (result) {
    console.log(result.text);
  }
  if (err) {
    console.error(err);
  }
});

Both libraries offer straightforward ways to implement QR code scanning, but zxing-js/library provides more flexibility and options for handling different barcode types. Instascan's API is simpler and more focused on QR codes specifically, which may be preferable for projects with simpler requirements.

html5-qrcode

4,880

A cross platform HTML5 QR code reader. See end to end implementation at: https://scanapp.org

Pros of html5-qrcode

More actively maintained with recent updates
Supports multiple camera selection
Offers both library and jQuery plugin versions

Cons of html5-qrcode

Larger file size and potentially more complex setup
May have slightly higher resource usage due to additional features

Code Comparison

html5-qrcode:

const html5QrCode = new Html5Qrcode("reader");
html5QrCode.start(
  { facingMode: "environment" },
  { fps: 10, qrbox: 250 },
  qrCodeSuccessCallback,
  qrCodeErrorCallback
);

Instascan:

let scanner = new Instascan.Scanner({ video: document.getElementById('preview') });
scanner.addListener('scan', function (content) {
  console.log(content);
});
Instascan.Camera.getCameras().then(function (cameras) {
  if (cameras.length > 0) {
    scanner.start(cameras[0]);
  }
});

Both libraries offer straightforward implementation, but html5-qrcode provides more configuration options out of the box. Instascan's code is slightly more concise but may require additional setup for advanced features.

qr-scanner

2,415

Lightweight Javascript QR Code Scanner

Pros of qr-scanner

More actively maintained with recent updates
Supports both front and back cameras on mobile devices
Offers better performance and faster scanning capabilities

Cons of qr-scanner

Larger file size, which may impact load times
Requires more setup and configuration compared to Instascan

Code Comparison

Instascan:

let scanner = new Instascan.Scanner({ video: document.getElementById('preview') });
scanner.addListener('scan', function (content) {
  console.log(content);
});
Instascan.Camera.getCameras().then(function (cameras) {
  if (cameras.length > 0) {
    scanner.start(cameras[0]);
  }
}).catch(function (e) {
  console.error(e);
});

qr-scanner:

const qrScanner = new QrScanner(videoElem, result => console.log('decoded qr code:', result));
QrScanner.hasCamera().then(hasCamera => {
  if (hasCamera) {
    qrScanner.start();
  }
});

Both libraries provide easy-to-use APIs for QR code scanning, but qr-scanner offers more flexibility and better performance. Instascan has a simpler setup process, making it easier for beginners to implement. However, qr-scanner's active development and additional features make it a more robust choice for long-term projects and advanced use cases.

jsQR

3,671

A pure javascript QR code reading library. This library takes in raw images and will locate, extract and parse any QR code found within.

Pros of jsQR

Pure JavaScript implementation, no external dependencies
Works in both browser and Node.js environments
Supports a wider range of QR code versions and error correction levels

Cons of jsQR

Lacks built-in camera integration for real-time scanning
May require more setup and configuration for live scanning use cases
Performance might be slower for real-time scanning compared to Instascan

Code Comparison

Instascan:

let scanner = new Instascan.Scanner({ video: document.getElementById('preview') });
scanner.addListener('scan', function (content) {
  console.log(content);
});
Instascan.Camera.getCameras().then(function (cameras) {
  if (cameras.length > 0) {
    scanner.start(cameras[0]);
  }
}).catch(function (e) {
  console.error(e);
});

jsQR:

function tick() {
  if (video.readyState === video.HAVE_ENOUGH_DATA) {
    canvasElement.hidden = false;
    canvasContext.drawImage(video, 0, 0, canvasElement.width, canvasElement.height);
    var imageData = canvasContext.getImageData(0, 0, canvasElement.width, canvasElement.height);
    var code = jsQR(imageData.data, imageData.width, imageData.height);
    if (code) {
      console.log("Found QR code", code.data);
    }
  }
  requestAnimationFrame(tick);
}

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Instascan

Real-time webcam-driven HTML5 QR code scanner. Try the live demo.

Installing

Note: Chrome requires HTTPS when using the WebRTC API. Any pages using this library should be served over HTTPS.

NPM

npm install --save instascan

const Instascan = require('instascan');

Bower

Pending. Drop a note if you need Bower support.

Minified

Copy instascan.min.js from the releases page and load with:

<script type="text/javascript" src="instascan.min.js"></script>

Example

<!DOCTYPE html>
<html>
  <head>
    <title>Instascan</title>
    <script type="text/javascript" src="instascan.min.js"></script>
  </head>
  <body>
    <video id="preview"></video>
    <script type="text/javascript">
      let scanner = new Instascan.Scanner({ video: document.getElementById('preview') });
      scanner.addListener('scan', function (content) {
        console.log(content);
      });
      Instascan.Camera.getCameras().then(function (cameras) {
        if (cameras.length > 0) {
          scanner.start(cameras[0]);
        } else {
          console.error('No cameras found.');
        }
      }).catch(function (e) {
        console.error(e);
      });
    </script>
  </body>
</html>

API

let scanner = new Instascan.Scanner(opts)

Create a new scanner with options:

let opts = {
  // Whether to scan continuously for QR codes. If false, use scanner.scan() to manually scan.
  // If true, the scanner emits the "scan" event when a QR code is scanned. Default true.
  continuous: true,
  
  // The HTML element to use for the camera's video preview. Must be a <video> element.
  // When the camera is active, this element will have the "active" CSS class, otherwise,
  // it will have the "inactive" class. By default, an invisible element will be created to
  // host the video.
  video: document.getElementById('preview'),
  
  // Whether to horizontally mirror the video preview. This is helpful when trying to
  // scan a QR code with a user-facing camera. Default true.
  mirror: true,
  
  // Whether to include the scanned image data as part of the scan result. See the "scan" event
  // for image format details. Default false.
  captureImage: false,
  
  // Only applies to continuous mode. Whether to actively scan when the tab is not active.
  // When false, this reduces CPU usage when the tab is not active. Default true.
  backgroundScan: true,
  
  // Only applies to continuous mode. The period, in milliseconds, before the same QR code
  // will be recognized in succession. Default 5000 (5 seconds).
  refractoryPeriod: 5000,
  
  // Only applies to continuous mode. The period, in rendered frames, between scans. A lower scan period
  // increases CPU usage but makes scan response faster. Default 1 (i.e. analyze every frame).
  scanPeriod: 1
};

scanner.start(camera)

Activate camera and start scanning using it as the source. Returns promise.
This must be called in order to use scanner.scan or receive scan events.
camera: Instance of Instascan.Camera from Instascan.Camera.getCameras.
.then(function () { ... }): called when camera is active and scanning has started.
.catch(function (err) { ... })
- Called when an error occurs trying to initialize the camera for scanning.
- err: An Instascan.MediaError in the case of a known getUserMedia failure (see error types).

scanner.stop()

Stop scanning and deactivate the camera. Returns promise.
.then(function () { ... }): called when camera and scanning have stopped.

let result = scanner.scan()

Scan video immediately for a QR code.
QR codes recognized with this method are not emitted via the scan event.
If no QR code is detected, result is null.
result.content: Scanned content decoded from the QR code.
result.image: Undefined if scanner.captureImage is false, otherwise, see the scan event for format.

scanner.addListener('scan', callback)

Emitted when a QR code is scanned using the camera in continuous mode (see scanner.continuous).
callback: function (content, image)
- content: Scanned content decoded from the QR code.
- image: null if scanner.captureImage is false, otherwise, a base64-encoded WebP-compressed data URI of the camera frame used to decode the QR code.

scanner.addListener('active', callback)

Emitted when the scanner becomes active as the result of scanner.start or the tab gaining focus.
If opts.video element was specified, it will have the active CSS class.
callback: function ()

scanner.addListener('inactive', callback)

Emitted when the scanner becomes inactive as the result of scanner.stop or the tab losing focus.
If opts.video element was specified, it will have the inactive CSS class.
callback: function ()

Instascan.Camera.getCameras()

Enumerate available video devices. Returns promise.
.then(function (cameras) { ... })
- Called when cameras are available.
- cameras: Array of Instascan.Camera instances available for use.
.catch(function (err) { ... })
- Called when an error occurs while getting cameras.
- err: An Instascan.MediaError in the case of a known getUserMedia failure (see error types).

camera.id

Unique camera ID provided by the browser.
These IDs are stable and can be persisted across instances of your application (e.g. in localStorage).

camera.name

Camera name, including manufacturer and model
e.g. "Microsoft LifeCam HD-3000".

Compatibility

Instascan works on non-iOS platforms in any browser that supports the WebRTC/getUserMedia API, which currently includes Chome, Firefox, Opera, and Edge. IE and Safari are not supported.

Instascan does not work on iOS since Apple does not yet support WebRTC in WebKit and forces other browser vendors (Chrome, Firefox, Opera) to use their implementation of WebKit. Apple is actively working on WebRTC support in WebKit.

Performance

Many factors affect how quickly and reliably Instascan can detect QR codes.

If you control creation of the QR code, consider the following:

A larger physical code is better. A 2" square code is better than a 1" square code.
Flat, smooth, matte surfaces are better than curved, rough, glossy surfaces.
Include a sufficient quiet zone, the white border surrounding QR code. The quiet zone should be at least four times the width of an individual element in your QR code.
A simpler code is better. You can use this QR code generator to see how your input affects complexity.
For the same length, numeric content is simpler than ASCII content, which is simpler than Unicode content.
Shorter content is simpler. If you're encoding a URL, consider using a shortener such as goo.gl or bit.ly.

When scanning, consider the following:

QR code orientation doesn't matter.
Higher resolution video is better, but is more CPU intensive.
Direct, orthogonal scanning is better than scanning at an angle.
Blurry video greatly reduces scanner performance.
Auto-focus can cause lags in detection as the camera adjusts focus. Consider disabling it or using a fixed-focus camera with the subject positioned at the focal point.
Exposure adjustment on cameras can cause lags in detection. Consider disabling it or having a fixed white backdrop.

Example Setup

Purpose: To scan QR code stickers on paper cards and plastic bags.
Camera: Microsoft LifeCam HD-3000, 720p, fixed focus, around $30 USD.
Small support to ensure camera is focused on subject.
White paper backdrop to mitigate exposure adjustment.

Setup

Credits

License

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of zxing-js/library

Cons of zxing-js/library

Code Comparison

Pros of html5-qrcode

Cons of html5-qrcode

Code Comparison

Pros of qr-scanner

Cons of qr-scanner

Code Comparison

Pros of jsQR

Cons of jsQR

Code Comparison

Convert designs to code with AI

README

Instascan

Installing

NPM

Bower

Minified

Example

API

let scanner = new Instascan.Scanner(opts)

scanner.start(camera)

scanner.stop()

let result = scanner.scan()

scanner.addListener('scan', callback)

scanner.addListener('active', callback)

scanner.addListener('inactive', callback)

Instascan.Camera.getCameras()

camera.id

camera.name

Compatibility

Performance

Example Setup

Credits

License

Top Related Projects

Convert designs to code with AI

NPM DownloadsLast 30 Days