# QRGen documentation (full text)

Source: https://rockyljewell.github.io/QR-GEN/docs/ · Repository: https://github.com/Rockyljewell/QR-GEN · License: Apache-2.0 (created by Rockyljewell; keep NOTICE when redistributing)


---

# Introduction

URL: https://rockyljewell.github.io/QR-GEN/docs/introduction/
Group: Get started

> QRGen is an open-source (Apache-2.0) SDK for scanning barcodes, QR codes and ID documents, and for generating and parsing barcodes, on the web, mobile, desktop and server.

QRGen is an open-source barcode, QR code and ID scanning SDK. It gives you a ready-made camera scanner you can drop into a page, a lower-level scanning API for custom interfaces, parsers that turn scanned text into structured data, and a barcode generator. Decoding runs on the device in WebAssembly (or the platform's native engine on iOS and Android), so camera frames never leave the user's device.

The whole project is free and open source under the Apache License 2.0, including for commercial products. It was created by [Rockyljewell](https://github.com/Rockyljewell). There are no license keys, usage limits or telemetry.

## What's in the box

| Piece | What it does | Start here |
| --- | --- | --- |
| Pre-built scanner UI | `<qrgen-scanner>` web component with viewfinder, highlights, torch, camera switch, zoom and success feedback. Wrappers for React and Vue. | [Web Components](../web-components/) |
| `BarcodeScanner` API | Camera scanning without UI: bring your own `<video>`, get `scan`, `frame` and `track` events. | [JavaScript](../javascript/) |
| Batch scanning | Track many codes with stable ids, choose from an accessible results list, count decoded items in view. | [Batch scanning](../batch-scanning/) |
| ID scanning | Read the PDF417 on North American driver licenses and ID cards and parse it into name, birth date, expiry and address. | [ID scanning](../id-scanning/) |
| Image scanning | Decode codes in files, photos, canvases, clipboard images and URLs, several per image. | [Image scanning](../image-scanning/) |
| Generator | Create any of 26 symbologies as SVG, PNG or a data URL, including GS1 data. | [Barcode generation](../barcode-generation/) |
| Parsers | Understand what was scanned: URLs, Wi-Fi, contacts, events, payments, product codes, GS1 element strings, GS1 Digital Link and AAMVA. | [Parsers](../parsers/) |
| CLI and REST API | `qrgen scan`, `qrgen generate` and `qrgen serve`, plus a Docker image, so any language can scan and generate over HTTP. | [CLI](../cli/), [REST API & Docker](../rest-api/) |
| Native SDKs | Swift, Kotlin, React Native, Flutter, .NET and Python packages that share the same symbology ids, result shape and parsers. | [Platforms](#platforms) |
| Agent Skills | Instructions that teach coding agents (Claude Code and others) to integrate QRGen correctly. | [Agent Skills](../../agent-skills/) |

You can try the scanner in your browser on the [demo page](../../demo/).

## Platforms

Every package follows the same cross-platform contract: the same lowercase [symbology ids](../symbologies/), the same [result object](../concepts/#the-barcode-result), the same option names and the same error codes. Code and knowledge carry over between platforms.

| Platform | Package | How it scans | Guide |
| --- | --- | --- | --- |
| Web (vanilla JS / TypeScript) | `qrgen-sdk` (npm) | zxing-cpp in WebAssembly, in a Web Worker | [JavaScript](../javascript/), [Web Components](../web-components/), [Script tag & CDN](../cdn/) |
| React, Next.js | `qrgen-sdk/react` | Same web engine | [React](../react/), [Next.js](../nextjs/) |
| Vue, Nuxt | `qrgen-sdk/vue` | Same web engine | [Vue & Nuxt](../vue/) |
| Angular | `qrgen-sdk/elements` | Same web engine | [Angular](../angular/) |
| Svelte, SvelteKit | `qrgen-sdk/elements` | Same web engine | [Svelte & SvelteKit](../svelte/) |
| iOS, macOS | `QRGenKit` (Swift Package) | Native | [iOS](../ios/) |
| Android | `dev.qrgen:qrgen-android` | Native | [Android](../android/) |
| React Native | `qrgen-react-native` | Native camera, or the embed page in a WebView | [React Native](../react-native/) |
| Flutter | `qrgen_flutter` | See the guide | [Flutter](../flutter/) |
| .NET / MAUI | `QRGen.Net` | See the guide | [.NET](../dotnet/) |
| Capacitor, Ionic | `qrgen-sdk` | Web engine in the app's WebView | [Capacitor & Ionic](../capacitor/) |
| Cordova | `qrgen-sdk` | Web engine in the app's WebView | [Cordova](../cordova/) |
| Electron | `qrgen-sdk` | Web engine in the renderer, `qrgen-sdk/node` in the main process | [Electron](../electron/) |
| Tauri | `qrgen-sdk` | Web engine in the system WebView | [Tauri](../tauri/) |
| Titanium | Hosted embed page | WebView guide | [Titanium](../titanium/) |
| Node.js, Bun | `qrgen-sdk/node` | WebAssembly, loaded from `node_modules` | [Node.js](../nodejs/) |
| Command line | `qrgen` (npm bin) | Node.js | [CLI](../cli/) |
| Any language over HTTP | `qrgen serve`, Docker image | Node.js | [REST API & Docker](../rest-api/) |
| Python | `qrgen-sdk` (PyPI) | zxing-cpp, OpenCV for webcams | [Python](../python/) |
| Linux, Raspberry Pi | Any of the above | CLI, REST, Python or a kiosk browser | [Linux & Raspberry Pi](../linux/) |
| Any other WebView | Hosted embed page | Web engine, events over a message bridge | [Embed bridge](../embed-bridge/) |

## How it works

On the web, QRGen wraps [zxing-cpp](https://github.com/zxing-cpp/zxing-cpp), a mature C++ barcode library, compiled to WebAssembly by [zxing-wasm](https://github.com/Sec-ant/zxing-wasm). The `BarcodeScanner` opens the camera with `getUserMedia`, crops each frame to the visible scan area, and decodes it in a Web Worker so the page stays responsive. Results go through a duplicate filter, trigger optional beep and vibration feedback, and arrive as plain JSON objects.

The decoder (`zxing_reader.wasm`, about 400 KB gzipped) is downloaded once and cached. By default it loads from jsDelivr; you can [self-host it](../installation/#self-host-the-webassembly-engine) for offline apps or strict networks. The generator uses a separate `zxing_writer.wasm` that is only fetched when you generate a barcode.

## Next steps

- [Quick start](../quick-start/): a working scanner in under 15 lines.
- [Installation](../installation/): package managers, CDN, self-hosting and Content Security Policy.
- [Core concepts](../concepts/): symbologies, scan modes, the result object and duplicate filtering.


---

# Quick start

URL: https://rockyljewell.github.io/QR-GEN/docs/quick-start/
Group: Get started

> Add a working barcode and QR code scanner to a web page in under 15 lines, with a script tag, npm and a web component, or React.

Pick the path that matches your project. Each one gives you the full scanner UI: camera preview, viewfinder, highlights, torch and camera controls, and a success toast.

> **Note:** Browsers only allow camera access in a secure context: `https://` or `http://localhost`. Opening the file directly or using a LAN address like `http://192.168.1.20` will fail with an `insecure-context` error. For local testing, run a static server such as `npx serve .` and open `http://localhost:3000`.

## Script tag

No build step. The ESM bundle includes everything and registers the elements when it loads.

```html
<!doctype html>
<html lang="en">
  <body>
    <qrgen-scanner symbologies="qr,ean13,code128" mode="single" style="height: 420px"></qrgen-scanner>
    <p id="result">Point the camera at a code</p>
    <script type="module">
      import "https://rockyljewell.github.io/QR-GEN/sdk/qrgen.js";
      document.querySelector("qrgen-scanner").addEventListener("scan", (event) => {
        document.querySelector("#result").textContent = event.detail.barcode.data;
      });
    </script>
  </body>
</html>
```

In `single` mode the scanner pauses after the first code and shows a **Scan again** button. Remove `mode="single"` to keep scanning continuously. See [Script tag & CDN](../cdn/) for the classic-script build and version notes.

## npm and a web component

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

```js
import "qrgen-sdk/elements";

const scanner = document.createElement("qrgen-scanner");
scanner.setAttribute("symbologies", "qr,ean13,code128");
scanner.style.height = "420px";
scanner.addEventListener("scan", (event) => {
  const { barcode } = event.detail;
  console.log(barcode.symbology, barcode.data);
});
document.body.append(scanner);
```

This works with any bundler (Vite, webpack, Parcel, esbuild). The element is framework-agnostic, so the same code runs in [Angular](../angular/), [Svelte](../svelte/) and plain HTML. Every attribute, property and event is listed in [Web Components](../web-components/).

## React

```tsx
import { useState } from "react";
import { QRGenScanner } from "qrgen-sdk/react";

export function Scanner() {
  const [code, setCode] = useState("");
  return (
    <div>
      <QRGenScanner symbologies={["qr", "ean13"]} mode="single" style={{ height: 420 }} onScan={(_, barcode) => setCode(barcode.data)} />
      <p>{code || "Point the camera at a code"}</p>
    </div>
  );
}
```

Using Next.js? Put this component in a file that starts with `"use client"`. See [Next.js](../nextjs/). For Vue, see [Vue & Nuxt](../vue/).

## No camera? Scan an image

`scanImage()` decodes codes in a file, blob, image, canvas or URL, and returns every code it finds:

```js
import { scanImage } from "qrgen-sdk";

document.querySelector("input[type=file]").addEventListener("change", async (event) => {
  const barcodes = await scanImage(event.target.files[0]);
  console.log(barcodes.map((b) => `${b.symbologyName}: ${b.data}`));
});
```

More in [Image scanning](../image-scanning/).

## Next steps

- Scan faster by [limiting symbologies](../barcode-scanning/#choose-symbologies) to the ones you need.
- Turn scanned text into data with [`parseContent()`](../parsers/): URLs, Wi-Fi credentials, contacts, product codes and GS1.
- Scan many codes at once with [batch scanning](../batch-scanning/).
- Match your brand with [UI customization](../ui-customization/).
- Using a coding agent? Install the [Agent Skills](../../agent-skills/) so it knows the API.


---

# Installation

URL: https://rockyljewell.github.io/QR-GEN/docs/installation/
Group: Get started

> Install QRGen from npm, a tarball or the CDN, self-host the WebAssembly engine, configure Content Security Policy and bundlers, and check browser support.

QRGen ships as one npm package, `qrgen-sdk`, with separate entry points for the core API, the web components, framework wrappers, parsers, Node.js helpers, the REST server and the embed bridge. It has a single runtime dependency, `zxing-wasm`, pinned to an exact version.

## Package managers

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

The package works the same with other package managers:

```bash
pnpm add qrgen-sdk
yarn add qrgen-sdk
bun add qrgen-sdk
```

The tarball URL works with all of them (`pnpm add https://...`, `yarn add https://...`, `bun add https://...`). Pin a copy of the tarball in your repository if you need reproducible builds before the npm release.

React (17 or later) and Vue (3.3 or later) are optional peer dependencies. You only need them if you import `qrgen-sdk/react` or `qrgen-sdk/vue`. Node.js 18.17 or later is required for the Node entry points and the CLI.

## Entry points

| Import | Contents | Environment |
| --- | --- | --- |
| `qrgen-sdk` | `BarcodeScanner`, `scanImage`, `generate`, parsers, symbology helpers, `configure`, errors | Browser (and Node, see below) |
| `qrgen-sdk/elements` | Registers `<qrgen-scanner>` and `<qrgen-barcode>` | Browser |
| `qrgen-sdk/react` | `QRGenScanner`, `QRGenBarcode` components | React 17+ |
| `qrgen-sdk/vue` | `QRGenScanner`, `QRGenBarcode`, `QRGenPlugin` | Vue 3.3+ |
| `qrgen-sdk/parsers` | `parseContent`, `parseGS1`, `parseAAMVA` and helpers only | Anywhere |
| `qrgen-sdk/node` | Everything in `qrgen-sdk`, plus `scanFile`, `scan`, `generatePNG`, `generateToFile`, with the engine loaded from `node_modules` | Node.js, Bun |
| `qrgen-sdk/server` | `createServer`, `createHandler` (REST API) | Node.js |
| `qrgen-sdk/bridge` | `connectBridge`, `parseBridgeMessage` and helpers for WebView and iframe hosts | Browser |
| `qrgen-sdk/browser` | The standalone ESM bundle (everything, elements registered) | Browser |
| `qrgen-sdk/wasm/reader.wasm` | `zxing_reader.wasm`, for self-hosting | Static file |
| `qrgen-sdk/wasm/writer.wasm` | `zxing_writer.wasm`, for self-hosting | Static file |

The package also installs the `qrgen` [CLI](../cli/). The module entry points ship ESM, CommonJS and TypeScript declarations; `qrgen-sdk/browser` is a single ES module.

> **Tip:** In Node.js, import from `qrgen-sdk/node`, not `qrgen-sdk`. The Node entry reads the engine from `node_modules`, so it never touches the network. See [Node.js](../nodejs/).

## CDN

Two prebuilt bundles are hosted with this site. Both contain the whole SDK (scanner, elements, generator, parsers and bridge) and register the custom elements when they load.

| File | Format | Use |
| --- | --- | --- |
| `https://rockyljewell.github.io/QR-GEN/sdk/qrgen.js` | ES module | `<script type="module">` or `import` from a URL |
| `https://rockyljewell.github.io/QR-GEN/sdk/qrgen.iife.js` | Classic script | `<script src>`; exposes the global `QRGen` |

```html
<script type="module">
  import { scanImage, generate } from "https://rockyljewell.github.io/QR-GEN/sdk/qrgen.js";
</script>

<script src="https://rockyljewell.github.io/QR-GEN/sdk/qrgen.iife.js"></script>
<script>
  QRGen.generate("https://example.com").then(({ svg }) => document.body.insertAdjacentHTML("beforeend", svg));
</script>
```

The bundle is about 60 KB gzipped. See [Script tag & CDN](../cdn/) for details.

## Self-host the WebAssembly engine

The decoder (`zxing_reader.wasm`, about 400 KB gzipped) and the generator (`zxing_writer.wasm`, about 340 KB gzipped) are fetched at runtime the first time you scan or generate. By default they load from jsDelivr, pinned to the exact engine version the SDK was built with (`ENGINE_VERSION`):

```text
https://cdn.jsdelivr.net/npm/zxing-wasm@<ENGINE_VERSION>/dist/reader/zxing_reader.wasm
https://cdn.jsdelivr.net/npm/zxing-wasm@<ENGINE_VERSION>/dist/writer/zxing_writer.wasm
```

Self-host them when your app must work offline, your network blocks third-party CDNs, or you don't want a third-party request.

1. Copy the two files from the package to a folder your web server serves. They live in `node_modules/qrgen-sdk/dist/wasm/`:

   ```bash
   mkdir -p public/qrgen
   cp node_modules/qrgen-sdk/dist/wasm/*.wasm public/qrgen/
   ```

2. Point the SDK at that folder before the first scan:

   ```js
   import { configure } from "qrgen-sdk";

   configure({ wasmBaseUrl: "/qrgen/" });
   ```

The folder must contain `zxing_reader.wasm` and `zxing_writer.wasm` under those names. Relative URLs resolve against the page's base URL.

If you load the SDK from a script tag and can't call `configure()` first, set a global before the script runs:

```html
<script>
  globalThis.QRGEN_WASM_BASE = "/qrgen/";
</script>
<script src="https://rockyljewell.github.io/QR-GEN/sdk/qrgen.iife.js"></script>
```

A copy of both files is also hosted at `https://rockyljewell.github.io/QR-GEN/sdk/wasm/zxing_reader.wasm` and `https://rockyljewell.github.io/QR-GEN/sdk/wasm/zxing_writer.wasm`, matching the CDN bundle.

`configure()` accepts these options:

| Option | Type | Meaning |
| --- | --- | --- |
| `wasmBaseUrl` | `string` | Folder containing both wasm files. |
| `readerWasmUrl` | `string` | Exact URL of `zxing_reader.wasm`. Takes precedence over `wasmBaseUrl`. |
| `writerWasmUrl` | `string` | Exact URL of `zxing_writer.wasm`. Takes precedence over `wasmBaseUrl`. |
| `readerWasmBinary` | `ArrayBuffer \| Uint8Array` | The reader wasm bytes, for environments without `fetch` access to a URL. |
| `writerWasmBinary` | `ArrayBuffer \| Uint8Array` | The writer wasm bytes. |
| `worker` | `boolean` | Decode camera frames in a Web Worker. Default `true`. |

> **Warning:** The wasm files must match the SDK version. When you self-host, copy them again every time you upgrade `qrgen-sdk`, for example in a `postinstall` script: `"postinstall": "mkdir -p public/qrgen && cp node_modules/qrgen-sdk/dist/wasm/*.wasm public/qrgen/"`.

> **Tip:** Serve `.wasm` files with `Content-Type: application/wasm` so the browser can compile them while downloading. With another type the engine still loads, but logs a "wasm streaming compile failed" message and falls back to a slower path.

## Content Security Policy

If your site sends a `Content-Security-Policy` header, allow the following:

| Directive | Value | Why |
| --- | --- | --- |
| `script-src` | `'wasm-unsafe-eval'` | Compiling WebAssembly. Add `https://rockyljewell.github.io` if you load the CDN bundle. |
| `worker-src` | `blob:` | The decoder worker is started from a Blob URL. |
| `connect-src` | `https://cdn.jsdelivr.net` (default), or `'self'` when self-hosting | Fetching the wasm files. Also any image URLs you pass to `scanImage()`. |
| `style-src` | nothing extra | The elements style their shadow DOM with constructable stylesheets, which CSP doesn't restrict. Only browsers without them (Safari before 16.4) fall back to an inline `<style>` and need `'unsafe-inline'`. |
| `img-src` | `data: blob:` | Only if you show `generateDataURL()` output in an `<img>`, or generate colored PNGs in the browser. |

A complete policy for a self-hosted setup:

```text
Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; worker-src 'self' blob:; connect-src 'self'; style-src 'self'; img-src 'self' data: blob:
```

Without `worker-src blob:` scanning still works: the SDK logs `[qrgen] decoding on the main thread: ...` and decodes on the main thread instead, which is slower on low-end phones.

Camera access is also controlled by the `Permissions-Policy` header. If you send one, it must allow the camera for your origin, for example `Permissions-Policy: camera=(self)`. A scanner inside an `<iframe>` also needs `allow="camera"` on the iframe element. Camera streams are attached with `srcObject`, so `media-src` does not affect them.

## Bundlers

The decoder worker is inlined in the JavaScript as a string and started from a Blob URL, and the wasm files are fetched at runtime. There is no worker file or wasm import for your bundler to handle, so QRGen works without plugins in Vite, webpack, Rollup, esbuild, Parcel, Rspack and Turbopack. The notes below only matter when you self-host the wasm.

### Vite

Import the wasm files as asset URLs. Vite copies them into the build with a content hash:

```ts
import { configure } from "qrgen-sdk";
import readerWasmUrl from "qrgen-sdk/wasm/reader.wasm?url";
import writerWasmUrl from "qrgen-sdk/wasm/writer.wasm?url";

configure({ readerWasmUrl, writerWasmUrl });
```

### webpack

Copy the files with [copy-webpack-plugin](https://github.com/webpack-contrib/copy-webpack-plugin) (a separate package), then set `wasmBaseUrl`:

```js
// webpack.config.js
const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  // ...
  plugins: [new CopyPlugin({ patterns: [{ from: "node_modules/qrgen-sdk/dist/wasm", to: "qrgen" }] })],
};
```

```js
import { configure } from "qrgen-sdk";

configure({ wasmBaseUrl: "/qrgen/" });
```

### Next.js

Copy the files into `public/qrgen/` (the `postinstall` script above works) and call `configure({ wasmBaseUrl: "/qrgen/" })` in a client component. Scanner components must render on the client. See [Next.js](../nextjs/).

## Browser support

Camera scanning needs `getUserMedia` and WebAssembly. Image scanning and generation only need WebAssembly.

| Browser | Supported |
| --- | --- |
| Chrome, Edge (desktop and Android) | Current versions |
| Firefox (desktop and Android) | Current versions |
| Samsung Internet | Current versions |
| Safari on macOS | Current versions |
| Safari on iOS and iPadOS | 14.5 and later |
| iOS in-app WebViews (`WKWebView`) | iOS 14.5 and later, with camera permission in the host app |
| Android WebView | With a `WebChromeClient` that grants camera requests. See [Embed bridge](../embed-bridge/). |

The SDK uses `requestVideoFrameCallback`, `OffscreenCanvas` and Web Workers when they are available and falls back when they are not. Vibration feedback uses the Vibration API, which iOS Safari does not support. On iOS, the beep only plays after the user has tapped something on the page (see [Core concepts](../concepts/#feedback)).

All camera features require a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts): HTTPS, `http://localhost` or `http://127.0.0.1`.


---

# Agent Skills

URL: https://rockyljewell.github.io/QR-GEN/docs/agent-skills/
Group: Get started

> Install QRGen's Agent Skills so Claude Code, Cursor, Codex, Copilot and other coding agents can integrate barcode scanning correctly on the first try.

QRGen ships a set of [Agent Skills](https://github.com/Rockyljewell/QR-GEN/tree/main/skills). Skills are Markdown instructions that coding agents load when a task matches. They describe the real APIs, platform setup (permissions, HTTPS, SSR), common failures, and how to verify the result.

## Install

With the open [skills CLI](https://github.com/vercel-labs/skills), which works with Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI and other agents:

```bash
npx skills add https://github.com/Rockyljewell/QR-GEN
```

Useful flags: `--list` shows the skills without installing, `--skill qrgen-sdk` installs one skill, `-g` installs for your user instead of the project, and `-a claude-code` targets a specific agent.

As a Claude Code plugin:

```bash
/plugin marketplace add Rockyljewell/QR-GEN
/plugin install qrgen-sdk@qrgen-plugins
```

Update later with `npx skills update` or `/plugin marketplace update qrgen-plugins`.

## The skills

| Skill | Use it for |
| --- | --- |
| `qrgen-sdk` | Adding a scanner to any stack: web frameworks, Node, Python, iOS, Android, React Native, Flutter, .NET, hybrid apps, REST. Includes one reference file per platform. |
| `qrgen-barcode-generation` | Creating QR, Data Matrix, GS1-128, EAN and other barcodes as SVG/PNG, with printing guidance. |
| `qrgen-data-parsing` | Turning scan results into data: URLs, Wi-Fi, contacts, payments, GS1 AIs, driver licenses. |
| `qrgen-batch-scanning` | Counting or choosing many codes with tracking and an accessible results list. |
| `qrgen-id-scanning` | Driver license parsing and age verification, with privacy guidance. |
| `qrgen-migration` | Replacing html5-qrcode, ZXing, QuaggaJS, BarcodeDetector or a commercial SDK. |
| `qrgen-testing` | Round-trip unit tests and camera-free Playwright tests with a fake webcam. |

## Without skills: the agent prompt

Paste the prompt from the [Agent Skills page](../../agent-skills/#prompt) into any assistant, or point it at the plain-text version:

```text
https://rockyljewell.github.io/QR-GEN/agent-prompt.txt
```

## Docs for LLMs

- [`/llms.txt`](../../llms.txt): an index of every page with one-line descriptions.
- [`/llms-full.txt`](../../llms-full.txt): all documentation in one plain-text file.
- Every docs page has a **Copy as Markdown** button.

## Writing good requests

Agents do best when you name the outcome and the constraints:

- "Add a QR scanner to the check-in screen. Single scan, then show the ticket details."
- "Let warehouse staff count items on a shelf. Batch mode, retail barcodes, export CSV."
- "Verify customers are 21+ by scanning the back of their license. Do not store personal data."
- "Replace html5-qrcode with QRGen and keep the existing result handler."

> **Tip:** Ask the agent to finish with the verification steps from the skill: build, type-check, a generate→scan round-trip test, and how to try it on a phone over HTTPS.


---

# Core concepts

URL: https://rockyljewell.github.io/QR-GEN/docs/concepts/
Group: Get started

> Symbologies and groups, scan modes, the Barcode result object, duplicate filtering, scan areas, feedback, worker decoding and privacy in QRGen.

These concepts apply to every QRGen package. The names are shared across the JavaScript, native and Python SDKs, so what you learn here carries over.

## Symbologies

A symbology is a barcode type: QR Code, EAN-13, Code 128, PDF417 and so on. QRGen identifies each one with a short lowercase id such as `qr`, `ean13`, `code128` or `data-matrix`. The full list, with aliases and platform support, is on the [Symbologies](../symbologies/) page.

Anywhere you pass symbologies, you can use ids, aliases, display names and groups. Matching ignores case and punctuation, so `QRCode`, `qr-code`, `QR` and `qr` all mean `qr`, and `EAN-13` means `ean13`. Unknown names are ignored.

```js
new BarcodeScanner({ symbologies: ["qr", "EAN-13", "code128"] });
new BarcodeScanner({ symbologies: "qr, ean13 code128" }); // strings are split on commas and spaces
new BarcodeScanner({ symbologies: ["retail", "qr"] }); // groups expand
```

### Groups

| Group | Expands to |
| --- | --- |
| `all` | Every symbology (the default) |
| `linear` or `1d` | `ean13` `ean8` `upca` `upce` `isbn` `code128` `code39` `code93` `codabar` `itf` `itf14` `databar` `databar-expanded` `databar-limited` `code32` `pzn` `telepen` `dx-film-edge` |
| `matrix` or `2d` | `qr` `micro-qr` `rmqr` `data-matrix` `aztec` `pdf417` `micro-pdf417` `maxicode` |
| `retail` | `ean13` `ean8` `upca` `upce` `isbn` `databar` `databar-expanded` `databar-limited` |
| `industrial` | `code128` `code39` `code93` `codabar` `itf` `itf14` `data-matrix` |
| `gs1` | `code128` `data-matrix` `qr` `databar` `databar-expanded` `databar-limited` |

When you don't pass symbologies, QRGen looks for all of them. That is convenient, but every extra symbology costs decode time and raises the chance of a false read. In production, enable only what you expect to scan. [Barcode scanning](../barcode-scanning/#choose-symbologies) has recommended sets.

## Scan modes

| Mode | Behavior | Use it for |
| --- | --- | --- |
| `continuous` (default) | Keeps scanning. Each new code fires a `scan` event, repeats are suppressed by the duplicate filter. | Checkout lanes, ticket gates, scanning a stack of parcels |
| `single` | Pauses after the first successful scan. Call `resume()` (or tap **Scan again** in the element) to scan the next one. | Login QR codes, "scan to fill this field" flows |
| `batch` | Tracks every code in view at once, with a stable id per physical code. Fires `track` events every frame and a `scan` event for each newly seen code. | Shelf audits, counting inventory, picking one code among many |

In `batch` mode, the defaults change: `maxResults` becomes 20 (codes decoded per frame) instead of 1, and `duplicateFilter` becomes `-1` (each code value reported once per session). See [Batch scanning](../batch-scanning/).

## The Barcode result

Every platform returns the same object for a decoded code:

```json
{
  "data": "https://example.com",
  "symbology": "qr",
  "symbologyName": "QR Code",
  "rawBytes": "aHR0cHM6Ly9leGFtcGxlLmNvbQ==",
  "contentType": "text",
  "isGS1": false,
  "location": {
    "topLeft": { "x": 10, "y": 10 },
    "topRight": { "x": 90, "y": 10 },
    "bottomRight": { "x": 90, "y": 90 },
    "bottomLeft": { "x": 10, "y": 90 }
  },
  "frameSize": { "width": 1280, "height": 720 },
  "orientation": 0,
  "ecLevel": "M",
  "symbologyIdentifier": "]Q1",
  "timestamp": 1735689600000
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `data` | `string` | The decoded text. GS1 data is returned in human-readable form, for example `(01)09501101530003(10)ABC123`. |
| `symbology` | `string` | Symbology id, for example `qr` or `ean13`. |
| `symbologyName` | `string` | Display name, for example `QR Code`. |
| `rawBytes` | `string` | Base64 of the raw payload bytes. May be `""`. Decode it with `fromBase64()` when you need the exact bytes, for binary payloads or data with control characters. |
| `contentType` | `string` | `text`, `binary`, `gs1`, `iso15434`, `mixed` or `unknown-eci`. |
| `isGS1` | `boolean` | `true` when the code carries GS1 data (FNC1 in first position). |
| `location` | `Quadrilateral` | The four corners of the code, in pixels of the source frame or image. |
| `frameSize` | `Size` | Width and height of the source frame or image, so you can map `location` to the screen. |
| `orientation` | `number` | Rotation of the code in degrees. |
| `ecLevel` | `string` | Error correction level when the symbology has one (`L`, `M`, `Q`, `H` for QR), else `""`. |
| `symbologyIdentifier` | `string` | AIM symbology identifier, for example `]Q1` for QR or `]C1` for GS1-128, when known. |
| `timestamp` | `number` | When the code was decoded, in milliseconds since the Unix epoch. |

In batch mode, results are `TrackedBarcode` objects: the same fields plus `id` (stable while the code stays in view), `firstSeen`, `lastSeen` (timestamps) and `count` (frames it was seen in).

`data` is raw text. To know what it means (a URL, Wi-Fi credentials, a product GTIN, a driver license), pass it to [`parseContent()`](../parsers/).

## Duplicate filter

A camera sees the same code in many consecutive frames. The duplicate filter decides how often a code is reported. Two results count as the same code when both `symbology` and `data` match.

| `duplicateFilter` | Behavior |
| --- | --- |
| `1000` (default) | Report a code at most once per second. Holding a code in front of the camera reports it again every second. |
| any positive number | Same, with that window in milliseconds. `3000` suits checkout, where a repeat within 3 seconds is almost always accidental. |
| `0` | Report every detection in every frame. Useful for measuring, rarely for users. |
| `-1` | Report each code once per session. The filter resets when you call `start()` or `resume()`. Default in `batch` mode. |

The filter only affects `scan` events. The `frame` event (and `track` in batch mode) always contains everything decoded in the frame, so overlays stay live.

## Scan area and viewfinder

Decoding the full camera frame is wasteful when the user aims at the center. The scan area is the region of each frame that is handed to the decoder, as a normalized rectangle (`0` to `1`) relative to the camera frame:

```js
new BarcodeScanner({ scanArea: { x: 0.1, y: 0.35, width: 0.8, height: 0.3 } });
```

The `<qrgen-scanner>` element derives the scan area from its viewfinder automatically. It measures the viewfinder on screen, maps it through the video's `object-fit: cover` crop into camera-frame coordinates, adds a 12% margin, and updates it whenever the element or the video resizes. Users can only scan what they can see inside the viewfinder, and the decoder never wastes time on the parts of the frame that are cropped off screen.

The viewfinder has three styles:

| `viewfinder` | Shape | Default when |
| --- | --- | --- |
| `frame` | Square with corner marks | The enabled symbologies include any 2D code |
| `line` | Wide, short rectangle with a pulsing laser line | Only linear (1D) symbologies are enabled |
| `none` | No viewfinder, the whole visible video is scanned | Never (batch mode hides the viewfinder automatically) |

Setting an explicit `scan-area` on the element overrides the automatic region; the viewfinder is then only a visual guide. With `BarcodeScanner`, there is no viewfinder: set `scanArea` yourself, or leave it unset to decode the full frame.

## Feedback

On each successful scan the SDK plays a short tone through the Web Audio API and vibrates for 40 ms through the Vibration API. Turn either off with `beep: false` or `vibrate: false` (`beep="false"`, `vibrate="false"` on the element). In batch mode, feedback is throttled to at most one beep every 250 ms.

Browsers only allow audio after a user gesture. `start()` unlocks audio, so the beep works when scanning starts from a tap. If the scanner starts automatically on page load, iOS stays silent until the user taps the page. Set `autostart="false"` on the element to show a **Start scanning** button instead. iOS Safari does not support vibration.

## Worker and main-thread decoding

Camera frames are decoded in a Web Worker by default, so decoding never blocks scrolling, animations or your own code. The worker is created from a Blob URL and loads the same wasm file.

If a worker can't be created (for example a Content Security Policy without `worker-src blob:`), the SDK logs `[qrgen] decoding on the main thread: ...` and falls back to decoding on the main thread. Everything still works, but heavy decoding can cause jank on slow devices. The `ready` event and `scanner.stats.engine` tell you which engine is in use (`"worker"` or `"main"`). Force the main thread with `worker: false` or `configure({ worker: false })`.

`scanImage()` always decodes on the main thread, because it runs once rather than 24 times a second.

## Privacy

All decoding happens on the device. Camera frames and images are never uploaded, and QRGen collects no analytics. The only network requests the browser SDK makes are:

- Downloading `zxing_reader.wasm` (and `zxing_writer.wasm` if you generate barcodes) from jsDelivr, unless you [self-host them](../installation/#self-host-the-webassembly-engine).
- Fetching image URLs you pass to `scanImage()`.

The REST API and CLI process images on the machine they run on. If you run `qrgen serve` on a server, images you send to it do leave the device, so treat that server like any other service that handles user data. For ID documents, read [privacy guidance for ID scanning](../id-scanning/#privacy).


---

# JavaScript

URL: https://rockyljewell.github.io/QR-GEN/docs/javascript/
Group: Web

> Scan barcodes from the camera with the BarcodeScanner API and your own video element, decode images with scanImage, and generate barcodes, in plain JavaScript or TypeScript.

The `qrgen-sdk` package exposes three core functions: `BarcodeScanner` for camera scanning, `scanImage()` for still images, and `generate()` for creating barcodes. Use them directly when you want full control over the UI. If you want a ready-made scanner, use the [`<qrgen-scanner>` element](../web-components/) instead; it is built on the same `BarcodeScanner`.

Everything is written in TypeScript and ships with type declarations.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

## Scan from the camera

Create a `BarcodeScanner`, give it a `<video>` element for the preview, listen for `scan` events, and call `start()`:

```html
<video id="preview" style="width: 100%; max-width: 640px; background: #000"></video>
<button id="start">Start scanning</button>
<p id="result"></p>
<script type="module" src="./main.ts"></script>
```

```ts
import { BarcodeScanner, QRGenError } from "qrgen-sdk";

const video = document.querySelector<HTMLVideoElement>("#preview")!;
const result = document.querySelector<HTMLParagraphElement>("#result")!;

const scanner = new BarcodeScanner({
  video,
  symbologies: ["qr", "ean13", "code128"],
  mode: "continuous",
});

scanner.on("scan", ({ barcodes }) => {
  const [barcode] = barcodes;
  result.textContent = `${barcode.symbologyName}: ${barcode.data}`;
});

document.querySelector("#start")!.addEventListener("click", async () => {
  try {
    await scanner.start();
  } catch (err) {
    const e = err as QRGenError;
    result.textContent = `${e.code}: ${e.message}`;
  }
});
```

`start()` asks for camera permission, opens the back camera, plays it into your video element (it sets `playsinline` and `muted` for you, which iOS requires), loads the decoder, and resolves once frames are being decoded. Call it from a click handler: the user gesture lets the beep play on iOS.

> **Note:** Camera access requires a secure context: HTTPS or `http://localhost`. On any other origin `start()` rejects with `insecure-context`.

If you don't pass a `video`, the scanner creates a detached one that is used only for decoding. Pass your own when you want the user to see the preview.

### Options

The constructor takes the shared [scanner options](../options-events/#scanner-options) plus a few web-specific ones:

```ts
import { BarcodeScanner } from "qrgen-sdk";

const video = document.querySelector("video")!;
const scanner = new BarcodeScanner({
  video,
  symbologies: ["qr", "data-matrix"], // ids, aliases or groups; default: all
  mode: "continuous",                 // "single" | "continuous" | "batch"
  duplicateFilter: 1000,              // ms; 0 = every frame, -1 = once per session
  beep: true,
  vibrate: true,
  camera: "back",                     // "back" | "front" | a deviceId
  resolution: "hd",                   // "sd" | "hd" | "fhd" | "4k"
  scanArea: { x: 0.2, y: 0.2, width: 0.6, height: 0.6 }, // normalized; default: full frame
  maxResults: 1,                      // codes per frame; default 1 (20 in batch mode)
  tryHarder: false,                   // more CPU per frame for damaged or tiny codes
  worker: true,                       // decode in a Web Worker
  maxDecodeSize: 1280,                // longest side of the image handed to the decoder
  maxFps: 24,                         // upper bound for decodes per second
  tryInvert: "alternate",             // look for white-on-black codes on every other frame
});
```

Read the resolved values (with defaults filled in) from `scanner.options`.

### Change options while scanning

`setOptions()` applies new options without restarting the camera. It works for `symbologies`, `mode`, `duplicateFilter`, `beep`, `vibrate`, `scanArea`, `maxResults`, `tryHarder`, `maxDecodeSize`, `maxFps` and `tryInvert`:

```ts
scanner.setOptions({ symbologies: ["pdf417"], tryHarder: true });
```

`setOptions()` merges with the options you passed before and re-derives the mode-dependent defaults, so switching modes is a one-liner:

```ts
scanner.setOptions({ mode: "batch" }); // maxResults 20, duplicateFilter -1, tryHarder true
scanner.setOptions({ mode: "continuous" }); // back to maxResults 1, duplicateFilter 1000
```

`camera`, `resolution` and `worker` are fixed when the scanner is created. To use a different camera, call `switchCamera()` or create a new scanner.

## Events

`on()` subscribes and returns a function that unsubscribes. `once()` fires a single time, `off()` removes a listener.

```ts
const unsubscribe = scanner.on("frame", ({ barcodes, decodeMs }) => drawOverlay(barcodes));
unsubscribe();
```

| Event | Payload | When |
| --- | --- | --- |
| `scan` | `{ barcodes: Barcode[] }` | New codes that passed the duplicate filter. Usually one; several when `maxResults` > 1. |
| `frame` | `{ barcodes: Barcode[], frameSize: Size, decodeMs: number }` | After every decoded frame, including frames with no codes and duplicates. Use it for overlays. |
| `track` | `{ tracked, added, updated, removed }` (all `TrackedBarcode[]`) | Batch mode only, after every decoded frame. See [Batch scanning](../batch-scanning/). |
| `state` | `ScannerState` | The state changed: `"idle"`, `"starting"`, `"scanning"`, `"paused"`, `"stopped"` or `"error"`. |
| `ready` | `{ engine: "worker" \| "main", camera: Camera }` | The camera is open and decoding has started. |
| `error` | `QRGenError` | Starting failed, or the engine failed to load while scanning. |

`start()` both emits `error` and rejects with the same `QRGenError`, so you can handle failures either way. The error's `code` tells you what went wrong; see [error codes](../options-events/#error-codes).

In `single` mode, the scanner pauses itself right before emitting `scan`. Call `resume()` to scan the next code.

## Controls

```ts
scanner.on("ready", async ({ camera }) => {
  const { torch, zoom } = camera.capabilities;

  if (torch) await scanner.setTorch(true);          // returns false if the camera refused
  if (zoom) await scanner.setZoom(Math.min(2, zoom.max));
});

scanner.pause();        // stop decoding, keep the camera open
scanner.resume();       // continue after pause() or a single-mode scan
await scanner.toggleTorch();
await scanner.switchCamera(); // front <-> back, or the next camera when there are more than two
```

| Member | Returns | Notes |
| --- | --- | --- |
| `start()` | `Promise<void>` | Open the camera and start decoding. No-op while already starting or scanning. |
| `stop()` | `void` | Stop decoding and release the camera. `start()` again to restart. |
| `pause()` | `void` | Stop decoding; the preview keeps running. |
| `resume()` | `void` | Continue decoding. Resets the duplicate filter. |
| `setTorch(on)` | `Promise<boolean>` | `false` when the camera has no torch or refused. |
| `toggleTorch()` | `Promise<boolean>` | The new torch state. |
| `setZoom(zoom)` | `Promise<boolean>` | Clamped to the camera's range. `false` when zoom is not supported. |
| `switchCamera()` | `Promise<void>` | Restarts the camera with the other facing mode or the next device. |
| `setOptions(partial)` | `void` | See above. |
| `destroy()` | `void` | Stop, remove all listeners and release audio. |
| `state` | `ScannerState` | Current state. |
| `options` | resolved options | Current options with defaults filled in. |
| `camera` | `Camera` | `capabilities`, `isTorchOn`, `isFront`, `videoSize`, `track`, `stream`. |
| `tracker` | `BarcodeTracker` | The batch-mode tracker. |
| `feedback` | `Feedback` | The beep and vibration helper. |
| `stats` | `{ decodeMs, fps, engine }` | Diagnostics, see below. |

Torch and zoom depend on the browser and device. Chrome on Android supports both on most phones; Safari on iOS has limited or no support depending on the version. Check `camera.capabilities` after `ready` instead of assuming: `torch` is `false` and `zoom` is `null` when the camera doesn't offer them.

### Choose a camera

```ts
import { BarcodeScanner, Camera } from "qrgen-sdk";

const cameras = await Camera.list(); // MediaDeviceInfo[]; labels are empty until permission is granted
const usb = cameras.find((c) => /usb|logitech/i.test(c.label));

const scanner = new BarcodeScanner({ video, camera: usb?.deviceId ?? "back" });
```

`camera` accepts `"back"` (default), `"front"` or a `deviceId`. If a pinned device disappears, the scanner falls back to the facing mode. `Camera.isSupported()` tells you whether `getUserMedia` exists at all.

## Stats

`scanner.stats` is updated after every decode:

| Field | Meaning |
| --- | --- |
| `decodeMs` | Smoothed decode time per frame, in milliseconds. |
| `fps` | Decodes in the last second. Capped by `maxFps` and the camera frame rate. |
| `engine` | `"worker"` or `"main"`, or `""` before the first start. |

```ts
setInterval(() => console.log(`${scanner.stats.fps} fps, ${scanner.stats.decodeMs.toFixed(1)} ms, ${scanner.stats.engine}`), 1000);
```

If `decodeMs` is high, see [slow scanning](../troubleshooting/#scanning-is-slow).

## Clean up

Release the camera when the user leaves the screen. In a single-page app, call `destroy()` when the view unmounts:

```ts
scanner.destroy();
```

While the tab is hidden, the scanner skips decoding but keeps the camera open. To release it, stop and restart on visibility changes:

```ts
document.addEventListener("visibilitychange", () => {
  if (document.hidden) scanner.stop();
  else void scanner.start();
});
```

## Scan images

`scanImage()` decodes a `File`, `Blob`, `ArrayBuffer`, `Uint8Array`, `ImageData`, `<img>`, `<canvas>`, `<video>` (current frame), `ImageBitmap`, `OffscreenCanvas` or a URL string, and resolves with every code it finds:

```ts
import { scanImage } from "qrgen-sdk";

const input = document.querySelector<HTMLInputElement>("input[type=file]")!;
input.addEventListener("change", async () => {
  const file = input.files?.[0];
  if (!file) return;
  const barcodes = await scanImage(file, { symbologies: ["qr", "ean13"] });
  if (barcodes.length === 0) console.log("No code found");
  for (const b of barcodes) console.log(b.symbology, b.data);
});
```

Options: `symbologies`, `maxResults` (default 255) and `tryHarder` (default `true` for images). Details, drag and drop and clipboard examples are in [Image scanning](../image-scanning/).

## Generate barcodes

```ts
import { generate } from "qrgen-sdk";

const { svg, png } = await generate("https://example.com", { symbology: "qr", ecLevel: "M", scale: 6 });
document.querySelector("#code")!.innerHTML = svg;
```

`generate()` returns the SVG markup, a PNG `Blob` (in browsers), the module matrix and a text rendering. `generateSVG()` returns only the SVG and `generateDataURL()` returns a `data:image/svg+xml` URL for an `<img>`. See [Barcode generation](../barcode-generation/).

## Parse the result

```ts
import { parseContent } from "qrgen-sdk";

scanner.on("scan", ({ barcodes }) => {
  const parsed = parseContent(barcodes[0].data, { symbology: barcodes[0].symbology });
  if (parsed.type === "url") window.open(parsed.url, "_blank", "noopener");
  if (parsed.type === "wifi") console.log(`Network ${parsed.ssid}, password ${parsed.password ?? "(none)"}`);
});
```

See [Parsers](../parsers/) for every content type.

## TypeScript

All types are exported from `qrgen-sdk`:

```ts
import type { Barcode, TrackedBarcode, BarcodeScannerOptions, ScannerState, ScanImageOptions, GenerateOptions, ParsedContent, QRGenErrorCode } from "qrgen-sdk";
```

The full list is in the [JavaScript API reference](../api/).


---

# Web Components

URL: https://rockyljewell.github.io/QR-GEN/docs/web-components/
Group: Web

> Reference for the <qrgen-scanner> and <qrgen-barcode> custom elements: attributes, properties, methods, events, CSS custom properties, parts and sizing.

`qrgen-sdk/elements` registers two framework-agnostic custom elements:

- `<qrgen-scanner>`: a complete camera scanner with viewfinder, code highlights, torch, camera switch, pause, a batch results list, a success toast, and start, loading and error screens.
- `<qrgen-barcode>`: renders any supported barcode as crisp, scalable SVG.

They work in plain HTML and in every framework. The React and Vue wrappers are thin layers over these elements.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

```js
import "qrgen-sdk/elements"; // registers <qrgen-scanner> and <qrgen-barcode>
```

The import is safe to run more than once and on the server (registration is skipped where `customElements` doesn't exist). Without a bundler, load the [CDN bundle](../cdn/) instead; it registers both elements too.

## `<qrgen-scanner>`

```html
<qrgen-scanner symbologies="qr,ean13,code128" mode="continuous" style="height: 480px"></qrgen-scanner>

<script type="module">
  import "qrgen-sdk/elements";

  const scanner = document.querySelector("qrgen-scanner");
  scanner.addEventListener("scan", (event) => {
    console.log(event.detail.barcode.symbology, event.detail.barcode.data);
  });
  scanner.addEventListener("error", (event) => {
    console.warn(event.detail.code, event.detail.message);
  });
</script>
```

By default the element opens the camera as soon as it is added to the page. The scanner needs a secure context (HTTPS or `http://localhost`); elsewhere it shows its error screen with an `insecure-context` error.

### Attributes and properties

Attributes are strings. The properties in the second column accept typed values (arrays, numbers, objects, booleans), which is convenient from frameworks. Setting a property updates the attribute.

| Attribute | Property | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `symbologies` | `symbologies` | Comma or space separated ids, aliases or groups. The property also accepts an array and returns the resolved id array. | all | What to scan. See [Symbologies](../symbologies/). |
| `mode` | `mode` | `single`, `continuous`, `batch` | `continuous` | [Scan mode](../concepts/#scan-modes). |
| `duplicate-filter` | `duplicateFilter` | Milliseconds; `0` reports every frame, `-1` once per session | `1000` (`-1` in batch) | [Duplicate filter](../concepts/#duplicate-filter). |
| `beep` | `beep` | boolean | `true` | Play a tone on scan. |
| `vibrate` | `vibrate` | boolean | `true` | Vibrate on scan, where supported. |
| `camera` | `camera` | `back`, `front` or a `deviceId` | `back` | Which camera to open. Changing it restarts the camera. |
| `torch` | `torch` | boolean | `false` | Turn the flashlight on when the camera supports it. |
| `viewfinder` | `viewfinder` | `frame`, `line`, `none` | `frame` (`line` when only linear symbologies are enabled) | Viewfinder style. Hidden in batch mode. |
| `scan-area` | `scanArea` | `"x,y,width,height"`, normalized 0 to 1 (property: `{ x, y, width, height }`) | derived from the viewfinder | Overrides the automatic decode region. |
| `max-results` | `maxResults` | integer | `1` (`20` in batch) | Codes decoded per frame. |
| `autostart` | `autostart` | boolean | `true` | Start the camera when the element connects. When `false`, a **Start scanning** screen is shown. |
| `controls` | | `none` | shown | `none` hides the camera control bars, the batch counter and the **Scan again** button. Batch results remain available. |
| `accent` | | CSS color, hex recommended | `#5cc9d6` | Accent color. Same as setting `--qrgen-accent`. |
| `hint` | | text | mode-specific | Instruction pill at the bottom. `hint=""` hides it. |
| `toast` | | boolean | `true` | Show the success toast with the scanned value (single and continuous modes). |
| `try-harder` | | boolean | `false` (single/continuous), `true` (batch) | Spend more CPU per frame on damaged or tiny codes. |
| `resolution` | | `sd`, `hd`, `fhd`, `4k` | `hd` | Requested camera resolution (640x480, 1280x720, 1920x1080, 3840x2160). |
| `worker` | | boolean | `true` | Decode in a Web Worker. |

Boolean attributes are `true` when present without a value (`<qrgen-scanner torch>`), and `false` for the values `false`, `0`, `off` and `no`. Because `autostart`, `beep` and `vibrate` default to `true`, turn them off with an explicit value: `autostart="false"`.

Changes to most attributes apply immediately while scanning. `camera` restarts the camera. `resolution` and `worker` take effect the next time the element creates its scanner (for example after you change `camera`, or remove and re-add the element).

Read-only properties:

| Property | Type | Description |
| --- | --- | --- |
| `state` | `ScannerState` | `idle`, `starting`, `scanning`, `paused`, `stopped` or `error`. |
| `scanner` | `BarcodeScanner \| null` | The underlying [`BarcodeScanner`](../javascript/), created on first start. Use it for `frame` events, `stats` and options the element has no attribute for, such as `maxDecodeSize`. |
| `lastResult` | `Barcode \| null` | The last barcode reported by a `scan` event. |
| `selection` | `TrackedBarcode[]` | Batch mode: codes chosen from the results list. |
| `options` | `BarcodeScannerOptions` | The scanner options derived from the current attributes. |

### Methods

| Method | Returns | Description |
| --- | --- | --- |
| `start()` | `Promise<void>` | Open the camera and start scanning. Rejects with a `QRGenError` on failure (the error screen is shown too). |
| `stop()` | `void` | Stop and release the camera. Shows the start screen. |
| `pause()` | `void` | Stop decoding, keep the preview. |
| `resume()` | `void` | Continue after `pause()` or a single-mode scan. |
| `setTorch(on)` | `Promise<boolean>` | `false` when the camera has no torch. |
| `toggleTorch()` | `Promise<boolean>` | The new torch state. |
| `setZoom(zoom)` | `Promise<boolean>` | `false` when zoom is not supported. |
| `switchCamera()` | `Promise<void>` | Front/back, or the next camera. |
| `clearSelection()` | `void` | Batch mode: clear the selection and fire `select` with an empty selection. |
| `selectBarcode(id, selected?)` | `boolean` | Select or deselect a track by id. Omit `selected` to toggle. Returns `false` for an unknown id or outside batch mode. |

Removing the element from the page stops the camera and releases everything. Adding it back starts it again (unless `autostart="false"`).

### Events

All events are `CustomEvent`s that bubble and cross shadow DOM boundaries. Read the payload from `event.detail`.

| Event | `detail` | When |
| --- | --- | --- |
| `scan` | `{ barcodes: Barcode[], barcode: Barcode }` | New codes passed the duplicate filter. `barcode` is `barcodes[0]`. |
| `track` | `{ tracked: TrackedBarcode[], added: TrackedBarcode[], removed: TrackedBarcode[] }` | Batch mode, after every decoded frame. |
| `select` | `{ barcode: TrackedBarcode \| null, selected: boolean, selection: TrackedBarcode[] }` | Batch mode: a result's selection changed, `clearSelection()` was called, or a nonempty selection was automatically cleared on mode/source recreation or disconnect (`barcode: null`). |
| `ready` | `{ engine: "worker" \| "main" }` | The camera is open and decoding started. |
| `statechange` | `{ state: ScannerState }` | The scanner state changed. |
| `error` | `{ code: QRGenErrorCode, message: string }` | Starting failed or the engine failed to load. See [error codes](../options-events/#error-codes). |

In TypeScript, cast the event to read `detail`:

```ts
import "qrgen-sdk/elements";
import type { Barcode } from "qrgen-sdk";

const el = document.querySelector("qrgen-scanner")!; // typed as QRGenScannerElement
el.addEventListener("scan", (event) => {
  const { barcode } = (event as CustomEvent<{ barcodes: Barcode[]; barcode: Barcode }>).detail;
  console.log(barcode.data);
});
```

The element doesn't re-dispatch the per-frame `frame` event. Subscribe on the underlying scanner when you need it:

```js
el.addEventListener("ready", () => {
  el.scanner.on("frame", ({ barcodes, decodeMs }) => console.log(barcodes.length, decodeMs));
});
```

### Screens and built-in controls

The element manages its own screens:

- **Start**: shown when `autostart="false"` or after `stop()`. A **Start scanning** button calls `start()`. Starting from a tap also unlocks audio on iOS.
- **Loading**: while the camera and engine start.
- **Error**: shows the error message and a **Try again** button.
- **Scan again**: in single mode, after a successful scan.

While scanning, the top bar has pause, torch and camera-switch buttons, and the bottom bar has a 1×/2× zoom toggle. Torch, camera switch and zoom appear when supported. Batch mode adds an automatic in-view counter and a scrollable results list below the preview. Choose rows by touch, mouse or keyboard; selected results remain available after leaving view. `controls="none"` hides both bars and the **Scan again** button; the batch results list remains available. In single mode, resume with `resume()` from your own UI. Set any other zoom level with `setZoom()`.

### Styling

CSS custom properties, set on the element or any ancestor:

| Property | Default | Used for |
| --- | --- | --- |
| `--qrgen-accent` | `#5cc9d6` | Highlights, laser line, buttons, toast icon, counter |
| `--qrgen-accent-contrast` | `#062029` | Text and icons on accent-colored surfaces |
| `--qrgen-radius` | `0px` | Corner radius of the element |
| `--qrgen-font` | system UI stack | All text |

```css
qrgen-scanner {
  --qrgen-accent: #ff6b35;
  --qrgen-accent-contrast: #ffffff;
  --qrgen-radius: 16px;
  --qrgen-font: "Inter", system-ui, sans-serif;
}
```

The `accent` attribute sets `--qrgen-accent` as an inline style, so it wins over stylesheet values. Use hex colors (`#rgb` or `#rrggbb`) for the accent: the overlay derives translucent fills from them.

Shadow parts, for deeper styling with `::part()`:

| Part | Element |
| --- | --- |
| `root` | Container of everything inside the element |
| `preview` | Camera area, including preview overlays and camera controls |
| `results` | Batch selection list below the camera area |
| `video` | The camera preview (`object-fit: cover`) |
| `overlay` | Canvas that draws code highlights |
| `viewfinder` | The viewfinder frame or line |
| `hint` | The instruction pill |
| `toast` | The success toast |
| `controls` | The top and bottom control bars (both carry this part) |

```css
qrgen-scanner::part(hint) {
  bottom: 24px;
  font-size: 15px;
}
qrgen-scanner::part(toast) {
  border-radius: 12px;
}
qrgen-scanner::part(video) {
  filter: saturate(0.8);
}
```

More recipes, including a fully custom UI, are in [UI customization](../ui-customization/).

### Sizing

The element is `display: block` with `width: 100%`, `height: 100%` and `min-height: 280px`. Inside a container without an explicit height it collapses to 280 px, so give it a height or an aspect ratio:

```css
/* Fixed height */
qrgen-scanner { height: 480px; }

/* Aspect ratio */
qrgen-scanner { height: auto; aspect-ratio: 3 / 4; max-width: 480px; }

/* Full screen */
qrgen-scanner { position: fixed; inset: 0; height: 100dvh; }
```

The video fills the element with `object-fit: cover`, so the preview is cropped rather than letterboxed. The decode region follows what is visible.

## `<qrgen-barcode>`

```html
<qrgen-barcode value="https://example.com" symbology="qr" ec-level="M" style="width: 160px"></qrgen-barcode>
<qrgen-barcode value="5901234123457" symbology="ean13" hrt style="width: 240px"></qrgen-barcode>
<qrgen-barcode value="(01)09501101530003(17)250101(10)ABC123" symbology="data-matrix" gs1></qrgen-barcode>
```

### Attributes

| Attribute | Default | Description |
| --- | --- | --- |
| `value` | | The data to encode. Nothing renders while it is empty. Also available as the `value` property. |
| `symbology` | `qr` | Symbology id or alias. Must be [writable](../symbologies/). |
| `scale` | `4` | Module size in pixels, which sets the SVG's natural size. |
| `ec-level` | encoder default | Error correction: `L`, `M`, `Q`, `H` for QR, or a percentage for Aztec and PDF417. |
| `foreground` | `#000000` | Bar and module color. |
| `background` | `#ffffff` | Background color, or `transparent`. |
| `hrt` | off | Print the human-readable text under linear barcodes. |
| `margin` | on | Quiet zone around the symbol. `margin="false"` removes it. |
| `gs1` | off | Encode `value` as GS1 (HRI form, `(01)...(10)...`). |
| `rotate` | `0` | `0`, `90`, `180` or `270`. |
| `alt` | `"<symbology> barcode: <value>"` | Accessible label on the SVG (`role="img"`). |

`hrt` and `gs1` are on when present, unless set to `"false"`. Changing any attribute re-renders.

The read-only `svg` property holds the last rendered SVG markup, handy for downloads:

```js
const el = document.querySelector("qrgen-barcode");
el.addEventListener("render", () => {
  const url = URL.createObjectURL(new Blob([el.svg], { type: "image/svg+xml" }));
  document.querySelector("a#download").href = url;
});
```

### Events

| Event | `detail` | When |
| --- | --- | --- |
| `render` | `{ svg: string, symbology: Symbology }` | The barcode rendered. |
| `error` | `{ message: string }` | The value can't be encoded (for example letters in an EAN-13). The message is also shown in place of the barcode. |

### Sizing and parts

The element is `inline-block`. Without CSS it renders at its natural size (modules times `scale`). Set a `width` (or `height`) and the SVG scales without blurring, keeping its aspect ratio. The inner container is exposed as `::part(barcode)`.

## Frameworks

- React: [`QRGenScanner` and `QRGenBarcode`](../react/)
- Vue and Nuxt: [components and plugin](../vue/)
- [Angular](../angular/), [Svelte](../svelte/): use the elements directly
- WebViews and iframes: the [embed page and bridge](../embed-bridge/)


---

# Script tag & CDN

URL: https://rockyljewell.github.io/QR-GEN/docs/cdn/
Group: Web

> Use QRGen without a build step: load the ES module or classic-script bundle from the CDN, use the elements and the global QRGen object, and self-host the files.

QRGen publishes two standalone bundles that contain the entire SDK: the scanner and generator, both custom elements, the parsers and the embed bridge. Both register `<qrgen-scanner>` and `<qrgen-barcode>` as soon as they load. Use them for static sites, CMS pages, prototypes, or anywhere you can't run a bundler.

| URL | Format | Size |
| --- | --- | --- |
| `https://rockyljewell.github.io/QR-GEN/sdk/qrgen.js` | ES module | about 60 KB gzipped |
| `https://rockyljewell.github.io/QR-GEN/sdk/qrgen.iife.js` | Classic script, global `QRGen` | about 60 KB gzipped |

The decoder wasm (about 400 KB gzipped) is fetched separately the first time you scan and cached by the browser.

## ES module

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Scanner</title>
  </head>
  <body>
    <qrgen-scanner symbologies="qr,ean13" style="height: 70vh"></qrgen-scanner>
    <pre id="out"></pre>

    <script type="module">
      import { parseContent } from "https://rockyljewell.github.io/QR-GEN/sdk/qrgen.js";

      document.querySelector("qrgen-scanner").addEventListener("scan", ({ detail }) => {
        const parsed = parseContent(detail.barcode.data, { symbology: detail.barcode.symbology });
        document.querySelector("#out").textContent = JSON.stringify(parsed, null, 2);
      });
    </script>
  </body>
</html>
```

Everything exported by `qrgen-sdk`, `qrgen-sdk/elements` and `qrgen-sdk/bridge` is available as a named export, plus a default export with the `QRGen` namespace object.

## Classic script

The IIFE build defines a global `QRGen` that holds every export:

```html
<qrgen-scanner id="scanner" mode="single" style="height: 420px"></qrgen-scanner>
<div id="qr"></div>

<script src="https://rockyljewell.github.io/QR-GEN/sdk/qrgen.iife.js"></script>
<script>
  document.getElementById("scanner").addEventListener("scan", function (event) {
    console.log(event.detail.barcode.data);
  });

  QRGen.generateSVG("https://example.com", { symbology: "qr" }).then(function (svg) {
    document.getElementById("qr").innerHTML = svg;
  });

  console.log(QRGen.version, QRGen.parseContent("WIFI:T:WPA;S:Guest;P:welcome1;;"));
</script>
```

Commonly used members of the global:

| Member | Description |
| --- | --- |
| `QRGen.BarcodeScanner` | Camera scanning class. `QRGen.createScanner(options)` is a shortcut. |
| `QRGen.scanImage(input, options)` | Decode images. |
| `QRGen.generate(data, options)`, `QRGen.generateSVG`, `QRGen.generateDataURL` | Generate barcodes. |
| `QRGen.parseContent`, `QRGen.parseGS1`, `QRGen.parseAAMVA` | Parsers. |
| `QRGen.configure(config)` | Engine configuration (wasm location, worker). |
| `QRGen.supportedSymbologies()` | `{ read: [...], write: [...] }` |
| `QRGen.connectBridge`, `QRGen.parseBridgeMessage` | Embed bridge helpers. |
| `QRGen.version`, `QRGen.engineVersion` | SDK and engine versions. |

The global has the same members as the ES module's named exports; see the [API reference](../api/).

## Scanning without the element

The bundle includes the low-level API too:

```html
<video id="preview" style="width: 100%"></video>
<button id="go">Scan</button>

<script type="module">
  import { BarcodeScanner } from "https://rockyljewell.github.io/QR-GEN/sdk/qrgen.js";

  const scanner = new BarcodeScanner({ video: document.querySelector("#preview"), mode: "single" });
  scanner.on("scan", ({ barcodes }) => alert(barcodes[0].data));
  document.querySelector("#go").addEventListener("click", () => scanner.start());
</script>
```

## Self-hosting the bundle

To avoid a third-party script, copy the bundle into your site. After `npm install qrgen-sdk` it is in `node_modules/qrgen-sdk/dist/browser/` (`qrgen.js`, `qrgen.iife.js` and source maps).

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`. Copy the wasm files too and point the engine at them with a global set before the bundle loads:

```html
<script>
  globalThis.QRGEN_WASM_BASE = "/vendor/qrgen/wasm/";
</script>
<script src="/vendor/qrgen/qrgen.iife.js"></script>
```

With the folder layout:

```text
/vendor/qrgen/qrgen.iife.js
/vendor/qrgen/wasm/zxing_reader.wasm
/vendor/qrgen/wasm/zxing_writer.wasm
```

The wasm files are in `node_modules/qrgen-sdk/dist/wasm/`. With the ES module you can call `configure({ wasmBaseUrl: "/vendor/qrgen/wasm/" })` instead of setting the global. Always copy the bundle and the wasm files from the same SDK version.

## Versions

The URLs above always serve the latest build from the main branch. For production, self-host a copy (above) so an update can't change your page unexpectedly. Once `qrgen-sdk` is published to npm, the same files are also available from npm CDNs with a pinned version, for example `https://cdn.jsdelivr.net/npm/qrgen-sdk@1.0.0/dist/browser/qrgen.js`, which you can combine with [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).

## Content Security Policy

If your page has a CSP, allow the bundle's origin in `script-src`, plus `'wasm-unsafe-eval'`, `worker-src blob:` and `connect-src https://cdn.jsdelivr.net` (or your self-hosted wasm origin). The full list is in [Installation](../installation/#content-security-policy).


---

# React

URL: https://rockyljewell.github.io/QR-GEN/docs/react/
Group: Web

> Use the QRGenScanner and QRGenBarcode React components: props, event callbacks, the imperative ref handle, and server-side rendering notes.

`qrgen-sdk/react` provides two components that wrap the [web components](../web-components/): `QRGenScanner` for camera scanning and `QRGenBarcode` for rendering barcodes. They work with React 17, 18 and 19.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

## Scan

```tsx
import { useState } from "react";
import { QRGenScanner, type Barcode } from "qrgen-sdk/react";

export function CheckoutScanner() {
  const [items, setItems] = useState<Barcode[]>([]);

  return (
    <section>
      <QRGenScanner
        symbologies={["ean13", "upca", "upce", "code128"]}
        duplicateFilter={3000}
        style={{ height: 420 }}
        onScan={(barcodes) => setItems((prev) => [...barcodes, ...prev])}
        onError={(error) => console.warn(error.code, error.message)}
      />
      <ul>
        {items.map((b) => (
          <li key={`${b.timestamp}-${b.data}`}>
            {b.symbologyName}: {b.data}
          </li>
        ))}
      </ul>
    </section>
  );
}
```

The camera starts when the component mounts and stops when it unmounts. Camera access requires HTTPS or `http://localhost`.

## `QRGenScanner` props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `symbologies` | `string[] \| string` | all | Ids, aliases or groups. |
| `mode` | `"single" \| "continuous" \| "batch"` | `"continuous"` | [Scan mode](../concepts/#scan-modes). |
| `duplicateFilter` | `number` | `1000` (`-1` in batch) | Milliseconds; `0` every frame, `-1` once per session. |
| `beep` | `boolean` | `true` | Tone on scan. |
| `vibrate` | `boolean` | `true` | Vibration on scan. |
| `camera` | `"back" \| "front" \| string` | `"back"` | Facing mode or `deviceId`. Changing it restarts the camera. |
| `torch` | `boolean` | `false` | Flashlight, where supported. |
| `viewfinder` | `"frame" \| "line" \| "none"` | depends on symbologies | Viewfinder style. |
| `scanArea` | `{ x, y, width, height }` | from the viewfinder | Normalized decode region. |
| `maxResults` | `number` | `1` (`20` in batch) | Codes per frame. |
| `autostart` | `boolean` | `true` | Start on mount. When `false`, a **Start scanning** screen is shown. |
| `controls` | `"default" \| "none"` | `"default"` | `"none"` hides the built-in buttons. |
| `accent` | `string` | `#5cc9d6` | Accent color (hex). |
| `hint` | `string` | mode-specific | Instruction text; `""` hides it. |
| `toast` | `boolean` | `true` | Success toast. |
| `tryHarder` | `boolean` | `false` (single/continuous), `true` (batch) | More CPU per frame for difficult codes. |
| `resolution` | `"sd" \| "hd" \| "fhd" \| "4k"` | `"hd"` | Camera resolution. |
| `className` | `string` | | Class on the `<qrgen-scanner>` element. |
| `style` | `CSSProperties` | | Inline style. Give the scanner a height. |

### Callbacks

| Prop | Signature | When |
| --- | --- | --- |
| `onScan` | `(barcodes: Barcode[], barcode: Barcode) => void` | New codes passed the duplicate filter. `barcode` is the first one. |
| `onTrack` | `(update: { tracked, added, removed }) => void` | Batch mode, every decoded frame. |
| `onSelect` | `(detail: { barcode: TrackedBarcode \| null, selected: boolean, selection: TrackedBarcode[] }) => void` | Batch results selection changed. |
| `onError` | `(error: { code: QRGenErrorCode, message: string }) => void` | Starting failed. See [error codes](../options-events/#error-codes). |
| `onReady` | `(detail: { engine: "worker" \| "main" }) => void` | Scanning started. |
| `onStateChange` | `(state: ScannerState) => void` | `idle`, `starting`, `scanning`, `paused`, `stopped`, `error`. |

Callbacks always see the latest props, so inline arrow functions don't cause re-subscriptions.

## Ref handle

Pass a ref to control the scanner imperatively:

```tsx
import { useRef, useState } from "react";
import { QRGenScanner, type QRGenScannerHandle } from "qrgen-sdk/react";

export function LoginScanner({ onToken }: { onToken: (token: string) => void }) {
  const scanner = useRef<QRGenScannerHandle>(null);
  const [torch, setTorch] = useState(false);

  return (
    <div>
      <QRGenScanner
        ref={scanner}
        symbologies="qr"
        mode="single"
        controls="none"
        style={{ height: 360 }}
        onScan={(_, barcode) => onToken(barcode.data)}
      />
      <button onClick={() => scanner.current?.resume()}>Scan again</button>
      <button onClick={async () => setTorch((await scanner.current?.toggleTorch()) ?? false)}>Torch {torch ? "off" : "on"}</button>
      <button onClick={() => scanner.current?.switchCamera()}>Switch camera</button>
    </div>
  );
}
```

| Member | Returns |
| --- | --- |
| `start()` | `Promise<void>` |
| `stop()` | `void` |
| `pause()` | `void` |
| `resume()` | `void` |
| `setTorch(on)` | `Promise<boolean>` |
| `toggleTorch()` | `Promise<boolean>` |
| `switchCamera()` | `Promise<void>` |
| `setZoom(zoom)` | `Promise<boolean>` |
| `clearSelection()` | `void` |
| `selectBarcode(id, selected?)` | `boolean` |
| `element` | The underlying `QRGenScannerElement`, or `null` before mount |

Use `element` to read `selection`, `lastResult` or the underlying `scanner` for `frame` events and `stats`:

```tsx
scanner.current?.element?.clearSelection();
console.log(scanner.current?.element?.scanner?.stats);
```

## Batch mode

```tsx
import { useState } from "react";
import { QRGenScanner, type TrackedBarcode } from "qrgen-sdk/react";

export function ShelfScanner() {
  const [inView, setInView] = useState<TrackedBarcode[]>([]);
  const [selected, setSelected] = useState<TrackedBarcode[]>([]);

  return (
    <>
      <QRGenScanner
        mode="batch"
        symbologies="retail"
        style={{ height: "70vh" }}
        onTrack={({ tracked }) => setInView(tracked)}
        onSelect={({ selection }) => setSelected(selection)}
      />
      <p>
        {inView.length} in view, {selected.length} selected
      </p>
    </>
  );
}
```

`onTrack` fires on every decoded frame (up to 24 times per second). If you render heavy UI from it, throttle the state updates. See [Batch scanning](../batch-scanning/).

## `QRGenBarcode`

```tsx
import { QRGenBarcode } from "qrgen-sdk/react";

export function Ticket({ id }: { id: string }) {
  return <QRGenBarcode value={`https://example.com/t/${id}`} symbology="qr" ecLevel="Q" style={{ width: 180 }} />;
}
```

Props: `value` (required), `symbology`, `scale`, `ecLevel`, `foreground`, `background`, `hrt`, `margin`, `gs1`, `rotate`, `alt`, `className`, `style`. They match the [`<qrgen-barcode>` attributes](../web-components/#qrgen-barcode).

## Server-side rendering

Both components are safe to import on the server. During SSR they render an empty `<qrgen-scanner>` or `<qrgen-barcode>` tag with attributes; the custom elements register and start in the browser. Nothing touches `window` or the camera at import time.

The components use hooks, so in frameworks with React Server Components (the Next.js App Router, for example) render them from a Client Component, a file that starts with `"use client"`. See [Next.js](../nextjs/). If you call `BarcodeScanner` or `scanImage` directly, do it in an effect or event handler, never during render.

## Without the wrapper

You can also use the element directly in JSX. Import `qrgen-sdk/elements` once to register it:

```tsx
import { useEffect, useRef } from "react";
import "qrgen-sdk/elements";
import type { Barcode } from "qrgen-sdk";

export function RawScanner() {
  const ref = useRef<HTMLElement>(null);

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const onScan = (e: Event) => console.log((e as CustomEvent<{ barcode: Barcode }>).detail.barcode.data);
    el.addEventListener("scan", onScan);
    return () => el.removeEventListener("scan", onScan);
  }, []);

  return <qrgen-scanner ref={ref} symbologies="qr" style={{ height: 400 }} />;
}
```

Importing `qrgen-sdk/react` anywhere in your app adds the JSX type declarations for `<qrgen-scanner>` and `<qrgen-barcode>`. Without it, declare them in your own `.d.ts` file.


---

# Next.js

URL: https://rockyljewell.github.io/QR-GEN/docs/nextjs/
Group: Web

> Add a QRGen barcode scanner to a Next.js App Router or Pages Router app with a client component, next/dynamic, self-hosted wasm and server-side scanning in route handlers.

QRGen's React components run in the browser, so in the Next.js App Router they belong in Client Components. This page shows the App Router setup, optional lazy loading with `next/dynamic`, self-hosting the wasm from `public/`, and scanning uploaded images in a route handler.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

## App Router

Create a Client Component. The `"use client"` directive is required because `QRGenScanner` uses hooks and the camera:

```tsx
// app/scan/scanner.tsx
"use client";

import { useState } from "react";
import { QRGenScanner } from "qrgen-sdk/react";
import { parseContent, type ParsedContent } from "qrgen-sdk";

export default function Scanner() {
  const [result, setResult] = useState<ParsedContent | null>(null);

  return (
    <div>
      <QRGenScanner
        symbologies={["qr", "ean13", "code128"]}
        mode="single"
        style={{ height: 420, borderRadius: 12, overflow: "hidden" }}
        onScan={(_, barcode) => setResult(parseContent(barcode.data, { symbology: barcode.symbology }))}
      />
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}
```

Use it from a Server Component page:

```tsx
// app/scan/page.tsx
import Scanner from "./scanner";

export const metadata = { title: "Scan" };

export default function ScanPage() {
  return (
    <main>
      <h1>Scan a code</h1>
      <Scanner />
    </main>
  );
}
```

During server rendering, the component outputs an empty `<qrgen-scanner>` tag. The element registers and opens the camera after the page loads in the browser.

> **Note:** The camera only works on HTTPS or `http://localhost`. `next dev` serves `http://localhost:3000`, which works. To test on a phone, use `next dev --experimental-https` or a tunnel, because a LAN address like `http://192.168.1.20:3000` is not a secure context.

## Load the scanner lazily

To keep the SDK out of the initial bundle and skip server rendering entirely, load the component with `next/dynamic` and `ssr: false`. In the App Router, `ssr: false` is only allowed inside a Client Component, so wrap it:

```tsx
// app/scan/lazy-scanner.tsx
"use client";

import dynamic from "next/dynamic";

const Scanner = dynamic(() => import("./scanner"), {
  ssr: false,
  loading: () => <div style={{ height: 420, background: "#05070a", borderRadius: 12 }} />,
});

export default function LazyScanner() {
  return <Scanner />;
}
```

Then render `<LazyScanner />` from `page.tsx` instead of `<Scanner />`.

## Pages Router

In the Pages Router, pages are rendered on the server and hydrated on the client. The component works as is; use `next/dynamic` with `ssr: false` if you want to skip the server render:

```tsx
// pages/scan.tsx
import dynamic from "next/dynamic";

const Scanner = dynamic(() => import("../components/scanner"), { ssr: false });

export default function ScanPage() {
  return <Scanner />;
}
```

`components/scanner.tsx` is the same component as above (the `"use client"` line is harmless in the Pages Router).

## Self-host the wasm

By default the engine loads from jsDelivr. To serve it from your own domain, copy the files into `public/` on install:

```json
{
  "scripts": {
    "postinstall": "mkdir -p public/qrgen && cp node_modules/qrgen-sdk/dist/wasm/*.wasm public/qrgen/"
  }
}
```

Then configure the engine once in client code, before the first scan. A module-level call in the scanner component works:

```tsx
// app/scan/scanner.tsx
"use client";

import { configure } from "qrgen-sdk";

configure({ wasmBaseUrl: "/qrgen/" });

// ...component as above
```

If your app uses a `basePath`, include it: `configure({ wasmBaseUrl: "/my-base/qrgen/" })`. Add `public/qrgen/` to `.gitignore` if it's generated on install.

## Content Security Policy

If you set a CSP in `next.config.js` headers or middleware, allow `'wasm-unsafe-eval'` in `script-src`, `blob:` in `worker-src` and the wasm origin in `connect-src`. See [Installation](../installation/#content-security-policy).

## Scan uploads on the server

Route handlers run in Node.js, so you can decode uploaded images with `qrgen-sdk/node`. It reads the engine from `node_modules`, with no network access:

```ts
// app/api/scan/route.ts
import { scan, parseContent } from "qrgen-sdk/node";

export const runtime = "nodejs";

export async function POST(request: Request) {
  const form = await request.formData();
  const file = form.get("image");
  if (!(file instanceof Blob)) return Response.json({ error: "Send an image field" }, { status: 400 });

  const barcodes = await scan(new Uint8Array(await file.arrayBuffer()), { symbologies: ["qr", "ean13", "code128"] });
  return Response.json({ barcodes: barcodes.map((b) => ({ ...b, parsed: parseContent(b.data, { symbology: b.symbology }) })) });
}
```

Keep the SDK out of the server bundle so the wasm files stay next to the code that reads them:

```js
// next.config.js
/** @type {import('next').NextConfig} */
module.exports = {
  serverExternalPackages: ["qrgen-sdk", "zxing-wasm"],
};
```

`serverExternalPackages` is the Next.js 15 name; in Next.js 14 use `experimental.serverComponentsExternalPackages`. The server can decode PNG, JPEG, GIF and BMP. More in [Node.js](../nodejs/#serverless).

## Troubleshooting

- **"useRef only works in Client Components"** or similar hook errors: the file that imports `QRGenScanner` is missing `"use client"`.
- **`window is not defined`**: code that calls `BarcodeScanner`, `scanImage` or `navigator` runs during server rendering. Move it into `useEffect` or an event handler.
- **Blank scanner with an `engine-load-failed` error**: a CSP or network filter blocks the wasm download. Self-host it as shown above.

More in [Troubleshooting](../troubleshooting/).


---

# Vue & Nuxt

URL: https://rockyljewell.github.io/QR-GEN/docs/vue/
Group: Web

> Use the QRGenScanner and QRGenBarcode Vue 3 components or QRGenPlugin, handle scan events, render on the client in Nuxt, and configure custom elements.

`qrgen-sdk/vue` provides Vue 3 components that wrap the [web components](../web-components/): `QRGenScanner` for camera scanning and `QRGenBarcode` for rendering barcodes, plus `QRGenPlugin` to register both globally. Requires Vue 3.3 or later.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

## Scan

```vue
<script setup lang="ts">
import { ref } from "vue";
import { QRGenScanner } from "qrgen-sdk/vue";
import type { Barcode } from "qrgen-sdk";

const last = ref<Barcode | null>(null);

function onScan({ barcode }: { barcodes: Barcode[]; barcode: Barcode }) {
  last.value = barcode;
}
</script>

<template>
  <QRGenScanner :symbologies="['qr', 'ean13', 'code128']" mode="continuous" :duplicate-filter="2000" style="height: 420px" @scan="onScan" @error="(e) => console.warn(e.code, e.message)" />
  <p v-if="last">{{ last.symbologyName }}: {{ last.data }}</p>
</template>
```

Camera access requires HTTPS or `http://localhost`.

## Register globally

```ts
// main.ts
import { createApp } from "vue";
import { QRGenPlugin } from "qrgen-sdk/vue";
import App from "./App.vue";

createApp(App).use(QRGenPlugin).mount("#app");
```

`QRGenPlugin` registers `QRGenScanner` and `QRGenBarcode`, so you can use them in any template without importing.

## Props

`QRGenScanner` accepts the same options as the [`<qrgen-scanner>` attributes](../web-components/#attributes-and-properties), in camelCase (or kebab-case in templates):

| Prop | Type | Default |
| --- | --- | --- |
| `symbologies` | `string[] \| string` | all |
| `mode` | `"single" \| "continuous" \| "batch"` | `"continuous"` |
| `duplicateFilter` | `number` | `1000` (`-1` in batch) |
| `beep` | `boolean` | `true` |
| `vibrate` | `boolean` | `true` |
| `camera` | `string` (`"back"`, `"front"` or a `deviceId`) | `"back"` |
| `torch` | `boolean` | `false` |
| `viewfinder` | `"frame" \| "line" \| "none"` | depends on symbologies |
| `scanArea` | `{ x, y, width, height }` | from the viewfinder |
| `maxResults` | `number` | `1` (`20` in batch) |
| `autostart` | `boolean` | `true` |
| `controls` | `"default" \| "none"` | `"default"` |
| `accent` | `string` (hex) | `#5cc9d6` |
| `hint` | `string` | mode-specific |
| `toast` | `boolean` | `true` |
| `tryHarder` | `boolean` | `false` (single/continuous), `true` (batch) |
| `resolution` | `"sd" \| "hd" \| "fhd" \| "4k"` | `"hd"` |

Props you don't set fall back to the element defaults.

## Events

The component emits the element's events with the same `detail` object as the payload:

| Event | Payload |
| --- | --- |
| `@scan` | `{ barcodes: Barcode[], barcode: Barcode }` |
| `@track` | `{ tracked, added, removed }` (`TrackedBarcode[]`) |
| `@select` | `{ barcode: TrackedBarcode \| null, selected: boolean, selection: TrackedBarcode[] }` |
| `@ready` | `{ engine: "worker" \| "main" }` |
| `@statechange` | `{ state: ScannerState }` |
| `@error` | `{ code: QRGenErrorCode, message: string }` |

## Template ref

The component exposes `start`, `stop`, `pause`, `resume`, `setTorch`, `toggleTorch`, `switchCamera`, `setZoom`, `clearSelection`, `selectBarcode(id, selected?)` and `element` (the underlying `<qrgen-scanner>`). In batch mode, `selectBarcode` chooses a tracked result by id and returns `false` for an unknown id. Omit `selected` to toggle it:

```vue
<script setup lang="ts">
import { ref } from "vue";
import { QRGenScanner } from "qrgen-sdk/vue";
import type { QRGenScannerElement } from "qrgen-sdk/elements";

// The members QRGenScanner exposes that this component uses
type ScannerRef = {
  resume(): void;
  toggleTorch(): Promise<boolean>;
  element: QRGenScannerElement | null;
};

const scanner = ref<ScannerRef | null>(null);
const code = ref("");
</script>

<template>
  <QRGenScanner ref="scanner" symbologies="qr" mode="single" controls="none" style="height: 360px" @scan="({ barcode }) => (code = barcode.data)" />
  <p>{{ code }}</p>
  <button @click="scanner?.resume()">Scan again</button>
  <button @click="scanner?.toggleTorch()">Torch</button>
  <button @click="scanner?.element?.clearSelection()">Clear selection</button>
</template>
```

## `QRGenBarcode`

```vue
<script setup lang="ts">
import { QRGenBarcode } from "qrgen-sdk/vue";
</script>

<template>
  <QRGenBarcode value="https://example.com" symbology="qr" ec-level="M" style="width: 160px" />
  <QRGenBarcode value="5901234123457" symbology="ean13" hrt style="width: 240px" />
</template>
```

Props: `value` (required), `symbology` (default `"qr"`), `scale`, `ecLevel`, `foreground`, `background`, `hrt`, `margin` (default `true`), `gs1`, `alt`. For rotation, use the [`<qrgen-barcode>` element](../web-components/#qrgen-barcode) directly with its `rotate` attribute.

## Using the elements directly

You can also use `<qrgen-scanner>` and `<qrgen-barcode>` in templates without the wrapper. Import `qrgen-sdk/elements` once, and tell the Vue compiler that tags starting with `qrgen-` are custom elements, otherwise it warns that it can't resolve them:

```ts
// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith("qrgen-"),
        },
      },
    }),
  ],
});
```

```vue
<script setup lang="ts">
import "qrgen-sdk/elements";
</script>

<template>
  <qrgen-scanner symbologies="qr,ean13" style="height: 420px" @scan="(e: CustomEvent) => console.log(e.detail.barcode.data)" />
</template>
```

You don't need `isCustomElement` when you use the `QRGenScanner` and `QRGenBarcode` components.

## Nuxt

The scanner needs the browser, so render it on the client. Wrap it in `<ClientOnly>`:

```vue
<!-- pages/scan.vue -->
<script setup lang="ts">
import { QRGenScanner } from "qrgen-sdk/vue";

const code = ref("");
</script>

<template>
  <main>
    <ClientOnly>
      <QRGenScanner symbologies="qr" mode="single" style="height: 420px" @scan="({ barcode }) => (code = barcode.data)" />
      <template #fallback>
        <div style="height: 420px; background: #05070a" />
      </template>
    </ClientOnly>
    <p>{{ code }}</p>
  </main>
</template>
```

To register the components globally, add a client-only plugin:

```ts
// plugins/qrgen.client.ts
import { QRGenPlugin } from "qrgen-sdk/vue";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(QRGenPlugin);
});
```

If you use the raw `<qrgen-scanner>` element in Nuxt templates, set the compiler option in `nuxt.config.ts`:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith("qrgen-"),
    },
  },
});
```

To self-host the wasm in Nuxt, copy `node_modules/qrgen-sdk/dist/wasm/*.wasm` into `public/qrgen/` and call `configure({ wasmBaseUrl: "/qrgen/" })` in the client plugin. See [Installation](../installation/#self-host-the-webassembly-engine).


---

# Angular

URL: https://rockyljewell.github.io/QR-GEN/docs/angular/
Group: Web

> Use the <qrgen-scanner> and <qrgen-barcode> custom elements in Angular with CUSTOM_ELEMENTS_SCHEMA, event and property bindings, and zone-aware setup.

Angular supports custom elements natively, so you use QRGen's [web components](../web-components/) directly. There is no wrapper package to install or keep in sync with your Angular version.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

## Standalone component

Import `qrgen-sdk/elements` to register the elements, and add `CUSTOM_ELEMENTS_SCHEMA` so the template compiler accepts the unknown tags and attributes:

```ts
// scanner.component.ts
import { JsonPipe } from "@angular/common";
import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from "@angular/core";
import "qrgen-sdk/elements";
import { parseContent, type Barcode, type ParsedContent, type QRGenErrorCode } from "qrgen-sdk";

type ScanDetail = { barcodes: Barcode[]; barcode: Barcode };
type ErrorDetail = { code: QRGenErrorCode; message: string };

@Component({
  selector: "app-scanner",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <qrgen-scanner
      [symbologies]="symbologies"
      mode="continuous"
      duplicate-filter="2000"
      accent="#dd0031"
      style="display: block; height: 420px"
      (scan)="onScan($event)"
      (error)="onError($event)"
    ></qrgen-scanner>

    @if (result(); as r) {
      <pre>{{ r | json }}</pre>
    }
    @if (error(); as e) {
      <p class="error">{{ e }}</p>
    }
  `,
  imports: [JsonPipe],
})
export class ScannerComponent {
  symbologies = ["qr", "ean13", "code128"];
  result = signal<ParsedContent | null>(null);
  error = signal<string | null>(null);

  onScan(event: Event) {
    const { barcode } = (event as CustomEvent<ScanDetail>).detail;
    this.result.set(parseContent(barcode.data, { symbology: barcode.symbology }));
  }

  onError(event: Event) {
    const { code, message } = (event as CustomEvent<ErrorDetail>).detail;
    this.error.set(`${code}: ${message}`);
  }
}
```

The `@if` block syntax and `viewChild()` below need Angular 17.2 or later; on older versions use `*ngIf` and `@ViewChild`.

Camera access requires HTTPS or `http://localhost`. `ng serve` uses `http://localhost:4200`, which works; to test on a phone, run `ng serve --ssl --host 0.0.0.0`.

## Bindings

- **Attributes** (`mode="single"`, `duplicate-filter="2000"`) pass strings, exactly like HTML.
- **Property bindings** (`[symbologies]="list"`, `[scanArea]="area"`, `[beep]="false"`) pass typed values to the element's properties. The element has properties for `symbologies`, `mode`, `duplicateFilter`, `beep`, `vibrate`, `camera`, `torch`, `viewfinder`, `scanArea`, `maxResults` and `autostart`.
- **Attribute bindings** (`[attr.hint]="hintText"`, `[attr.controls]="'none'"`) for everything else: `controls`, `accent`, `hint`, `toast`, `try-harder`, `resolution`, `worker`.
- **Event bindings**: `(scan)`, `(track)`, `(select)`, `(ready)`, `(statechange)` and `(error)`. `$event` is a `CustomEvent`; the payload is in `detail`. The shapes are in [Web Components](../web-components/#events).

## Control the scanner

Get the element with a template reference and call its methods:

```ts
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, viewChild } from "@angular/core";
import "qrgen-sdk/elements";
import type { QRGenScannerElement } from "qrgen-sdk/elements";

@Component({
  selector: "app-login-scanner",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <qrgen-scanner #scanner symbologies="qr" mode="single" controls="none" style="display: block; height: 360px" (scan)="onScan($event)"></qrgen-scanner>
    <button (click)="scanner.resume()">Scan again</button>
    <button (click)="scanner.toggleTorch()">Torch</button>
  `,
})
export class LoginScannerComponent {
  scannerRef = viewChild.required<ElementRef<QRGenScannerElement>>("scanner");

  onScan(event: Event) {
    const token = (event as CustomEvent<{ barcode: { data: string } }>).detail.barcode.data;
    console.log("token", token);
  }

  stop() {
    this.scannerRef().nativeElement.stop();
  }
}
```

The element stops the camera by itself when Angular removes it from the DOM, so you don't need an `ngOnDestroy` hook.

## Zones and change detection

With zone.js, event bindings like `(scan)` run inside the Angular zone, so change detection runs after each scan and your template updates.

The scanner's internal animation frames also run inside the zone, because the element starts from Angular's rendering. On slow devices you can move that work outside the zone: set `autostart="false"`, start the element with `NgZone.runOutsideAngular()`, and keep your `(scan)` handlers as they are. Handlers registered from the template still run in the zone.

```ts
import { AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, NgZone, inject, viewChild } from "@angular/core";
import "qrgen-sdk/elements";
import type { QRGenScannerElement } from "qrgen-sdk/elements";

@Component({
  selector: "app-fast-scanner",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<qrgen-scanner #scanner autostart="false" style="display: block; height: 420px" (scan)="onScan($event)"></qrgen-scanner>`,
})
export class FastScannerComponent implements AfterViewInit {
  private zone = inject(NgZone);
  private scanner = viewChild.required<ElementRef<QRGenScannerElement>>("scanner");

  ngAfterViewInit() {
    this.zone.runOutsideAngular(() => void this.scanner().nativeElement.start().catch(() => undefined));
  }

  onScan(event: Event) {
    console.log((event as CustomEvent).detail.barcode.data);
  }
}
```

With zoneless change detection (`provideZonelessChangeDetection()`), update a signal in the event handler, as in the first example, and the view updates.

## `<qrgen-barcode>`

```html
<qrgen-barcode [attr.value]="ticketUrl" symbology="qr" ec-level="Q" style="width: 180px"></qrgen-barcode>
```

`value` is also a property, so `[value]="ticketUrl"` works too. All attributes are listed in [Web Components](../web-components/#qrgen-barcode).

## Self-host the wasm

Copy the wasm files into your build with the `assets` option in `angular.json`:

```json
{
  "projects": {
    "app": {
      "architect": {
        "build": {
          "options": {
            "assets": [
              { "glob": "**/*", "input": "public" },
              { "glob": "*.wasm", "input": "node_modules/qrgen-sdk/dist/wasm", "output": "qrgen" }
            ]
          }
        }
      }
    }
  }
}
```

Then configure the engine in `main.ts`, before bootstrapping:

```ts
// main.ts
import { bootstrapApplication } from "@angular/platform-browser";
import { configure } from "qrgen-sdk";
import { AppComponent } from "./app/app.component";

configure({ wasmBaseUrl: "qrgen/" });

bootstrapApplication(AppComponent).catch((err) => console.error(err));
```

A relative `wasmBaseUrl` resolves against the document's `<base href>`, so it works when the app is deployed under a sub-path.

## Server-side rendering

Importing `qrgen-sdk/elements` is safe during Angular SSR: registration is skipped on the server and the tag is rendered as is. The element starts in the browser after hydration.


---

# Svelte & SvelteKit

URL: https://rockyljewell.github.io/QR-GEN/docs/svelte/
Group: Web

> Use the <qrgen-scanner> element in Svelte 5 and Svelte 4, handle scan events, and load the SDK on the client in SvelteKit.

Svelte renders custom elements natively, so you use QRGen's [web components](../web-components/) directly. The examples below cover Svelte 5 (runes) and Svelte 4, and loading the SDK on the client in SvelteKit.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

## Svelte 5

Event attributes on custom elements use the lowercase event name: `onscan`, `ontrack`, `onselect`, `onready`, `onstatechange`, `onerror`.

```svelte
<script lang="ts">
  import "qrgen-sdk/elements";
  import type { Barcode } from "qrgen-sdk";

  let last = $state<Barcode | null>(null);

  function handleScan(event: Event) {
    last = (event as CustomEvent<{ barcode: Barcode }>).detail.barcode;
  }
</script>

<qrgen-scanner symbologies="qr,ean13,code128" duplicate-filter="2000" style="height: 420px" onscan={handleScan}></qrgen-scanner>

{#if last}
  <p>{last.symbologyName}: {last.data}</p>
{/if}
```

## Svelte 4

Use `on:` directives:

```svelte
<script lang="ts">
  import "qrgen-sdk/elements";
  import type { Barcode } from "qrgen-sdk";

  let last: Barcode | null = null;
</script>

<qrgen-scanner symbologies="qr,ean13" style="height: 420px" on:scan={(e) => (last = e.detail.barcode)}></qrgen-scanner>

{#if last}
  <p>{last.data}</p>
{/if}
```

## Pass typed values

Svelte sets properties on custom elements when the element has one with that name, so you can pass arrays and objects directly:

```svelte
<script lang="ts">
  import "qrgen-sdk/elements";

  let symbologies = $state(["qr", "data-matrix"]);
  const scanArea = { x: 0.1, y: 0.3, width: 0.8, height: 0.4 };
</script>

<qrgen-scanner {symbologies} {scanArea} beep={false} style="height: 420px"></qrgen-scanner>
```

Pass booleans as expressions (`beep={false}`), not as strings. The element has properties for `symbologies`, `mode`, `duplicateFilter`, `beep`, `vibrate`, `camera`, `torch`, `viewfinder`, `scanArea`, `maxResults` and `autostart`; the other options (`controls`, `accent`, `hint`, `toast`, `try-harder`, `resolution`, `worker`) are plain attributes.

## Control the scanner

Bind the element and call its methods:

```svelte
<script lang="ts">
  import "qrgen-sdk/elements";
  import type { QRGenScannerElement } from "qrgen-sdk/elements";

  let scanner = $state<QRGenScannerElement>();
  let code = $state("");
</script>

<qrgen-scanner bind:this={scanner} symbologies="qr" mode="single" controls="none" style="height: 360px" onscan={(e: Event) => (code = (e as CustomEvent).detail.barcode.data)}></qrgen-scanner>

<p>{code}</p>
<button onclick={() => scanner?.resume()}>Scan again</button>
<button onclick={() => scanner?.toggleTorch()}>Torch</button>
```

Removing the element (for example with `{#if}`) stops the camera automatically.

## SvelteKit

Importing `qrgen-sdk/elements` during server rendering is safe: registration is skipped on the server and the tag renders as plain HTML. The element starts when the page hydrates. Camera access requires HTTPS or `http://localhost`.

To keep the SDK out of the server bundle and load it only when the page is shown, import it in `onMount`:

```svelte
<!-- src/routes/scan/+page.svelte -->
<script lang="ts">
  import { onMount } from "svelte";
  import type { Barcode } from "qrgen-sdk";

  let ready = $state(false);
  let last = $state<Barcode | null>(null);

  onMount(async () => {
    const { configure } = await import("qrgen-sdk");
    await import("qrgen-sdk/elements");
    configure({ wasmBaseUrl: "/qrgen/" }); // optional: self-hosted wasm in static/qrgen/
    ready = true;
  });
</script>

{#if ready}
  <qrgen-scanner symbologies="qr,ean13" style="height: 420px" onscan={(e: Event) => (last = (e as CustomEvent).detail.barcode)}></qrgen-scanner>
{:else}
  <div style="height: 420px; background: #05070a"></div>
{/if}

{#if last}<p>{last.data}</p>{/if}
```

Remove the `configure()` call to load the engine from jsDelivr instead. To self-host, copy `node_modules/qrgen-sdk/dist/wasm/*.wasm` into `static/qrgen/`. You can also disable server rendering for the route with `export const ssr = false;` in `+page.ts`.

## TypeScript

If `svelte-check` reports unknown attributes or events on the QRGen elements, declare the tags in `src/app.d.ts`. This types `bind:this` as the element class and accepts any attribute:

```ts
// src/app.d.ts
import type { HTMLAttributes } from "svelte/elements";
import type { QRGenBarcodeElement, QRGenScannerElement } from "qrgen-sdk/elements";

declare module "svelte/elements" {
  export interface SvelteHTMLElements {
    "qrgen-scanner": HTMLAttributes<QRGenScannerElement> & Record<string, unknown>;
    "qrgen-barcode": HTMLAttributes<QRGenBarcodeElement> & Record<string, unknown>;
  }
}

export {};
```


---

# iOS & macOS (Swift)

URL: https://rockyljewell.github.io/QR-GEN/docs/ios/
Group: Mobile & desktop

> Scan barcodes and QR codes in iOS and macOS apps with QRGenKit: SwiftUI and UIKit scanner views on AVFoundation and Apple Vision, image scanning, generation and parsers.

> **Note:** This page is generated from [`packages/ios/README.md`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/ios/README.md). Source code: [`packages/ios`](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/ios).

Native Swift package of **QRGen**, the open-source (Apache-2.0) barcode, QR and ID scanning SDK.

- **Camera scanning** with AVFoundation + Apple Vision: single, continuous and batch (multi-code tracking) modes,
  duplicate filter, region of interest, torch, zoom, camera switching, beep and haptics.
- **Ready-made UI**: `QRGenScannerViewController` (UIKit) and `QRGenScannerView` (SwiftUI) with a dark camera
  screen, corner-bracket or laser-line viewfinder, animated highlights on detected codes, torch and close
  buttons and a success toast.
- **Still images**: `QRGen.scan(image:)` for `CGImage`, `UIImage`, `NSImage`, image data and files.
- **Generation**: QR, PDF417, Aztec and Code 128 with Core Image (crisp nearest-neighbour scaling); everything
  else through the QRGen REST API.
- **Parsers** (pure Swift, also on Linux): GS1 element strings and Digital Link, AAMVA driver licenses / ID cards,
  and QR payloads (URL, Wi-Fi, vCard, MECARD, e-mail, SMS, geo, calendar events, EPC/SEPA, bitcoin, ethereum,
  UPI, GTIN check digits).

Results, symbology ids, options and error codes follow the cross-platform contract in
[`docs/SPEC.md`](https://github.com/Rockyljewell/QR-GEN/blob/main/docs/SPEC.md), so code and JSON are interchangeable with the JavaScript, Python,
Android, React Native, Flutter and .NET packages.

## Requirements

- iOS 15+ or macOS 12+ (the scanner UI is iOS / iPadOS / Mac Catalyst; the engine, image scanning,
  generation and parsers also work on macOS)
- Xcode 15+ (Swift 5.9+)

## Installation

### Swift Package Manager

In Xcode: **File > Add Package Dependencies...**, enter

```
https://github.com/Rockyljewell/QR-GEN
```

and add the **QRGenKit** library to your app target. The package manifest lives at the repository root.

In a `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/Rockyljewell/QR-GEN", from: "1.0.0"),
    // or, before a release tag exists: .package(url: "https://github.com/Rockyljewell/QR-GEN", branch: "main"),
],
targets: [
    .target(name: "MyApp", dependencies: [.product(name: "QRGenKit", package: "QR-GEN")]),
]
```

### CocoaPods

```ruby
pod 'QRGenKit', :git => 'https://github.com/Rockyljewell/QR-GEN.git'
```

### Camera permission

Add a camera usage description to your app's Info.plist (Xcode: target > Info > "Privacy - Camera Usage
Description"):

```xml
<key>NSCameraUsageDescription</key>
<string>The camera is used to scan barcodes and QR codes.</string>
```

The scanner asks for access the first time it starts. If access is denied it reports
`QRGenError.cameraPermissionDenied` (code `camera-permission-denied`) and the built-in UI shows an
"Open Settings" prompt. On macOS, sandboxed apps also need the **Camera** entitlement
(`com.apple.security.device.camera`).

## Quick start: SwiftUI

```swift
import QRGenKit
import SwiftUI

struct ScanScreen: View {
    @State private var isScanning = false
    @State private var code: String?

    var body: some View {
        Button("Scan") { isScanning = true }
            .fullScreenCover(isPresented: $isScanning) {
                QRGenScannerView(options: .init(symbologies: ["qr", "ean13"], mode: .single)) { barcodes in
                    code = barcodes.first?.data
                    isScanning = false
                }
                .onError { error in print(error.code, error.message) }
                .onClose { isScanning = false }
                .ignoresSafeArea()
            }
    }
}
```

Modifiers: `.onError { }`, `.onTrack { }` (batch mode), `.onClose { }` (shows the close button),
`.scannerAccentColor(_:)` (`Color` or `UIColor`, default teal `#2EC1CE`) and
`.scannerControls(torchButton:toast:)`. Apply them before generic modifiers such as `.ignoresSafeArea()`.
Changing `options` while the view is on screen updates the running scanner.

## Quick start: UIKit

```swift
import QRGenKit
import UIKit

final class HomeViewController: UIViewController {
    @objc func scan() {
        let scanner = QRGenScannerViewController(
            options: ScannerOptions(symbologies: ["qr", "ean13", "code128"], mode: .single),
            accentColor: QRGenScannerViewController.defaultAccentColor
        )
        scanner.onScan = { [weak scanner] barcodes in
            print(barcodes[0].symbologyName, barcodes[0].data)
            scanner?.dismiss(animated: true)
        }
        scanner.onError = { error in print(error.code) }
        present(scanner, animated: true)   // full screen; the close button dismisses it
    }
}
```

`QRGenScannerViewController` starts the camera in `viewWillAppear` and stops it in `viewDidDisappear`. After a
single-mode scan the preview keeps running; call `resumeScanning()` to scan again. `scanner.scanner` is the
underlying `BarcodeScanner` (torch, zoom, pause, delegate).

## Headless engine: `BarcodeScanner`

Use the engine directly with your own UI (iOS and macOS):

```swift
let scanner = BarcodeScanner(options: ScannerOptions(symbologies: ["2d"], mode: .continuous))
scanner.onReady = { print("camera running") }
scanner.onScan = { barcodes in print(barcodes.map(\.data)) }
scanner.onError = { error in print(error.code) }

let preview = AVCaptureVideoPreviewLayer(session: scanner.captureSession)
preview.videoGravity = .resizeAspectFill
preview.frame = view.bounds
view.layer.addSublayer(preview)

scanner.start()          // asks for camera permission if needed
scanner.setTorch(true)
scanner.setZoom(2)       // 1 = natural field of view, < 1 = ultra-wide when available
scanner.switchCamera()   // back <-> front
scanner.pause(); scanner.resume(); scanner.stop()
```

You can also set `scanner.delegate` to a `BarcodeScannerDelegate` (all methods optional, main actor):
`barcodeScannerDidBecomeReady`, `barcodeScanner(_:didScan:)`, `barcodeScanner(_:didTrack:)`,
`barcodeScanner(_:didFailWithError:)`. Closures and delegate are both called. `onDetections` receives every
detection of every processed frame (before the duplicate filter), which is handy for overlays.

**Coordinates.** For camera frames, `Barcode.location` is in pixels of the camera buffer in the sensor's
native orientation (landscape on iPhone), exactly as Vision saw it. Map it onto a preview layer with

```swift
let corners: [CGPoint] = previewLayer.layerPoints(for: barcode)   // handles aspect fill, rotation, mirroring
```

To restrict scanning to part of your preview, pass a capture-device rect:
`scanner.setRegionOfInterest(previewLayer.metadataOutputRectConverted(fromLayerRect: rectInLayer))`.
(`QRGenScannerViewController` does this for you from `options.scanArea`.)

## Scanning still images

```swift
let barcodes = try await QRGen.scan(image: cgImage, symbologies: ["qr", "ean13"])
let fromUIImage = try await QRGen.scan(image: uiImage)            // honours imageOrientation
let fromFile = try await QRGen.scan(contentsOf: fileURL)          // PNG, JPEG, HEIC...; honours EXIF orientation
let fromData = try await QRGen.scan(imageData: data)
```

For images, `location` is in pixels of the upright image.

## Generating codes

```swift
let cgImage = try QRGen.generate("https://example.com")                          // QR, scale 8, EC level M
let uiImage = try QRGen.generateImage("HELLO-123", symbology: .code128, scale: 4) // UIImage / NSImage
let png = try QRGen.generatePNG("PDF417 payload", symbology: .pdf417)
let aztec = try QRGen.generate("Ticket 42", symbology: .aztec, ecLevel: "33")     // Aztec EC percentage
```

Core Image can render **qr, pdf417, aztec and code128** (`QRGen.writableSymbologies()`). Every other symbology
throws `QRGenError.unsupported`. For those, run the QRGen REST server (`qrgen serve` or the Docker image, see
SPEC section 6) and call `GET /v1/generate`, for example:

```swift
let server = URL(string: "http://localhost:8080")!   // wherever `qrgen serve` listens
let ean = try await QRGen.generateRemotely("5901234123457", symbology: .ean13, server: server, format: .png)
```

## Parsers

Pure Swift, no camera needed, never throw (SPEC section 3):

```swift
QRGen.parseGS1("(01)09501101530003(17)250101(10)ABC123")
// values ["01": "09501101530003", "17": "250101", "10": "ABC123"], element("17")?.date == "2025-01-01"
QRGen.parseGS1("]C1010950110153000310ABC123\u{1D}21XYZ")                       // raw with GS separators
QRGen.parseGS1("https://id.gs1.org/01/09501101530003/10/ABC123?17=250101")    // GS1 Digital Link

let id = QRGen.parseAAMVA(pdf417Text)   // AAMVAResult: names, dates (ISO), address, age, isExpired, isUnder21, fields

switch QRGen.parseContent(barcode.data, symbology: barcode.symbology) {   // or barcode.parsed
case .wifi(let wifi): print(wifi.ssid, wifi.password ?? "", wifi.security)
case .url(let url): print(url)
case .contact(let card): print(card.name ?? "", card.phones)
case .product(let product): print(product.gtin, product.checksumValid)
case .aamva(let license): print(license.fullName)
default: break
}
```

`ParsedContent` cases: `url`, `gs1DigitalLink`, `email`, `phone`, `sms`, `wifi`, `geo`, `contact`, `event`,
`payment`, `product`, `gs1`, `aamva`, `text`. `.type` gives the SPEC type string and `toJSON()` the
cross-platform JSON (`{"type":"wifi","ssid":...}`).

## Batch mode

Batch mode tracks many codes at once. Tracks keep a stable `id` while a code stays in view (matched by symbology
+ data, then by bounding-box overlap) and are dropped after 500 ms without a sighting.

```swift
let scanner = BarcodeScanner(options: ScannerOptions(symbologies: ["retail", "code128"], mode: .batch))
scanner.onTrack = { tracked in
    for code in tracked {
        print(code.id, code.data, code.count, code.lastSeen - code.firstSeen)   // Barcode fields via dynamic member lookup
    }
}
scanner.onScan = { newCodes in print("new:", newCodes.map(\.data)) }        // duplicate filter applies
```

`QRGenScannerView(...).onTrack { }` and `QRGenScannerViewController.onTrack` work the same way and draw a
highlight on every tracked code.

## Options (`ScannerOptions`)

| option | type | default | meaning |
| --- | --- | --- | --- |
| `symbologies` | `[String]` (or `[Symbology]`) | `["all"]` | ids, aliases or groups (`all`, `1d`/`linear`, `2d`/`matrix`, `retail`, `industrial`, `gs1`) |
| `mode` | `.single` / `.continuous` / `.batch` | `.continuous` | `single` pauses after the first scan; `batch` tracks many codes |
| `duplicateFilter` | `Int` (ms) | `1000` | same symbology + data is not reported again within the window; `0` = every frame, `-1` = once per session |
| `beep` | `Bool` | `true` | system sound 1057 on scan |
| `vibrate` | `Bool` | `true` | success haptic on scan |
| `camera` | `.back` / `.front` / `.device(id:)` | `.back` | camera selection (`AVCaptureDevice.uniqueID` for `.device`) |
| `torch` | `Bool` | `false` | turn the flashlight on at start |
| `viewfinder` | `.frame` / `.line` / `.none` / `nil` | `nil` = `.frame`, or `.line` for linear-only sets | overlay style |
| `scanArea` | `CGRect?`, normalized 0...1, origin top-left | `nil` (full visible frame) | region of interest |
| `maxResults` | `Int?` | `nil` = 1 (20 in batch) | codes per frame (closest to the centre first) |

Errors (`QRGenError`, `.code`): `camera-permission-denied`, `camera-not-found`, `camera-in-use`,
`insecure-context` (web only), `engine-load-failed`, `unsupported`, `unknown`.

## Symbology support on Apple platforms

`QRGen.supportedSymbologies()` returns what the running OS can read. With Apple Vision (iOS 15+ / macOS 12+):

| Read | ids |
| --- | --- |
| yes | `qr`, `micro-qr`, `data-matrix`, `aztec`, `pdf417`, `micro-pdf417`, `ean13`, `ean8`, `upca`, `upce`, `isbn`, `code128`, `code39`, `code93`, `codabar`, `itf`, `itf14`, `databar`, `databar-expanded`, `databar-limited` |
| no (skipped silently) | `rmqr`, `maxicode`, `code32`, `pzn`, `telepen`, `dx-film-edge` |

Vision reports UPC-A as EAN-13 with a leading `0` and ISBN as EAN-13 with a `978`/`979` prefix. When you ask for
`upca` or `isbn`, QRGenKit reports those ids (UPC-A data is shortened to 12 digits); otherwise such codes are
reported as `ean13`. GS1 DataBar data (and, on iOS 17+, any code Vision flags as a GS1 carrier) is converted to
the human readable `(01)...` form with `isGS1 == true`. `rawBytes` holds Vision's raw payload on iOS 17+ and the
UTF-8 of the text before that.

## Example app

[`Example/`](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/ios/Example) contains a minimal SwiftUI app (`QRGenExampleApp.swift`, `ContentView.swift`): a scan
button, a full-screen single-mode scanner and a result sheet with the parsed content and JSON. There is no
Xcode project; to run it:

1. In Xcode, **File > New > Project... > iOS > App** (Interface: SwiftUI, Language: Swift).
2. Delete the generated `ContentView.swift` and `<Name>App.swift`, then drag both files from `Example/` into
   the project (tick "Copy items if needed").
3. **File > Add Package Dependencies...**, enter `https://github.com/Rockyljewell/QR-GEN` (or **Add Local...**
   and pick your checkout of this repository), and add **QRGenKit** to the app target.
4. Target > Info: add **Privacy - Camera Usage Description** with any text.
5. Run on a real iPhone or iPad (the simulator has no camera).

## Tests

```
swift test
```

from the repository root. The parser, symbology, JSON and tracker tests are platform independent and also run on
Linux; the camera, Vision, Core Image and UIKit code is compiled only on Apple platforms.

## Status

What has and has not been verified for this release, stated plainly:

- **Compiled and tested:** the platform-independent code (`Symbology` and `resolve`, `Barcode` /
  `TrackedBarcode` / `ParsedContent` JSON, `ScannerOptions`, `QRGenError`, the GS1, AAMVA and content parsers,
  the duplicate filter and the batch tracker) was built and tested on **Linux with Swift 5.10.1**:
  `swift build` and `swift test` pass (39 XCTest cases, including the GS1 and AAMVA test vectors from the SPEC),
  with no compiler warnings.
- **Written, syntax-checked only:** the Apple-only files (`BarcodeScanner`, `VisionBarcodeMapper`,
  `ImageScanner`, `Generator`, `Feedback`, `QRGenScannerViewController`, `QRGenScannerView`) and the example
  app. The Linux compiler parses them (inactive `#if` blocks are syntax-checked), but they have **not yet been
  type-checked against the iOS / macOS SDKs, built in Xcode, or run on a device**. `pod lib lint` has not been
  run either.
- **Needs on-device verification:** camera start / permission flow, highlight placement (especially with the
  front camera and in landscape), region-of-interest mapping, torch and zoom on multi-camera iPhones, and batch
  tracking performance.

Please open an issue or a pull request if something does not build with your Xcode version.

## License

Apache-2.0, see [LICENSE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/ios/LICENSE) and [NOTICE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/ios/NOTICE).

Created by [Rockyljewell](https://github.com/Rockyljewell).


---

# Android (Kotlin)

URL: https://rockyljewell.github.io/QR-GEN/docs/android/
Group: Mobile & desktop

> Scan barcodes and QR codes in Android apps with QRGen: a CameraX + ML Kit scanner view, a Jetpack Compose component, image scanning, generation and parsers.

> **Note:** This page is generated from [`packages/android/README.md`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/android/README.md). Source code: [`packages/android`](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/android).

Native Android SDK for [QRGen](https://github.com/Rockyljewell/QR-GEN), the open-source (Apache-2.0)
barcode, QR and ID scanning SDK. It follows the cross-platform contract in
[`docs/SPEC.md`](https://github.com/Rockyljewell/QR-GEN/blob/main/docs/SPEC.md): the same symbology ids, result shape, parsers, scanner
options and error codes as every other QRGen platform.

| Module | Artifact | What it is |
| --- | --- | --- |
| `qrgen-core` | `dev.qrgen:qrgen-core` | Pure Kotlin/JVM (no Android): symbologies, `Barcode` model + JSON, `ScannerOptions`, duplicate filter, batch tracker, GS1 / AAMVA / content parsers, generator (ZXing). Works on servers and desktop too. |
| `qrgen-android` | `dev.qrgen:qrgen-android` | CameraX + ML Kit scanner (`QRGenScanner`), drop-in `QRGenScannerView`, still-image scanning, beep/haptics, `Bitmap` rendering. Depends on `qrgen-core` (`api`). |
| `qrgen-compose` | `dev.qrgen:qrgen-compose` | Jetpack Compose `QRGenScanner(...)` composable. Depends on `qrgen-android` (`api`). |
| `sample` | not published | Small Compose app using all of the above. |

Requirements: minSdk 24, compileSdk 35+, Java 17, Kotlin 2.x.

## Installation

### JitPack

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}
```

```kotlin
// app/build.gradle.kts
dependencies {
    implementation("com.github.Rockyljewell.QR-GEN:qrgen-android:<tag>")   // View / controller API
    implementation("com.github.Rockyljewell.QR-GEN:qrgen-compose:<tag>")   // + Compose (optional)
    // or everything at once: implementation("com.github.Rockyljewell:QR-GEN:<tag>")
    // or only the JVM core (parsers, generator): "com.github.Rockyljewell.QR-GEN:qrgen-core:<tag>"
}
```

`<tag>` is a git tag of this repository (for example `1.0.0`), a commit hash, or
`main-SNAPSHOT`. JitPack builds from the repository root using [`/jitpack.yml`](https://github.com/Rockyljewell/QR-GEN/blob/main/jitpack.yml),
which runs `./gradlew publishToMavenLocal` in `packages/android`. On JitPack the build publishes
under the group `com.github.Rockyljewell.QR-GEN` (outside JitPack the group is `dev.qrgen`).

### Local build (`includeBuild`)

Clone the repository next to your app and include the Gradle build. Gradle substitutes
`dev.qrgen:*` with the local projects automatically.

```kotlin
// your app's settings.gradle.kts
includeBuild("../QR-GEN/packages/android")
```

```kotlin
// app/build.gradle.kts
dependencies {
    implementation("dev.qrgen:qrgen-android:1.0.0")
    implementation("dev.qrgen:qrgen-compose:1.0.0")
}
```

The Android modules are only part of that build when an Android SDK is found: set
`ANDROID_HOME`, or put `sdk.dir=...` in `packages/android/local.properties` (Android Studio
writes it the first time you open that folder). Without an SDK only `qrgen-core` is built.

Alternatively publish to `~/.m2` and use `mavenLocal()`:

```bash
cd packages/android && ./gradlew publishToMavenLocal
```

## Camera permission

`qrgen-android` merges `CAMERA` and `VIBRATE` into your manifest (with
`uses-feature ... android:required="false"`), so you do not need to declare them. `CAMERA` is a
runtime permission and must be requested before scanning:

```kotlin
class ScanActivity : AppCompatActivity() {
    private val requestCamera = registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
        if (granted) scannerView.start() else showPermissionRationale()
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        if (!QRGen.hasCameraPermission(this)) requestCamera.launch(QRGen.CAMERA_PERMISSION)
    }
}
```

If the permission is missing when the scanner starts, `onError` receives
`camera-permission-denied`; call `start()` again once it is granted.

## Quick start: Views

```xml
<!-- res/layout/activity_scan.xml -->
<dev.qrgen.android.QRGenScannerView xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/scanner"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:qrgen_symbologies="qr,retail"
    app:qrgen_mode="continuous"
    app:qrgen_accentColor="#2EC1CE" />
```

```kotlin
class ScanActivity : AppCompatActivity() {
    private lateinit var scannerView: QRGenScannerView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_scan)
        scannerView = findViewById(R.id.scanner)
        scannerView.options = ScannerOptions(
            symbologies = Symbology.resolve("qr", "retail"),
            duplicateFilter = 1500,
        )
        scannerView
            .onScan { barcodes -> Log.i("QRGen", barcodes.first().toJson()) }
            .onError { error -> Log.w("QRGen", "${error.code.id}: ${error.message}") }
        scannerView.bind(this) // camera follows the Activity lifecycle
    }
}
```

All XML attributes are optional: `qrgen_accentColor`, `qrgen_viewfinder` (`auto|frame|line|none`),
`qrgen_symbologies`, `qrgen_mode` (`single|continuous|batch`), `qrgen_beep`, `qrgen_vibrate`,
`qrgen_showToast`, `qrgen_showHighlights`, `qrgen_dimBackground`.

The view draws a rounded corner-bracket viewfinder (or an aiming line when only 1D
symbologies are requested), outlines detected codes (frame coordinates mapped onto the
`FILL_CENTER` preview, front camera mirrored), and a success pill with the scanned text.

### Your own UI: `QRGenScanner`

`QRGenScanner` is the controller behind the view. Give it any `PreviewView` (or none, for
headless analysis):

```kotlin
val scanner = QRGenScanner(context, ScannerOptions(mode = ScannerOptions.Mode.SINGLE))
    .onScan { barcodes -> handle(barcodes.first()) }
    .onError { error -> show(error.message) }
    .onReady { torchButton.isVisible = true }
scanner.bind(viewLifecycleOwner, binding.previewView)

scanner.setTorch(true)      // false if the camera has no flash
scanner.switchCamera()
scanner.setZoomRatio(2f)
scanner.pause(); scanner.resume()
scanner.stop(); scanner.start()
```

Threading and lifecycle: call everything on the main thread; listeners are delivered on the
main thread. Frames are analysed on one background thread with CameraX
`STRATEGY_KEEP_ONLY_LATEST`; every `ImageProxy` is closed. When the bound lifecycle is
destroyed the scanner releases itself (camera, ML Kit client, executor, tone generator); call
`release()` to do it earlier.

## Quick start: Compose

```kotlin
@Composable
fun ScanScreen() {
    val context = LocalContext.current
    var granted by remember { mutableStateOf(QRGen.hasCameraPermission(context)) }
    val permission = rememberLauncherForActivityResult(ActivityResultContracts.RequestPermission()) { granted = it }
    LaunchedEffect(Unit) { if (!granted) permission.launch(QRGen.CAMERA_PERMISSION) }

    var result by remember { mutableStateOf<String?>(null) }
    val state = rememberQRGenScannerState()

    if (granted) {
        Box(Modifier.fillMaxSize()) {
            QRGenScanner(
                options = ScannerOptions(symbologies = Symbology.resolve("qr", "retail")),
                onScan = { barcodes -> result = barcodes.first().data },
                onError = { error -> result = "${error.code.id}: ${error.message}" },
                modifier = Modifier.fillMaxSize(),
                state = state,
            )
            TextButton(onClick = { state.setTorch(!state.isTorchOn) }, Modifier.align(Alignment.TopEnd)) {
                Text(if (state.isTorchOn) "Torch off" else "Torch on")
            }
            result?.let { Text(it, Modifier.align(Alignment.BottomCenter).padding(24.dp)) }
        }
    }
}
```

Options passed to the composable are applied live. `rememberQRGenScannerState()` exposes
`setTorch`, `pause`, `resume`, `switchCamera`, `setZoomRatio` and the underlying `scanner`.
The full example app is in [`sample/`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/android/sample/src/main/kotlin/dev/qrgen/sample/MainActivity.kt).

## Scanning images

```kotlin
// From a Bitmap
val barcodes: List<Barcode> = QRGen.scanImage(context, bitmap, Symbology.resolve("qr", "pdf417"))

// From a gallery pick / content URI (EXIF rotation applied)
val pick = registerForActivityResult(ActivityResultContracts.PickVisualMedia()) { uri ->
    if (uri != null) lifecycleScope.launch {
        val codes = QRGen.scanImage(this@MainActivity, uri)
        codes.forEach { Log.i("QRGen", "${it.symbology.id}: ${it.data}") }
    }
}
```

Java: `QRGen.scanImageAsync(context, bitmap, (barcodes, error) -> { ... })`.

## Generating codes

```kotlin
val code = Generator.generate("https://rockyljewell.github.io/QR-GEN/", Symbology.QR, GenerateOptions(ecLevel = "Q"))
imageView.setImageBitmap(code.toBitmap(scale = 10))  // Android
val svg: String = code.toSvg()                         // any JVM
val png: ByteArray = code.toPng(scale = 8)             // any JVM, no java.awt needed
val grid: Array<BooleanArray> = code.toBooleanGrid()   // or code.toBitMatrix() (ZXing)

// GS1-128 / GS1 DataMatrix / GS1 QR from HRI
Generator.generate("(01)09501101530003(17)250101(10)ABC123", Symbology.CODE128, GenerateOptions(gs1 = true, hrt = true))

// One-liners
QRGen.generateBitmap("hello", Symbology.AZTEC)
generateSvg("5901234123457", Symbology.EAN13)
```

Writable: `qr`, `data-matrix`, `aztec`, `pdf417`, `code128`, `code39`, `code93`, `codabar`,
`ean13`, `ean8`, `upca`, `upce`, `itf`, `itf14`, `isbn` (retail codes accept the number with or
without its check digit). Other ids throw `UnsupportedSymbologyException` (code `unsupported`);
use the QRGen REST API for them. `GenerateOptions`: `ecLevel` (QR `L/M/Q/H`, Aztec percent or
`L/M/Q/H`, PDF417 `0-8` or `L/M/Q/H`), `margin`, `quietZone`, `gs1`, `barHeight`, `scale`,
`foreground`, `background` (`transparent` allowed), `hrt`, `charset`.

## Parsers

Pure functions from `qrgen-core` (SPEC §3). They never throw.

```kotlin
when (val c = barcode.parse()) {            // or ContentParser.parse(text) / parseContent(text)
    is ParsedContent.Url -> open(c.url)
    is ParsedContent.Wifi -> connect(c.ssid, c.password, c.security)
    is ParsedContent.Contact -> addContact(c.name, c.phones, c.emails)
    is ParsedContent.Payment -> pay(c.scheme, c.iban ?: c.address, c.amount, c.currency)
    is ParsedContent.Product -> lookup(c.gtin)          // 14-digit GTIN, checksumValid
    is ParsedContent.Gs1 -> println(c.gs1.values)        // { "01": ..., "17": ... }
    is ParsedContent.Aamva -> verifyAge(c.aamva.isUnder21)
    else -> println(c.toJson())
}

val gs1 = GS1.parse("(01)09501101530003(17)250101(10)ABC123")!!
gs1.values            // {01=09501101530003, 17=250101, 10=ABC123}
gs1.element("17")?.date   // "2025-01-01"
gs1.element("17")?.title  // "USE BY or EXPIRY"
GS1.parse("https://id.gs1.org/01/09501101530003/10/ABC123?17=250101")  // Digital Link
GS1.parse("]C10109501101530003" + "10ABC123" + GS1.GS + "17250101")    // raw with GS

val id = AAMVA.parse(pdf417Text)!!   // AAMVA.parse(text, today = CalendarDate(2025, 6, 1)) in tests
id.fullName; id.dateOfBirth; id.expiryDate; id.age; id.isExpired; id.isUnder21; id.fields["DAQ"]
```

Content types: `url`, `gs1-digital-link`, `email` (`mailto:`, `MATMSG:`), `phone`, `sms`
(`sms:`, `smsto:`), `wifi` (backslash escapes), `geo`, `contact` (vCard 2.1/3.0/4.0, MECARD),
`event` (VEVENT), `payment` (EPC "BCD", `bitcoin:`, `ethereum:`, `upi://pay`, other crypto),
`product` (GTIN check digit), `gs1`, `aamva`, `text`.

GS1 covers the AIs listed in SPEC and more (00–03, 10–22, 235, 240–243, 250–255, 30, all
310n–369n, 37, 390n–395n, 400–403, 410–417, 420–427, 4300–4326, 7001–7259, 8001–8200, 90–99),
with fixed/variable lengths, HRI input, GS input with `]C1`/`]d2`/`]Q3`/`]e0`/`]J1` prefixes,
Digital Link URLs on any domain, dates as ISO (day `00` = last day of month, GS1 century rule)
and `number` for decimal AIs. AAMVA handles versions 1–10, wrong subfile offsets, legacy
`DAA` names, `MMDDCCYY` (USA) vs `CCYYMMDD` (Canada, version 1) dates.

Every model has `toMap()` / `toJson()` producing the SPEC JSON shapes (useful for bridges).

## Batch mode

```kotlin
scannerView.options = ScannerOptions(mode = ScannerOptions.Mode.BATCH)   // maxResults defaults to 20
scannerView
    .onTrack { tracked -> counter.text = "${tracked.size} in view" }     // every frame
    .onScan { newCodes -> inventory += newCodes.map { it.data } }        // new tracks only
```

`BarcodeTracker` matches detections across frames by symbology + data, then by box overlap
(absorbing misreads), gives each track a stable `id` with `firstSeen`, `lastSeen` and `count`,
and drops tracks unseen for 500 ms. `TrackedBarcode.toJson()` is `Barcode & { id, firstSeen,
lastSeen, count }`. Both `BarcodeTracker` and `DuplicateFilter` are plain Kotlin classes you
can use with any engine.

## Options

`ScannerOptions` (SPEC §4). Kotlin: named arguments / `copy`; Java: `ScannerOptions.builder()`;
bridges: `ScannerOptions.fromMap(map)`.

| Option | Type | Default | Meaning |
| --- | --- | --- | --- |
| `symbologies` | `Set<Symbology>` | all | `Symbology.resolve("qr", "retail", ...)`; ids that Android cannot read are skipped (`QRGen.supportedSymbologies()`) |
| `mode` | `SINGLE` / `CONTINUOUS` / `BATCH` | `CONTINUOUS` | `SINGLE` pauses analysis after the first scan (`resume()` to scan again) |
| `duplicateFilter` | `Long` ms | `1000` | same symbology+data is not reported again within the window after a report; `0` = every frame, `-1` = once per session (`start()` begins a session) |
| `beep` | `Boolean` | `true` | short tone (skipped in silent/vibrate ringer mode) |
| `vibrate` | `Boolean` | `true` | haptic click |
| `camera` | `BACK` / `FRONT` | `BACK` | camera facing |
| `cameraId` | `String?` | `null` | a specific Camera2 id; overrides `camera` |
| `torch` | `Boolean` | `false` | flashlight |
| `viewfinder` | `FRAME` / `LINE` / `NONE` / `null` | `null` | `null` = `LINE` when every symbology is 1D, else `FRAME` |
| `scanArea` | `ScanArea(x, y, width, height)` 0..1 | full | region of interest, normalized to the visible preview; codes whose center is outside are ignored |
| `maxResults` | `Int?` | `null` | codes per frame; `null` = 1, or 20 in batch mode (closest to the scan area center win) |

Error codes delivered to `onError` (`QRGenException.code`): `camera-permission-denied`,
`camera-not-found`, `camera-in-use`, `engine-load-failed`, `unsupported`, `unknown`
(`insecure-context` exists for web parity and is never raised on Android).

## Supported symbologies

Reading (ML Kit, bundled model): `qr`, `data-matrix`, `aztec`, `pdf417`, `ean13`, `ean8`,
`upca`, `upce`, `isbn`, `code128`, `code39`, `code93`, `codabar`, `itf`, `itf14`. UPC-A vs
EAN-13, ISBN and ITF-14 are disambiguated according to what you requested
(`Symbology.refine`). GS1 payloads (GS1-128, GS1 DataMatrix, GS1 QR) are detected and reported
in HRI form with `isGS1 = true` and `contentType = gs1`.

Not readable on Android (skipped silently): `micro-qr`, `rmqr`, `micro-pdf417`, `maxicode`,
`databar*`, `code32`, `pzn`, `telepen`, `dx-film-edge`.

## Building and testing

```bash
cd packages/android
./gradlew :qrgen-core:test                 # JVM only, no Android SDK needed
ANDROID_HOME=/path/to/sdk ./gradlew build  # everything: tests, lint, AARs, sample APK
./gradlew :qrgen-android:assembleRelease
./gradlew :sample:installDebug
```

## Status

What was verified for this version (1.0.0), in a Linux container with JDK 21, Gradle 8.14.3
(wrapper), Kotlin 2.2.21, AGP 8.13.2, Android SDK platform 35 and build-tools 35.0.0:

- `qrgen-core`: compiled; **127 JUnit 5 tests pass** (`./gradlew :qrgen-core:test`). They cover
  the SPEC GS1 and AAMVA test vectors, all symbology aliases and groups, the content parser
  types, `DuplicateFilter` and `BarcodeTracker` behaviour, coordinate mapping, JSON shapes, and
  generator round trips for all 15 writable symbologies plus GS1-128 / GS1 DataMatrix / GS1 QR
  (encode with ZXing, decode the rendered matrix with ZXing's `MultiFormatReader`, compare).
- `qrgen-android`: compiled with `./gradlew :qrgen-android:assembleRelease`; Android lint passes
  (only notice: compileSdk 36 is available); 3 JVM unit tests for the ML Kit format mapping pass.
- `qrgen-compose`: compiled (`assembleRelease`) and lint passes.
- `sample`: `assembleDebug` and a minified (R8) `assembleRelease` build succeed.
- Publishing: `publishToMavenLocal` produces `dev.qrgen:qrgen-core|qrgen-android|qrgen-compose:1.0.0`
  (jar/aar, sources, POM with Apache-2.0 license and SCM). The JitPack build was simulated locally with
  `JITPACK=true GROUP=com.github.Rockyljewell ARTIFACT=QR-GEN VERSION=1.0.0`, which publishes
  `com.github.Rockyljewell.QR-GEN:*:1.0.0` with matching inter-module dependencies.

Not verified: live camera scanning on a device or emulator (none was available in the build
environment), and a real JitPack build. The camera, overlay and ML Kit code paths are compiled
and lint-checked but have not been exercised at runtime yet.

Implementation note: ZXing 3.5.4's minimal Data Matrix encoder can corrupt GS1 symbols (it
omits the C40/Text unlatch before padding once FNC1 is prepended), so GS1 DataMatrix is
encoded by QRGen directly (FNC1 + ASCII/digit-pair codewords, ZXing for error correction and
placement). The round-trip test guards this.

## License

Apache-2.0, see [LICENSE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/android/LICENSE) and [NOTICE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/android/NOTICE).

Created by [Rockyljewell](https://github.com/Rockyljewell).


---

# React Native

URL: https://rockyljewell.github.io/QR-GEN/docs/react-native/
Group: Mobile & desktop

> Scan barcodes in React Native and Expo apps with qrgen-react-native: native scanning on VisionCamera, or a zero-setup WebView scanner.

> **Note:** This page is generated from [`packages/react-native/README.md`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/react-native/README.md). Source code: [`packages/react-native`](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/react-native).

Barcode, QR and ID scanning for React Native, part of [QRGen](https://github.com/Rockyljewell/QR-GEN)
(Apache-2.0). Two scanning back ends share one API:

| Component | Engine | Native setup | Best for |
| --- | --- | --- | --- |
| `QRGenScanner` | [react-native-vision-camera](https://react-native-vision-camera.com) 4 (ML Kit on Android, AVFoundation on iOS) | Development build (not Expo Go) | Production apps, best speed |
| `QRGenWebScanner` | Hosted QRGen embed page in [react-native-webview](https://github.com/react-native-webview/react-native-webview) | None (works in Expo Go) | Prototypes, every QRGen symbology, zero native code |

Both use the QRGen symbology ids, result shape, options and error codes from the
[cross-platform specification](https://github.com/Rockyljewell/QR-GEN/blob/main/docs/SPEC.md), so the results look the same as
in the JavaScript, iOS, Android, Flutter and Python SDKs.

## Install

```sh
npm install qrgen-react-native
```

### Expo

`QRGenScanner` needs a [development build](https://docs.expo.dev/develop/development-builds/introduction/)
because vision-camera ships native code:

```sh
npx expo install react-native-vision-camera@^4.7.3
```

Pin major version 4: vision-camera 5 has a different API and is not supported yet.

Add the config plugin to `app.json` / `app.config.js`. It writes the iOS camera
permission text and the Android `CAMERA` permission. `enableCodeScanner` bundles the
ML Kit barcode model (about 2.4 MB) so scanning works the first time the app is
opened, even offline:

```json
{
  "expo": {
    "plugins": [
      [
        "react-native-vision-camera",
        {
          "cameraPermissionText": "$(PRODUCT_NAME) uses the camera to scan barcodes and QR codes.",
          "enableCodeScanner": true
        }
      ]
    ],
    "android": {
      "permissions": ["android.permission.VIBRATE"]
    }
  }
}
```

Then run `npx expo prebuild` (or `eas build`).

For `QRGenWebScanner`, which also works in Expo Go:

```sh
npx expo install react-native-webview
```

### Bare React Native

```sh
npm install react-native-vision-camera@^4.7.3   # for QRGenScanner
npm install react-native-webview                # for QRGenWebScanner (optional)
cd ios && pod install
```

iOS `ios/<App>/Info.plist`:

```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) uses the camera to scan barcodes and QR codes.</string>
```

Android `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.CAMERA" />
<!-- Only for vibrate on scan: -->
<uses-permission android:name="android.permission.VIBRATE" />
```

To bundle the ML Kit model on Android instead of downloading it through Google Play
services on first use, add to `android/gradle.properties`:

```properties
VisionCamera_enableCodeScanner=true
```

Both components ask for the camera permission themselves when they mount.

## QRGenScanner (vision-camera)

```tsx
import { useIsFocused } from '@react-navigation/native';
import { QRGenScanner } from 'qrgen-react-native';

export function ScanScreen() {
  const isFocused = useIsFocused();
  return (
    <QRGenScanner
      style={{ flex: 1 }}
      isActive={isFocused}
      symbologies={['qr', 'ean13', 'code128']}
      mode="single"
      onScan={(barcodes) => console.log(barcodes[0].symbology, barcodes[0].data)}
      onError={(e) => console.warn(e.code, e.message)}
    />
  );
}
```

The component:

- resolves SPEC ids, aliases and groups (`QRCode`, `ean-13`, `retail`, `2d`, ...) and maps
  them to vision-camera code types, dropping the ones the platform cannot read
  (see `supportedSymbologies()`);
- refines results so they match the other QRGen SDKs: on iOS, UPC-A arrives as EAN-13 with
  a leading `0` and is reported as a 12 digit `upca`, EAN-13 starting with `978`/`979` is
  reported as `isbn`, and a 14 digit ITF as `itf14`, whenever those ids were requested;
- stops the camera while the app is in the background; pass `isActive={false}` (for example
  from `useIsFocused()`) when the screen is not visible;
- draws a rounded corner-bracket viewfinder (or a scan line for linear-only sets), highlight
  frames around detected codes and a success toast pill, in the QRGen accent `#2EC1CE`.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `symbologies` | `string[]` | `['all']` | SPEC ids, aliases or groups |
| `mode` | `'single' \| 'continuous' \| 'batch'` | `'continuous'` | `single` stops the camera after the first scan (call `ref.start()` to scan again); `batch` tracks many codes |
| `duplicateFilter` | `number` (ms) | `1000` | Ignore the same symbology + data inside this window. `0` reports every frame, `-1` once per session |
| `beep` | `boolean \| () => void` | `true` | Sound on scan, see [Beep](#beep) |
| `vibrate` | `boolean` | `true` | `Vibration.vibrate(50)` on scan |
| `camera` | `'back' \| 'front' \| deviceId` | `'back'` | Unknown device ids fall back to the back camera |
| `torch` | `boolean` | `false` | Flashlight (ignored with an `unsupported` error when the camera has none) |
| `viewfinder` | `'frame' \| 'line' \| 'none'` | `'frame'` (`'line'` for linear-only sets) | Overlay style |
| `scanArea` | `{ x, y, width, height }` (0..1 of the frame) | full frame | Codes whose center is outside are ignored; the viewfinder is drawn there |
| `maxResults` | `number` | `1` (`20` in batch) | Codes per frame; the ones closest to the center win |
| `spatialTracking` | `boolean` | `false` | Batch mode: separate equal-payload observations by position |
| `trackMaxJump` | `number` | `3` | Nonnegative finite movement gate relative to detection size |
| `trackMaxAssociationWork` | positive safe integer | `250000` | Bound spatial association work; reject the complete frame above the limit |
| `isActive` | `boolean` | `true` | Run the camera |
| `onScan` | `(barcodes: Barcode[]) => void` | | New codes (after the duplicate filter) |
| `onTrack` | `(tracked: TrackedBarcode[]) => void` | | Batch mode: every tracked code, whenever the set changes |
| `onError` | `(error: { code, message }) => void` | | SPEC error codes |
| `onReady` | `() => void` | | Camera initialized |
| `accentColor` | `string` | `'#2EC1CE'` | Viewfinder, highlight and toast color |
| `showToast` | `boolean` | `true` | Success toast pill |
| `showHighlights` | `boolean` | `true` | Highlight frames around detected codes |
| `fallback` | `ReactNode` | built-in message | Shown when the camera cannot run |
| `children` | `ReactNode` | | Rendered on top (buttons, hints) |
| `style` | `ViewStyle` | | Container style (give it a size, for example `flex: 1`) |

### Optional native spatial observations

Opt into position-based batch observations with `spatialTracking`. The default
continues to aggregate equal symbology and payload values. `onScan` still applies
the payload duplicate window; two visible identical labels can produce two
`onTrack` entries and one `onScan` entry.

```tsx
<QRGenScanner
  style={{ flex: 1 }}
  mode="batch"
  spatialTracking
  onTrack={(observations) => console.log(observations)}
/>
```

Within each exact symbology/payload group, matching maximizes eligible one-to-one
associations inside the movement gate, then minimizes total center movement.
The gate is `trackMaxJump` times the incoming detection's largest extent, with
a minimum extent of one pixel. Incoming detection order does not add an extra
observation when a complete eligible match exists. Spatial IDs are opaque and
fresh after expiry or reset within a session. Replacing the tracking policy uses
a new ID namespace. `count` is the number of decoded frame observations; tracks
do not establish confirmed product quantities or physical identity through occlusion.

The three native props are reactive. An equal effective policy keeps tracks.
A successful policy replacement clears tracks and preserves duplicate history.
A rejected proposal reports through `onError` and retains the accepted settings
and histories. Actual permission loss, device removal or `isActive={false}` still gates that camera;
view-axis or preview-orientation changes still establish coordinate boundaries.
Camera-source and coordinate boundaries clear spatial observations while keeping
duplicate history. Clearing a nonempty set while remaining in batch produces one
current empty tracking notification. Default payload mode keeps its existing
camera behavior.

Spatial batch frames require finite nonzero geometry and consistent positive integer
upright frame dimensions. Blank and ROI-excluded frames also carry full-frame
dimensions. Invalid geometry, clock or work-budget updates retain both histories
and IDs and report through `onError`.

The work estimate sums `n*n*(m+n)` per exact payload group with `n` current
detections and `m > 0` surviving tracks, including out-of-gate prior columns.
New-only groups cost zero. Exceeding the budget rejects the complete frame before
assignment matrices or state changes; it does not truncate the result. The budget
bounds association work, not frame time or memory. Larger limits need workload testing.

These options belong to `QRGenScanner`, `ScanSession` and `BarcodeTracker`;
they are not embed URL or `QRGenWebScanner` options. Pure users can construct
`new BarcodeTracker({ spatial: true, maxJump: 3, maxAssociationWork: 250000 })`
or `new ScanSession({ mode: 'batch', spatialTracking: true })` and pass an optional
source size to `update(barcodes, now?, frameSize?)` / `process(...)` for blank
resize detection. Direct same-size source switches must call `reset()` on the
tracker or `resetSpatial()` on the session. `resetSpatial()` preserves duplicate
history and stopped state; full session `reset()` clears both histories and resumes.

Camera callback ownership is checked in JavaScript. Physical camera alignment,
dense-scene latency, long phone sessions and comparison with Scandit still require
device testing.

### Ref

```tsx
const ref = useRef<QRGenScannerHandle>(null);
<QRGenScanner ref={ref} mode="single" onScan={...} />;
ref.current?.start(); // scan again after a single-mode result
```

| Method | Description |
| --- | --- |
| `start()` / `resume()` | Run again after `stop()`, `pause()` or a single-mode scan |
| `stop()` | Stop the camera |
| `pause()` | Keep the preview running but ignore codes |
| `reset()` | Clear duplicate history and tracked codes, and resume |
| `setTorch(on)` | Flashlight on or off (until the `torch` prop changes) |
| `supportedSymbologies()` | Ids this back end reads on this device |

### Beep

React Native cannot play a sound without a library, and QRGen does not force one on
you. `beep` (default `true`) plays whatever you register once with `setBeepHandler`,
and is silent until you do. You can also pass a function as the `beep` prop.

```ts
import { createAudioPlayer } from 'expo-audio';
import { setBeepHandler } from 'qrgen-react-native';

const player = createAudioPlayer(require('./assets/beep.mp3'));
setBeepHandler(() => {
  player.seekTo(0);
  player.play();
});
```

`react-native-sound`, `expo-av` or any other player works the same way.

## QRGenWebScanner (WebView, zero native setup)

Loads the hosted page `https://rockyljewell.github.io/QR-GEN/embed/` with the options in
the query string (SPEC section 5) and forwards its events. It reads every QRGen
symbology (the page runs the QRGen WebAssembly engine), beeps from the page and vibrates
natively.

```tsx
import { useRef } from 'react';
import { QRGenWebScanner, type QRGenWebScannerHandle } from 'qrgen-react-native';

export function WebScanScreen() {
  const ref = useRef<QRGenWebScannerHandle>(null);
  return (
    <QRGenWebScanner
      ref={ref}
      style={{ flex: 1 }}
      symbologies={['qr', 'pdf417']}
      mode="continuous"
      onReady={() => console.log('ready')}
      onScan={(barcodes) => console.log(barcodes)}
      onError={(e) => console.warn(e.code, e.message)}
    />
  );
}
```

It accepts the same scanner options as `QRGenScanner` (`symbologies`, `mode`,
`duplicateFilter`, `beep`, `vibrate`, `camera`, `torch`, `viewfinder`, `scanArea`,
`maxResults`) plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `embedUrl` | `string` | hosted page | Self-hosted copy of the embed page (must be `https`) |
| `isActive` | `boolean` | `true` | Sends `start` / `stop` to the page; the page is also stopped while the app is in the background |
| `onScan`, `onTrack`, `onError`, `onReady` | | | Same as above, from the page's `scan`, `track`, `error` and `ready` messages |
| `fallback` | `ReactNode` | built-in message | Shown when the WebView cannot run |
| `webViewProps` | `object` | | Extra props for the underlying `<WebView>` |

Ref methods: `start()`, `stop()`, `pause()`, `resume()`, `setTorch(on)`, `sendCommand(command)`,
`reload()`. Ref commands use the WebView's JavaScript bridge,
and camera-dependent commands wait for the page's actual `ready` message.
`start`/`stop` can reach a verified command bridge before camera-ready, including
with `autostart=0` or after an initial camera error. Transport acknowledgement
does not call `onReady`. Private transport messages stay internal. Load and page
message handling also runs when advanced
`webViewProps` callbacks are supplied; those callbacks are invoked afterward.

The WebView is configured with `mediaPlaybackRequiresUserAction={false}`,
`allowsInlineMediaPlayback`, and `mediaCapturePermissionGrantType="grant"` (iOS 15+, so the
page does not ask a second time). On Android the component requests the `CAMERA` runtime
permission before it mounts the WebView; react-native-webview then grants the page's
`getUserMedia` request. On iOS the page's camera request uses your app's
`NSCameraUsageDescription`.

## Results

`onScan` receives SPEC section 2 objects:

```ts
interface Barcode {
  data: string;               // decoded text
  symbology: SymbologyId;     // 'qr', 'ean13', ...
  symbologyName: string;      // 'QR Code'
  rawBytes: string;           // base64, '' when the engine does not expose bytes (vision-camera)
  contentType: 'text' | 'binary' | 'gs1' | 'iso15434' | 'mixed' | 'unknown-eci';
  isGS1: boolean;
  location: { topLeft; topRight; bottomRight; bottomLeft }; // pixels of the upright frame
  frameSize: { width: number; height: number };            // the upright frame
  orientation: number;
  ecLevel: string;
  symbologyIdentifier: string;
  timestamp: number;          // ms since epoch
}
```

With `QRGenScanner`, `location` and `frameSize` describe the camera frame as it appears
upright on screen (the sensor's landscape size is swapped for portrait views);
`contentType` is `text` except for GS1 DataBar, which is reported in HRI form
(`(01)...`). Batch mode adds `TrackedBarcode` fields: `id` (derived from symbology
and data by default, with collision suffixes when needed; an opaque fresh observation ID
with `spatialTracking`), `firstSeen`, `lastSeen` and `count`.
IDs are opaque and unique among active tracks; they stay stable while a track remains visible.
Codes are dropped after more than 500 ms unseen, before matching the next frame. A returning
code starts fresh timestamps and count. Default payload mode can reuse a deterministic base ID.

Native duplicate windows and tracking expiry use elapsed monotonic time, so changing the
system clock does not extend or shorten them. `timestamp`, `firstSeen` and `lastSeen` remain
milliseconds since epoch. Pure helpers accept an optional `now` for an injected clock;
switching between injected and default clocks preserves retained timestamp age. Environments
without `performance.now()` retain the wall-clock fallback.

In native batch mode, `onScan` runs before `onTrack`. If `onScan` resets the scanner,
synchronously unmounts it, commits a different mode or spatial policy/source/coordinate boundary,
or processes a newer tracking update, the obsolete
track snapshot is discarded. An unchanged session, a cosmetic prop change, or an idempotent
`start()` / `resume()` keeps the current track callback and duplicate history.
A no-change empty frame also preserves the still-current notification; an empty frame
that expires tracks delivers the replacement list.

Errors are `{ code, message }` with `code` one of `camera-permission-denied`,
`camera-not-found`, `camera-in-use`, `insecure-context`, `engine-load-failed`,
`unsupported`, `unknown`.

## Parsing the content

The core JavaScript SDK exposes pure parsers that run in React Native (no DOM, no
WebAssembly). Install `qrgen-sdk` next to this package if you need them:

```ts
import { parseContent, parseGS1, parseAAMVA } from 'qrgen-sdk/parsers';

const parsed = parseContent(barcode.data); // url, wifi, contact, payment, product, gs1, aamva, ...
const gs1 = parseGS1('(01)09501101530003(17)250101(10)ABC123');
const license = parseAAMVA(pdf417Barcode.data); // driver license / ID card back side
```

## Utilities

Pure helpers, also usable in Node and tests:

- `resolveSymbologies(input)`, `resolveSymbology(id)`, `symbologyName(id)`, `SYMBOLOGIES`, `SYMBOLOGY_GROUPS`
- `toVisionCameraCodeTypes(ids, { os, version })`, `fromVisionCameraCode(type, value, requested)`,
  `visionCameraSupportedSymbologies(platform)`
- `DuplicateFilter`, `BarcodeTracker`, `trackingId`, `ScanSession`
- `buildEmbedUrl(url, options)`, `parseEmbedMessage(json)`, `buildCommandScript(command)`
- `frameToViewTransform`, `uprightFrameSize`, `quadrilateralToView` (map `location` to screen points)
- `isVisionCameraAvailable()`, `isWebViewAvailable()`: pick a back end at runtime

`QRGenScanner` loads vision-camera lazily, so importing this package in Expo Go (where
the native module is missing) does not crash. `QRGenScanner` then reports
`engine-load-failed` and you can fall back to `QRGenWebScanner`:

```tsx
{isVisionCameraAvailable() ? <QRGenScanner {...props} /> : <QRGenWebScanner {...props} />}
```

## Example

[`example/App.tsx`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/react-native/example/App.tsx) is a small screen with a mode switch, a torch toggle,
a back end switch and a result list.

## Status

- **Tested:** `npm test` runs Jest unit tests (ts-jest, Node) for symbology resolution
  (ids, aliases, groups), the vision-camera mapping in both directions per platform, the
  duplicate filter, the batch tracker, the scan session state machine (single, continuous,
  batch), the frame-to-view math (aspect-fill crop, mirroring), code conversion, the embed
  URL builder, embed message parsing and commands, error mapping, and an import test of the
  entry point against a mocked `react-native`. `npx tsc --noEmit` type-checks all sources,
  tests and the example against react-native 0.87, react-native-vision-camera 4.7.3 and
  react-native-webview 14.
- **Not tested yet:** the components have not been run on a device or simulator. The
  coordinate handling follows the vision-camera 4.7 native sources (iOS multiplies
  preview-oriented normalized coordinates by the landscape sensor size; Android reports
  ML Kit coordinates in the rotated image), and highlight placement, especially with the
  front camera, still needs checking on hardware. `QRGenWebScanner` depends on the hosted
  embed page implementing SPEC section 5.

## License

Apache-2.0, see [LICENSE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/react-native/LICENSE) and [NOTICE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/react-native/NOTICE).

Created by [Rockyljewell](https://github.com/Rockyljewell).


---

# Flutter

URL: https://rockyljewell.github.io/QR-GEN/docs/flutter/
Group: Mobile & desktop

> Scan barcodes in Flutter apps with qrgen_flutter: a mobile_scanner-based widget and a WebView scanner that reads every QRGen symbology.

> **Note:** This page is generated from [`packages/flutter/README.md`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/flutter/README.md). Source code: [`packages/flutter`](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/flutter).

Barcode, QR and ID scanning for Flutter, part of [QRGen](https://github.com/Rockyljewell/QR-GEN)
(Apache-2.0). Two widgets share one API:

| Widget | Engine | Best for |
| --- | --- | --- |
| `QRGenScanner` | [`mobile_scanner`](https://pub.dev/packages/mobile_scanner) 5.1+, 6 or 7 (ML Kit on Android; ML Kit on iOS up to 6, Apple Vision from 7) | Production apps, best speed |
| `QRGenWebScanner` | Hosted QRGen embed page in [`webview_flutter`](https://pub.dev/packages/webview_flutter) | Every QRGen symbology, no camera plugin setup |

Both use the QRGen symbology ids, result shape (`QRGenBarcode`), options and error codes
from the [cross-platform specification](https://github.com/Rockyljewell/QR-GEN/blob/main/docs/SPEC.md), so results look the same as
in the JavaScript, iOS, Android, React Native and Python SDKs.

## Install

```yaml
dependencies:
  qrgen_flutter: ^0.1.0
```

Requires Dart 3.3 and Flutter 3.19 or later (newer `mobile_scanner` and `webview_flutter`
releases are picked automatically on newer Flutter versions).

### iOS

`ios/Runner/Info.plist`:

```xml
<key>NSCameraUsageDescription</key>
<string>This app uses the camera to scan barcodes and QR codes.</string>
```

`mobile_scanner` 6 needs iOS 15.5 (`platform :ios, '15.5'` in `ios/Podfile`); 5 and 7
work from iOS 12. The WebView scanner needs iOS 14.3+ for camera access in `WKWebView`.

### Android

`android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.CAMERA" />
```

`mobile_scanner` 7 needs `minSdk 23`, `webview_flutter_android` 4 needs `minSdk 24`.
`QRGenScanner` asks for the camera permission itself (through `mobile_scanner`).
For `QRGenWebScanner` the app must hold the permission before the page opens the camera,
see [below](#android-camera-permission-for-the-webview).

To bundle the ML Kit model instead of downloading it through Google Play services, see the
`mobile_scanner` README (`dev.steenbakker.mobile_scanner.useUnbundled`).

## QRGenScanner (mobile_scanner)

```dart
import 'package:qrgen_flutter/qrgen_flutter.dart';

class ScanPage extends StatelessWidget {
  const ScanPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: QRGenScanner(
        options: const QRGenScannerOptions(
          symbologies: ['qr', 'ean13', 'code128'],
          mode: QRGenScanMode.single,
        ),
        onScan: (barcodes) => Navigator.pop(context, barcodes.first.data),
        onError: (error) => debugPrint('${error.code.value}: ${error.message}'),
      ),
    );
  }
}
```

The widget:

- resolves SPEC ids, aliases and groups (`QRCode`, `ean-13`, `retail`, `2d`, ...) and maps them
  to the `BarcodeFormat`s of the installed `mobile_scanner` version, dropping the ones the
  platform cannot read (see `qrgenSupportedSymbologies()`);
- refines results so they match the other QRGen SDKs: UPC-A read as EAN-13 with a leading `0`
  (Apple Vision) is reported as a 12 digit `upca`, EAN-13 starting with `978`/`979` as
  `isbn`, and a 14 digit ITF as `itf14`, whenever those ids were requested;
- stops the camera while the app is in the background, while `isActive` is `false`, and while
  its route is covered by another full-screen route, and disposes its `mobile_scanner`
  controller;
- draws a rounded corner-bracket viewfinder (or a scan line for linear-only sets), outlines
  detected codes when `mobile_scanner` reports corners, and shows a success toast pill, in the
  QRGen accent `Color(0xFF2EC1CE)`;
- gives haptic feedback (`HapticFeedback.mediumImpact`) and a short system click on scan. Pass
  `onBeep` to play a real beep with your audio package.

| Parameter | Default | Description |
| --- | --- | --- |
| `options` | `QRGenScannerOptions()` | SPEC options, see below |
| `onScan` | | `void Function(List<QRGenBarcode>)`: new codes after the duplicate filter |
| `onTrack` | | `void Function(List<QRGenTrackedBarcode>)`: batch mode, every tracked code whenever the set changes |
| `onError` | | `void Function(QRGenError)` |
| `onReady` | | The camera started |
| `controller` | | `QRGenScannerController` for `start`, `stop`, `pause`, `resume`, `reset`, `setTorch`, `switchCamera` |
| `isActive` | `true` | Run the camera |
| `accentColor` | `Color(0xFF2EC1CE)` | Viewfinder, outline and toast color |
| `showToast` / `showHighlights` | `true` | Overlay parts |
| `onBeep` | system click | Scan sound |
| `errorBuilder` | built-in message | `Widget Function(BuildContext, QRGenError)` |
| `child` | | Drawn on top (buttons, hints) |

Give the scanner a bounded size (`Expanded`, `SizedBox`, `AspectRatio`, or a `Scaffold` body).

### Options

`QRGenScannerOptions` is shared by both widgets:

| Option | Type | Default | Meaning |
| --- | --- | --- | --- |
| `symbologies` | `List<String>` | `['all']` | SPEC ids or groups |
| `mode` | `QRGenScanMode` | `continuous` | `single` stops the camera after the first scan (call `controller.start()` to scan again); `batch` tracks many codes |
| `duplicateFilter` | `int` (ms) | `1000` | Ignore the same symbology + data within this window. `0` reports every frame, `-1` once per session |
| `beep` | `bool` | `true` | Sound on scan |
| `vibrate` | `bool` | `true` | Haptic feedback on scan |
| `camera` | `QRGenCameraFacing` | `back` | `back` or `front` |
| `torch` | `bool` | `false` | Flashlight |
| `viewfinder` | `QRGenViewfinder?` | `frame` (`line` for linear-only sets) | `frame`, `line` or `none` |
| `scanArea` | `QRGenScanArea?` | full frame | Normalized region of interest; codes whose center is outside are ignored |
| `maxResults` | `int?` | `1` (`20` in batch) | Codes per frame, closest to the center first |

## QRGenWebScanner (webview_flutter)

Loads `https://rockyljewell.github.io/QR-GEN/embed/` with the options in the query string,
registers the `QRGenBridge` JavaScript channel and parses the SPEC section 5 messages. It reads
every QRGen symbology because the page runs the QRGen WebAssembly engine.

```dart
final controller = QRGenWebScannerController();

QRGenWebScanner(
  controller: controller,
  options: const QRGenScannerOptions(symbologies: ['qr', 'pdf417']),
  onReady: () => debugPrint('ready'),
  onScan: (barcodes) => debugPrint(barcodes.first.data),
  onError: (error) => debugPrint(error.message),
);

// Later:
await controller.setTorch(true);
await controller.pause();
```

- iOS: the controller is created with `WebKitWebViewControllerCreationParams(allowsInlineMediaPlayback: true, mediaTypesRequiringUserAction: {})`
  and the page's camera request is granted (iOS 15+), so the user only sees the app-level
  permission prompt.
- Android: `setMediaPlaybackRequiresUserGesture(false)` and `setOnPlatformPermissionRequest`
  grant the page's camera request.
- Controller commands (`start`, `stop`, `pause`, `resume`, `setTorch`, `send`) call
  `runJavaScript("window.qrgen && window.qrgen.command({...});")`. Commands sent before the page
  reports `ready` are queued, except `start`/`stop`: those can reach a verified
  command bridge before camera-ready, so `autostart=0` and startup retries work.
  `onReady` and `controller.isReady` still reflect the page's actual camera-ready
  message; pause/resume/torch keep their camera-ready queue.
- `isActive: false`, a covered route and the app going to the background send `stop`; coming
  back sends `start`. Changing `torch` sends a command, changing other options reloads the page.
- Haptics run natively; the page gets `vibrate=0`. The page plays the beep.
- `embedUrl` points to a self-hosted copy of the page (it must be `https`).

### Android camera permission for the WebView

Android WebViews can only grant camera access the app already holds. Request it first, for
example with [`permission_handler`](https://pub.dev/packages/permission_handler):

```dart
QRGenWebScanner(
  requestCameraPermission: () async => (await Permission.camera.request()).isGranted,
  onScan: (barcodes) {},
);
```

When `requestCameraPermission` returns `false`, the page is not loaded and
`camera-permission-denied` is reported. Without it, a missing permission is reported by the
page as `camera-permission-denied`.

## Results

`QRGenBarcode` follows SPEC section 2 and round-trips through `toJson()` / `fromJson()`:

| Field | Type | Notes |
| --- | --- | --- |
| `data` | `String` | Decoded text; GS1 DataBar in HRI form `(01)...` |
| `symbology` | `QRGenSymbology` | `.id` is the SPEC id, for example `ean13` |
| `symbologyName` | `String` | `EAN-13` |
| `rawBytes` | `String` | Base64 of the raw bytes, `''` when unavailable |
| `contentType` | `QRGenContentType` | `text`, or `binary` for byte-only codes |
| `isGS1` | `bool` | |
| `location` | `QRGenQuadrilateral` | Corners in pixels of `frameSize` (the upright camera frame) |
| `frameSize` | `QRGenSize` | |
| `orientation`, `ecLevel`, `symbologyIdentifier` | | `0` / `''` when unknown |
| `timestamp` | `DateTime` | JSON: ms since epoch |

`QRGenTrackedBarcode` adds `id` (stable, by default derived from symbology and data, with collision
suffixes when needed), `firstSeen`, `lastSeen` and `count`. Treat IDs as opaque; active tracks
have unique IDs. Base IDs use the same scheme as React Native, while collision suffixes
depend on track insertion order. Codes are dropped after more than 500 ms unseen, before
matching the next frame; a returning code starts fresh timestamps and count.
Default duplicate windows and unseen-track timeouts use monotonic elapsed time;
public barcode and tracking timestamps remain epoch-valued `DateTime` values.
The pure helpers retain their optional explicit `DateTime` arguments and preserve
retained timestamp ages when switching between explicit and default time.
In native batch mode, `onScan` precedes `onTrack`. A reset, real widget disposal,
committed mode change or newer tracking update cancels an older pending track result.
No-op start/resume, cosmetic rebuilds and no-change blank input preserve the current
notification. Requesting a parent rebuild takes effect when that rebuild is committed.
Errors are `QRGenError` with a `QRGenErrorCode` (`camera-permission-denied`,
`camera-not-found`, `camera-in-use`, `insecure-context`, `engine-load-failed`, `unsupported`,
`unknown`).

## Utilities

Pure Dart helpers (no Flutter needed): `resolveSymbologies`, `QRGenSymbology.tryParse`,
`qrgenSymbologyGroups`, `mobileScannerFormatNames`, `fromMobileScannerFormat`,
`QRGenDuplicateFilter`, `QRGenBarcodeTracker`, `qrgenTrackingId`, `QRGenScanSession`,
`buildEmbedUri`, `parseBridgeMessage`, `QRGenBridgeCommand`, `QRGenFrameTransform` (map
`location` to widget coordinates with the `BoxFit.cover` crop), `QRGenScannerOverlay` (reuse the
overlay with your own camera widget).

### Optional spatial observations in the pure helpers

Custom camera integrations can separate identical decoded labels by their positions:

```dart
final session = QRGenScanSession(
  mode: QRGenScanMode.batch,
  spatialTracking: true,
  trackMaxJump: 3,
  trackMaxAssociationWork: 250000,
);

// Each barcode's location uses the same full upright frame dimensions.
final result = session.process(barcodes, null, const QRGenSize(640, 480));
final observations = result.tracked;
```

This opt-in belongs to `QRGenScanSession` and `QRGenBarcodeTracker`. The existing
`QRGenScanner` widget, shared `QRGenScannerOptions`, WebView and embed bridge do not
acquire these flags. Direct widget integration remains separate work; its camera
source ownership and orientation handling need their own validation. Existing
scanner rendering, styling and default payload grouping are unchanged.

The tracker equivalent is `QRGenBarcodeTracker(spatial: true, maxJump: 3,
maxAssociationWork: 250000)` with `update(barcodes, now?, frameSize?)`.
The session accepts the optional full size on `process`, including empty frames.
Each spatial record requires finite corners with nonzero extent and its own positive
integral `frameSize`, consistent across the frame. Coordinates remain full-frame
pixels when an application filters an ROI; do not relabel them as crop coordinates.
An empty frame with changed dimensions clears observations. For a same-size source
switch, call `session.resetSpatial()` before admitting frames from the new source;
it returns an empty-list change once and keeps payload duplicate history.
The application must reject delayed callbacks and frames from the old source.

Association groups by exact symbology and payload. It maximizes eligible one-to-one
matches, then minimizes total Euclidean center movement. Each current detection's
movement gate is `max(extent, 1) * maxJump`, where extent is its larger bounding-box
dimension. Equal-position ties follow numeric observation creation order. Unmatched
observations remain until more than the tracking timeout has elapsed, so the result
can temporarily contain more observations than visible detections.

Before assignment, work is summed as `n*n*(m+n)` across payload groups with `n`
current detections and `m > 0` surviving old observations. The default budget of
250,000 rejects an oversized complete frame without partial tracking or payload
reports. New-only groups cost zero. The budget is a positive safe integer and does
not guarantee frame time or memory use; an offline override can still be expensive.
Each spatial session frame also copies retained duplicate-history maps; once-per-session
history persists until reset, so long sessions need separate allocation and latency measurements.
Invalid geometry, source sizes, late caller reads, time comparisons and exhausted
identity/count ranges also reject without consuming histories or IDs.

Session `configure(spatialTracking: ..., trackMaxJump: ...,
trackMaxAssociationWork: ...)` validates the entire proposal first. Equal effective
policies preserve observations; changed policies clear them and use a fresh public
ID namespace, while retaining duplicate history and stopped state. A mode change
also resumes. Ordinary reset, source reset and expiry never reuse a spatial ID within
the same helper lifetime. Treat IDs as opaque. Scan reports remain payload-based,
including for identical observations; window `0` still reports every detection.
Public timestamps remain `DateTime` values, while default expiry and duplicate ages
use monotonic elapsed time. Injected `DateTime` arguments retain their established
microsecond and clock-transition behavior.

Spatial tracks describe short-lived decoded observations. They do not establish
persistent physical identity through occlusion, confirmed quantities, or Scandit
parity. Those require physical camera and workflow validation.

## Example

[`example/lib/main.dart`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/flutter/example/lib/main.dart): a scanner screen with a mode switch, a torch
toggle, a back end switch and a result list. Run `flutter create .` inside `example/` to
generate the platform folders, then add the permissions above.

## Status

- **Core validation:** 220 pure Dart tests pass with `dart test` in a Flutter-free
  package (Dart 3.13.5), with strict analysis clean. They cover symbology resolution, the
  mobile_scanner mapping for versions 5/6, 7.0-7.2 and 7.3+, JSON round trips, the duplicate filter,
  the tracker, the scan session, geometry and bridge parsing, including optional spatial
  association, complete-frame transactions and an independent exhaustive small-scene oracle.
- **CI validation:** `flutter analyze` and `flutter test` check the package and example.
  The resolved test environment uses Flutter 3.47.7, Dart 3.13.5, mobile_scanner 7.4.2
  and webview_flutter 4.14.1. Widget tests drive `QRGenScanner` against a fake `mobile_scanner`
  platform (formats, start and stop, single, batch, duplicate filter, torch, `isActive`, error
  mapping, reset, nested callback ownership and torch state across camera/configuration
  changes, including stopped and single-camera no-op controls) and `QRGenWebScanner` against a fake `webview_flutter` platform (URL, `QRGenBridge`
  channel, message dispatch, command queueing, permission grants). CI also compiles the
  87 spatial tracker/session/oracle cases for Node with the official Dart web compiler.
  The separate compiled-core probe runs 48 clock checks in an isolated Node context:
  four calibrations, 24 default-clock regressions and 20 compatibility/metadata controls.
  See `tool/clock_probe.dart` and `tool/run_clock_probe.mjs`; JavaScript supplies clock
  boundaries, while the algorithms come from the compiled Dart sources.
  Earlier compatibility checks analyzed `lib/` against the lowest
  allowed dependencies (mobile_scanner 5.1.0, webview_flutter 4.4.0, webview_flutter_android
  3.12.0, webview_flutter_wkwebview 3.9.0) and against mobile_scanner 6.0.10 and 7.0.0;
  those older dependency combinations have not been rerun for this spatial-helper change. The
  tracking ids are checked to be the same on the Dart VM, in dart2js output and in the React
  Native package.
- **Not tested yet:** nothing has run on a real device or simulator. Camera behavior, highlight
  placement (especially with the front camera, which is not mirrored in the overlay) and the
  hosted embed page inside real WebViews still need checking on hardware. The widget tests use
  the mobile_scanner 7 platform interface, so they need mobile_scanner 7 to compile.

## License

Apache-2.0, see [LICENSE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/flutter/LICENSE) and [NOTICE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/flutter/NOTICE).

Created by [Rockyljewell](https://github.com/Rockyljewell).


---

# Capacitor & Ionic

URL: https://rockyljewell.github.io/QR-GEN/docs/capacitor/
Group: Mobile & desktop

> Scan barcodes in Capacitor and Ionic apps with the QRGen web SDK: camera permissions on iOS and Android, secure contexts, live reload over HTTPS and offline wasm.

Capacitor apps run your web code in the system WebView (WKWebView on iOS, Android System WebView on Android), so the regular web SDK works without a native plugin. You use `<qrgen-scanner>` or `BarcodeScanner` exactly as in a browser; the only native work is declaring camera permission.

This works with any framework on top of Capacitor: Ionic with Angular, React or Vue, or plain Capacitor.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

Then follow the guide for your framework: [React](../react/), [Vue](../vue/), [Angular](../angular/) or [Web Components](../web-components/). An Ionic page is a regular component:

```tsx
// src/pages/Scan.tsx (Ionic React)
import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from "@ionic/react";
import { QRGenScanner } from "qrgen-sdk/react";

export default function Scan() {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Scan</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent>
        <QRGenScanner symbologies={["qr", "ean13", "code128"]} style={{ height: "100%" }} onScan={(_, barcode) => console.log(barcode.data)} />
      </IonContent>
    </IonPage>
  );
}
```

## Camera permission

### iOS

Add a camera usage description to `ios/App/App/Info.plist`. Without it, iOS terminates the app the first time the page asks for the camera:

```xml
<key>NSCameraUsageDescription</key>
<string>The camera is used to scan barcodes and QR codes.</string>
```

The user sees the iOS permission prompt the first time the scanner starts. WKWebView supports `getUserMedia` from iOS 14.3; QRGen supports iOS 14.5 and later.

### Android

Declare the permission in `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.CAMERA" />
```

When the page calls `getUserMedia`, Capacitor's WebView asks the user for the Android runtime permission and passes the result to the page. If the user denies it, the scanner reports `camera-permission-denied`; the user has to allow it again in the system settings.

## Secure context

`getUserMedia` only works in a secure context. Capacitor's default origins are secure:

| Platform | Default origin | Secure |
| --- | --- | --- |
| iOS | `capacitor://localhost` (`server.iosScheme`, default `capacitor`) | Yes |
| Android | `https://localhost` (`server.androidScheme`, default `https` in Capacitor 6+) | Yes |

If you changed `androidScheme` to `http`, camera access fails with `insecure-context`. Keep the defaults, or set them explicitly:

```ts
// capacitor.config.ts
import type { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  appId: "com.example.scanner",
  appName: "Scanner",
  webDir: "dist",
  server: {
    androidScheme: "https",
    iosScheme: "capacitor",
  },
};

export default config;
```

## Live reload

Live reload (`npx cap run ios --livereload --external`) points the WebView at your dev server's LAN address, such as `http://192.168.1.20:5173`. That is not a secure context, so the camera is blocked.

Serve the dev server over HTTPS instead and point Capacitor at it:

1. Create a certificate the device trusts, for example with [mkcert](https://github.com/FiloSottile/mkcert) (an external tool). Install mkcert's root CA on the device: on iOS, install the profile and enable it under **Settings > General > About > Certificate Trust Settings**; on Android, install it under **Settings > Security > Encryption & credentials**. Android apps only trust user CAs when the app's network security config allows it, so add a debug-only `network_security_config.xml` that trusts user certificates.
2. Run the dev server with that certificate (for Vite: `server.https` with the mkcert key and cert, and `server.host: true`).
3. Set the URL in `capacitor.config.ts` while developing, then `npx cap run`:

```ts
// capacitor.config.ts (development only)
import type { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  appId: "com.example.scanner",
  appName: "Scanner",
  webDir: "dist",
  server: {
    url: "https://192.168.1.20:5173",
    cleartext: false,
  },
};

export default config;
```

Remove `server.url` before building for release. Alternatively, rebuild and run without live reload (`npm run build && npx cap run android`), which always uses the secure bundled origin.

## Offline apps

By default the decoder wasm is downloaded from jsDelivr on first use and cached by the WebView. To work offline from the first launch, bundle it with your web assets:

```bash
mkdir -p public/qrgen && cp node_modules/qrgen-sdk/dist/wasm/*.wasm public/qrgen/
```

```ts
import { configure } from "qrgen-sdk";

configure({ wasmBaseUrl: "/qrgen/" });
```

The files end up in `webDir` and are served from `capacitor://localhost/qrgen/` or `https://localhost/qrgen/`.

## Tips

- Give the scanner the full height of the page (`IonContent` with `style={{ height: "100%" }}` on the scanner) and set `viewport-fit=cover` in your viewport meta tag so the preview extends under the notch.
- Stop the camera when the app goes to the background. With `@capacitor/app`: `App.addListener("pause", () => scanner.stop())` and `App.addListener("resume", () => scanner.start())`.
- Vibration works on Android. iOS WebViews don't support the Vibration API; for haptics on iOS, call `@capacitor/haptics` from your `scan` handler and set `vibrate={false}`.
- For a native camera pipeline instead of the WebView, see the [iOS](../ios/) and [Android](../android/) SDKs.


---

# Cordova

URL: https://rockyljewell.github.io/QR-GEN/docs/cordova/
Group: Mobile & desktop

> Scan barcodes in Apache Cordova apps with the QRGen web SDK: Android runtime camera permission, NSCameraUsageDescription via config.xml, WKWebView settings and offline wasm.

Cordova apps run your web code in the platform WebView, so QRGen's web SDK works without a Cordova plugin of its own. You need to declare camera permission for each platform, make sure Android grants it at runtime, and let iOS play the camera preview inline.

Requirements: cordova-android 10 or later (the app is served from `https://localhost`, a secure context) and cordova-ios 6 or later (WKWebView, with the app served from a custom scheme). With older versions the app runs from `file://`, where `getUserMedia` is unavailable.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

Cordova doesn't bundle JavaScript, so either use your own bundler to build `www/`, or copy the standalone bundle and wasm into `www/` and load them with a script tag:

```bash
mkdir -p www/vendor/qrgen/wasm
cp node_modules/qrgen-sdk/dist/browser/qrgen.iife.js www/vendor/qrgen/
cp node_modules/qrgen-sdk/dist/wasm/*.wasm www/vendor/qrgen/wasm/
```

## config.xml

```xml
<?xml version="1.0" encoding="utf-8"?>
<widget id="com.example.scanner" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:android="http://schemas.android.com/apk/res/android">
  <name>Scanner</name>
  <content src="index.html" />

  <platform name="android">
    <config-file target="AndroidManifest.xml" parent="/manifest">
      <uses-permission android:name="android.permission.CAMERA" />
    </config-file>
  </platform>

  <platform name="ios">
    <edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
      <string>The camera is used to scan barcodes and QR codes.</string>
    </edit-config>
    <preference name="AllowInlineMediaPlayback" value="true" />
    <preference name="scheme" value="app" />
    <preference name="hostname" value="localhost" />
  </platform>
</widget>
```

- `NSCameraUsageDescription` is required on iOS; without it the app is terminated when the page requests the camera.
- `AllowInlineMediaPlayback` lets WKWebView play the camera preview inline instead of switching to full-screen video, which would hide the scanner UI.
- `scheme` and `hostname` serve the iOS app from `app://localhost` through WKWebView's URL scheme handler instead of `file://`. `file://` is not a secure context.
- The `xmlns:android` declaration on `<widget>` is required for the `android:` attribute.

## Android runtime permission

Declaring `CAMERA` in the manifest is not enough on Android 6 and later: the app must also hold the runtime permission before the WebView can open the camera. Request it before starting the scanner, for example with [cordova-plugin-android-permissions](https://github.com/NeoLSN/cordova-plugin-android-permissions) (a third-party plugin):

```bash
cordova plugin add cordova-plugin-android-permissions
```

```html
<!-- www/index.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
    <style>
      html, body { margin: 0; height: 100%; background: #000; }
      qrgen-scanner { height: 100%; }
    </style>
  </head>
  <body>
    <qrgen-scanner id="scanner" autostart="false" symbologies="qr,ean13,code128"></qrgen-scanner>

    <script>
      window.QRGEN_WASM_BASE = "vendor/qrgen/wasm/";
    </script>
    <script src="vendor/qrgen/qrgen.iife.js"></script>
    <script src="cordova.js"></script>
    <script>
      var scanner = document.getElementById("scanner");

      scanner.addEventListener("scan", function (event) {
        console.log(event.detail.barcode.data);
      });

      function startScanner() {
        scanner.start().catch(function (err) {
          console.warn(err.code, err.message);
        });
      }

      document.addEventListener("deviceready", function () {
        var permissions = window.cordova && cordova.plugins && cordova.plugins.permissions;
        if (!permissions) return startScanner(); // iOS: WKWebView shows its own prompt

        permissions.requestPermission(
          permissions.CAMERA,
          function (status) {
            if (status.hasPermission) startScanner();
            else console.warn("Camera permission denied");
          },
          function () {
            console.warn("Could not request camera permission");
          }
        );
      });
    </script>
  </body>
</html>
```

`autostart="false"` keeps the element from opening the camera before the permission is granted.

Why request it yourself: cordova-android grants the WebView's own camera request, but whether it also shows the Android runtime permission prompt depends on the cordova-android version. Without the runtime permission, `getUserMedia` fails and the scanner reports `camera-permission-denied` or `camera-in-use`. Requesting the permission before `start()` works on every version. If you write native code instead, request `Manifest.permission.CAMERA` in your activity and grant `RESOURCE_VIDEO_CAPTURE` in a custom `WebChromeClient.onPermissionRequest`.

## iOS notes

- With the `scheme` preference set, the app is served from `app://localhost`, which WKWebView treats as a secure context. If the app is loaded from `file://` instead, the camera is unavailable.
- WKWebView asks for camera permission with its own prompt, in addition to the iOS system prompt the first time. This is standard WKWebView behavior.
- The Vibration API is not supported in iOS WebViews, so `vibrate` has no effect there.

## Content Security Policy

Cordova templates include a CSP `<meta>` tag. Extend it so the engine can compile and run:

```html
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self' data: gap: https://ssl.gstatic.com; script-src 'self' 'wasm-unsafe-eval'; worker-src 'self' blob:; connect-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; media-src *"
/>
```

With the wasm bundled in `www/` (as above), `connect-src 'self'` is enough. If you load it from jsDelivr instead, add `https://cdn.jsdelivr.net`. The inline `<script>` blocks in the example above also need `'unsafe-inline'` in `script-src`; move them into a `.js` file to avoid that.

## Troubleshooting

- **`insecure-context`**: the app runs from `file://`. Upgrade to cordova-android 10+ and cordova-ios 6+, and set the iOS `scheme` preference.
- **`camera-permission-denied` on Android**: the runtime permission wasn't granted before starting. Request it first, as shown above.
- **Black preview on iOS, or video opens full screen**: set `AllowInlineMediaPlayback` to `true`.

More in [Troubleshooting](../troubleshooting/).


---

# Electron

URL: https://rockyljewell.github.io/QR-GEN/docs/electron/
Group: Mobile & desktop

> Scan barcodes in Electron apps: camera permission handlers, macOS camera access and NSCameraUsageDescription, offline wasm, and file scanning in the main process.

In Electron, the renderer is Chromium, so the web SDK (`<qrgen-scanner>` or `BarcodeScanner`) works as in a browser. The main process is Node.js, so it can decode image files with `qrgen-sdk/node`. This page covers camera permissions on each OS, packaging the camera usage description on macOS, loading the engine offline, and scanning files from the main process.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

In the renderer, use the SDK like in any web app: see [Web Components](../web-components/), [React](../react/) or [Vue](../vue/). Pages loaded with `loadFile()`, from `http://localhost`, or from a privileged custom scheme (below) are secure contexts, so `getUserMedia` is available.

## Permission handler

Electron approves permission requests by default. Restrict that to camera access from your own pages:

```js
// main.js
const { app, BrowserWindow, session } = require("electron");
const path = require("node:path");

function allowCamera() {
  const ses = session.defaultSession;

  ses.setPermissionRequestHandler((webContents, permission, callback, details) => {
    const ownPage = details.requestingUrl.startsWith("app://") || details.requestingUrl.startsWith("file://");
    const videoOnly = permission === "media" && (details.mediaTypes ?? []).every((type) => type === "video");
    callback(ownPage && videoOnly);
  });

  ses.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
    return permission === "media" && (requestingOrigin.startsWith("app://") || requestingOrigin.startsWith("file://"));
  });
}

app.whenReady().then(() => {
  allowCamera();
  const win = new BrowserWindow({
    width: 900,
    height: 700,
    webPreferences: { preload: path.join(__dirname, "preload.js") },
  });
  win.loadFile(path.join(__dirname, "renderer", "index.html"));
});
```

Adjust the origin checks to match how you load your UI (for example `http://localhost:5173` in development). The permission check handler also controls whether `enumerateDevices()` returns camera labels, which the camera switch button uses.

## macOS camera access

macOS asks the user before any app can use the camera. Ask from the main process before the renderer starts scanning, so the system prompt appears at a sensible time:

```js
const { systemPreferences, shell } = require("electron");

async function ensureCameraAccess() {
  if (process.platform !== "darwin") return true;
  const status = systemPreferences.getMediaAccessStatus("camera");
  if (status === "granted") return true;
  if (status === "not-determined") return systemPreferences.askForMediaAccess("camera");
  // "denied" or "restricted": only the user can change it
  await shell.openExternal("x-apple.systempreferences:com.apple.preference.security?Privacy_Camera");
  return false;
}
```

Call `await ensureCameraAccess()` in `app.whenReady()` or from an IPC handler when the user opens the scanner.

### NSCameraUsageDescription

A packaged macOS app must declare why it uses the camera, or macOS terminates it on first camera access. With the hardened runtime (required for notarization) it also needs the camera entitlement.

electron-builder (`electron-builder.yml`):

```yaml
mac:
  hardenedRuntime: true
  entitlements: build/entitlements.mac.plist
  entitlementsInherit: build/entitlements.mac.plist
  extendInfo:
    NSCameraUsageDescription: The camera is used to scan barcodes and QR codes.
```

`build/entitlements.mac.plist`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.device.camera</key>
    <true/>
  </dict>
</plist>
```

Keep any other entitlements your app already uses. With Electron Forge, set `packagerConfig.extendInfo: { NSCameraUsageDescription: "..." }` and pass the entitlements file through `packagerConfig.osxSign`.

Windows and Linux have no per-app camera declaration. On Windows, the user can block desktop apps from the camera under **Settings > Privacy & security > Camera**; the scanner then reports `camera-permission-denied` or `camera-in-use`.

## Offline engine

By default the decoder wasm is downloaded from jsDelivr on first use. Chromium can't `fetch()` `file://` URLs, so to bundle the wasm with your app, serve the renderer from a privileged custom scheme:

```js
// main.js
const { app, BrowserWindow, net, protocol } = require("electron");
const path = require("node:path");
const { pathToFileURL } = require("node:url");

protocol.registerSchemesAsPrivileged([
  { scheme: "app", privileges: { standard: true, secure: true, supportFetchAPI: true } },
]);

app.whenReady().then(() => {
  const root = path.join(__dirname, "renderer");
  protocol.handle("app", (request) => {
    const { pathname } = new URL(request.url);
    return net.fetch(pathToFileURL(path.join(root, decodeURIComponent(pathname))).toString());
  });

  const win = new BrowserWindow({ width: 900, height: 700 });
  win.loadURL("app://bundle/index.html");
});
```

Copy `node_modules/qrgen-sdk/dist/wasm/*.wasm` into `renderer/qrgen/` as part of your build, and configure the engine in the renderer:

```js
import { configure } from "qrgen-sdk";

configure({ wasmBaseUrl: "/qrgen/" }); // resolves to app://bundle/qrgen/
```

`registerSchemesAsPrivileged` must run before the `ready` event. `protocol.handle` needs Electron 25 or later.

## Scan files in the main process

`qrgen-sdk/node` decodes PNG, JPEG, GIF and BMP files in the main process, with the engine read from `node_modules` (it works inside `app.asar`). Expose it to the renderer over IPC:

```js
// main.js
const { app, BrowserWindow, dialog, ipcMain } = require("electron");
const path = require("node:path");
const { scanFile, parseContent } = require("qrgen-sdk/node");

ipcMain.handle("scanner:scan-files", async () => {
  const { canceled, filePaths } = await dialog.showOpenDialog({
    properties: ["openFile", "multiSelections"],
    filters: [{ name: "Images", extensions: ["png", "jpg", "jpeg", "gif", "bmp"] }],
  });
  if (canceled) return [];

  const results = [];
  for (const file of filePaths) {
    const barcodes = await scanFile(file, { symbologies: ["qr", "data-matrix", "code128", "ean13"] });
    results.push({ file, barcodes: barcodes.map((b) => ({ ...b, parsed: parseContent(b.data, { symbology: b.symbology }) })) });
  }
  return results;
});

app.whenReady().then(() => {
  const win = new BrowserWindow({ webPreferences: { preload: path.join(__dirname, "preload.js") } });
  win.loadFile(path.join(__dirname, "renderer", "index.html"));
});
```

```js
// preload.js
const { contextBridge, ipcRenderer } = require("electron");

contextBridge.exposeInMainWorld("scanner", {
  scanFiles: () => ipcRenderer.invoke("scanner:scan-files"),
});
```

```js
// renderer
const results = await window.scanner.scanFiles();
for (const { file, barcodes } of results) console.log(file, barcodes.map((b) => b.data));
```

For images already in the renderer (drag and drop, paste), `scanImage()` from `qrgen-sdk` decodes them without a round trip. See [Image scanning](../image-scanning/). The main process can also generate barcode files with `generateToFile()`; see [Node.js](../nodejs/).

## Tips

- USB and built-in webcams often have fixed focus and no torch. For small codes, raise `resolution` to `fhd` and position the barcode where the camera can focus.
- Laptop webcams face the user. `camera="back"` falls back to whatever camera exists, and the element mirrors the preview when the camera reports that it faces the user.
- To pick a specific webcam, list them with `Camera.list()` and pass the `deviceId` as `camera`.


---

# Tauri

URL: https://rockyljewell.github.io/QR-GEN/docs/tauri/
Group: Mobile & desktop

> Scan barcodes in Tauri 2 apps with the QRGen web SDK: camera permissions in the system WebView on macOS, Windows and Linux (WebKitGTK), CSP and offline wasm.

Tauri renders your UI in the operating system's WebView: WKWebView on macOS and iOS, WebView2 on Windows, WebKitGTK on Linux and the Android System WebView on Android. QRGen's web SDK runs in all of them, so you use `<qrgen-scanner>` or `BarcodeScanner` from your frontend as in a browser. What differs per OS is how camera permission is granted to the WebView.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

Then follow the guide for your frontend framework: [React](../react/), [Vue](../vue/), [Svelte](../svelte/), [Angular](../angular/) or [Web Components](../web-components/).

Tauri 2 serves the app from `tauri://localhost` (macOS, iOS, Linux) or `http://tauri.localhost` (Windows, Android), and from `http://localhost` during `tauri dev`. All of these are secure contexts, so `getUserMedia` is available.

## Content Security Policy

If `app.security.csp` is set in `tauri.conf.json`, Tauri enforces it. Allow the engine:

```json
{
  "app": {
    "security": {
      "csp": "default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; worker-src 'self' blob:; connect-src 'self' ipc: http://ipc.localhost; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:"
    }
  }
}
```

This assumes the wasm is bundled with the app (below). To load it from jsDelivr instead, add `https://cdn.jsdelivr.net` to `connect-src`.

## Bundle the wasm

Desktop apps should work offline. Copy the wasm files into your frontend's static folder (`public/` for Vite) so they are embedded in the app:

```bash
mkdir -p public/qrgen && cp node_modules/qrgen-sdk/dist/wasm/*.wasm public/qrgen/
```

```ts
import { configure } from "qrgen-sdk";

configure({ wasmBaseUrl: "/qrgen/" });
```

## macOS

WKWebView needs the app to declare camera usage. Tauri 2 merges an `Info.plist` placed next to `tauri.conf.json` into the bundle:

```xml
<!-- src-tauri/Info.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSCameraUsageDescription</key>
    <string>The camera is used to scan barcodes and QR codes.</string>
  </dict>
</plist>
```

Without this key, macOS terminates the app when the page requests the camera. If you sign with the hardened runtime or enable the App Sandbox, also add the `com.apple.security.device.camera` entitlement (`bundle.macOS.entitlements` in `tauri.conf.json`).

The first time, the user sees the macOS camera prompt. WKWebView may also show its own per-site prompt.

> **Tip:** If camera access fails or the app quits when the scanner starts during `tauri dev`, test with a bundled build (`tauri build --debug`) and run the generated `.app`, which always carries the merged `Info.plist`.

## Windows

WebView2 shows a permission prompt the first time the page asks for the camera and remembers the answer. The user must also allow desktop apps to use the camera under **Settings > Privacy & security > Camera**. No configuration is needed.

## Linux

On Linux, Tauri uses WebKitGTK. Camera support there depends on the WebKitGTK build and on GStreamer:

- Install GStreamer plugins so WebKitGTK can open V4L2 cameras. On Debian and Ubuntu: `sudo apt install gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad`.
- WebKitGTK disables media streams by default and denies permission requests unless the app handles them. Enable them and allow camera requests from Rust in your setup hook:

```rust
// src-tauri/src/lib.rs
use tauri::Manager;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            #[cfg(target_os = "linux")]
            {
                let window = app.get_webview_window("main").expect("main window");
                window.with_webview(|webview| {
                    use webkit2gtk::{PermissionRequestExt, SettingsExt, WebViewExt};
                    let view = webview.inner();
                    if let Some(settings) = WebViewExt::settings(&view) {
                        settings.set_enable_media_stream(true);
                    }
                    view.connect_permission_request(|_, request| {
                        request.allow();
                        true
                    });
                })?;
            }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

Add the matching dependency, using the `webkit2gtk` version your Tauri release depends on (check `cargo tree -i webkit2gtk`):

```toml
# src-tauri/Cargo.toml
[target.'cfg(target_os = "linux")'.dependencies]
webkit2gtk = "2.0"
```

Treat this as a starting point: the `webkit2gtk` crate gates some APIs behind version features, and names can change between releases, so check the crate documentation for the version in your lockfile. This handler allows every permission request from your own UI. Narrow it (for example by checking for a `UserMediaPermissionRequest`) if your app loads remote content.

The user running the app needs access to `/dev/video*`, which usually means being in the `video` group. See [Linux & Raspberry Pi](../linux/) for webcam tips.

## iOS and Android

Tauri 2 mobile apps use WKWebView and the Android WebView:

- **iOS**: add `NSCameraUsageDescription` to the iOS `Info.plist` generated under `src-tauri/gen/apple/`.
- **Android**: add `<uses-permission android:name="android.permission.CAMERA" />` to `src-tauri/gen/android/app/src/main/AndroidManifest.xml`. The app must hold the runtime permission, and the WebView must grant the page's camera request; if the scanner reports `camera-permission-denied`, handle `onPermissionRequest` in the activity's `WebChromeClient`.

## Scanning files without the camera

For images the user picks or drops, `scanImage()` decodes them in the WebView, with no native code:

```ts
import { scanImage } from "qrgen-sdk";

const barcodes = await scanImage(file); // a File from <input type="file"> or a drop event
```

See [Image scanning](../image-scanning/).


---

# Titanium

URL: https://rockyljewell.github.io/QR-GEN/docs/titanium/
Group: Mobile & desktop

> A WebView-based guide for Titanium apps: load the hosted QRGen embed page in Ti.UI.WebView and receive scan events through an injected bridge or polling.

There is no native QRGen module for Titanium. This guide shows a WebView-based integration: the app loads QRGen's hosted [embed page](../embed-bridge/) in a `Ti.UI.WebView`, the page does the scanning, and scan events are passed back to your Titanium code. It uses only public Titanium APIs, but it is a guide, not a supported package: test it on your Titanium SDK version and target devices.

Requirements: Titanium SDK 8 or later (WKWebView on iOS, asynchronous `evalJS`), iOS 14.5 or later, and an Android System WebView recent enough to support `getUserMedia`.

## How it works

1. A `Ti.UI.WebView` loads `https://rockyljewell.github.io/QR-GEN/embed/?symbologies=qr,ean13&mode=single`. The page is served over HTTPS, so it is a secure context and may use the camera.
2. The embed page posts every event (`ready`, `scan`, `error`, ...) to any host channel it finds in the page. Titanium doesn't provide one of the standard channels, so the app injects one.
3. The app reads the messages and sends commands back with `evalJS`.

## Camera permission

Declare the permission in `tiapp.xml`:

```xml
<ti:app xmlns:ti="http://ti.tidev.io">
  <ios>
    <plist>
      <dict>
        <key>NSCameraUsageDescription</key>
        <string>The camera is used to scan barcodes and QR codes.</string>
      </dict>
    </plist>
  </ios>
  <android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
      <uses-permission android:name="android.permission.CAMERA" />
    </manifest>
  </android>
</ti:app>
```

Request the runtime permission before opening the scanner:

```js
function withCameraPermission(callback) {
  if (Ti.Media.hasCameraPermissions()) return callback(true);
  Ti.Media.requestCameraPermissions((e) => callback(e.success));
}
```

## Open the scanner

```js
// app/lib/qrgen-scanner.js (Alloy) or Resources/qrgen-scanner.js (classic)
const EMBED_URL = "https://rockyljewell.github.io/QR-GEN/embed/?symbologies=qr,ean13,code128&mode=single";

// Defines window.QRGenBridge inside the page. The embed page posts every event to it.
const BRIDGE = `
  (function () {
    if (window.QRGenBridge) return;
    window.__qrgenQueue = [];
    window.QRGenBridge = {
      postMessage: function (json) {
        if (window.Ti && Ti.App && Ti.App.fireEvent) Ti.App.fireEvent("qrgen:message", { json: json });
        else window.__qrgenQueue.push(json);
      }
    };
  })();
`;

function openScanner(onMessage) {
  const win = Ti.UI.createWindow({ backgroundColor: "#000", title: "Scan" });
  const webView = Ti.UI.createWebView({
    url: EMBED_URL,
    allowsInlineMediaPlayback: true, // iOS: keep the camera preview inline
  });
  win.add(webView);

  const handle = (json) => {
    try {
      onMessage(JSON.parse(json), webView, win);
    } catch (err) {
      Ti.API.warn(`qrgen: bad message ${json}`);
    }
  };

  // Local pages can call Ti.App.fireEvent directly.
  const onFire = (e) => handle(e.json);
  Ti.App.addEventListener("qrgen:message", onFire);

  // The hosted page can't see Ti, so drain the queue by polling.
  let timer = null;
  webView.addEventListener("load", () => {
    webView.evalJS(BRIDGE, () => {});
    if (!timer) {
      timer = setInterval(() => {
        webView.evalJS("JSON.stringify((window.__qrgenQueue || []).splice(0))", (result) => {
          if (!result) return;
          for (const json of JSON.parse(result)) handle(json);
        });
      }, 200);
    }
  });

  win.addEventListener("close", () => {
    clearInterval(timer);
    Ti.App.removeEventListener("qrgen:message", onFire);
  });

  win.open();
  return { win, webView };
}

module.exports = { openScanner };
```

Use it:

```js
const { openScanner } = require("qrgen-scanner");

withCameraPermission((granted) => {
  if (!granted) return alert("Camera permission is required to scan.");

  openScanner((message, webView, win) => {
    if (message.type === "scan") {
      const barcode = message.barcodes[0];
      Ti.API.info(`${barcode.symbology}: ${barcode.data}`);
      win.close();
    } else if (message.type === "error") {
      alert(`${message.code}: ${message.message}`);
    }
  });
});
```

Messages use the [embed envelope](../embed-bridge/#message-envelope): `{ source: "qrgen", version: 1, type, ... }` with `barcodes` for `scan` and `code` and `message` for `error`. Each barcode has the standard [result shape](../concepts/#the-barcode-result).

`Ti.App.fireEvent` is only available to web content that Titanium injects its bridge into, which in practice means local HTML files, and a local page loaded from the file system is not a secure context. With the hosted HTTPS page, the polling path is what delivers messages. The polling interval adds up to 200 ms of latency, which is fine for scanning.

Messages the page posts before the `load` event (and the injection) are lost. In practice that is at most the first `state` message; the `ready` event arrives after the camera starts.

### iOS: script message handler

On iOS, the embed page also posts to `window.webkit.messageHandlers.qrgen`. Titanium SDK 8 and later can register that handler on the WebView, which delivers messages without polling. Check the `Ti.UI.WebView` documentation for your SDK version. Add this inside `openScanner()`, after `handle` is defined:

```js
const isIOS = Ti.Platform.osname === "iphone" || Ti.Platform.osname === "ipad";
if (isIOS) {
  webView.addScriptMessageHandler("qrgen");
  webView.addEventListener("message", (e) => {
    if (e.name === "qrgen") handle(e.body);
  });
}
```

If you use this, skip the `BRIDGE` injection on iOS, otherwise each message arrives twice.

## Send commands

Call `window.qrgen.command()` in the page with `evalJS`:

```js
function command(webView, cmd) {
  webView.evalJS(`window.qrgen && window.qrgen.command(${JSON.stringify(cmd)})`, () => {});
}

command(webView, { type: "pause" });
command(webView, { type: "resume" });
command(webView, { type: "torch", value: true });
command(webView, { type: "switchCamera" });
```

The full command list is in [Embed bridge](../embed-bridge/#host-to-page-commands).

## Limitations

- **Android camera grants.** The app holding the `CAMERA` permission is necessary but not always sufficient: the WebView must also grant the page's camera request. If the page reports `camera-permission-denied` on Android although the app has the permission, your Titanium SDK's WebView doesn't grant web camera requests, and you need a native module that does.
- **Network.** The hosted page and the decoder are loaded from the internet on first use (and then cached). For offline use, host your own copy of the embed page on an HTTPS origin you control; see [self-hosting the embed page](../embed-bridge/#self-host-the-embed-page).
- **Performance.** Scanning runs in the WebView with WebAssembly. It handles everyday QR and retail barcodes well, but a native scanner is faster on low-end devices.


---

# .NET, MAUI & Xamarin

URL: https://rockyljewell.github.io/QR-GEN/docs/dotnet/
Group: Mobile & desktop

> QRGen.Net for .NET: GS1/AAMVA/content parsers, a REST client, local encode/decode with ZXing.Net, and a .NET MAUI camera scanner page.

> **Note:** This page is generated from [`packages/dotnet/README.md`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/dotnet/README.md). Source code: [`packages/dotnet`](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/dotnet).

Open-source (Apache-2.0) barcode, QR code and ID scanning for .NET. `QRGen.Net` gives you:

* **Parsers** for GS1 element strings and Digital Link, AAMVA driver licenses, and QR
  payloads (URL, Wi-Fi, vCard/MECARD, events, payments, products...). Pure C#, no
  network, never throw.
* **`QRGenClient`**, an `HttpClient` client for the QRGen REST API: 26 symbologies
  (including Micro QR, rMQR, MicroPDF417, DataBar Limited, Telepen, DX Film Edge) decoded
  and generated by any QRGen server.
* **`QRGenLocal`**, offline encode/decode with [ZXing.Net](https://github.com/micjahn/ZXing.Net)
  (SVG, PNG and raw pixels).
* **Embed helpers** and a **.NET MAUI** scanner page that hosts the QRGen camera scanner
  in a WebView on Android, iOS, Mac Catalyst and Windows.

It follows the cross-platform
[QRGen specification](https://github.com/Rockyljewell/QR-GEN/blob/main/docs/SPEC.md):
the same symbology ids, the same `Barcode` JSON, the same parser output as the JavaScript,
Python, iOS, Android, Flutter and React Native packages.

Targets `netstandard2.0` (so .NET Framework 4.6.2+ and older Xamarin-era projects) and `net8.0`.

## Install

```bash
dotnet add package QRGen.Net
```

Until the package is on NuGet, build it from source:

```bash
git clone https://github.com/Rockyljewell/QR-GEN.git
cd QR-GEN/packages/dotnet
dotnet pack src/QRGen.Net -c Release -o ./nupkg
dotnet add <your project> package QRGen.Net --source ./nupkg
```

```csharp
using QRGen;
```

## Parsers

```csharp
var gs1 = Gs1Parser.Parse("(01)09501101530003(17)250101(10)ABC123");
gs1["01"];                        // "09501101530003"
gs1.Elements[1].Title;            // "USE BY or EXPIRY"
gs1.Elements[1].Date;             // "2025-01-01"

Gs1Parser.Parse("]C1" + "0109501101530003" + "10ABC123\u001d" + "3103000195");   // raw + GS
Gs1Parser.Parse("https://id.gs1.org/01/09501101530003/10/ABC123?17=250101");      // Digital Link
Gs1Parser.ToHri(gs1);             // "(01)09501101530003(17)250101(10)ABC123"

var license = AamvaParser.Parse(pdf417Text, today: DateTime.Today);
license?.FullName;                // "JANE Q SAMPLE"
license?.DateOfBirth;             // "1990-01-31"
license?.IsUnder21;               // false

var content = ContentParser.Parse("WIFI:T:WPA;S:Home;P:secret;;");
content.Type;                     // "wifi"
content.Ssid;                     // "Home"
QRGenJson.Serialize(content);     // {"type":"wifi","ssid":"Home","password":"secret","security":"WPA","hidden":false}
```

* `ContentParser.Parse(data, symbology?, today?)` returns a `ParsedContent` whose `Type`
  is one of `url`, `gs1-digital-link`, `email`, `phone`, `sms`, `wifi`, `geo`, `contact`,
  `event`, `payment`, `product`, `gs1`, `aamva`, `text` (constants in `ParsedContentType`).
  Only the properties of that type are set; `QRGenJson` omits the rest, so the JSON matches
  the other platforms field for field.
* `Gs1Parser` knows 750+ AIs (fixed and variable lengths, dates with day `00` = last day of
  the month, decimal AIs as `Number`), and `Gs1Parser.AiTable` exposes the definitions.
* `AamvaParser` handles AAMVA versions 1-10, legacy `DAA`/`DCT` names, US `MMDDCCYY` vs
  Canadian `CCYYMMDD` dates and ZIP+4, with an injectable `today` for `Age`, `IsExpired` and
  `IsUnder21`.

## REST client

Run a QRGen server (`qrgen serve` from npm, `qrgen-py serve` from PyPI, or the Docker image),
then:

```csharp
using var client = new QRGenClient("http://localhost:8080");

await client.HealthAsync();                                   // { Ok = true, Version = "1.0.0" }

IReadOnlyList<Barcode> codes = await client.ScanAsync(File.ReadAllBytes("shelf.jpg"), new[] { "retail", "qr" });
foreach (var code in codes)
    Console.WriteLine($"{code.Symbology} {code.Data} -> {code.Parsed?.Type}");

byte[] png = await client.GenerateAsync("(01)09501101530003(10)ABC",
    new GenerateOptions { Symbology = "data-matrix", Format = "png", Gs1 = true, Scale = 6 });
string svg = await client.GenerateSvgAsync("https://example.com", new GenerateOptions { EcLevel = "H" });

ParsedContent parsed = await client.ParseAsync("MECARD:N:Doe,Jane;TEL:+15550100;;");
SymbologySupport support = await client.GetSymbologiesAsync();
```

* `ScanAsync` accepts `byte[]` or a `Stream`, detects PNG/JPEG/GIF/BMP/WebP/TIFF from the
  bytes, and takes `ScanOptions` (`Symbologies`, `TryHarder`, `MaxResults`, `ContentType`).
* Errors from the server (`{ "error": { code, message } }`) throw `QRGenApiException` with
  `StatusCode`, `Code` and `Message`.
* Pass your own `HttpClient` (for `IHttpClientFactory`, auth headers, proxies):
  `new QRGenClient(new Uri("https://scanner.internal/"), httpClient)`.

## Local encode / decode (ZXing.Net)

```csharp
string svg = QRGenLocal.Generate("https://example.com");                                   // SVG
string label = QRGenLocal.Generate("(01)09501101530003(10)ABC",
    new GenerateOptions { Symbology = "code128", Gs1 = true, Hrt = true, Scale = 3 });
byte[] png = QRGenLocal.GeneratePng("hello", new GenerateOptions { Scale = 8, Foreground = "#003366" });
BarcodeImage image = QRGenLocal.GenerateImage("hello");                                     // grayscale pixels

// Decode from a camera frame or bitmap you already have in memory
IReadOnlyList<Barcode> found = QRGenLocal.Decode(luminanceBytes, width, height, new[] { "qr", "ean13" });
IReadOnlyList<Barcode> fromBgra = QRGenLocal.Decode(bgraBytes, width, height, PixelFormat.Bgra32);
```

* Readable locally: qr, data-matrix, aztec, pdf417, maxicode, ean13, ean8, upca, upce, isbn,
  code128, code39, code93, codabar, itf, itf14, databar, databar-expanded
  (`QRGenLocal.ReadableSymbologies`).
* Writable locally: qr, data-matrix, aztec, pdf417, ean13, ean8, upca, upce, isbn, code128,
  code39, code93, codabar, itf, itf14 (`QRGenLocal.WritableSymbologies`). GS1 mode works for
  code128 and qr. For everything else (Micro QR, rMQR, MaxiCode output, DataBar output, GS1
  Data Matrix...) use `QRGenClient`.
* Results use the same `Barcode` shape: GS1 data in HRI form (`(01)...`), UPC-A as 12
  digits, UPC-E as 8 digits, Codabar with start/stop characters. `Location` is the bounding
  box of ZXing's result points (finder-pattern centers for 2D codes), so treat it as
  approximate.
* PNG output comes from a small built-in encoder (`PngEncoder`), so there is no dependency
  on System.Drawing or SkiaSharp. Human readable text (`Hrt`) is rendered in SVG only.

## JSON

`QRGenJson.Options` (camelCase, nulls omitted, relaxed escaping) produces the SPEC JSON:

```csharp
string json = QRGenJson.Serialize(barcode);
// {"data":"https://example.com","symbology":"qr","symbologyName":"QR Code","rawBytes":"aHR0...","contentType":"text",
//  "isGS1":false,"location":{"topLeft":{"x":10,"y":10},...},"frameSize":{"width":1280,"height":720},"orientation":0,
//  "ecLevel":"M","symbologyIdentifier":"]Q1","timestamp":1735689600000}
Barcode? back = QRGenJson.Deserialize<Barcode>(json);
```

`Barcode`, `TrackedBarcode`, `Quad`, `Point` and `ImageSize` are records. Every property
carries a `[JsonPropertyName]`, so any `JsonSerializerOptions` gives the same names.

## Symbologies

```csharp
Symbologies.Resolve(new[] { "QRCode", "retail" });  // ["qr","ean13","ean8","upca","upce","isbn","databar",...]
Symbologies.Resolve("qr, ean-13");                  // ["qr","ean13"]
Symbologies.Get("GS1-128").Id;                      // "code128"
Symbology.DataMatrix.Name;                          // "Data Matrix"
Symbologies.Groups["industrial"];                   // code128 code39 code93 codabar itf itf14 data-matrix
```

Names are matched case-insensitively after removing everything except `[a-z0-9]`.
Unknown names throw `ArgumentException` (or pass `ignoreUnknown: true`).

## .NET MAUI camera scanner

`src/QRGen.Maui` is a sample library (copy it into your app or reference the project) with a
`QRGenScannerPage` that hosts the hosted scanner page
(`https://rockyljewell.github.io/QR-GEN/embed/`) in a WebView and receives results through the
platform channel from SPEC section 5:

| Platform | WebView | Channel used by the page |
| --- | --- | --- |
| Windows | WebView2 | `window.chrome.webview.postMessage(json)` |
| iOS / Mac Catalyst | WKWebView | `window.webkit.messageHandlers.qrgen.postMessage(json)` |
| Android | android.webkit.WebView | `window.QRGenAndroid.postMessage(json)` (JavascriptInterface) |

```csharp
// MauiProgram.cs
builder.UseMauiApp<App>().UseQRGen();

// One-shot scan
var barcode = await QRGenScannerPage.ScanOnceAsync(Navigation,
    new EmbedOptions { Symbologies = { "qr", "ean13" }, Beep = true });

// Continuous / batch scanning
var page = new QRGenScannerPage(new EmbedOptions { Mode = "batch", Symbologies = { "retail" } });
page.Scanned += (s, e) => Debug.WriteLine(string.Join(", ", e.Barcodes.Select(b => b.Data)));
page.Tracked += (s, e) => Debug.WriteLine($"{e.Tracked.Count} codes in view");
page.ScannerError += (s, e) => Debug.WriteLine($"{e.Code}: {e.Message}");
await Navigation.PushAsync(page);
await page.SetTorchAsync(true);
```

`EmbedOptions.BuildUri()`, `EmbedMessage.TryParse(json)` and `EmbedCommands` (in
`QRGen.Net`, namespace `QRGen.Embed`) work with any WebView, for example WPF or WinUI
WebView2, if you do not use MAUI.

Camera permissions (the WebView can only open the camera after the app has the permission):

* **Android**: `AndroidManifest.xml` needs
  `<uses-permission android:name="android.permission.CAMERA" />` and
  `<uses-feature android:name="android.hardware.camera" android:required="false" />`.
  The handler requests the runtime permission and grants the page's `getUserMedia` request in
  `WebChromeClient.OnPermissionRequest`.
* **iOS**: `Info.plist` needs `NSCameraUsageDescription`. WKWebView supports camera access
  from iOS 14.3; the handler creates the WKWebView with inline media playback and grants the
  page's capture request (iOS 15+).
* **Mac Catalyst**: `NSCameraUsageDescription` plus the `com.apple.security.device.camera`
  entitlement.
* **Windows**: add `<DeviceCapability Name="webcam" />` to `Package.appxmanifest`; the handler
  allows WebView2's camera permission request.

### Xamarin

Xamarin and Xamarin.Forms reached end of support on May 1, 2024, so there is no Xamarin
package. Move to .NET MAUI and use `QRGenScannerPage`, or keep your Xamarin app and use
`QRGen.Net` itself (it targets netstandard2.0): the parsers, `QRGenLocal` and `QRGenClient`
work there, and the embed page runs in any WebView through the channels listed above.

## Building from source

```bash
cd packages/dotnet
dotnet build QRGen.Net.sln
dotnet test QRGen.Net.sln
```

The MAUI sample is not part of the solution; build it separately after
`dotnet workload install maui`.

## Status

Version 1.0.0.

* Built and tested with the .NET 8 SDK on Linux: `QRGen.Net` for `netstandard2.0` and `net8.0`,
  and 147 xUnit tests covering symbology resolution, the SPEC GS1 and AAMVA vectors and many
  parser cases, the SPEC section 2 JSON shape, `QRGenLocal` generate-then-decode round trips for
  16 cases (plus PNG, SVG, pixel formats and errors), `QRGenClient` against a fake HTTP handler,
  and the embed helpers.
* Checked by hand during development, not in the test suite: `QRGenClient` against the Python
  `qrgen-py serve` server (scan, generate, parse, errors), with parser JSON identical between
  the two; PNGs from `QRGenLocal` decoded by zxing-cpp.
* The MAUI sample's shared code compiles against Microsoft.Maui.Controls 8. The platform
  handlers (Android, iOS/Mac Catalyst, Windows) have **not** been compiled or run on devices;
  treat them as a documented starting point.
* Not yet published to NuGet.

## License

Apache-2.0. See [LICENSE](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/dotnet/LICENSE) and [NOTICE](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/dotnet/NOTICE).

Created by [Rockyljewell](https://github.com/Rockyljewell).


---

# Node.js

URL: https://rockyljewell.github.io/QR-GEN/docs/nodejs/
Group: Server & Linux

> Decode barcodes in image files and buffers and generate barcode PNG and SVG files in Node.js with qrgen-sdk/node, including serverless deployment notes.

`qrgen-sdk/node` is the Node.js entry point. It loads the WebAssembly engine from `node_modules` (no network access, no native addons) and adds helpers for files and buffers. Use it for batch jobs, upload handlers, label printing and tests. It also runs in Bun.

Requires Node.js 18.17 or later.

## Install

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

```js
// ESM
import { scanFile, generateToFile } from "qrgen-sdk/node";

// CommonJS
const { scanFile, generateToFile } = require("qrgen-sdk/node");
```

`qrgen-sdk/node` re-exports everything from `qrgen-sdk` (`generate`, `scanImage`, `parseContent`, `parseGS1`, `parseAAMVA`, symbology helpers, types), so one import is enough.

> **Warning:** Import from `qrgen-sdk/node`, not `qrgen-sdk`. The browser entry doesn't know where `node_modules` is and would download the engine from jsDelivr at runtime.

## Scan files

```js
import { scanFile } from "qrgen-sdk/node";

const barcodes = await scanFile("label.jpg");
for (const b of barcodes) {
  console.log(b.symbologyName, b.data);
}
```

`scanFile(path, options?)` reads a PNG, JPEG, GIF or BMP file and resolves with every code found (an empty array when there is none). Options:

| Option | Default | Description |
| --- | --- | --- |
| `symbologies` | all | Ids, aliases or groups, as an array or a comma-separated string. Limiting them is faster and avoids false reads. |
| `maxResults` | `255` | Maximum codes to return. |
| `tryHarder` | `true` | Extra effort for small, damaged or rotated codes. Set `false` for speed on clean images. |

Scan a whole folder:

```js
import { readdir } from "node:fs/promises";
import path from "node:path";
import { scanFile } from "qrgen-sdk/node";

const dir = process.argv[2] ?? ".";
for (const name of await readdir(dir)) {
  if (!/\.(png|jpe?g|gif|bmp)$/i.test(name)) continue;
  const barcodes = await scanFile(path.join(dir, name), { symbologies: ["qr", "code128", "data-matrix"] });
  console.log(`${name}: ${barcodes.map((b) => b.data).join(", ") || "(none)"}`);
}
```

## Scan buffers

`scan(input, options?)` accepts a file path, a `Buffer`, a `Uint8Array` or an `ArrayBuffer` of image file bytes. Use it for uploads and data that never touches the disk:

```js
import express from "express";
import { scan, parseContent } from "qrgen-sdk/node";

const app = express();

app.post("/scan", express.raw({ type: "image/*", limit: "10mb" }), async (req, res) => {
  const barcodes = await scan(req.body, { symbologies: ["qr", "ean13", "code128"] });
  res.json(barcodes.map((b) => ({ data: b.data, symbology: b.symbology, parsed: parseContent(b.data, { symbology: b.symbology }) })));
});

app.listen(3000);
```

```bash
curl --data-binary @photo.jpg -H "content-type: image/jpeg" http://localhost:3000/scan
```

For a ready-made HTTP API with multipart and base64 support, use the built-in [REST server](../rest-api/).

`scanImage()` also works in Node when you pass image file bytes (`Uint8Array`, `ArrayBuffer`). Use `scanFile()` or `scan()` for paths; `scanImage()` treats strings as URLs.

### Other formats: PDF, WebP, HEIC, TIFF

The engine decodes PNG, JPEG, GIF and BMP. Convert anything else first. These tools are not part of QRGen:

- **WebP, AVIF, TIFF, HEIC**: with [sharp](https://sharp.pixelplumbing.com/), convert to PNG in memory (HEIC needs a libvips build with HEIF support):

  ```js
  import sharp from "sharp";
  import { scan } from "qrgen-sdk/node";

  const png = await sharp("photo.webp").png().toBuffer();
  const barcodes = await scan(png);
  ```

- **PDF**: render each page to PNG, for example with `pdftoppm` from Poppler (`apt install poppler-utils`, `brew install poppler`), then scan the pages. Use at least 200 DPI for small barcodes:

  ```bash
  pdftoppm -r 300 -png invoice.pdf page
  npx qrgen scan page-*.png --json
  ```

Very large photos decode more slowly. Downscaling to about 2000 px on the long side (with sharp's `resize`) usually keeps codes readable and speeds things up.

## Generate barcodes

```js
import { generateToFile, generatePNG, generate } from "qrgen-sdk/node";

// SVG, PNG or text, chosen by the file extension
await generateToFile("https://example.com", "qr.svg", { ecLevel: "M" });
await generateToFile("(01)09501101530003(17)250101(10)ABC123", "label.png", { symbology: "code128", gs1: true, hrt: true, scale: 3 });
await generateToFile("hello", "hello.txt"); // terminal-style text rendering

// PNG bytes as a Buffer, for HTTP responses or PDFs
const png = await generatePNG("5901234123457", { symbology: "ean13", hrt: true });

// Everything: svg, png (Blob), module matrix, text
const { svg, matrix } = await generate("hello", { symbology: "data-matrix" });
console.log(`${matrix.width}x${matrix.height} modules`);
```

| Function | Returns | Notes |
| --- | --- | --- |
| `generateToFile(data, path, options?)` | `Promise<GeneratedBarcode>` | `.png` writes PNG, `.txt` writes the text rendering, anything else writes SVG with an XML declaration. |
| `generatePNG(data, options?)` | `Promise<Buffer>` | PNG bytes. |
| `generate(data, options?)` | `Promise<GeneratedBarcode>` | `{ symbology, data, svg, png, matrix, text }`. |

Imported from `qrgen-sdk/node`, PNG output honours `foreground` and `background` (including `transparent`), the same as the SVG. All generator options are in [Barcode generation](../barcode-generation/).

## Parse

The parsers are plain functions and have no engine dependency:

```js
import { parseContent, parseGS1 } from "qrgen-sdk/node";

console.log(parseContent("WIFI:T:WPA;S:Office;P:correct horse;;"));
console.log(parseGS1("(01)09501101530003(17)250101(10)ABC123").values);
```

If you only need parsing, `qrgen-sdk/parsers` has them without the engine. See [Parsers](../parsers/).

## Engine loading

The engine binaries are read from `node_modules/zxing-wasm/dist/reader/zxing_reader.wasm` and `.../writer/zxing_writer.wasm` when `qrgen-sdk/node` is imported, and compiled on the first scan and the first generate call. Keep one import per process (module scope) so the compiled engine is reused.

`useLocalEngine()` performs this setup. It runs automatically on import and in every helper; you only need it if you import `scanImage` or `generate` from somewhere else and want to make sure the local engine is used. To provide the binaries yourself (for example from a bundle), call `configure()` from `qrgen-sdk` before importing `qrgen-sdk/node`:

```js
import { readFileSync } from "node:fs";
import { configure } from "qrgen-sdk";

configure({
  readerWasmBinary: readFileSync("./wasm/zxing_reader.wasm"),
  writerWasmBinary: readFileSync("./wasm/zxing_writer.wasm"),
  worker: false,
});

const { scanFile } = await import("qrgen-sdk/node");
```

Decoding runs synchronously inside the wasm module, so a large image occupies the event loop while it decodes (typically tens of milliseconds, more for big photos with `tryHarder`). For high-throughput services, run scans in a pool of [worker threads](https://nodejs.org/api/worker_threads.html); each worker loads its own engine.

## Serverless

The engine is loaded from files in `node_modules`, so the deployment must include them:

- **Keep the packages external.** If your bundler inlines dependencies, mark `qrgen-sdk` and `zxing-wasm` as external and ship them in `node_modules`, so the `.wasm` files stay where the code expects them.
- **AWS Lambda** with esbuild (SAM, CDK `NodejsFunction`, Serverless Framework): with CDK, `bundling: { nodeModules: ["qrgen-sdk", "zxing-wasm"] }` installs them next to the bundle. With plain esbuild, use `--external:qrgen-sdk --external:zxing-wasm` and include `node_modules` in the zip, or use a Lambda layer.
- **Vercel** Node.js functions: file tracing usually picks the files up. If a function fails with `ENOENT ... zxing_reader.wasm`, add them with `includeFiles` in `vercel.json` (`"functions": { "api/scan.js": { "includeFiles": "node_modules/zxing-wasm/dist/**/*.wasm" } }`). For Next.js route handlers, see [Next.js](../nextjs/#scan-uploads-on-the-server).
- **Edge runtimes** (Vercel Edge, Cloudflare Workers) have no file system, so `qrgen-sdk/node` doesn't run there. Use the Node.js runtime, or the [REST API](../rest-api/).

The first request after a cold start pays for reading and compiling the engine (about 1.6 MB of wasm). Warm invocations reuse it. Give functions that decode large photos at least 512 MB of memory.

## TypeScript

Types are included. The Node helpers are typed as:

```ts
function scanFile(path: string, options?: ScanImageOptions): Promise<Barcode[]>;
function scan(input: string | Uint8Array | ArrayBuffer, options?: ScanImageOptions): Promise<Barcode[]>;
function generatePNG(data: string, options?: GenerateOptions): Promise<Buffer>;
function generateToFile(data: string, path: string, options?: GenerateOptions): Promise<GeneratedBarcode>;
function useLocalEngine(): void;
```


---

# CLI

URL: https://rockyljewell.github.io/QR-GEN/docs/cli/
Group: Server & Linux

> Scan, generate and parse barcodes from the command line with the qrgen CLI, and start the REST API server. Commands, flags, JSON output, stdin and exit codes.

The `qrgen` command ships with the `qrgen-sdk` npm package. It scans image files, generates barcode images, parses scanned text, lists symbologies and starts the [REST API](../rest-api/). It runs anywhere Node.js 18.17+ runs, including Raspberry Pi and CI runners.

## Install

Run it without installing:

```bash
npx qrgen-sdk --help
```

Or install it globally, which puts `qrgen` on your `PATH`:

```bash
npm install -g qrgen-sdk
qrgen --help
```

> **Note:** Until the first npm release is published, install the latest build with `npm install -g https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

In a project that depends on `qrgen-sdk`, use `npx qrgen` (the bin is named `qrgen`) or call it from `package.json` scripts.

## Commands

| Command | Aliases | Description |
| --- | --- | --- |
| `qrgen scan <image...>` | `decode`, `read` | Decode barcodes in one or more image files (PNG, JPEG, GIF, BMP). `-` reads an image from stdin. |
| `qrgen generate <data>` | `encode`, `write` | Generate a barcode. Writes a file with `-o`, otherwise prints a text rendering to the terminal. |
| `qrgen parse <data>` | | Parse scanned text with [`parseContent()`](../parsers/) and print JSON. |
| `qrgen serve` | `server` | Start the [REST API](../rest-api/). |
| `qrgen symbologies` | | List symbologies and whether they can be read and written. |

Global flags: `-h`, `--help` prints usage; `-v`, `--version` prints the version.

## scan

```bash
qrgen scan label.jpg
```

```text
QR Code	https://example.com
```

Each code is printed as `symbology name<TAB>data`. With several files, results are grouped under each file name:

```bash
qrgen scan front.png back.png
```

```text
front.png:
  QR Code	https://example.com
back.png:
  (no barcode found)
```

| Flag | Short | Description |
| --- | --- | --- |
| `--symbologies <list>` | `-s` | Only look for these ids, aliases or groups: `-s qr,ean13`, `-s retail`. Default: all. |
| `--json` | | Print JSON instead of text. |
| `--no-parse` | | Leave out the `parsed` field in JSON output. |
| `--fast` | | Skip the thorough search (faster on large, clean images). |

Scanning uses the thorough mode (`tryHarder`) by default, which finds small, rotated and inverted codes. Pass `--fast` to turn it off.

### JSON output

With a single file, `--json` prints an array of [Barcode](../concepts/#the-barcode-result) objects, each with a `parsed` field from `parseContent()`:

```bash
qrgen scan qr.png --json
```

```json
[
  {
    "data": "https://example.com",
    "symbology": "qr",
    "symbologyName": "QR Code",
    "rawBytes": "aHR0cHM6Ly9leGFtcGxlLmNvbQ==",
    "contentType": "text",
    "isGS1": false,
    "location": {
      "topLeft": { "x": 16, "y": 16 },
      "topRight": { "x": 116, "y": 16 },
      "bottomRight": { "x": 116, "y": 116 },
      "bottomLeft": { "x": 16, "y": 116 }
    },
    "frameSize": { "width": 132, "height": 132 },
    "orientation": 0,
    "ecLevel": "Q",
    "symbologyIdentifier": "]Q1",
    "timestamp": 1790467200000,
    "parsed": { "type": "url", "url": "https://example.com" }
  }
]
```

With several files, it prints an array of `{ "file": "...", "barcodes": [...] }` objects instead. Combine with [jq](https://jqlang.github.io/jq/):

```bash
qrgen scan *.png --json | jq -r '.[] | "\(.file)\t\(.barcodes[0].data // "-")"'
```

### stdin

Use `-` as the file name to read an image from standard input:

```bash
curl -s https://example.com/label.png | qrgen scan -
convert page.tiff png:- | qrgen scan - --json   # ImageMagick, for formats the engine can't read
```

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. For `scan`: at least one code was found in at least one file. |
| `1` | Error: bad arguments, an unreadable file, or data that can't be encoded. The message goes to stderr, prefixed with `qrgen:`. |
| `2` | `scan` ran but found no code in any file. |

This makes `scan` easy to use in scripts:

```bash
if qrgen scan receipt.jpg -s qr > /dev/null; then
  echo "Receipt has a QR code"
fi
```

## generate

```bash
qrgen generate "https://example.com" -o qr.svg
qrgen generate "https://example.com" -o qr.png --scale 8 --ec H
qrgen generate "5901234123457" -t ean13 --hrt -o ean.png
qrgen generate "(01)09501101530003(17)250101(10)ABC123" -t data-matrix --gs1 -o dm.png
qrgen generate "Hello"   # prints the code to the terminal
```

All positional arguments after `generate` are joined with spaces, so quotes are only needed for shell special characters. On success with `-o`, it prints `wrote qr.svg (qr, 25x25 modules)`.

| Flag | Short | Description |
| --- | --- | --- |
| `--output <file>` | `-o` | Output file. The extension picks the format: `.png`, `.txt` (text rendering), anything else SVG. Without `-o`, a text rendering is printed. |
| `--symbology <id>` | `-t` | Symbology id or alias. Default `qr`. |
| `--scale <n>` | | Module size in pixels. Default `4`. |
| `--ec <level>` | | Error correction: `L`, `M`, `Q`, `H` for QR, or a percentage for Aztec and PDF417. |
| `--gs1` | | Encode as GS1. Pass the data in HRI form, `(01)...(10)...`. |
| `--hrt` | | Print the human-readable text under linear barcodes. |
| `--no-margin` | | Leave out the quiet zone. |
| `--fg <color>` | | Bar color. Default `#000000`. |
| `--bg <color>` | | Background color or `transparent`. Default `#ffffff`. |

`--fg` and `--bg` apply to SVG and PNG output alike. See [Barcode generation](../barcode-generation/) for what each symbology accepts.

## parse

```bash
qrgen parse "WIFI:T:WPA;S:Office;P:correct horse;;"
```

```json
{
  "type": "wifi",
  "ssid": "Office",
  "password": "correct horse",
  "security": "WPA",
  "hidden": false
}
```

Works for every [content type](../parsers/#parsecontent): URLs, contacts, GS1 element strings, product codes and more. Pass `--symbology` (`-t`) when you know where the text came from, for example `qrgen parse 01234565 -t upce` expands a UPC-E to its GTIN.

## serve

```bash
qrgen serve --port 8080 --host 0.0.0.0
```

```text
qrgen REST API listening on http://0.0.0.0:8080  (GET /health)
```

| Flag | Short | Default | Description |
| --- | --- | --- | --- |
| `--port <n>` | `-p` | `$PORT` or `8080` | Port to listen on. |
| `--host <addr>` | | `$HOST` or `0.0.0.0` | Interface to bind. Use `127.0.0.1` to accept local connections only. |

The server logs one line per request and shuts down cleanly on `SIGINT` and `SIGTERM`. Endpoints are documented in [REST API & Docker](../rest-api/).

## symbologies

```bash
qrgen symbologies
```

```text
qr                 QR Code                  read/write
micro-qr           Micro QR Code            read/write
rmqr               rMQR Code                read/write
data-matrix        Data Matrix              read/write
...
```

`qrgen symbologies --json` prints the full table, including zxing-cpp format names and aliases.

## Examples

Rename scanned documents by the QR code they carry:

```bash
for f in scans/*.jpg; do
  code=$(qrgen scan "$f" -s qr --json | jq -r '.[0].data // empty')
  [ -n "$code" ] && mv "$f" "scans/${code//[^A-Za-z0-9._-]/_}.jpg"
done
```

Generate a sheet of asset labels from a CSV (`id,name`):

```bash
tail -n +2 assets.csv | while IFS=, read -r id name; do
  qrgen generate "https://assets.example.com/$id" -o "labels/$id.svg" --ec M
done
```

Check in CI that a printed label still decodes to the expected value:

```bash
test "$(qrgen scan build/label.png --json | jq -r '.[0].data')" = "https://example.com/p/42"
```


---

# REST API & Docker

URL: https://rockyljewell.github.io/QR-GEN/docs/rest-api/
Group: Server & Linux

> Scan, generate and parse barcodes from any language over HTTP with qrgen serve or the Docker image: endpoints, curl examples, errors, CORS, framework mounting and client code.

QRGen includes a small HTTP server that exposes scanning, generation and parsing as a REST API. Run it with `qrgen serve`, with Docker, or mount it inside your own Node.js app. Any language that can send an HTTP request can then decode barcodes in images and create barcode images.

The server processes images on the machine it runs on and stores nothing.

## Run the server

### Docker

```bash
docker run --rm -p 8080:8080 ghcr.io/rockyljewell/qr-gen:latest
```

```bash
curl http://localhost:8080/health
```

```json
{ "ok": true, "name": "qrgen", "version": "1.0.0", "docs": "https://rockyljewell.github.io/QR-GEN/docs/rest-api/" }
```

The image is built from the repository's root `Dockerfile` and runs `qrgen serve` on port 8080. To build it yourself:

```bash
git clone https://github.com/Rockyljewell/QR-GEN.git
cd QR-GEN
docker build -t qrgen .
docker run --rm -p 8080:8080 qrgen
```

With Docker Compose:

```yaml
# compose.yaml
services:
  qrgen:
    image: ghcr.io/rockyljewell/qr-gen:latest
    ports:
      - "8080:8080"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:8080/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3
```

Other services in the same Compose project reach it at `http://qrgen:8080`.

### Node.js

```bash
npx qrgen-sdk serve --port 8080
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz` and run `npx qrgen serve`.

`--host` sets the interface (default `0.0.0.0`), and the `PORT` and `HOST` environment variables are used when the flags are absent. See [CLI](../cli/#serve).

> **Warning:** The API has no authentication or rate limiting. Keep it on a private network, or put it behind a reverse proxy or API gateway that adds them, before exposing it to the internet.

## Endpoints

| Method | Path | Request | Response |
| --- | --- | --- | --- |
| `GET` | `/health` (also `/`) | | `{ ok, name, version, docs }` |
| `GET` | `/v1/symbologies` | | `{ read: [...], write: [...], details: [{ id, name, kind, aliases }] }` |
| `POST` | `/v1/scan` | Raw image bytes, `multipart/form-data`, or JSON with base64 | `{ barcodes: [...] }` |
| `GET` | `/v1/generate` | Options in the query string | Image bytes |
| `POST` | `/v1/generate` | Options as a JSON body | Image bytes |
| `POST` | `/v1/parse` | JSON `{ "data": "..." }` or raw text | `ParsedContent` |

## Scan

`POST /v1/scan` accepts the image in three ways. The server reads PNG, JPEG, GIF and BMP.

**Raw bytes.** Send the file as the body with any image content type:

```bash
curl --data-binary @photo.jpg -H 'content-type: image/jpeg' http://localhost:8080/v1/scan
```

**Multipart.** The first file part is used (or a field named `image` or `file`). An optional `symbologies` field limits the search:

```bash
curl -F image=@photo.jpg http://localhost:8080/v1/scan
curl -F image=@photo.jpg -F symbologies=qr,ean13 http://localhost:8080/v1/scan
```

**JSON.** `image` is base64 or a data URL. Build the body in a file, because base64 images quickly exceed the shell's argument length limit:

```bash
printf '{"image":"%s","symbologies":["qr"]}' "$(base64 < photo.jpg | tr -d '\n')" > body.json
curl -H 'content-type: application/json' --data-binary @body.json http://localhost:8080/v1/scan
```

Options can go in the query string for every body type, in the JSON body, or in multipart fields. Body options override query options:

| Option | Default | Description |
| --- | --- | --- |
| `symbologies` | all | Comma-separated in the query (`?symbologies=qr,ean13`), an array or string in JSON. |
| `tryHarder` | `true` | `false` is faster on clean, high-contrast images. |
| `maxResults` | `255` | Maximum codes to return. Integer from 1 to 255. |
| `parse` | `true` | Add a `parsed` field (from [`parseContent()`](../parsers/)) to each result. |

Booleans in the query string accept `true`/`false`, `1`/`0`, `yes`/`no` and `on`/`off`.

Response:

```json
{
  "barcodes": [
    {
      "data": "https://example.com",
      "symbology": "qr",
      "symbologyName": "QR Code",
      "rawBytes": "aHR0cHM6Ly9leGFtcGxlLmNvbQ==",
      "contentType": "text",
      "isGS1": false,
      "location": {
        "topLeft": { "x": 16, "y": 16 },
        "topRight": { "x": 116, "y": 16 },
        "bottomRight": { "x": 116, "y": 116 },
        "bottomLeft": { "x": 16, "y": 116 }
      },
      "frameSize": { "width": 132, "height": 132 },
      "orientation": 0,
      "ecLevel": "Q",
      "symbologyIdentifier": "]Q1",
      "timestamp": 1790467200000,
      "parsed": { "type": "url", "url": "https://example.com" }
    }
  ]
}
```

Each entry is a [Barcode](../concepts/#the-barcode-result). An image without codes returns `200` with `{ "barcodes": [] }`.

## Generate

`GET /v1/generate` takes options in the query string, which makes it usable directly as an image URL:

```bash
curl -o qr.svg "http://localhost:8080/v1/generate?data=https%3A%2F%2Fexample.com&symbology=qr"
curl -o qr.png "http://localhost:8080/v1/generate?data=hello&format=png&scale=8&ecLevel=H"
```

```html
<img src="http://localhost:8080/v1/generate?data=5901234123457&symbology=ean13&hrt=1" alt="EAN-13 barcode" />
```

`POST /v1/generate` takes the same options as JSON, which is easier for long or binary-looking data:

```bash
curl -o label.png -H 'content-type: application/json' \
  -d '{"data": "(01)09501101530003(17)250101(10)ABC123", "symbology": "code128", "gs1": true, "hrt": true, "format": "png", "scale": 3}' \
  http://localhost:8080/v1/generate
```

| Option | Default | Description |
| --- | --- | --- |
| `data` | required | The text to encode (`text` and `value` are accepted as aliases). |
| `symbology` | `qr` | Any [writable symbology](../symbologies/). |
| `format` | `svg` | `svg` (`image/svg+xml`), `png` (`image/png`) or `txt` (`text/plain` text rendering). |
| `scale` | `4` | Module size in pixels. |
| `ecLevel` | encoder default | Error correction (`ec` is accepted too): `L`, `M`, `Q`, `H` for QR. |
| `gs1` | `false` | Encode as GS1; `data` in HRI form `(01)...`. |
| `hrt` | `false` | Human-readable text under linear barcodes. |
| `margin` | `true` | Quiet zone. |
| `foreground`, `background` | `#000000`, `#ffffff` | Colors for SVG and PNG output (`background` may be `transparent`). |
| `rotate` | `0` | `0`, `90`, `180` or `270`. |

Remember to URL-encode query values: `#` in colors becomes `%23`, `(` and `)` in GS1 data are safe.

## Parse

```bash
curl -H 'content-type: application/json' -d '{"data": "WIFI:T:WPA;S:Office;P:secret;;"}' http://localhost:8080/v1/parse
```

```json
{ "type": "wifi", "ssid": "Office", "password": "secret", "security": "WPA", "hidden": false }
```

A body that isn't JSON is parsed as raw text, so `curl --data-binary 'tel:+15551234567' http://localhost:8080/v1/parse` works too. The response is a [`ParsedContent`](../parsers/) object.

## Errors

Errors return a 4xx or 5xx status with a JSON body:

```json
{ "error": { "code": "bad-request", "message": "Cannot encode as EAN-13: Invalid character at position 1 in input (digits and \"+\" or space only)" } }
```

| Status | `code` | Cause |
| --- | --- | --- |
| 400 | `bad-request` | Invalid JSON, missing `data` or `image`, an empty image, an unknown symbology, or data the symbology can't encode. |
| 400 | `unsupported` | The requested operation isn't available for that symbology. |
| 404 | `not-found` | Unknown path or method. |
| 413 | `payload-too-large` | The body is larger than `maxBodyBytes` (15 MiB by default). |
| 500 | `engine-load-failed` | The engine couldn't be loaded (for example, the wasm files are missing from the deployment). |
| 500 | `unknown` | Anything else. |

## CORS

The server sends `Access-Control-Allow-Origin: *`, allows `GET`, `POST` and `OPTIONS` with a `Content-Type` header, and answers preflight `OPTIONS` requests with `204`. Browser apps on any origin can call it. To restrict or disable CORS, create the server in code (below) with the `cors` option.

## Mount in your own server

`qrgen-sdk/server` exports `createServer(options)`, which returns a Node `http.Server`, and `createHandler(options)`, which returns a `(req, res)` handler for any framework built on Node's HTTP module.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `maxBodyBytes` | `number` | `15728640` (15 MiB) | Largest accepted request body. |
| `cors` | `string \| false` | `"*"` | `Access-Control-Allow-Origin` value, or `false` to send no CORS headers. |
| `log` | `boolean` | `false` | Log one line per request to the console. |

### Plain Node.js

```js
import { createServer } from "qrgen-sdk/server";

createServer({ cors: "https://app.example.com", maxBodyBytes: 5 * 1024 * 1024, log: true }).listen(8080);
```

### Express

Mount the handler under a prefix. It reads the raw request body itself, and it also works after `express.json()` or `express.raw()` (it uses `req.body` when a parser already consumed the stream). Mount it before multipart parsers such as multer, which move the file out of the body.

```js
import express from "express";
import { createHandler } from "qrgen-sdk/server";

const app = express();

app.use("/qrgen", createHandler({ maxBodyBytes: 10 * 1024 * 1024 }));

app.use(express.json());
app.post("/api/orders", (req, res) => res.json({ ok: true }));

app.listen(3000); // POST http://localhost:3000/qrgen/v1/scan
```

### Fastify

Fastify parses bodies before handlers run. Register the handler in an encapsulated plugin that leaves bodies unread, then hand the raw request over:

```js
import Fastify from "fastify";
import { createHandler } from "qrgen-sdk/server";

const app = Fastify();
const qrgen = createHandler();

app.register(
  async (scope) => {
    scope.removeAllContentTypeParsers();
    scope.addContentTypeParser("*", (_request, _payload, done) => done(null));
    scope.all("/*", (request, reply) => {
      reply.hijack();
      request.raw.url = request.raw.url.slice("/qrgen".length) || "/";
      qrgen(request.raw, reply.raw);
    });
  },
  { prefix: "/qrgen" }
);

await app.listen({ port: 3000 });
```

The content-type parser change only applies inside the plugin, so the rest of your Fastify routes keep their normal body parsing.

### Hono on Node.js

With `@hono/node-server`, route the prefix to QRGen at the Node level and everything else to Hono:

```js
import { createServer } from "node:http";
import { getRequestListener } from "@hono/node-server";
import { Hono } from "hono";
import { createHandler } from "qrgen-sdk/server";

const app = new Hono();
app.get("/", (c) => c.text("Hello"));

const hono = getRequestListener(app.fetch);
const qrgen = createHandler();

createServer((req, res) => {
  if (req.url === "/qrgen" || req.url?.startsWith("/qrgen/")) {
    req.url = req.url.slice("/qrgen".length) || "/";
    return qrgen(req, res);
  }
  return hono(req, res);
}).listen(3000);
```

The handler needs Node's `IncomingMessage` and `ServerResponse`, so it doesn't run on edge runtimes such as Cloudflare Workers.

## Clients

Every example sends a JPEG as raw bytes to `/v1/scan` and prints each result.

### Python

With [requests](https://requests.readthedocs.io/):

```python
import requests

BASE = "http://localhost:8080"

with open("photo.jpg", "rb") as f:
    r = requests.post(f"{BASE}/v1/scan", params={"symbologies": "qr,ean13"}, data=f, headers={"Content-Type": "image/jpeg"})
r.raise_for_status()
for b in r.json()["barcodes"]:
    print(b["symbology"], b["data"])

png = requests.get(f"{BASE}/v1/generate", params={"data": "https://example.com", "format": "png", "scale": 8})
png.raise_for_status()
with open("qr.png", "wb") as out:
    out.write(png.content)
```

To decode locally in Python without a server, use the [Python SDK](../python/).

### Go

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

type Barcode struct {
	Data          string `json:"data"`
	Symbology     string `json:"symbology"`
	SymbologyName string `json:"symbologyName"`
}

func main() {
	f, err := os.Open("photo.jpg")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	resp, err := http.Post("http://localhost:8080/v1/scan?symbologies=qr,ean13", "image/jpeg", f)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("scan failed: %s", resp.Status)
	}

	var result struct {
		Barcodes []Barcode `json:"barcodes"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	for _, b := range result.Barcodes {
		fmt.Printf("%s: %s\n", b.SymbologyName, b.Data)
	}
}
```

### Java

With the built-in `java.net.http.HttpClient` (Java 11+). Parse the JSON with the library you already use, such as Jackson or Gson:

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;

public class ScanExample {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newHttpClient();

    HttpRequest request = HttpRequest.newBuilder(URI.create("http://localhost:8080/v1/scan?symbologies=qr,ean13"))
        .header("Content-Type", "image/jpeg")
        .POST(HttpRequest.BodyPublishers.ofFile(Path.of("photo.jpg")))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() != 200) throw new RuntimeException("Scan failed: " + response.body());
    System.out.println(response.body()); // {"barcodes":[...]}
  }
}
```

### C#

With `HttpClient` and `System.Net.Http.Json` (.NET 6+):

```csharp
using System.Net.Http.Headers;
using System.Net.Http.Json;

using var http = new HttpClient { BaseAddress = new Uri("http://localhost:8080") };

using var content = new ByteArrayContent(await File.ReadAllBytesAsync("photo.jpg"));
content.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");

using var response = await http.PostAsync("/v1/scan?symbologies=qr,ean13", content);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadFromJsonAsync<ScanResult>();
foreach (var b in result!.Barcodes)
    Console.WriteLine($"{b.SymbologyName}: {b.Data}");

record Barcode(string Data, string Symbology, string SymbologyName);
record ScanResult(List<Barcode> Barcodes);
```

For on-device scanning in .NET apps, see the [.NET SDK](../dotnet/).

### PHP

With the curl extension, as a multipart upload:

```php
<?php
$ch = curl_init("http://localhost:8080/v1/scan?symbologies=qr,ean13");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => ["image" => new CURLFile("photo.jpg", "image/jpeg")],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($body === false || $status !== 200) {
    throw new RuntimeException("Scan failed ($status): $body");
}

foreach (json_decode($body, true)["barcodes"] as $b) {
    echo $b["symbologyName"], ": ", $b["data"], PHP_EOL;
}
```

### Ruby

With `Net::HTTP` from the standard library:

```ruby
require "json"
require "net/http"

uri = URI("http://localhost:8080/v1/scan?symbologies=qr,ean13")
request = Net::HTTP::Post.new(uri, "Content-Type" => "image/jpeg")
request.body = File.binread("photo.jpg")

response = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(request) }
raise "Scan failed (#{response.code}): #{response.body}" unless response.is_a?(Net::HTTPSuccess)

JSON.parse(response.body)["barcodes"].each do |b|
  puts "#{b["symbologyName"]}: #{b["data"]}"
end
```

## Deployment tips

- **Sizing.** Decoding is CPU-bound and single-threaded per process. For more throughput, run several containers (or processes) behind a load balancer rather than a bigger single instance.
- **Image size.** Phone photos decode faster when downscaled to about 2000 px on the long side before upload.
- **Timeouts.** Most scans complete in well under a second. Set client timeouts of a few seconds to cover large images with `tryHarder`.
- **Health checks.** Use `GET /health`.


---

# Python

URL: https://rockyljewell.github.io/QR-GEN/docs/python/
Group: Server & Linux

> Scan images and webcams, generate barcodes, parse GS1 and driver licenses, and run the REST API with the qrgen-sdk Python package.

> **Note:** This page is generated from [`packages/python/README.md`](https://github.com/Rockyljewell/QR-GEN/blob/main/packages/python/README.md). Source code: [`packages/python`](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/python).

Open-source (Apache-2.0) barcode, QR code and ID scanning for Python. Decode 26 symbologies
from images and webcams, generate SVG/PNG barcodes, parse GS1, AAMVA driver licenses
and QR payloads (Wi-Fi, vCard, payments…), and run a REST API with the standard
library only.

It is the Python member of the [QRGen](https://github.com/Rockyljewell/QR-GEN) family.
Symbology ids, the result JSON, parsers and the REST API follow the shared
[specification](https://github.com/Rockyljewell/QR-GEN/blob/main/docs/SPEC.md), so
results are interchangeable with the JavaScript, iOS, Android, Flutter, React Native
and .NET packages. Decoding and encoding use [zxing-cpp](https://github.com/zxing-cpp/zxing-cpp).

## Install

```bash
pip install qrgen-sdk                 # scan, generate, parse, REST server
pip install "qrgen-sdk[camera]"       # + webcam / Raspberry Pi camera (OpenCV, numpy)
```

Until the package is published on PyPI, install it from GitHub:

```bash
pip install "git+https://github.com/Rockyljewell/QR-GEN.git#subdirectory=packages/python"
pip install "qrgen-sdk[camera] @ git+https://github.com/Rockyljewell/QR-GEN.git#subdirectory=packages/python"
```

Requirements: Python 3.9+, `zxing-cpp>=3.1` and Pillow (installed automatically).
zxing-cpp 3.1 ships wheels for Python 3.10+ on Linux x86-64/aarch64 (glibc 2.28+), macOS and
Windows; on Python 3.9 or other platforms pip builds it from source, which needs CMake and a
C++17 compiler.

## Quick start

```python
import qrgen_sdk

# Generate
svg = qrgen_sdk.generate("https://example.com")                      # SVG string
png = qrgen_sdk.generate("https://example.com", format="png", scale=8)  # PNG bytes
qrgen_sdk.save("(01)09501101530003(17)250101(10)ABC123", "label.png",
               symbology="code128", gs1=True, hrt=True)

# Scan: a path, bytes, a file object, a PIL image or a numpy (OpenCV) array
for code in qrgen_sdk.scan("label.png", symbologies=["qr", "retail", "code128"]):
    print(code.symbology, code.data)          # code128 (01)09501101530003(17)250101(10)ABC123
    print(code.to_dict())                      # SPEC section 2 JSON (camelCase)
    print(qrgen_sdk.parse_content(code.data))  # {"type": "gs1", "gs1": {...}}
```

### Scanning options

```python
qrgen_sdk.scan(image, symbologies=None, try_harder=True, max_results=None) -> list[Barcode]
qrgen_sdk.scan_file(path, **same_options)
```

* `symbologies`: ids, aliases or groups (`"qr"`, `"QRCode"`, `"ean-13"`, `"retail"`,
  `"2d"`, `"qr,ean13"`...). `None` means `all`.
* `try_harder`: also search rotated, downscaled and inverted variants and retry with a
  second binarizer. Use `False` for speed.
* GS1 data comes back in HRI form (`"(01)...(10)..."`) with `is_gs1=True`.
* UPC-A is reported as 12 digits and UPC-E as 8 digits; books report as `ean13` unless
  you ask only for `isbn`.

`Barcode` fields: `data`, `symbology`, `symbology_name`, `raw_bytes`, `content_type`,
`is_gs1`, `location` (`Quad` of `Point`s), `frame_size`, `orientation`, `ec_level`,
`symbology_identifier`, `timestamp`. `Barcode.to_dict()` returns the camelCase JSON
shape shared by every QRGen platform; `Barcode.from_dict()` reads it back.

### Generating options

```python
qrgen_sdk.generate(data, symbology="qr", format="svg", scale=4, ec_level=None,
                   gs1=False, hrt=False, margin=True, foreground=None, background=None)
qrgen_sdk.save(data, "out.svg", **options)   # format from the extension
```

* Writable: qr, micro-qr, rmqr, data-matrix, aztec, pdf417, micro-pdf417, maxicode,
  ean13, ean8, upca, upce, isbn, code128, code39, code93, codabar, itf, itf14, databar,
  databar-expanded, databar-limited, code32, pzn, telepen, dx-film-edge.
* `format`: `svg` (returns `str`) or `png` (returns `bytes`); `jpeg`, `webp`, `bmp`,
  `gif` and `tiff` work too.
* `ec_level`: `L`/`M`/`Q`/`H` for QR codes; `0`-`8` or a percentage for PDF417/Aztec.
* `foreground`/`background`: `#rrggbb`, `#rrggbbaa` or `"transparent"`.
* `data` may be `bytes` for binary 2D codes.

Invalid input raises `qrgen_sdk.GenerateError` (a `ValueError`).

## Parsers

Pure Python, never raise, and return dicts with the SPEC's camelCase keys so
`json.dumps()` matches the other platforms.

```python
from qrgen_sdk import parse_content, parse_gs1, parse_aamva

parse_content("WIFI:T:WPA;S:Home;P:secret;;")
# {'type': 'wifi', 'ssid': 'Home', 'password': 'secret', 'security': 'WPA', 'hidden': False}

parse_gs1("(01)09501101530003(17)250101(10)ABC123")["values"]
# {'01': '09501101530003', '17': '250101', '10': 'ABC123'}

parse_gs1("https://id.gs1.org/01/09501101530003/10/ABC123?17=250101")   # Digital Link
parse_gs1("]C1" "0109501101530003" "10ABC123\x1d" "3103000195")           # raw + GS
# element 3103 -> {"ai": "3103", "title": "NET WEIGHT (kg)", "value": "000195", "number": 0.195}

license = parse_aamva(pdf417_text)          # North American DL/ID cards
license["fullName"], license["dateOfBirth"], license["age"], license["isUnder21"]
```

* `parse_content` types: `url`, `gs1-digital-link`, `email` (mailto:, MATMSG, SMTP),
  `phone`, `sms`, `wifi` (with backslash escapes), `geo`, `contact` (vCard, MECARD),
  `event` (VEVENT), `payment` (EPC/SEPA `BCD`, `bitcoin:`, `ethereum:`, `upi://pay`,
  `payto://` and other coins as `other`), `product` (GTIN with check digit), `gs1`,
  `aamva` and `text`. Pass `symbology=` as a hint (for example to read 8 digits as UPC-E).
* `parse_gs1` knows 750+ AIs (counting decimal variants) (00-03, 10-17, 20-22, 235, 240-243, 250-255, 30, 310n-369n,
  37, 390n-395n, 400-403, 410-417, 420-427, 4300-4333, 7001-7259, 8001-8200, 90-99)
  with fixed/variable lengths, dates as ISO `date` (day `00` = last day of the month)
  and decimal AIs as `number`.
* `parse_aamva(data, today=date(...))` handles AAMVA versions 1-10, legacy `DAA`/`DCT`
  names, US (`MMDDCCYY`) vs Canadian (`CCYYMMDD`) dates, ZIP+4, and computes `age`,
  `isExpired` and `isUnder21` against an injectable `today`.

## Command line

The console script is `qrgen-py` (so it does not clash with the Node `qrgen` CLI);
`qrgen-sdk` and `python -m qrgen_sdk` are aliases.

```bash
qrgen-py scan photo.jpg shelf.png --symbologies qr,ean13      # "symbology<TAB>data"
qrgen-py scan photo.jpg --json --parse                         # SPEC JSON + parsed content
qrgen-py generate "https://example.com" -o qr.svg
qrgen-py generate "(01)09501101530003(10)ABC" --symbology code128 --gs1 --hrt -o label.png
qrgen-py generate "hello" --format png --scale 8 > hello.png
qrgen-py parse "WIFI:T:WPA;S:Home;P:secret;;"
qrgen-py parse --unescape '@\n\x1e\rANSI 636014100002DL...'   # AAMVA with escapes
qrgen-py camera --mode batch --symbologies retail
qrgen-py serve --port 8080
qrgen-py symbologies
```

Exit codes: `0` success, `1` nothing found / not parseable, `2` error.

## Webcam scanning

```python
from qrgen_sdk.camera import Camera, scan_camera

# One-liner: preview window, highlight quads, prints every new code
scan_camera(on_scan=lambda codes: print([c.data for c in codes]))

# Full control
with Camera(device=0, symbologies=["qr", "ean13"], mode="continuous",
            duplicate_filter=1000, width=1280, height=720) as cam:
    for frame, result in cam.frames():
        for code in result.new:           # passed the duplicate filter
            print(code.symbology, code.data)
```

* `mode`: `single` (stop after the first scan), `continuous`, or `batch` (tracks many
  codes with stable ids; `result.tracked` holds `TrackedBarcode`s with `id`,
  `first_seen`, `last_seen`, `count`, dropped after 500 ms unseen).
* `duplicate_filter`: ms before the same symbology+data is reported again; `0` reports
  every frame, `-1` once per session.
* `scan_area=(x, y, w, h)` (0..1) restricts decoding to a region of interest.
* `Camera.process(frame)` works on any BGR/grayscale numpy frame, so you can plug in
  picamera2, GStreamer, RTSP streams or video files. `DuplicateFilter` and
  `BatchTracker` (in `qrgen_sdk.tracking`) are plain Python classes with an injectable
  clock.
* With omitted `now_ms`, duplicate/tracking windows use monotonic elapsed time;
  barcode and track timestamps remain milliseconds since the Unix epoch. Explicit
  `now_ms` supplies both timeouts and timestamps. Mixing default and injected calls
  rebases retained history using timestamp differences at each transition, preserving
  the previous behavior; use a consistent timestamp basis when mixing clocks.

### Optional spatial observations

Batch tracking aggregates equal symbology/payload values by default. To keep
separate observations of identical codes at different positions, opt in explicitly:

```python
with Camera(mode="batch", spatial_tracking=True, track_max_jump=3.0) as cam:
    for frame, result in cam.frames():
        for observed in result.tracked:
            print(observed.id, observed.data, observed.count)
```

For external frame sources, use `BatchTracker(timeout_ms=500, spatial=True,
max_jump=3.0)`. Each record must have finite corner coordinates, a nonzero extent,
and a consistent positive `frame_size`. Narrow linear-code quads are supported.
Invalid records or a negative/nonfinite movement gate raise `ValueError`; a rejected
update leaves tracker state and clock history unchanged. The options are constructor
policy; `spatial`, `max_jump` and `max_association_work` are read-only.

Within each exact symbology/payload group, spatial tracking maximizes one-to-one
matches inside the movement gate, then minimizes total center movement. The gate
is `max(detection width, height, 1) * max_jump` source pixels. IDs are opaque strings,
fresh after expiry, coordinate resets and `clear()` within that tracker object.
An observed track's `count` is the number of frames matched to it.

Supply `tracker.update(codes, frame_size=Size(width, height))` when a frame's size is
known, including blank frames. Records must carry the same positive size; the
argument does not fill missing record metadata. A size change removes old spatial
tracks before matching. `Camera.process` supplies full-frame size automatically and
keeps ROI coordinates in that space. Successful camera opens and closes reset only
spatial history; removed tracks are reported once in the next successful
`FrameResult`, even if intervening frame processing fails. Idempotent or failed
opens do not reset it. When directly processing different same-size sources, call
`tracker.clear()` yourself. A gap without frames preserves tracks until their normal
timeout is checked on the next update.

`result.new` and `on_scan` remain payload duplicate-filter notifications; use
`tracked`, `added` or `on_track` for observed tracks. Resets do not clear payload
report history. Spatial IDs do not establish persistent physical identity through
crossings, camera motion, occlusion or leaving view. Decoder duplicates/misses can
also affect observed counts. These tracks and frame counts are not confirmed
receiving quantities. Dense repeated payload groups require more assignment work;
`max_results` limits each decoded frame, not the number of retained unseen tracks.
The default `max_association_work=250_000` conservatively sums `n*n*(m+n)` over
each exact symbology/payload group with `n` detections and `m > 0` surviving prior
tracks. It includes prior columns outside the movement gate. New-only, expired and
coordinate-reset groups do not spend assignment units. A frame over this budget
raises `ValueError` before allocating matching matrices or changing clocks, tracks,
events, queued source removals or Camera duplicate-report history. There is no
truncation or fallback matching policy. The limit must be a positive integer and is
an assignment-work bound, not a whole-frame time guarantee. For large offline
workloads, explicitly raise `BatchTracker(max_association_work=...)` or
`Camera(track_max_association_work=...)`; measure performance for your hardware.

* The `camera` extra installs `opencv-python-headless`, which has no GUI. For a preview
  window install `opencv-python` instead; without GUI support scanning continues and a
  warning is printed. Press `q` or Esc to quit the window.

## REST server

A dependency-free implementation of SPEC section 6 (`http.server.ThreadingHTTPServer`,
CORS enabled, JSON errors).

```bash
qrgen-py serve --port 8080                 # localhost only
qrgen-py serve --host 0.0.0.0 --port 8080  # reachable from other machines
```

```bash
curl -s localhost:8080/health
curl -s -X POST --data-binary @photo.png -H "Content-Type: image/png" "localhost:8080/v1/scan?symbologies=qr,ean13"
curl -s -X POST -H "Content-Type: application/json" \
     -d '{"image":"data:image/png;base64,iVBOR...","symbologies":["qr"],"tryHarder":true}' localhost:8080/v1/scan
curl -s "localhost:8080/v1/generate?data=hello&format=png&scale=8" -o hello.png
curl -s -X POST -H "Content-Type: application/json" -d '{"data":"hello","symbology":"qr","format":"svg"}' localhost:8080/v1/generate
curl -s -X POST -H "Content-Type: application/json" -d '{"data":"WIFI:T:WPA;S:Home;P:x;;"}' localhost:8080/v1/parse
```

| Method | Path | Notes |
| --- | --- | --- |
| GET | `/health` | `{"ok": true, "version": "1.0.0"}` |
| GET | `/v1/symbologies` | `{"read": [...], "write": [...]}` |
| POST | `/v1/scan` | raw image bytes or JSON `{image, symbologies, tryHarder, maxResults}`; `?symbologies=` |
| GET/POST | `/v1/generate` | `data, symbology, format, scale, ecLevel, gs1, hrt, margin, foreground, background` |
| POST | `/v1/parse` | JSON `{data}` (or a text body); `type: "gs1"/"aamva"` runs a specific parser |

Errors look like `{"error": {"code": "bad-request", "message": "..."}}`. Embed it with
`qrgen_sdk.server.create_server(host, port)` or `start_in_thread()`. The server has no
authentication; put it behind a reverse proxy before exposing it publicly.

## Linux and Raspberry Pi

* **Wheels:** zxing-cpp publishes manylinux wheels (glibc 2.28+) for x86-64 and aarch64 on
  Python 3.10+, so `pip install qrgen-sdk` works on 64-bit Raspberry Pi OS (Bookworm) and
  Ubuntu without a compiler. On 32-bit (armv7) systems or Python 3.9, pip builds zxing-cpp from
  source: `sudo apt install cmake g++ python3-dev` first (it takes a while on a Pi), or use a
  64-bit OS.
* **Virtual environments:** Raspberry Pi OS and recent Debian/Ubuntu block system-wide
  pip installs. Use `python3 -m venv ~/qrgen && ~/qrgen/bin/pip install "qrgen-sdk[camera]"`.
  To reuse the distro's OpenCV and picamera2, create the venv with
  `--system-site-packages` and `sudo apt install python3-opencv python3-picamera2`.
* **USB webcams** use V4L2: `qrgen-py camera --device 0` (or `/dev/video0`). Add your
  user to the `video` group if you get `camera-in-use`/permission errors
  (`sudo usermod -aG video $USER`, then log in again). `v4l2-ctl --list-devices` lists cameras.
* **Raspberry Pi Camera Module** (libcamera): run `qrgen-py camera --device picamera2`
  (uses picamera2), or wrap OpenCV with `libcamerify qrgen-py camera`.
* **Headless / SSH:** use `--no-window` (or `show_window=False`) and `--json` to stream
  results; `qrgen-py camera --no-window --json | jq .data`.
* **Performance:** on a Pi 4/5 use 640x480 or 1280x720 capture (`--width 1280 --height 720`),
  narrow `--symbologies`, and set a `--scan-area`. Camera frames use a fast decoder
  configuration by default (`try_harder=False`).
* **Run as a service:** `qrgen-py serve --host 0.0.0.0` under systemd gives every device
  on the network a barcode API.

## Status

Version 1.0.0.

* Tested (pytest, 220 tests, Linux x86-64, Python 3.11, zxing-cpp 3.1.1): symbology
  ids/aliases/groups and zxing-cpp mapping; generate -> scan round trips through real
  PNGs for 26 symbologies (including GS1 Code 128, QR and Data Matrix); the SPEC GS1 and
  AAMVA vectors plus many parser cases; duplicate filter and batch tracker; camera
  frame processing on synthetic frames and a generated video file; the REST server on
  an ephemeral port; the CLI.
* Not tested here: physical webcams, Raspberry Pi hardware and picamera2, the OpenCV
  preview window, Python versions other than 3.11 (3.9+ is supported by design),
  Windows and macOS.
* Not yet on PyPI; install from GitHub as shown above.

## License

Apache-2.0. See [LICENSE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/python/LICENSE) and [NOTICE](https://github.com/Rockyljewell/QR-GEN/tree/main/packages/python/NOTICE).

Created by [Rockyljewell](https://github.com/Rockyljewell).

### Reversed-reflectance decoding

The default `scan(..., try_harder=True)` also finds reversed-reflectance
(light-on-dark) codes. zxing-cpp searches QR, Micro QR, rMQR, Data Matrix and Aztec
in both polarities within the normal pass. PDF417, MaxiCode and linear codes need
an explicit pass over an inverted copy, and it runs only when the normal pass found
nothing. An image holding only inverted codes is decoded in full, up to
`max_results`, and identical payloads at separate positions remain separate
detections. A mixed-polarity image (a normal code next to an inverted linear code)
returns the normal code only; crop and scan the inverted region separately if you
need both. The alternate-binarizer retry also applies to the inverted pass. Set
`try_harder=False`, or low-level `decode(..., try_invert=False)`, to skip inversion.
Caller PIL images and NumPy arrays are not modified.


---

# Linux & Raspberry Pi

URL: https://rockyljewell.github.io/QR-GEN/docs/linux/
Group: Server & Linux

> Scan barcodes on Linux servers, desktops and Raspberry Pi: the Node CLI, the REST API and Docker, Python with OpenCV webcams, and a Chromium kiosk running the web scanner.

QRGen runs on Linux in several ways. Pick the one that matches where your images come from and who looks at the screen.

| Option | Best for | Camera | Guide |
| --- | --- | --- | --- |
| Node CLI (`qrgen`) | Scanning and generating image files, scripts, cron jobs | No | [CLI](../cli/) |
| REST API or Docker | A barcode service for other machines or languages | No | [REST API & Docker](../rest-api/) |
| Python package with OpenCV | Headless scanning from USB webcams and Raspberry Pi camera modules | Yes | [Python](../python/#webcam-scanning) |
| Chromium kiosk with `<qrgen-scanner>` | A touchscreen scanning station with the full scanner UI | Yes | Below |

## Node CLI

Install Node.js 18.17 or later (Raspberry Pi OS Bookworm and current Ubuntu releases ship a recent enough `nodejs` package; otherwise use [NodeSource](https://github.com/nodesource/distributions) or nvm), then:

```bash
npm install -g qrgen-sdk
qrgen scan label.jpg
qrgen generate "https://example.com" -o qr.png
```

> **Note:** Until the first npm release is published, install the latest build with `npm install -g https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

The engine is WebAssembly, so there are no native modules to compile: the same package runs on x86-64, arm64 and 32-bit ARM. Every command and flag is in [CLI](../cli/).

A watch folder that decodes new scans into a JSON Lines file (uses `inotifywait` from `inotify-tools` and `jq`, both external packages):

```bash
inotifywait -m -e close_write --format '%w%f' ~/incoming | while read -r file; do
  qrgen scan "$file" --json | jq -c --arg file "$file" '{file: $file, barcodes: .}' >> ~/results.jsonl
done
```

## REST API and Docker

```bash
docker run -d --name qrgen --restart unless-stopped -p 8080:8080 ghcr.io/rockyljewell/qr-gen:latest
```

Or without Docker, as a systemd service:

```ini
# /etc/systemd/system/qrgen.service
[Unit]
Description=QRGen REST API
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/bin/env qrgen serve --host 127.0.0.1 --port 8080
Restart=on-failure
DynamicUser=yes

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now qrgen
curl http://127.0.0.1:8080/health
```

Use `--host 0.0.0.0` to accept connections from other machines, and put a reverse proxy with authentication in front if the network isn't trusted. Endpoints are documented in [REST API & Docker](../rest-api/).

## Python and OpenCV

For headless camera scanning (a Pi on a conveyor, a USB webcam at a door), the Python package reads frames with OpenCV or picamera2 and prints or posts results, with no browser involved. It is documented on its own page: see [webcam scanning](../python/#webcam-scanning) and the [Linux and Raspberry Pi notes](../python/#linux-and-raspberry-pi) for wheels, virtual environments, the `video` group, camera modules and performance.

## Chromium kiosk

To give a scanning station the full scanner UI (viewfinder, highlights, feedback), run the web scanner full screen in Chromium.

### 1. The page

```html
<!-- ~/kiosk/index.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Scanner</title>
    <style>
      html, body { margin: 0; height: 100%; background: #000; }
      qrgen-scanner { position: fixed; inset: 0; height: 100%; }
    </style>
  </head>
  <body>
    <qrgen-scanner symbologies="qr,code128,ean13" duplicate-filter="3000" resolution="hd"></qrgen-scanner>
    <script type="module">
      import { configure } from "./vendor/qrgen.js";

      configure({ wasmBaseUrl: "./vendor/wasm/" });

      document.querySelector("qrgen-scanner").addEventListener("scan", async ({ detail }) => {
        // Hand the result to your backend, for example a local service on port 3000.
        await fetch("http://localhost:3000/scanned", {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify(detail.barcode),
        }).catch(() => undefined);
      });
    </script>
  </body>
</html>
```

Copy the SDK and engine next to it so the kiosk works offline:

```bash
mkdir -p ~/kiosk/vendor/wasm
cp node_modules/qrgen-sdk/dist/browser/qrgen.js ~/kiosk/vendor/
cp node_modules/qrgen-sdk/dist/wasm/*.wasm ~/kiosk/vendor/wasm/
```

### 2. Serve it on localhost

The camera needs a secure context, and `http://localhost` counts as one. Any static server works:

```bash
python3 -m http.server 8000 --bind 127.0.0.1 --directory ~/kiosk
```

### 3. Start Chromium in kiosk mode

```bash
chromium --kiosk --noerrdialogs --disable-session-crashed-bubble \
  --use-fake-ui-for-media-stream \
  --autoplay-policy=no-user-gesture-required \
  http://localhost:8000/
```

On Raspberry Pi OS the binary may be called `chromium-browser`.

| Flag | Why |
| --- | --- |
| `--kiosk` | Full screen, no browser UI. |
| `--use-fake-ui-for-media-stream` | Accepts camera permission requests automatically, so nobody has to click **Allow** on an unattended kiosk. |
| `--autoplay-policy=no-user-gesture-required` | Lets the scan beep play without a tap first. |
| `--noerrdialogs`, `--disable-session-crashed-bubble` | No restore prompts after a power cut. |

> **Warning:** `--use-fake-ui-for-media-stream` grants camera access to every page the browser opens. Use it only on a dedicated kiosk that loads your own page.

If the page is served from another machine over plain HTTP, Chromium treats it as insecure. Serve it over HTTPS, or explicitly allow that origin (for kiosks on a trusted network only): `--unsafely-treat-insecure-origin-as-secure=http://192.168.1.10:8000 --user-data-dir=$HOME/.kiosk-profile`.

Start Chromium from your desktop session's autostart, or from a systemd user unit, so it comes back after a reboot.

## USB webcams

Linux exposes webcams through Video4Linux (V4L2), and Chromium and OpenCV both read them. A few tips:

- **Permissions.** The user running the browser or script needs access to `/dev/video*`. Add it to the `video` group: `sudo usermod -aG video $USER`, then log in again.
- **Find cameras.** Install `v4l-utils` and run `v4l2-ctl --list-devices`. A single webcam often has several `/dev/video` nodes; the first one of each camera is usually the video stream, the others are metadata.
- **Formats.** `v4l2-ctl -d /dev/video0 --list-formats-ext` shows supported resolutions and frame rates. Over USB 2, 1080p at 30 fps usually needs MJPEG; 720p is a good default for scanning (`resolution="hd"`).
- **Focus.** Many cheap webcams have fixed focus tuned for faces at arm's length, so small barcodes up close are blurry. Hold codes further away and raise the resolution, or use an autofocus webcam. On cameras with manual controls, `v4l2-ctl -d /dev/video0 --list-ctrls` shows them; for example `v4l2-ctl -d /dev/video0 -c focus_automatic_continuous=0 -c focus_absolute=40` (control names vary by camera and kernel version; older kernels use `focus_auto`).
- **Exposure.** Under bright lights or with glossy labels, lowering exposure reduces glare: look for `auto_exposure` and `exposure_time_absolute` in `--list-ctrls`.
- **Choosing a camera in the browser.** With several webcams, list them with `Camera.list()` and set the element's `camera` attribute to the `deviceId` you want. Labels are available after the first permission grant (immediately with `--use-fake-ui-for-media-stream`).

### Raspberry Pi camera modules

Camera modules on the CSI connector use libcamera. Browser support for them depends on the OS release and Chromium's configuration, so for a browser kiosk a USB (UVC) webcam is the most reliable choice. With a camera module, the Python package with picamera2 is the simplest route; see the [Python Linux notes](../python/#linux-and-raspberry-pi).

## ARM64 and Raspberry Pi notes

- **Use a 64-bit OS.** Raspberry Pi OS (64-bit) on a Pi 4 or Pi 5 runs everything on this page. Node.js and the npm package also work on 32-bit ARM, but prebuilt Python wheels for the engine are only published for 64-bit ARM.
- **Docker images.** Check which architectures an image provides with `docker buildx imagetools inspect ghcr.io/rockyljewell/qr-gen:latest`. If there is no `linux/arm64` entry, build the image on the device: `docker build -t qrgen .` in a clone of the repository.
- **Performance.** WebAssembly decoding is CPU-bound. On a Pi, limit `symbologies` to what you scan, keep `resolution="hd"` or lower, and for the web scanner consider a smaller decode size: after the element's `ready` event, call `el.scanner.setOptions({ maxDecodeSize: 960 })`, where `el` is the `<qrgen-scanner>` element.
- **Cooling.** Continuous camera decoding keeps a core busy. A Pi without a heatsink can throttle after a few minutes; `vcgencmd get_throttled` reports it.


---

# Barcode scanning

URL: https://rockyljewell.github.io/QR-GEN/docs/barcode-scanning/
Group: Features

> Scan barcodes and QR codes from the camera: single and continuous modes, symbology choice, viewfinders, scan areas, duplicate filtering, feedback, torch and zoom.

This page covers camera scanning of one code at a time, the most common use: checkout, ticket validation, login QR codes, asset lookup. The examples use the [`<qrgen-scanner>` element](../web-components/); every option exists on [`BarcodeScanner`](../javascript/) under the camelCase name, and on the React and Vue components as props.

To scan many codes at once, see [Batch scanning](../batch-scanning/). For photos and files, see [Image scanning](../image-scanning/).

## Single and continuous

**Single** mode stops after the first code. Use it when a scan completes a task, such as filling a form field or logging in:

```html
<qrgen-scanner id="scanner" mode="single" symbologies="qr" style="height: 360px"></qrgen-scanner>

<script type="module">
  import "qrgen-sdk/elements";

  const scanner = document.getElementById("scanner");
  scanner.addEventListener("scan", async ({ detail }) => {
    const ok = await submitToken(detail.barcode.data);
    if (!ok) scanner.resume(); // wrong code: scan again
  });

  async function submitToken(token) {
    const res = await fetch("/api/login/qr", { method: "POST", body: token });
    return res.ok;
  }
</script>
```

After a scan the scanner pauses and shows a **Scan again** button. Call `resume()` to continue from code, or `stop()` to release the camera.

**Continuous** mode (the default) keeps scanning and reports each new code once per duplicate-filter window. Use it for queues of items: checkout, receiving parcels, validating a line of tickets.

```html
<qrgen-scanner mode="continuous" symbologies="retail" duplicate-filter="3000" style="height: 360px"></qrgen-scanner>
```

## Choose symbologies

By default the scanner looks for all 26 symbologies. Each one you enable costs decode time on every frame and adds a small chance of misreading something else as that type. Enable only what you expect:

| Use case | `symbologies` |
| --- | --- |
| QR codes only (logins, links, payments, Wi-Fi) | `qr` |
| Retail products, groceries | `retail` (EAN-13, EAN-8, UPC-A, UPC-E, ISBN, GS1 DataBar) |
| Books | `ean13` (ISBNs are EAN-13 barcodes starting with 978 or 979) |
| Shipping labels, warehouses | `code128,data-matrix,qr` or `gs1` |
| Healthcare packs, UDI | `data-matrix,code128` (GS1) |
| Boarding passes, tickets | `pdf417,aztec,qr` |
| Driver licenses and IDs | `pdf417` (see [ID scanning](../id-scanning/)) |
| Asset tags, industrial | `code128,code39,qr,data-matrix` |
| Automotive (VIN) | `code39,data-matrix` |

Ids, aliases and groups can be mixed: `symbologies="retail,qr"`. The full list is on the [Symbologies](../symbologies/) page.

> **Note:** ISBN and ITF-14 are special cases of EAN-13 and Interleaved 2 of 5. When the parent symbology is enabled too (as with the default `all` or `retail`), a book barcode is reported as `ean13` and an ITF-14 as `itf`; enable `isbn` or `itf14` without the parent to get the specific id. `parseContent()` still tells you the kind: see [product codes](../parsers/#product-codes).

Linear-only sets (for example `retail`) switch the viewfinder to a wide `line` style automatically.

## Viewfinder styles

| `viewfinder` | Looks like | Use for |
| --- | --- | --- |
| `frame` | Square with rounded corner marks | QR, Data Matrix and mixed sets (default) |
| `line` | Wide, short box with a pulsing laser line | Linear barcodes (default when only linear symbologies are enabled) |
| `none` | Nothing; the whole preview is scanned | Documents, large labels, or your own overlay |

The viewfinder dims the area around it and flashes the accent color on a successful scan. Code highlights are drawn on the video wherever the code is detected.

## Scan area

The element only decodes the part of the frame inside the viewfinder, plus a small margin, and updates this region automatically on resize. That makes scanning faster and prevents picking up a neighboring code by accident. With `viewfinder="none"`, the whole visible preview is decoded.

To set the region yourself, pass normalized coordinates of the camera frame (`x,y,width,height`, each 0 to 1):

```html
<!-- A horizontal band across the middle of the frame -->
<qrgen-scanner scan-area="0.05,0.4,0.9,0.2" viewfinder="none"></qrgen-scanner>
```

With `BarcodeScanner` there is no viewfinder, so the default is the full frame. Set `scanArea` to speed it up:

```js
const scanner = new BarcodeScanner({ video, scanArea: { x: 0.2, y: 0.2, width: 0.6, height: 0.6 } });
```

The `location` of each result is always in full-frame pixels, whatever the scan area.

## Duplicate filter

A code held in front of the camera is seen in every frame. `duplicate-filter` sets how long, in milliseconds, the same code (same symbology and data) is suppressed after it was reported:

| Value | Behavior | Typical use |
| --- | --- | --- |
| `1000` (default) | Once per second | General use |
| `3000` to `5000` | Once per few seconds | Checkout: prevents double-scanning an item that stays in view |
| `0` | Every frame | Measuring, custom logic |
| `-1` | Once until `start()` or `resume()` | Collecting a set of unique codes |

To count the same product twice, the user moves it out of view and back after the window, or you use `-1` with your own "add again" button. See [Core concepts](../concepts/#duplicate-filter).

## Feedback

A short beep and a 40 ms vibration confirm each scan. Turn them off with `beep="false"` and `vibrate="false"`. Browsers only play audio after a user gesture, so on iOS the beep works when scanning starts from a tap; use `autostart="false"` to show a **Start scanning** button that provides one.

For custom feedback, turn off the built-in beep and react to `scan` yourself:

```js
const ok = new Audio("/sounds/ok.mp3");

scanner.setAttribute("beep", "false");
scanner.addEventListener("scan", () => {
  ok.currentTime = 0;
  void ok.play();
  navigator.vibrate?.([30, 40, 30]);
});
```

With `BarcodeScanner`, you can tune the built-in tone through `scanner.feedback.options` (`frequency` in Hz, default 2100; `duration` in ms, default 90; `volume` 0 to 1, default 0.12).

## Torch and zoom

The element shows torch, zoom and camera-switch buttons when the device supports them. Camera controls are also available from code:

```js
scanner.addEventListener("ready", async () => {
  const caps = scanner.scanner.camera.capabilities; // { torch, zoom, focusMode }
  if (caps.torch) await scanner.setTorch(true);
  if (caps.zoom) await scanner.setZoom(Math.min(2, caps.zoom.max));
});
```

`setTorch()` and `setZoom()` resolve to `false` when the camera doesn't support them. Support depends on the browser and device: Chrome on Android exposes both on most phones, while Safari on iOS offers limited or no support. The `torch` attribute turns the torch on as soon as the camera is ready.

For small codes, request `resolution="fhd"` and keep the barcode sharply focused. 2× zoom lets the user hold the phone further away, where the camera can focus; move only as close as the lens can focus.

## Difficult codes

| Problem | Option |
| --- | --- |
| Small, blurry or damaged codes | `try-harder` (more CPU per frame) and `resolution="fhd"` |
| White-on-black (inverted) codes | Checked on every other frame by default. With `BarcodeScanner`, `tryInvert: true` checks every frame. |
| Several codes in view, you want all of them | `max-results="5"` in continuous mode, or [batch mode](../batch-scanning/) |
| Slow phones | Fewer symbologies, `resolution="sd"`, and a smaller `maxDecodeSize` on the underlying scanner |

More in [Troubleshooting](../troubleshooting/#codes-are-not-found).

## Handle results

`data` is the raw text. Use `parseContent()` to find out what it is and act on it:

```js
import "qrgen-sdk/elements";
import { parseContent } from "qrgen-sdk";

document.querySelector("qrgen-scanner").addEventListener("scan", ({ detail }) => {
  const { barcode } = detail;
  const content = parseContent(barcode.data, { symbology: barcode.symbology });

  switch (content.type) {
    case "url":
      if (new URL(content.url).hostname === "example.com") location.href = content.url; // only follow trusted hosts
      break;
    case "wifi":
      showWifi(content.ssid, content.password ?? "");
      break;
    case "product":
      lookUpProduct(content.gtin); // 14-digit GTIN, zero padded
      break;
    case "gs1":
      console.log("Batch", content.gs1.values["10"], "expires", content.gs1.elements.find((e) => e.ai === "17")?.date);
      break;
    default:
      console.log(barcode.symbologyName, barcode.data);
  }
});

function showWifi(ssid, password) {
  alert(`Network: ${ssid}\nPassword: ${password}`);
}

function lookUpProduct(gtin) {
  console.log("Look up", gtin);
}
```

Pass the `symbology` hint so numeric data is interpreted correctly (for example an 8-digit UPC-E). Every content type is described in [Parsers](../parsers/).

> **Warning:** Scanned data is untrusted input. Don't open scanned URLs automatically without checking the host, and never insert `data` into the page as HTML.


---

# Batch scanning

URL: https://rockyljewell.github.io/QR-GEN/docs/batch-scanning/
Group: Features

> Scan and track many barcodes at once with batch mode: track events, TrackedBarcode ids, an accessible selection list, counts of codes in view, and BarcodeTracker for custom interfaces.

Batch mode finds every code in view on every frame and follows each one as the camera moves. Each physical code gets a stable `id` while it stays in view, so two identical cans on a shelf are two separate tracks. Use it for shelf audits, receiving pallets with many labels, counting stock, or letting the user pick one code among several.

## Turn it on

```html
<qrgen-scanner mode="batch" symbologies="retail,code128" style="height: 70vh"></qrgen-scanner>
```

In batch mode the element:

- Decodes the whole visible preview (the viewfinder is hidden) and up to 20 codes per frame (`max-results`).
- Draws a highlight on every tracked code, with a label when eight or fewer are in view.
- Shows an automatic counter pill such as "3 barcodes in view". Choosing results leaves this detected total unchanged.
- Lists decoded values below the camera preview. Choose a row by touch, mouse or keyboard; selected codes show a check mark in the preview.
- Keeps selected results available after they leave the camera view, with an "out of view" label, until you deselect or clear them.
- Beeps (at most every 250 ms) when a code value appears for the first time.

The same mode is available as `mode: "batch"` on `BarcodeScanner`, the React `QRGenScanner` and the Vue component.

## Events

| Event | `detail` | When |
| --- | --- | --- |
| `track` | `{ tracked, added, removed }` | After every decoded frame or when a symbology change removes disabled tracks. `tracked` is everything currently in view. |
| `scan` | `{ barcodes, barcode }` | A code value appeared for the first time this session. |
| `select` | `{ barcode, selected, selection }` | A result's selection changed (`selected` is `true` when it was added). |

`track` is the source of truth for what is in view. It fires up to 24 times per second, so update your UI from it sparingly (for example with `requestAnimationFrame`).

`scan` is filtered by the duplicate filter, which defaults to `-1` in batch mode: each distinct value (symbology plus data) is reported once until the scanner restarts. Two identical cans produce one `scan` event but two tracks. Use `track` to count.

## TrackedBarcode

Tracked results are regular [Barcode](../concepts/#the-barcode-result) objects with four extra fields:

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | `number` | Stable id for as long as the code stays in view. |
| `firstSeen` | `number` | When the track started (ms since epoch). |
| `lastSeen` | `number` | When the code was last decoded. |
| `count` | `number` | Number of frames the code was decoded in. |

`location` is updated every frame, in camera-frame pixels. A track is dropped when its code hasn't been decoded for 500 ms; if the code comes back later, it gets a new `id`.

## Choose results

Use the buttons below the live preview. Each row has an `aria-pressed` state and supports Enter or Space. The preview highlights indicate locations and selection state; choose results from the list. Different tracks with identical values have separate rows and track ids.

```html
<qrgen-scanner id="scanner" mode="batch" symbologies="code128" style="height: 60vh"></qrgen-scanner>
<button id="confirm" disabled>Pick selected</button>
<button id="clear">Clear</button>

<script type="module">
  import "qrgen-sdk/elements";

  const scanner = document.getElementById("scanner");
  const confirm = document.getElementById("confirm");

  scanner.addEventListener("select", ({ detail }) => {
    confirm.disabled = detail.selection.length === 0;
    confirm.textContent = "Pick selected";
  });

  confirm.addEventListener("click", () => {
    const codes = scanner.selection.map((b) => b.data);
    console.log("Picked", codes);
    scanner.clearSelection();
  });

  document.getElementById("clear").addEventListener("click", () => scanner.clearSelection());
</script>
```

`selection` holds chosen `TrackedBarcode` objects captured at the moment of selection. Activate a selected row again to deselect it. `clearSelection()` empties the selection and fires `select` with `barcode: null`. Custom controls can call `selectBarcode(trackId, selected?)`; it returns `false` for unknown tracks or outside batch mode. Changing mode, recreating the scanner through its camera, resolution or worker attributes, or removing it from the page clears the session's selection. If it was nonempty, this sends one `select` reset with `barcode: null`, `selected: false` and `selection: []`. Changing enabled symbologies removes disabled in-view tracks immediately, including while paused; chosen snapshots remain available as out-of-view selections until you deselect or clear them.

## Count items in view

This example counts how many of each product are visible, and adds the current view to an inventory when the user confirms. Counting from the current view (instead of summing every `added` event) avoids double counting when a code briefly leaves the frame and comes back with a new track id.

```html
<qrgen-scanner id="scanner" mode="batch" symbologies="retail" hint="Frame the whole shelf, then tap Count" style="height: 60vh"></qrgen-scanner>
<p id="live">Nothing in view</p>
<button id="count">Count</button>
<table id="inventory"></table>

<script type="module">
  import "qrgen-sdk/elements";

  const scanner = document.getElementById("scanner");
  const live = document.getElementById("live");
  const inventory = new Map(); // GTIN -> quantity
  let inView = new Map();

  scanner.addEventListener("track", ({ detail }) => {
    inView = new Map();
    for (const code of detail.tracked) inView.set(code.data, (inView.get(code.data) ?? 0) + 1);
    live.textContent = inView.size
      ? [...inView].map(([gtin, n]) => `${gtin} x${n}`).join(", ")
      : "Nothing in view";
  });

  document.getElementById("count").addEventListener("click", () => {
    for (const [gtin, n] of inView) inventory.set(gtin, (inventory.get(gtin) ?? 0) + n);
    const table = document.getElementById("inventory");
    table.replaceChildren(
      ...[...inventory].map(([gtin, n]) => {
        const row = document.createElement("tr");
        row.append(Object.assign(document.createElement("td"), { textContent: gtin }), Object.assign(document.createElement("td"), { textContent: String(n) }));
        return row;
      })
    );
  });
</script>
```

Tips for reliable counts:

- Hold the camera still for a moment so every code is decoded; wait until the live count stops changing.
- Use `resolution="fhd"` for shelves with many small codes, so each code has enough pixels.
- Codes that are too small, too angled or occluded won't be found. Show the live count so the user can reposition.

## Batch mode with BarcodeScanner

```ts
import { BarcodeScanner } from "qrgen-sdk";

const scanner = new BarcodeScanner({ video, mode: "batch", symbologies: ["qr", "data-matrix"] });

scanner.on("track", ({ tracked, added, removed }) => {
  for (const t of added) console.log("new", t.id, t.data);
  for (const t of removed) console.log("gone", t.id, t.data);
  drawBoxes(tracked); // see UI customization for mapping locations to the screen
});

await scanner.start();
```

`BarcodeScanner`'s `track` payload also includes `updated`: the tracks that were seen again in this frame. The tracker is available as `scanner.tracker` (`size`, `all`, `clear()`).

Switching an existing scanner with `scanner.setOptions({ mode: "batch" })` applies the batch defaults (`maxResults: 20`, `duplicateFilter: -1`, `tryHarder: true`) unless you set those options yourself.

## BarcodeTracker for custom interfaces

`BarcodeTracker` is the tracking logic on its own. Feed it detections from any source (camera frames, a video file, your own decoder) and it assigns ids:

```ts
import { BarcodeScanner, BarcodeTracker } from "qrgen-sdk";

const tracker = new BarcodeTracker({ timeout: 800, maxJump: 3 });
const scanner = new BarcodeScanner({ video, mode: "continuous", maxResults: 10, duplicateFilter: 0 });

scanner.on("frame", ({ barcodes }) => {
  const { tracked, added, removed } = tracker.update(barcodes);
  render(tracked, added, removed);
});
```

| Option | Default | Meaning |
| --- | --- | --- |
| `timeout` | `500` | Drop a track after this many milliseconds without a detection. |
| `maxJump` | `3` | How far a code may move between frames and keep its id, relative to its size. |

`update(detections, now?)` returns `{ tracked, added, updated, removed }`. Detections match an existing track only when symbology and data are equal and the code is within `maxJump` code-sizes of the track's last position, so identical codes in different places get separate ids.

## Performance

Batch mode decodes the full frame for up to 20 codes, which is heavier than single-code scanning. On older phones:

- Limit `symbologies` to what is on the shelf.
- Lower `max-results` if you never have that many codes in view.
- Keep `resolution="hd"` unless codes are small.
- Check `scanner.stats` (`decodeMs`, `fps`) on the underlying `BarcodeScanner` to measure.


---

# ID scanning

URL: https://rockyljewell.github.io/QR-GEN/docs/id-scanning/
Group: Features

> Read the PDF417 barcode on North American driver licenses and ID cards and parse it with parseAAMVA: fields, age verification, privacy guidance and limitations.

Driver licenses and state ID cards in the United States and Canada carry a PDF417 barcode on the back, encoded according to the AAMVA DL/ID Card Design Standard. It contains the holder's name, date of birth, address, document number, expiry date and physical description. QRGen scans the PDF417 and `parseAAMVA()` turns its contents into a structured object, entirely on the device.

Typical uses: age checks at a counter, pre-filling a form, visitor check-in.

## Scan a license

```html
<qrgen-scanner id="id-scanner" symbologies="pdf417" mode="single" viewfinder="line" resolution="fhd" try-harder hint="Scan the barcode on the back of the card" style="height: 420px"></qrgen-scanner>
<pre id="out"></pre>

<script type="module">
  import "qrgen-sdk/elements";
  import { parseAAMVA } from "qrgen-sdk";

  const scanner = document.getElementById("id-scanner");
  scanner.addEventListener("scan", ({ detail }) => {
    const id = parseAAMVA(detail.barcode.data);
    if (!id) {
      document.getElementById("out").textContent = "This barcode is not a driver license or ID card.";
      scanner.resume();
      return;
    }
    document.getElementById("out").textContent = `${id.fullName}, born ${id.dateOfBirth}, expires ${id.expiryDate}`;
  });
</script>
```

Settings that help with license barcodes:

- `symbologies="pdf417"`: nothing else is on the back of the card that you want.
- `viewfinder="line"`: a wide box that matches the barcode's shape.
- `resolution="fhd"` and `try-harder`: PDF417 on licenses is dense, and older cards are worn.

Ask the user to lay the card flat, fill most of the viewfinder with the barcode, and avoid glare from overhead lights (tilt the card slightly). Turning on the torch helps in dim places but can cause glare on laminated cards.

AAMVA data separates its fields with control characters (line feed, record separator, carriage return). `barcode.data` keeps them as they were encoded, so you can pass it to `parseAAMVA()` directly; `fromBase64(barcode.rawBytes)` gives the exact bytes if you need them.

`parseContent()` also recognizes AAMVA data and returns `{ type: "aamva", aamva }`, so a general-purpose scanner can handle licenses without a separate code path.

## Result fields

`parseAAMVA(data, options?)` returns `null` when the input isn't AAMVA data. Otherwise:

| Field | Source element | Example | Notes |
| --- | --- | --- | --- |
| `firstName` | `DAC` | `JANE` | Falls back to legacy `DCT`/`DAA`. |
| `middleName` | `DAD` | `Q` | |
| `lastName` | `DCS` | `SAMPLE` | Falls back to legacy `DAB`/`DAA`. |
| `suffix` | `DCU` | `JR` | |
| `fullName` | computed | `JANE Q SAMPLE` | First, middle, last and suffix. |
| `dateOfBirth` | `DBB` | `1990-01-31` | ISO date, `""` when missing. |
| `issueDate` | `DBD` | `2020-02-01` | ISO date. |
| `expiryDate` | `DBA` | `2028-01-31` | ISO date. |
| `sex` | `DBC` | `F` | `M`, `F`, `X` or `""`. |
| `documentNumber` | `DAQ` | `D1234567` | License or ID number. |
| `documentDiscriminator` | `DCF` | | Identifies this particular card. |
| `documentType` | subfile type | `DL` | `DL` (driver license) or `ID` (identification card). |
| `street`, `street2` | `DAG`, `DAH` | `123 MAIN ST` | |
| `city` | `DAI` | `SACRAMENTO` | |
| `state` | `DAJ` | `CA` | State or province code. |
| `postalCode` | `DAK` | `95814` | ZIP+4 is formatted `95814-1234`; a `0000` extension is dropped. |
| `country` | `DCG` | `USA` | `USA` or `CAN`; inferred from the issuer when missing. |
| `eyeColor`, `hairColor` | `DAY`, `DAZ` | `BRO` | AAMVA color codes. |
| `height` | `DAU` | `065 IN` | As encoded (inches or centimeters). |
| `weight` | `DAW` or `DAX` | | Pounds or kilograms, as encoded. |
| `vehicleClass`, `restrictions`, `endorsements` | `DCA`, `DCB`, `DCD` | | Jurisdiction-specific codes. |
| `issuerId` | header | `636014` | Issuer Identification Number of the jurisdiction. |
| `aamvaVersion`, `jurisdictionVersion` | header | `10`, `0` | Standard version the card follows. |
| `age` | computed | `36` | Whole years, or `null` without a birth date. |
| `isExpired` | computed | `false` | `null` without an expiry date. |
| `isUnder21`, `isUnder18` | computed | `false` | `null` without a birth date. |
| `fields` | all elements | `{ "DAQ": "D1234567", ... }` | Every element by its three-letter code, including jurisdiction-specific `Z..` elements. |

Dates are converted from the card's format: US issuers use `MMDDCCYY`, Canadian issuers `CCYYMMDD`. Values such as `NONE` or `UNAVL` become `""`. `AAMVA_FIELDS` maps element codes to readable labels, for example `AAMVA_FIELDS.DAQ` is `"Customer ID number"`.

`age`, `isExpired`, `isUnder21` and `isUnder18` are computed against the current date. Pass `{ now }` to compute them for another date, which is also how you write deterministic tests:

```js
parseAAMVA(data, { now: new Date("2026-06-01T00:00:00Z") });
```

## Age verification

```js
import { parseAAMVA } from "qrgen-sdk";

export function checkAge(data, minimumAge = 21) {
  const id = parseAAMVA(data);
  if (!id) return { ok: false, reason: "Not a driver license or ID card" };
  if (id.age === null) return { ok: false, reason: "No date of birth on the card" };
  if (id.isExpired !== false) return { ok: false, reason: "The card is expired or has no expiry date" };
  if (id.age < minimumAge) return { ok: false, reason: `Under ${minimumAge}` };
  return { ok: true, age: id.age };
}
```

For the common case of 21, `id.isUnder21` is available directly. Show the staff member the result together with the name and photo on the physical card: the barcode doesn't prove that the person in front of you is the card holder.

## Privacy

License data is personal data, and in many places regulated. Handle it with care:

- **Process on the device.** QRGen decodes and parses locally; nothing is uploaded unless your code sends it.
- **Keep only what you need.** For an age check, keep the yes/no result and discard the parsed object. Don't log `data`, `rawBytes` or `fields`.
- **Don't store it by default.** If you must store data (for example for a visitor log), store the minimum fields, tell the user, encrypt it at rest and delete it on a schedule.
- **Check local law.** Several US states and Canadian provinces restrict when businesses may scan licenses and how long they may keep the data.
- **Don't treat the barcode as proof of authenticity.** Anyone can print a PDF417 with arbitrary data. Parsing a license verifies its format, not that the card is genuine.

## Limitations

- **North America only.** The AAMVA PDF417 is used on US and Canadian driver licenses and ID cards. Licenses and ID cards from other regions use other formats.
- **No MRZ or OCR.** Passports, passport cards and many national ID cards carry a machine-readable zone (MRZ): printed text that needs optical character recognition. QRGen reads barcodes only; it doesn't include OCR, so it can't read an MRZ or the printed front of a card.
- **No authenticity checks.** No security features (holograms, UV, microprint) are verified.
- **Jurisdiction quirks.** Some issuers deviate from the standard. Unknown and jurisdiction-specific elements are kept in `fields`, so you can read them even when there is no named property.

## Test without a real license

Don't use a real person's license during development. The [cross-platform spec](https://github.com/Rockyljewell/QR-GEN/blob/main/docs/SPEC.md) includes a fictional AAMVA test vector. Render it as a PDF417 on your screen and scan it with your phone:

```html
<qrgen-barcode id="test-license" symbology="pdf417" scale="3" style="width: 480px"></qrgen-barcode>

<script type="module">
  import "qrgen-sdk/elements";

  document.getElementById("test-license").value =
    "@\n\x1e\rANSI 636014100002DL00410279ZC03200024DLDAQD1234567\nDCSSAMPLE\nDACJANE\nDADQ\nDBB01311990\nDBA01312028\nDBD02012020\nDBC2\nDAYBRO\nDAU065 IN\nDAG123 MAIN ST\nDAISACRAMENTO\nDAJCA\nDAK958140000\nDCGUSA\n\rZCZCAA\r";
</script>
```

Or test the parser directly:

```js
import { parseAAMVA } from "qrgen-sdk";

const sample =
  "@\n\x1e\rANSI 636014100002DL00410279ZC03200024DLDAQD1234567\nDCSSAMPLE\nDACJANE\nDADQ\nDBB01311990\nDBA01312028\nDBD02012020\nDBC2\nDAYBRO\nDAU065 IN\nDAG123 MAIN ST\nDAISACRAMENTO\nDAJCA\nDAK958140000\nDCGUSA\n\rZCZCAA\r";

const id = parseAAMVA(sample, { now: new Date("2026-06-01T00:00:00Z") });
console.log(id.fullName, id.dateOfBirth, id.expiryDate, id.postalCode, id.age); // JANE Q SAMPLE 1990-01-31 2028-01-31 95814 36
```


---

# Image scanning

URL: https://rockyljewell.github.io/QR-GEN/docs/image-scanning/
Group: Features

> Decode barcodes and QR codes in images with scanImage: file inputs, drag and drop, clipboard paste, URLs, canvases and video frames, multiple codes per image, and tryHarder.

`scanImage()` decodes every barcode in a still image. It runs entirely in the browser (or in Node with [`qrgen-sdk/node`](../nodejs/)), needs no camera and no permission, and works in any context, including plain `http://` pages.

```js
import { scanImage } from "qrgen-sdk";

const barcodes = await scanImage(input, { symbologies: ["qr", "ean13"] });
```

It resolves with an array of [Barcode](../concepts/#the-barcode-result) results, empty when nothing was found. It rejects with a `QRGenError` (`bad-request`) when the input can't be read, for example a URL that returns 404.

## Inputs

| Input | Notes |
| --- | --- |
| `File`, `Blob` | From `<input type="file">`, drag and drop, the clipboard or `fetch()`. PNG, JPEG, GIF and BMP are decoded by the engine. |
| `ArrayBuffer`, `Uint8Array` | Image file bytes (PNG, JPEG, GIF, BMP). |
| `HTMLImageElement` | Waits for the image to load. Cross-origin images need CORS. |
| `HTMLCanvasElement`, `OffscreenCanvas` | The current canvas contents. |
| `HTMLVideoElement` | The current frame. |
| `ImageBitmap` | Any format the browser can decode. |
| `ImageData` | Raw RGBA pixels. |
| `string` | A URL (absolute, relative or `blob:`) or a `data:` URL. Fetched with `fetch()`, so CORS applies. |

### Formats the engine can't read

`File`, `Blob`, byte and URL inputs are decoded by the engine, which reads PNG, JPEG, GIF and BMP. For WebP, AVIF, HEIC (on Safari) or any other format the browser itself can display, let the browser decode it first:

```js
const bitmap = await createImageBitmap(file);
const barcodes = await scanImage(bitmap);
bitmap.close();
```

## Options

| Option | Default | Description |
| --- | --- | --- |
| `symbologies` | all | Ids, aliases or groups. Fewer is faster and avoids false reads. |
| `maxResults` | `255` | Maximum number of codes to return (1 to 255). |
| `tryHarder` | `true` | Extra passes for small, damaged or low-contrast codes. Set `false` for speed on clean images. |

Rotated codes are always searched, and large images are also tried downscaled. Inverted (white on black) codes are searched too unless you pass `tryInvert: false`. QR, Data Matrix and Aztec are checked in both polarities in one pass. Inverted linear and PDF417 codes need a second pass, which runs only when the first found nothing, so an image with a normal code next to an inverted linear or PDF417 code returns the normal code only.

## File input

```html
<input type="file" id="file" accept="image/*" />
<ul id="results"></ul>

<script type="module">
  import { scanImage } from "qrgen-sdk";

  document.getElementById("file").addEventListener("change", async (event) => {
    const list = document.getElementById("results");
    list.replaceChildren();
    for (const file of event.target.files) {
      const bitmap = await createImageBitmap(file); // works for every format the browser supports
      const barcodes = await scanImage(bitmap);
      bitmap.close();
      for (const b of barcodes) {
        list.append(Object.assign(document.createElement("li"), { textContent: `${file.name}: ${b.symbologyName} ${b.data}` }));
      }
      if (!barcodes.length) list.append(Object.assign(document.createElement("li"), { textContent: `${file.name}: no code found` }));
    }
  });
</script>
```

On phones, `accept="image/*"` offers the camera as a source too. Add `capture="environment"` to open the camera directly. This takes a full-resolution photo, which can read codes that are too small for the live scanner.

## Drag and drop

```js
import { scanImage } from "qrgen-sdk";

const zone = document.getElementById("drop-zone");

zone.addEventListener("dragover", (event) => {
  event.preventDefault();
  zone.classList.add("over");
});
zone.addEventListener("dragleave", () => zone.classList.remove("over"));
zone.addEventListener("drop", async (event) => {
  event.preventDefault();
  zone.classList.remove("over");
  const files = [...event.dataTransfer.files].filter((f) => f.type.startsWith("image/"));
  for (const file of files) {
    const barcodes = await scanImage(await createImageBitmap(file));
    console.log(file.name, barcodes.map((b) => b.data));
  }
});
```

## Paste from the clipboard

Screenshots are the most common source: a QR code in a chat, a boarding pass in an email.

```js
import { scanImage } from "qrgen-sdk";

document.addEventListener("paste", async (event) => {
  const item = [...event.clipboardData.items].find((i) => i.type.startsWith("image/"));
  if (!item) return;
  const barcodes = await scanImage(item.getAsFile());
  console.log(barcodes.length ? barcodes[0].data : "No code in the pasted image");
});
```

To read the clipboard from a button instead of a paste event (this prompts for permission in some browsers):

```js
async function scanClipboard() {
  for (const item of await navigator.clipboard.read()) {
    const type = item.types.find((t) => t.startsWith("image/"));
    if (type) return scanImage(await item.getType(type));
  }
  return [];
}
```

## URLs

```js
const fromUrl = await scanImage("https://example.com/images/label.png");
const fromDataUrl = await scanImage("data:image/png;base64,iVBORw0KGgo...");
```

The URL is fetched with `fetch()`, so a cross-origin image must be served with CORS headers (`Access-Control-Allow-Origin`), and your Content Security Policy's `connect-src` must allow it. Otherwise fetch it on your server, or use the [REST API](../rest-api/).

## Canvas and video frames

Scan something you drew or rendered, for example a PDF page rendered with [PDF.js](https://mozilla.github.io/pdf.js/) (a separate library):

```js
import { scanImage } from "qrgen-sdk";
import * as pdfjs from "pdfjs-dist";

pdfjs.GlobalWorkerOptions.workerSrc = new URL("pdfjs-dist/build/pdf.worker.min.mjs", import.meta.url).toString();

export async function scanPdf(url) {
  const pdf = await pdfjs.getDocument(url).promise;
  const results = [];
  for (let n = 1; n <= pdf.numPages; n++) {
    const page = await pdf.getPage(n);
    const viewport = page.getViewport({ scale: 3 }); // about 216 DPI; small codes need resolution
    const canvas = Object.assign(document.createElement("canvas"), { width: viewport.width, height: viewport.height });
    await page.render({ canvasContext: canvas.getContext("2d"), viewport }).promise;
    for (const b of await scanImage(canvas)) results.push({ page: n, ...b });
  }
  return results;
}
```

A `<video>` element is scanned at its current frame, which is handy for scanning a paused video file:

```js
const barcodes = await scanImage(document.querySelector("video"));
```

For live camera scanning, use [`BarcodeScanner`](../javascript/) instead: it is optimized for many frames per second.

## Multiple codes

`scanImage()` returns every code it finds, up to `maxResults`:

```js
const barcodes = await scanImage(photoOfShelf, { symbologies: "retail" });
console.log(`${barcodes.length} codes`);

// Sort top to bottom, then left to right, using each code's position in the image
barcodes.sort((a, b) => a.location.topLeft.y - b.location.topLeft.y || a.location.topLeft.x - b.location.topLeft.x);
```

`location` gives the four corners of each code in image pixels, and `frameSize` the image size, so you can draw boxes over a preview. `quadCenter()` and `quadBounds()` return the center point and the axis-aligned bounding box of a `location`.

## tryHarder

`tryHarder` is on by default for images, because a single image is worth the extra effort. Turn it off when you scan many clean, computer-generated images (labels, screenshots) and want speed:

```js
const barcodes = await scanImage(bytes, { symbologies: ["code128"], tryHarder: false });
```

If a code isn't found:

- Make sure its symbology is in `symbologies`.
- Check the resolution: each module (the smallest bar or square) needs at least 2 to 3 pixels. Photos of small codes taken from far away often don't have that.
- Crop to the code. Large photos with a small code are downscaled in some passes.
- Avoid heavy JPEG compression, blur and glare.

`scanImage()` decodes on the main thread. For batches of large images, run it inside a Web Worker of your own, or process them on a server with [`qrgen-sdk/node`](../nodejs/) or the [REST API](../rest-api/).


---

# Barcode generation

URL: https://rockyljewell.github.io/QR-GEN/docs/barcode-generation/
Group: Features

> Generate QR codes and 25 other barcode types as SVG, PNG or data URLs with generate(), <qrgen-barcode>, the CLI and the REST API, including GS1 data.

QRGen generates all 26 supported symbologies, from QR codes and Data Matrix to EAN-13 and GS1-128. Output is a clean SVG (scalable, ideal for print and the web), a PNG, a module matrix or a text rendering. Generation runs locally in the browser or in Node.js; the generator engine (`zxing_writer.wasm`, about 340 KB gzipped) is only downloaded the first time you generate.

## generate()

For a QR code with a known print size, use the [QR print planner](../print-planning/) to choose whole printer dots and retain the quiet zone. The [interactive print flow](../../plan/) starts with a link, text or Wi-Fi network.

```js
import { generate } from "qrgen-sdk";

const result = await generate("https://example.com", { symbology: "qr", ecLevel: "M", scale: 6 });

document.querySelector("#code").innerHTML = result.svg;
```

`generate(data, options?)` resolves with:

| Field | Type | Description |
| --- | --- | --- |
| `svg` | `string` | Standalone SVG markup with `width`, `height` and a `viewBox`, no XML declaration. |
| `png` | `Blob \| null` | PNG image, with colors applied (in Node.js when you import from `qrgen-sdk/node`). |
| `matrix` | `{ width, height, modules }` | The symbol's module grid. `modules[y * width + x]` is `1` for dark and `0` for light. |
| `text` | `string` | A text rendering with block characters, for terminals. |
| `symbology`, `data` | `string` | What was encoded. |

Shortcuts:

```js
import { generateSVG, generateDataURL } from "qrgen-sdk";

const svg = await generateSVG("hello");                    // just the SVG string
const src = await generateDataURL("hello", { scale: 8 });  // "data:image/svg+xml;charset=utf-8,..."
document.querySelector("img").src = src;
```

## Options

| Option | Default | Description |
| --- | --- | --- |
| `symbology` | `"qr"` | Symbology id or alias. Groups like `retail` are not accepted here. |
| `scale` | `4` | Module size in pixels (the width of the narrowest bar or one QR square). |
| `ecLevel` | encoder's choice | Error correction: `"L"`, `"M"`, `"Q"`, `"H"` for QR and Micro QR, or a percentage for Aztec and PDF417. |
| `gs1` | `false` | Encode as GS1. Pass the data in HRI form: `(01)09501101530003(10)ABC123`. |
| `hrt` | `false` | Print human-readable text under linear barcodes. |
| `margin` | `true` | Add the quiet zone (the blank border scanners need). |
| `foreground` | `"#000000"` | Bar and module color. |
| `background` | `"#ffffff"` | Background color, or `"transparent"`. |
| `rotate` | `0` | `0`, `90`, `180` or `270`. |
| `version` | automatic | Symbol size for 2D codes, for example QR version 1 to 40. |
| `extraOptions` | | Additional encoder options as a comma-separated string, passed through to the engine. |

Errors reject with a `QRGenError`: `bad-request` for an unknown symbology, empty data, or data the symbology can't encode (the message says why, for example `Cannot encode as EAN-13: Invalid check digit '8', expecting '7'`), and `engine-load-failed` if the generator wasm can't be loaded.

## SVG, PNG and downloads

SVG is the best format for screens and print: it stays sharp at any size. Set its size with CSS; the `viewBox` keeps the aspect ratio:

```js
const { svg } = await generate("https://example.com");
const box = document.querySelector("#qr");
box.innerHTML = svg;
box.querySelector("svg").style.width = "200px";
box.querySelector("svg").style.height = "auto";
```

Download buttons:

```js
import { generate } from "qrgen-sdk";

async function download(data, filename) {
  const { svg, png } = await generate(data, { scale: 10 });
  const blob = filename.endsWith(".png") && png ? png : new Blob([svg], { type: "image/svg+xml" });
  const url = URL.createObjectURL(blob);
  const a = Object.assign(document.createElement("a"), { href: url, download: filename });
  a.click();
  setTimeout(() => URL.revokeObjectURL(url), 1000);
}

download("https://example.com", "qr.png");
```

For PNGs, choose `scale` for the pixel size you need: the PNG is exactly `modules x scale` pixels (plus the quiet zone). Don't resize PNGs of barcodes with smoothing; it blurs the edges.

## Colors and transparency

```js
const { svg } = await generate("https://example.com", { foreground: "#1d3557", background: "transparent" });
```

Keep strong contrast: dark bars on a light background. Most scanners can't read light-on-dark codes by default (QRGen's scanner does, but your users' apps may not), and low-contrast color pairs such as red on blue fail on many devices. With `background: "transparent"`, make sure whatever is behind the code is light.

In Node.js, import from `qrgen-sdk/node` (or use the CLI or REST API) and PNG output gets the same colors and transparency as the SVG.

## GS1 data

GS1 barcodes carry application identifiers (AIs) such as GTIN `(01)`, expiry date `(17)` and batch `(10)`. Pass the data in human-readable form and set `gs1: true`:

```js
import { generate, isValidCheckDigit } from "qrgen-sdk";

const gtin = "09501101530003";
if (!isValidCheckDigit(gtin)) throw new Error("Bad GTIN check digit");

const label = await generate(`(01)${gtin}(17)250101(10)ABC123`, { symbology: "code128", gs1: true, hrt: true });  // GS1-128
const pack = await generate(`(01)${gtin}(17)250101(10)ABC123(21)SN42`, { symbology: "data-matrix", gs1: true }); // GS1 DataMatrix
```

GS1 works with `code128`, `data-matrix` and `qr`. The GS1 DataBar family (`databar`, `databar-expanded`, `databar-limited`) always carries GS1 data, so `gs1: true` is optional there; pass the data in HRI form too, for example `(01)09521234543213(3103)000123` for DataBar Expanded.

The generator checks the element string's syntax but not every check digit, so validate GTINs with `isValidCheckDigit()` (or compute one with `computeCheckDigit()`) before printing. When scanned, GS1 codes come back with `isGS1: true` and `data` in the same HRI form, ready for [`parseGS1()`](../parsers/#parsegs1).

For GS1 Digital Link, encode the URL in a regular QR code: `generate("https://id.gs1.org/01/09501101530003/10/ABC123")`.

## What each symbology accepts

| Symbology | Data |
| --- | --- |
| `qr` | Any text (UTF-8), up to about 2,900 bytes at level L. |
| `micro-qr`, `rmqr` | Short text: up to 35 digits or about 20 characters for Micro QR; rMQR holds a bit more in a rectangle. |
| `data-matrix`, `aztec` | Any text. Data Matrix supports GS1. |
| `pdf417`, `micro-pdf417` | Any text. |
| `maxicode` | Up to about 90 characters. |
| `ean13` | 12 digits (the check digit is added) or 13 digits (the check digit is verified). |
| `ean8` | 7 or 8 digits. |
| `upca` | 11 or 12 digits. |
| `upce` | 7 or 8 digits, starting with number system `0` or `1`. |
| `isbn` | An ISBN-10 or ISBN-13 (9, 10 or 13 characters). |
| `code128` | Any text; GS1-128 with `gs1: true`. |
| `code39` | `A-Z`, `0-9`, space and `- . $ / + %` (lowercase is uppercased). |
| `code93` | ASCII text. |
| `codabar` | Digits and `- $ : / . +`, starting and ending with `A`, `B`, `C` or `D`. |
| `itf` | Digits; an odd count is padded with a leading zero. |
| `itf14` | 13 digits (check digit added) or 14 digits. |
| `databar`, `databar-limited` | A GTIN, optionally as `(01)...`. DataBar Limited needs a GTIN starting with 0 or 1. |
| `databar-expanded` | A GS1 element string in HRI form. |
| `code32` | 8 digits (the check digit is added). |
| `pzn` | 6 or 7 digits (the check digit is added). |
| `telepen` | ASCII text. |
| `dx-film-edge` | A DX number such as `77-4`, or up to four digits. |

Some symbologies transform the data: a scanned Code 32 is reported with its `A` prefix, a PZN with its `-` prefix and check digit, and a 13-digit ITF-14 with its computed check digit.

## Human-readable text

`hrt: true` prints the encoded value under linear barcodes, formatted the way the symbology expects (for EAN-13, the leading digit outside the bars). 2D codes ignore it. The text uses the OCR-B font when installed and falls back to monospace.

## The `<qrgen-barcode>` element

For UI, the [`<qrgen-barcode>` element](../web-components/#qrgen-barcode) renders and re-renders a barcode from attributes:

```html
<script type="module">
  import "qrgen-sdk/elements";
</script>

<qrgen-barcode value="https://example.com/tickets/8841" symbology="qr" ec-level="Q" style="width: 180px"></qrgen-barcode>
<qrgen-barcode value="5901234123457" symbology="ean13" hrt style="width: 240px"></qrgen-barcode>
```

React and Vue have `QRGenBarcode` components with the same options; see [React](../react/#qrgenbarcode) and [Vue](../vue/#qrgenbarcode).

## CLI and REST API

```bash
qrgen generate "https://example.com" -o qr.svg --ec M
qrgen generate "(01)09501101530003(10)ABC123" -t code128 --gs1 --hrt -o label.png --scale 3
```

```bash
curl -o qr.png "http://localhost:8080/v1/generate?data=https%3A%2F%2Fexample.com&format=png&scale=8"
```

See [CLI](../cli/#generate) and [REST API](../rest-api/#generate).

## Printing tips

- **Keep the quiet zone.** Leave `margin` on, and don't place text or borders right up to the code. Linear codes need about 10 modules of blank space on each side; QR codes 4 modules.
- **Print at whole modules.** For raster output, pick `scale` so one module is a whole number of printer dots. At 300 DPI, `scale: 4` gives modules of about 0.34 mm; at 203 DPI (common thermal label printers), `scale: 3` gives about 0.38 mm. Prefer SVG when your print pipeline supports it.
- **Minimum sizes.** Retail EAN-13 and UPC-A are nominally about 37 x 26 mm (0.33 mm modules) and shouldn't be printed below 80% of that. For QR codes read by phones, aim for at least 2 cm across for short URLs; more data or longer reading distance needs a larger code.
- **Error correction.** Level `M` suits most QR codes. Use `Q` or `H` for codes that may get scratched, dirty or partially covered, at the cost of a denser symbol.
- **Shorter data scans better.** A short URL makes a QR code with fewer, larger modules. Use a URL shortener or short paths for printed codes.
- **Test the output.** Scan the printed result with the devices your users have, in their lighting. You can also verify files in CI: `qrgen scan label.png` exits with code 2 if nothing is found.


---

# QR print planning

URL: https://rockyljewell.github.io/QR-GEN/docs/print-planning/
Group: Features

> Plan a QR code for a physical print size, build common payloads and verify exported files.

Start with the [print planner](../../plan/) to make a website, text or Wi-Fi QR code using the available space and printer resolution. Content stays on your device. The interface keeps the white quiet zone, explains when a payload needs more room, and can scan the exported PNG back to check its content.

## Plan with the SDK

```js
import { buildUrlPayload, planQRCode } from "qrgen-sdk";

const data = buildUrlPayload("https://example.com/menu");
const plan = await planQRCode(data, { widthMm: 30, dpi: 203 });
if (plan.suitable) {
  // Send this to your existing SVG download helper.
  downloadSvg(plan.printSvg);
  console.log(plan.geometry.widthMm, plan.geometry.dotsPerModule);
} else {
  console.log(plan.diagnostics);
}
```

For Node.js, import from `qrgen-sdk/node` to use the locally packaged engine. These APIs do not yet have native Swift/Kotlin/Python equivalents.

The planner encodes the real payload at each permitted error-correction level. It includes four quiet-zone modules on every side, chooses whole printer dots and favors larger modules; ties favor stronger correction. Automatic mode permits M, Q and H. You can supply an exact `ecLevel`, a `minEcLevel` floor or a different `minDotsPerModule` profile.

The default three-dot minimum is a starting profile. It does not establish readability on a particular printer, material, camera or damaged label. Print an actual sample and test the devices people will use. Higher error correction may require a denser symbol and is not automatically the best choice for limited space.

The returned `target`, `candidates` and `diagnostics` explain the decision. An unsuitable plan has no rendered output and reports the minimum required width when encodable. Invalid inputs throw an error. Targets over 2048 printer dots are rejected to bound image allocations. Leading Unicode BOM is rejected because the current string writer would remove it; the planner never silently trims the payload.

## Export and check

`printSvg` has physical millimeter dimensions and the original viewBox. Print at 100% with fit-to-page disabled. `barcode.svg` and `barcode.png` retain pixel dimensions; a PNG needs the reported physical width and DPI applied by the printing application.

The planner's PNG check requires the decoded text to exactly match the encoded payload. This verifies the exported pixels with QRGen's reader. It does not verify a printed label, another scanner engine or an action such as joining Wi-Fi. Keep an equivalent readable link or instruction beside a published QR code.

## Wi-Fi and links

`buildUrlPayload(url)` accepts absolute HTTP(S) addresses and returns them unchanged. It rejects raw whitespace/backslashes, unsupported schemes and malformed Unicode.

```js
import { buildWifiPayload } from "qrgen-sdk";
const data = buildWifiPayload({
  ssid: "Café; room:1",
  authentication: "WPA",
  password: "example-password",
  hidden: false,
});
```

The Wi-Fi helper follows the [ZXing WIFI convention](https://github.com/zxing/zxing/wiki/Barcode-Contents#wi-fi-network-config-android-ios-11): delimiters are escaped, hex-looking text names/passwords receive quote wrappers, and open networks cannot include a password. The existing QRGen parser retains encoded quote wrappers. Text credentials with literal quotes at both ends are rejected for portability. The helper validates text bounds but does not test a router's credentials or phone support. Anyone with the code can read the credentials.


---

# Parsers

URL: https://rockyljewell.github.io/QR-GEN/docs/parsers/
Group: Features

> Turn scanned text into structured data with parseContent (URLs, Wi-Fi, contacts, events, payments, product codes, GS1, driver licenses), parseGS1 and parseAAMVA.

A barcode's `data` is just text. QRGen's parsers tell you what it means: a URL, Wi-Fi credentials, a contact card, a product GTIN, a GS1 element string with expiry date and batch, or a driver license. They are pure functions: no engine, no network, no DOM. They never throw; when the input doesn't match, they return `{ type: "text" }` or `null`.

```js
import { parseContent, parseGS1, parseAAMVA } from "qrgen-sdk";
```

If you only need the parsers (for example on a server that receives scan results), import them from `qrgen-sdk/parsers`, which doesn't include the scanning engine. The same parsers, with the same output shapes, exist in every QRGen SDK.

## parseContent

`parseContent(data, options?)` detects the kind of content and returns an object with a `type` field:

```js
parseContent("WIFI:T:WPA;S:Office;P:correct horse;;");
// { type: "wifi", ssid: "Office", password: "correct horse", security: "WPA", hidden: false }
```

| `type` | Fields | Recognized input |
| --- | --- | --- |
| `url` | `url` | `http://` and `https://` URLs; `www.` hosts get `https://` prepended |
| `gs1-digital-link` | `url`, `gs1` | URLs with a GS1 primary key path such as `/01/<GTIN>` |
| `email` | `to`, `subject?`, `body?` | `mailto:`, `MATMSG:`, bare addresses |
| `phone` | `number` | `tel:`, or a bare number starting with `+` |
| `sms` | `number`, `body?` | `SMSTO:`, `sms:`, `mmsto:` |
| `wifi` | `ssid`, `password?`, `security`, `hidden` | `WIFI:` (with backslash escapes) |
| `geo` | `latitude`, `longitude`, `altitude?`, `query?` | `geo:` URIs |
| `contact` | `format`, `name?`, `organization?`, `title?`, `phones`, `emails`, `urls`, `address?`, `note?` | vCard (`BEGIN:VCARD`) and `MECARD:` |
| `event` | `summary?`, `start?`, `end?`, `location?`, `description?` | iCalendar `BEGIN:VEVENT` or `BEGIN:VCALENDAR` |
| `payment` | `scheme`, `address?`, `name?`, `iban?`, `bic?`, `amount?`, `currency?`, `reference?` | EPC/SEPA (`BCD`), `bitcoin:`, `ethereum:`, other coin URIs, `upi://pay` |
| `product` | `gtin`, `kind`, `checksumValid` | 8, 12, 13 and 14 digit product codes |
| `gs1` | `gs1` | GS1 element strings (HRI or raw) |
| `aamva` | `aamva` | North American driver license and ID card data |
| `text` | `text` | Anything else |

### Options

| Option | Description |
| --- | --- |
| `symbology` | The symbology the data came from. Pass `barcode.symbology`: it lets the parser read 8 digits from a UPC-E as UPC-E, and stops it from treating digits inside a QR code as a product number. |
| `now` | Reference `Date` for the age and expiry fields of `aamva` results. |

```js
scanner.addEventListener("scan", ({ detail: { barcode } }) => {
  const content = parseContent(barcode.data, { symbology: barcode.symbology });
});
```

In TypeScript, `ParsedContent` is a discriminated union, so checking `type` narrows the fields:

```ts
import { parseContent, type ParsedContent } from "qrgen-sdk";

function describe(content: ParsedContent): string {
  switch (content.type) {
    case "url":
      return `Link to ${new URL(content.url).hostname}`;
    case "wifi":
      return `Wi-Fi network ${content.ssid}`;
    case "product":
      return `Product ${content.gtin}${content.checksumValid ? "" : " (bad check digit)"}`;
    default:
      return content.type;
  }
}
```

### Examples

**URLs and GS1 Digital Link**

```js
parseContent("https://example.com");
// { type: "url", url: "https://example.com" }

parseContent("https://id.gs1.org/01/09501101530003/10/ABC123?17=250101");
// { type: "gs1-digital-link", url: "https://id.gs1.org/...", gs1: { values: { "01": "09501101530003", "10": "ABC123", "17": "250101" }, elements: [...] } }
```

**Email, phone and SMS**

```js
parseContent("mailto:hi@example.com?subject=Hello");
// { type: "email", to: "hi@example.com", subject: "Hello" }

parseContent("tel:+15551234567");
// { type: "phone", number: "+15551234567" }

parseContent("SMSTO:+15551234567:On my way");
// { type: "sms", number: "+15551234567", body: "On my way" }
```

**Wi-Fi**

```js
parseContent("WIFI:T:WPA;S:Office;P:correct horse;;");
// { type: "wifi", ssid: "Office", password: "correct horse", security: "WPA", hidden: false }

parseContent("WIFI:S:Guest;;");
// { type: "wifi", ssid: "Guest", security: "nopass", hidden: false }
```

**Location**

```js
parseContent("geo:40.7128,-74.0060?q=New%20York");
// { type: "geo", latitude: 40.7128, longitude: -74.006, query: "New York" }
```

**Contacts**

```js
parseContent("BEGIN:VCARD\nVERSION:3.0\nFN:Jane Doe\nORG:Example Inc.\nTEL:+15550100\nEMAIL:jane@example.com\nEND:VCARD");
// { type: "contact", format: "vcard", name: "Jane Doe", organization: "Example Inc.", phones: ["+15550100"], emails: ["jane@example.com"], urls: [] }

parseContent("MECARD:N:Doe,Jane;TEL:5550100;EMAIL:jane@example.com;;");
// { type: "contact", format: "mecard", name: "Jane Doe", phones: ["5550100"], emails: ["jane@example.com"], urls: [] }
```

**Calendar events**

```js
parseContent("BEGIN:VEVENT\nSUMMARY:Launch\nDTSTART:20261001T170000Z\nDTEND:20261001T180000Z\nLOCATION:Online\nEND:VEVENT");
// { type: "event", summary: "Launch", start: "2026-10-01T17:00:00Z", end: "2026-10-01T18:00:00Z", location: "Online" }
```

Dates are converted to ISO 8601; all-day dates become `YYYY-MM-DD`.

**Payments**

```js
parseContent("BCD\n002\n1\nSCT\nBPOTBEB1\nRed Cross\nBE72000000001616\nEUR12.30\n\n\nDonation");
// { type: "payment", scheme: "epc", bic: "BPOTBEB1", name: "Red Cross", iban: "BE72000000001616", currency: "EUR", amount: 12.3, reference: "Donation" }

parseContent("bitcoin:1BoatSLRHtKNngkdXEeobR76b53LETtpyT?amount=0.01&label=Tip");
// { type: "payment", scheme: "bitcoin", address: "1BoatSLRHtKNngkdXEeobR76b53LETtpyT", amount: 0.01, name: "Tip", currency: "BTC" }

parseContent("upi://pay?pa=shop@upi&pn=Shop&am=10");
// { type: "payment", scheme: "upi", address: "shop@upi", name: "Shop", amount: 10, currency: "INR" }
```

For `ethereum:` URIs, `amount` is the raw `value` parameter (in wei). Other coin schemes (`litecoin:`, `dogecoin:`, `bitcoincash:`) return `scheme: "other"`.

### Product codes

Numeric data of 8, 12, 13 or 14 digits is returned as a product with its GTIN padded to 14 digits and a check digit test:

```js
parseContent("5901234123457");
// { type: "product", kind: "ean13", gtin: "05901234123457", checksumValid: true }

parseContent("9780306406157");
// { type: "product", kind: "isbn", gtin: "09780306406157", checksumValid: true }

parseContent("036000291452", { symbology: "upca" });
// { type: "product", kind: "upca", gtin: "00036000291452", checksumValid: true }

parseContent("01234565", { symbology: "upce" });
// { type: "product", kind: "upce", gtin: "00012345000065", checksumValid: true }
```

`kind` is `ean13`, `ean8`, `upca`, `upce`, `isbn` (13 digits starting with 978 or 979) or `gtin14`. A UPC-E is expanded to its UPC-A form before padding, so the GTIN matches what your product database stores. Because every UPC-A is also a valid EAN-13 with a leading zero, both forms produce the same `gtin`: use `gtin` as your lookup key.

**GS1 and driver licenses**

```js
parseContent("(01)09501101530003(17)250101(10)ABC123");
// { type: "gs1", gs1: { values: { "01": "09501101530003", "17": "250101", "10": "ABC123" }, elements: [...] } }
```

AAMVA data returns `{ type: "aamva", aamva }` with the same object as `parseAAMVA()` below.

## parseGS1

`parseGS1(input)` parses GS1 element strings in three forms and returns `null` for anything else:

```js
import { parseGS1 } from "qrgen-sdk";

// 1. Human-readable (HRI) form, as QRGen scanners return GS1 data
parseGS1("(01)09501101530003(17)250101(10)ABC123");

// 2. Raw form with GS (ASCII 29) separators and an optional symbology prefix (]C1, ]d2, ]Q3, ]e0)
parseGS1("]C101095011015300031725010110ABC123\u001d21SN-42");

// 3. GS1 Digital Link URLs
parseGS1("https://id.gs1.org/01/09501101530003/10/ABC123?17=250101");
```

The result:

```json
{
  "elements": [
    { "ai": "01", "title": "GTIN", "description": "Global Trade Item Number", "value": "09501101530003", "checkDigitValid": true },
    { "ai": "17", "title": "USE BY or EXPIRY", "description": "Expiration date", "value": "250101", "date": "2025-01-01" },
    { "ai": "10", "title": "BATCH/LOT", "description": "Batch or lot number", "value": "ABC123" }
  ],
  "values": { "01": "09501101530003", "17": "250101", "10": "ABC123" }
}
```

| Field | Description |
| --- | --- |
| `elements` | Every element in order: `ai`, `title` (the GS1 data title), `description`, `value`, plus the fields below when they apply. |
| `values` | AI to value map for quick lookups. The first occurrence wins. |
| `digitalLink` | The original URL, for Digital Link input. |

Per-element extras:

| Field | When | Example |
| --- | --- | --- |
| `date` | Date AIs 11, 12, 13, 15, 16, 17 (and 7250) | `"250101"` becomes `"2025-01-01"`. Day `00` means the last day of the month: `"261200"` becomes `"2026-12-31"`. Two-digit years use the GS1 sliding century rule. |
| `number` | Decimal AIs such as 310n to 369n (measures) and 390n to 395n (amounts) | `(3103)001250` is 1.250 kg, `number: 1.25`. The last AI digit is the number of decimals. |
| `iso` | AIs that start with an ISO currency or country code (391n, 393n, 421, ...) | `(3913)978550` is `iso: "978"` (EUR), `number: 0.55` |
| `checkDigitValid` | AIs with a mod-10 check digit (GTIN, SSCC, GLN, ...) | `true` or `false` |

```js
const gs1 = parseGS1("(01)09501101530003(3103)001250(3922)1999(15)261200");
const weight = gs1.elements.find((e) => e.ai === "3103").number; // 1.25
const price = gs1.elements.find((e) => e.ai === "3922").number;  // 19.99
const bestBefore = gs1.elements.find((e) => e.ai === "15").date; // "2026-12-31"
```

The AI table covers the identifiers used on products, logistics labels and healthcare packs. In HRI input, a parenthesized number that isn't a known AI is kept as part of the previous element's value. `GS1_AIS` exposes the table (`GS1_AIS["17"]` is `{ title: "USE BY or EXPIRY", fixed: 6, numeric: true, date: true, ... }`).

Raw numeric strings without a separator are ambiguous, so `parseGS1` only accepts them when they start with an AI of predefined length (such as `01` or `00`) or contain a separator. Plain numbers like `12345` return `null`.

### GS1 helpers

```js
import { computeCheckDigit, formatGS1, gs1Date, isValidCheckDigit, parseDigitalLink } from "qrgen-sdk";

isValidCheckDigit("09501101530003"); // true (works for GTIN-8/12/13/14, SSCC, GLN)
computeCheckDigit("0950110153000");  // 3
gs1Date("261200");                   // "2026-12-31"
formatGS1(parseGS1("https://id.gs1.org/01/9501101530003/10/ABC123")); // "(01)09501101530003(10)ABC123"
parseDigitalLink("https://example.com/01/09501101530003"); // Digital Link only; null for other input
```

In Digital Link URLs, GTINs shorter than 14 digits are zero padded, and both numeric AIs (`/01/`) and short names (`/gtin/`, `/lot/`, `/ser/`, `?exp=`) are understood.

## parseAAMVA

`parseAAMVA(data, options?)` parses the PDF417 on the back of US and Canadian driver licenses and ID cards:

```js
import { parseAAMVA } from "qrgen-sdk";

const id = parseAAMVA(licenseData);
if (id) console.log(id.fullName, id.dateOfBirth, id.expiryDate, id.isUnder21);
```

It returns `null` for other input. The full field list, age verification and privacy guidance are in [ID scanning](../id-scanning/#result-fields). `parseAamvaDate(value, canadian)` converts a single AAMVA date, and `AAMVA_FIELDS` maps element codes such as `DAQ` to labels.


---

# Embed bridge

URL: https://rockyljewell.github.io/QR-GEN/docs/embed-bridge/
Group: Features

> Run the QRGen scanner in any WebView or iframe with the hosted embed page, its message bridge and host commands, or self-host it with qrgen-sdk/bridge.

The embed page is a full-screen QRGen scanner that any app with a WebView can load: React Native, Flutter, native iOS and Android, .NET MAUI and WinUI, Titanium, Unity, or an `<iframe>` on another website. The page scans; your app receives the results as JSON messages and can send commands back. No QRGen code runs in your app.

```text
https://rockyljewell.github.io/QR-GEN/embed/?symbologies=qr,ean13&mode=single
```

The page is served over HTTPS, so it can use the camera in any WebView that supports `getUserMedia`, as long as your app grants camera permission (see the host examples below). It loads the decoder from the same origin, so the WebView only needs access to `rockyljewell.github.io`. The [React Native](../react-native/) and [Flutter](../flutter/) packages wrap this for you.

## Query options

The query string takes the [scanner options](../options-events/#scanner-options). Lists are comma-separated, and booleans accept `1`/`0` or `true`/`false`.

| Parameter | Example | Description |
| --- | --- | --- |
| `symbologies` | `qr,ean13` | Ids, aliases or groups. Default: all. |
| `mode` | `continuous` | `single`, `continuous` or `batch`. The hosted page defaults to `single`. |
| `duplicateFilter` | `2000` | Milliseconds; `0` every frame, `-1` once per session. |
| `beep`, `vibrate` | `0` | Feedback on scan. Default on. |
| `camera` | `front` | `back`, `front` or a device id. |
| `torch` | `1` | Turn the torch on when supported. |
| `viewfinder` | `line` | `frame`, `line` or `none`. |
| `scanArea` | `0.1,0.3,0.8,0.4` | Normalized `x,y,width,height`. |
| `maxResults` | `5` | Codes per frame. |
| `tryHarder` | `1` | More effort per frame. |
| `resolution` | `fhd` | `sd`, `hd`, `fhd` or `4k`. |
| `accent` | `%23ff6b35` | Accent color. URL-encode `#` as `%23`. |
| `hint` | `Scan%20your%20ticket` | Instruction text. Empty hides it. |
| `controls` | `none` | Hide the built-in buttons. |
| `autostart` | `0` | Wait for a `start` command instead of opening the camera immediately. |

Kebab-case names (`duplicate-filter`, `scan-area`, `max-results`, `try-harder`) work too. Add `debug=1` to show an on-screen log of the detected host channels and every event, which helps when wiring up a new host. Opened directly in a browser, with no host channel, the page also shows a short note explaining how to embed it.

## Message envelope

The page posts every event as a message with this envelope:

```json
{ "source": "qrgen", "version": 1, "type": "scan", "barcodes": [] }
```

| `type` | Extra fields | When |
| --- | --- | --- |
| `ready` | `engine` (`"worker"` or `"main"`) | The camera is open and scanning started. |
| `scan` | `barcodes`: [Barcode](../concepts/#the-barcode-result)[] | New codes passed the duplicate filter. |
| `track` | `tracked`: TrackedBarcode[] | Batch mode, after every decoded frame. |
| `select` | `barcode`, `selected`, `selection` | Batch results selection changed. |
| `state` | `state` | `idle`, `starting`, `scanning`, `paused`, `stopped`, `error`. |
| `error` | `code`, `message` | Starting failed. See [error codes](../options-events/#error-codes). |

Always check `source === "qrgen"` before handling a message; other scripts in the page may post messages too. `parseBridgeMessage()` does this for you (see below).

## Host channels

The page posts each message to every channel it finds, so the same page works in every host:

| Host | Channel in the page | What the host receives |
| --- | --- | --- |
| React Native (`react-native-webview`) | `window.ReactNativeWebView.postMessage(json)` | `onMessage` event, `nativeEvent.data` is the JSON string |
| Flutter (`webview_flutter`) | `window.QRGenBridge.postMessage(json)` | A `JavaScriptChannel` named `QRGenBridge` |
| iOS / macOS `WKWebView` | `window.webkit.messageHandlers.qrgen.postMessage(json)` | A `WKScriptMessageHandler` registered as `qrgen` |
| Windows WebView2, .NET MAUI on Windows | `window.chrome.webview.postMessage(json)` | `WebMessageReceived`, `TryGetWebMessageAsString()` |
| Android `WebView` | `window.QRGenAndroid.postMessage(json)` | A `@JavascriptInterface` object added as `QRGenAndroid` |
| `<iframe>` | `window.parent.postMessage(object, "*")` | A `message` event on the parent window; `event.data` is an object |
| Popup | `window.opener.postMessage(object, "*")` | A `message` event on the opener |

Native channels receive the message as a JSON string; iframe and popup hosts receive an object.

## Host-to-page commands

Control the scanner by calling `window.qrgen.command(command)` through your WebView's JavaScript evaluation API (`evaluateJavaScript`, `evaluateJavascript`, `ExecuteScriptAsync`, `injectJavaScript`, `runJavaScript`), or by posting `{ source: "qrgen-host", ...command }` into the page (iframes, React Native `postMessage`, Android `postWebMessage`).

| Command | Effect |
| --- | --- |
| `{ "type": "start" }` | Start the camera (after `autostart=0` or `stop`). |
| `{ "type": "stop" }` | Stop and release the camera. |
| `{ "type": "pause" }` | Stop decoding, keep the preview. |
| `{ "type": "resume" }` | Continue, for example after a `single` mode scan. |
| `{ "type": "torch" }` | Toggle the torch. With `"value": true` or `false`, set it. |
| `{ "type": "switchCamera" }` | Switch between front and back cameras. |
| `{ "type": "zoom", "value": 2 }` | Set the zoom factor. |
| `{ "type": "options", "value": { "mode": "batch", "symbologies": "qr" } }` | Set element attributes (kebab-case names, string values) at runtime. |

```js
// From a WebView evaluation API:
window.qrgen.command({ type: "torch", value: true });

// From an iframe host:
iframe.contentWindow.postMessage({ source: "qrgen-host", type: "resume" }, "https://rockyljewell.github.io");
```

`window.qrgen.channels` lists the host channels the page detected, which helps when debugging.

## Host examples

### iframe

```html
<iframe
  id="scanner"
  src="https://rockyljewell.github.io/QR-GEN/embed/?symbologies=qr,ean13&mode=single"
  allow="camera"
  style="width: 100%; height: 480px; border: 0"
></iframe>
<button id="again">Scan again</button>

<script>
  const ORIGIN = "https://rockyljewell.github.io";
  const frame = document.getElementById("scanner");

  window.addEventListener("message", (event) => {
    if (event.origin !== ORIGIN || event.data?.source !== "qrgen") return;
    if (event.data.type === "scan") console.log(event.data.barcodes[0].data);
    if (event.data.type === "error") console.warn(event.data.code, event.data.message);
  });

  document.getElementById("again").addEventListener("click", () => {
    frame.contentWindow.postMessage({ source: "qrgen-host", type: "resume" }, ORIGIN);
  });
</script>
```

`allow="camera"` is required for a cross-origin iframe to use the camera, and the parent page must itself be a secure context. On your own site, the [web components](../web-components/) are simpler than an iframe; the embed page is useful when you can't add scripts to the host page.

### iOS (WKWebView)

Add `NSCameraUsageDescription` to `Info.plist`, then:

```swift
import UIKit
import WebKit

final class ScannerViewController: UIViewController, WKScriptMessageHandler, WKUIDelegate {
    private var webView: WKWebView!

    override func viewDidLoad() {
        super.viewDidLoad()
        let config = WKWebViewConfiguration()
        config.allowsInlineMediaPlayback = true
        config.mediaTypesRequiringUserActionForPlayback = []
        config.userContentController.add(self, name: "qrgen")

        webView = WKWebView(frame: view.bounds, configuration: config)
        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        webView.uiDelegate = self
        view.addSubview(webView)
        webView.load(URLRequest(url: URL(string: "https://rockyljewell.github.io/QR-GEN/embed/?symbologies=qr,ean13&mode=single")!))
    }

    func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage) {
        guard let json = message.body as? String,
              let object = try? JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any],
              object["source"] as? String == "qrgen" else { return }
        if object["type"] as? String == "scan",
           let barcode = (object["barcodes"] as? [[String: Any]])?.first,
           let data = barcode["data"] as? String {
            print("Scanned", data)
        }
    }

    // iOS 15+: grant the page's camera request for this origin without WebKit's extra prompt.
    @available(iOS 15.0, *)
    func webView(_ webView: WKWebView, requestMediaCapturePermissionFor origin: WKSecurityOrigin, initiatedByFrame frame: WKFrameInfo, type: WKMediaCaptureType, decisionHandler: @escaping (WKPermissionDecision) -> Void) {
        decisionHandler(origin.host == "rockyljewell.github.io" ? .grant : .prompt)
    }

    func send(_ commandJSON: String) {
        webView.evaluateJavaScript("window.qrgen && window.qrgen.command(\(commandJSON))")
    }
}
```

`WKUserContentController` retains its handlers; remove the `qrgen` handler when you dismiss the scanner. For a native scanner without a WebView, see the [iOS SDK](../ios/).

### Android (WebView)

Declare `<uses-permission android:name="android.permission.CAMERA" />` in the manifest, then:

```kotlin
import android.Manifest
import android.content.pm.PackageManager
import android.os.Bundle
import android.webkit.JavascriptInterface
import android.webkit.PermissionRequest
import android.webkit.WebChromeClient
import android.webkit.WebView
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat
import org.json.JSONObject

class ScannerActivity : AppCompatActivity() {
    private lateinit var webView: WebView
    private val url = "https://rockyljewell.github.io/QR-GEN/embed/?symbologies=qr,ean13&mode=single"

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        webView = WebView(this)
        setContentView(webView)

        webView.settings.javaScriptEnabled = true
        webView.settings.mediaPlaybackRequiresUserGesture = false
        webView.addJavascriptInterface(Bridge(), "QRGenAndroid")
        webView.webChromeClient = object : WebChromeClient() {
            override fun onPermissionRequest(request: PermissionRequest) {
                val wantsCamera = request.resources.contains(PermissionRequest.RESOURCE_VIDEO_CAPTURE)
                if (wantsCamera && hasCameraPermission()) request.grant(arrayOf(PermissionRequest.RESOURCE_VIDEO_CAPTURE))
                else request.deny()
            }
        }

        if (hasCameraPermission()) webView.loadUrl(url)
        else requestPermissions(arrayOf(Manifest.permission.CAMERA), 1)
    }

    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        webView.loadUrl(url) // the page shows camera-permission-denied if the user refused
    }

    private fun hasCameraPermission() =
        ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED

    fun command(json: String) = webView.evaluateJavascript("window.qrgen && window.qrgen.command($json)", null)

    inner class Bridge {
        @JavascriptInterface
        fun postMessage(json: String) {
            val message = JSONObject(json)
            if (message.optString("source") != "qrgen") return
            if (message.optString("type") == "scan") {
                val data = message.getJSONArray("barcodes").getJSONObject(0).getString("data")
                runOnUiThread { Toast.makeText(this@ScannerActivity, data, Toast.LENGTH_SHORT).show() }
            }
        }
    }
}
```

`@JavascriptInterface` methods run on a background thread; switch to the main thread before touching views. For a native scanner, see the [Android SDK](../android/).

### Windows (WebView2, WinUI and WPF)

```csharp
using System.Text.Json;
using Microsoft.Web.WebView2.Core;

await webView.EnsureCoreWebView2Async();

webView.CoreWebView2.PermissionRequested += (_, e) =>
{
    if (e.PermissionKind == CoreWebView2PermissionKind.Camera && new Uri(e.Uri).Host == "rockyljewell.github.io")
        e.State = CoreWebView2PermissionState.Allow;
};

webView.CoreWebView2.WebMessageReceived += (_, e) =>
{
    using var doc = JsonDocument.Parse(e.TryGetWebMessageAsString());
    var root = doc.RootElement;
    if (root.GetProperty("source").GetString() != "qrgen") return;
    if (root.GetProperty("type").GetString() == "scan")
        Console.WriteLine(root.GetProperty("barcodes")[0].GetProperty("data").GetString());
};

webView.CoreWebView2.Navigate("https://rockyljewell.github.io/QR-GEN/embed/?symbologies=qr,ean13&mode=single");

// Commands
await webView.CoreWebView2.ExecuteScriptAsync("window.qrgen && window.qrgen.command({ type: 'pause' })");
```

Send commands with `ExecuteScriptAsync`, or post them with `PostWebMessageAsJson("{\"source\":\"qrgen-host\",\"type\":\"pause\"}")`. The bridge listens on `window.chrome.webview` too. For .NET MAUI on every platform, see the [.NET SDK](../dotnet/).

### React Native and Flutter

The [React Native package](../react-native/) includes `QRGenWebScanner`, which wraps the embed page in `react-native-webview`, and the [Flutter package](../flutter/) covers `webview_flutter`. Their guides show the setup, including camera permissions.

## Self-host the embed page

Host your own copy to pin the SDK version, work offline inside an app bundle served over HTTPS, change the look, or avoid a third-party origin. The page is a `<qrgen-scanner>` element configured from the query string and connected to the bridge:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
    <title>Scanner</title>
    <style>
      html, body { margin: 0; height: 100%; background: #000; overflow: hidden; }
      qrgen-scanner { position: fixed; inset: 0; height: 100%; }
    </style>
  </head>
  <body>
    <script type="module">
      import { attributesFromQuery, configure, connectBridge } from "./qrgen.js"; // dist/browser/qrgen.js

      configure({ wasmBaseUrl: "./wasm/" }); // zxing_reader.wasm next to the page

      const scanner = document.createElement("qrgen-scanner");
      for (const [name, value] of Object.entries(attributesFromQuery(location.search))) {
        scanner.setAttribute(name, value);
      }
      connectBridge(scanner); // forward events to the host, accept commands
      document.body.append(scanner);
    </script>
  </body>
</html>
```

Copy `node_modules/qrgen-sdk/dist/browser/qrgen.js` next to the page and the wasm files into `wasm/`. Serve it over HTTPS (or from `https://localhost` in app shells like Capacitor). Call `connectBridge()` before adding the element to the page so no early event is missed.

With a bundler, import from the npm entry points instead:

```js
import "qrgen-sdk/elements";
import { attributesFromQuery, connectBridge } from "qrgen-sdk/bridge";
```

## qrgen-sdk/bridge

| Export | Signature | Description |
| --- | --- | --- |
| `connectBridge` | `(element, window?) => () => void` | Forwards the element's `ready`, `scan`, `track`, `select`, `statechange` and `error` events to every host channel, defines `window.qrgen.command()` and listens for `{ source: "qrgen-host" }` messages on `window` and `document`. Returns a function that disconnects everything. |
| `parseBridgeMessage` | `(data: unknown) => BridgeMessage \| null` | Parses a message from the page (a JSON string or an object). Returns `null` unless it is a QRGen message. Use it in hosts. |
| `postToHost` | `(message: BridgeMessage, window?) => void` | Sends a message to every host channel in the window. |
| `detectChannels` | `(window?) => string[]` | Which host channels exist: `react-native`, `flutter`, `wkwebview`, `webview2`, `android`, `iframe`, `opener`. |
| `attributesFromQuery` | `(search: string) => Record<string, string>` | Maps an embed query string to `<qrgen-scanner>` attributes (camelCase and kebab-case names, `1`/`0` to `true`/`false`). Unknown parameters are ignored. |

`BridgeMessage` and `BridgeCommand` are exported as TypeScript types. A typed host handler for an iframe or a JavaScript-based WebView host:

```ts
import { parseBridgeMessage, type BridgeMessage } from "qrgen-sdk/bridge";

function onHostMessage(raw: unknown) {
  const message: BridgeMessage | null = parseBridgeMessage(raw);
  if (!message) return;
  switch (message.type) {
    case "scan":
      console.log(message.barcodes.map((b) => b.data));
      break;
    case "error":
      console.warn(message.code, message.message);
      break;
  }
}

window.addEventListener("message", (event) => onHostMessage(event.data));
```


---

# UI customization

URL: https://rockyljewell.github.io/QR-GEN/docs/ui-customization/
Group: Features

> Restyle the <qrgen-scanner> element with the accent color, CSS custom properties and shadow parts, or build a fully custom scanner UI on BarcodeScanner.

`<qrgen-scanner>` is designed to look right out of the box, and to be restyled without forking it. There are three levels of customization:

1. **Theme it**: accent color, font and corner radius through attributes and CSS custom properties.
2. **Restyle parts**: position and style the hint, toast, controls, viewfinder and video with `::part()`, or hide them.
3. **Build your own UI**: use `BarcodeScanner` with your own `<video>`, overlay and controls.

## Accent color

```html
<qrgen-scanner accent="#ff6b35"></qrgen-scanner>
```

The accent colors the code highlights, the laser line, the success flash on the viewfinder, the toast icon, buttons and the batch counter. Use a hex color (`#rgb` or `#rrggbb`); the overlay derives translucent fills from it. Text and icons on accent-colored surfaces use `--qrgen-accent-contrast`, so set that too when you pick a light or dark accent:

```css
qrgen-scanner {
  --qrgen-accent: #ffd60a;
  --qrgen-accent-contrast: #1c1c1e;
}
```

## CSS custom properties

| Property | Default | Controls |
| --- | --- | --- |
| `--qrgen-accent` | `#5cc9d6` | Highlights, laser, buttons, toast icon, counter |
| `--qrgen-accent-contrast` | `#062029` | Text and icons on accent surfaces |
| `--qrgen-radius` | `0px` | Corner radius of the scanner |
| `--qrgen-font` | system UI font stack | All text in the scanner |

```css
qrgen-scanner {
  --qrgen-accent: #6e56cf;
  --qrgen-accent-contrast: #ffffff;
  --qrgen-radius: 20px;
  --qrgen-font: "Inter", ui-sans-serif, system-ui, sans-serif;
  height: 520px;
  box-shadow: 0 20px 50px rgb(0 0 0 / 0.25);
}
```

Custom properties inherit, so you can set them once on `:root` or a theme class. The `accent` attribute is applied as an inline style and wins over stylesheet values.

## Shadow parts

| Part | What it is |
| --- | --- |
| `root` | The container that holds everything |
| `video` | The camera preview |
| `overlay` | The canvas with code highlights |
| `viewfinder` | The viewfinder frame or line box |
| `hint` | The instruction pill near the bottom |
| `toast` | The success toast at the top |
| `controls` | The top and bottom control bars |

```css
/* Move the hint to the top and make it larger */
qrgen-scanner::part(hint) {
  top: 72px;
  bottom: auto;
  font-size: 15px;
  padding: 10px 18px;
}

/* A square, flat toast */
qrgen-scanner::part(toast) {
  border-radius: 8px;
  background: rgb(0 0 0 / 0.85);
}

/* A slightly desaturated preview */
qrgen-scanner::part(video) {
  filter: saturate(0.85) contrast(1.05);
}

/* Hide the viewfinder outline but keep the automatic scan area */
qrgen-scanner::part(viewfinder) {
  visibility: hidden;
}
```

Hiding the `viewfinder` part keeps the decode region the viewfinder defines; `viewfinder="none"` instead scans the whole preview.

## Hint text

```html
<qrgen-scanner hint="Scan the QR code on your ticket"></qrgen-scanner>
<qrgen-scanner hint=""></qrgen-scanner> <!-- no hint -->
```

The default hint depends on the mode ("Point the camera at a barcode or QR code", or a batch-specific text). It fades out after the first successful scan.

## Hide controls and the toast

```html
<!-- No buttons, no counter, no "Scan again" button -->
<qrgen-scanner controls="none"></qrgen-scanner>

<!-- No success toast (the highlight and viewfinder flash remain) -->
<qrgen-scanner toast="false"></qrgen-scanner>
```

With `controls="none"`, provide your own buttons that call the element's methods: `pause()`, `resume()`, `toggleTorch()`, `switchCamera()`, `setZoom()`. In single mode, call `resume()` to scan again.

```html
<qrgen-scanner id="scanner" mode="single" controls="none" toast="false" style="height: 400px"></qrgen-scanner>
<div class="toolbar">
  <button id="torch">Flashlight</button>
  <button id="again" hidden>Scan next</button>
</div>

<script type="module">
  import "qrgen-sdk/elements";

  const scanner = document.getElementById("scanner");
  const again = document.getElementById("again");

  scanner.addEventListener("scan", ({ detail }) => {
    console.log(detail.barcode.data);
    again.hidden = false;
  });
  again.addEventListener("click", () => {
    again.hidden = true;
    scanner.resume();
  });
  document.getElementById("torch").addEventListener("click", () => scanner.toggleTorch());
</script>
```

## Build a fully custom UI

For complete control, skip the element and use `BarcodeScanner` with your own markup. The scanner reports every decoded frame through the `frame` event, with code corners in camera-frame pixels. To draw them over a preview that uses `object-fit: cover`, map each point from frame coordinates to element coordinates.

### The mapping

With `object-fit: cover`, the video is scaled uniformly until it covers the element, then centered, and the overflow is cropped:

```text
scale   = max(viewWidth / frameWidth, viewHeight / frameHeight)
offsetX = (viewWidth  - frameWidth  * scale) / 2     // <= 0: cropped on the left and right
offsetY = (viewHeight - frameHeight * scale) / 2     // <= 0: cropped at the top and bottom

viewX = offsetX + frameX * scale
viewY = offsetY + frameY * scale
```

If you mirror the preview for a front camera (`transform: scaleX(-1)`), mirror the x coordinate too: `viewX = viewWidth - viewX`.

The inverse maps a rectangle on screen (for example your own viewfinder) to a normalized `scanArea`:

```text
frameX = (viewX - offsetX) / scale
frameY = (viewY - offsetY) / scale
scanArea.x = frameX / frameWidth, scanArea.width = (frameX2 - frameX) / frameWidth, ...
```

### Complete example

```html
<div class="scanner">
  <video id="video"></video>
  <canvas id="overlay"></canvas>
  <div class="finder"></div>
  <div class="controls">
    <button id="start">Start</button>
    <button id="torch" hidden>Torch</button>
  </div>
  <output id="result"></output>
</div>

<style>
  .scanner { position: relative; height: 70vh; overflow: hidden; background: #000; color: #fff; font: 14px system-ui, sans-serif; }
  .scanner video, .scanner canvas { position: absolute; inset: 0; width: 100%; height: 100%; }
  .scanner video { object-fit: cover; }
  .scanner video.mirror { transform: scaleX(-1); }
  .scanner canvas { pointer-events: none; }
  .finder { position: absolute; left: 10%; right: 10%; top: 35%; height: 30%; border: 2px dashed rgb(255 255 255 / 0.7); border-radius: 12px; pointer-events: none; }
  .controls { position: absolute; top: 12px; right: 12px; display: flex; gap: 8px; }
  #result { position: absolute; left: 12px; right: 12px; bottom: 12px; padding: 8px 12px; border-radius: 8px; background: rgb(0 0 0 / 0.6); }
  #result:empty { display: none; }
</style>

<script type="module" src="./custom-scanner.ts"></script>
```

```ts
// custom-scanner.ts
import { BarcodeScanner, type Barcode, type Point, type ScanArea, type Size } from "qrgen-sdk";

const root = document.querySelector<HTMLDivElement>(".scanner")!;
const video = document.querySelector<HTMLVideoElement>("#video")!;
const canvas = document.querySelector<HTMLCanvasElement>("#overlay")!;
const finder = document.querySelector<HTMLDivElement>(".finder")!;
const result = document.querySelector<HTMLOutputElement>("#result")!;
const torchButton = document.querySelector<HTMLButtonElement>("#torch")!;
const ctx = canvas.getContext("2d")!;

const scanner = new BarcodeScanner({ video, symbologies: ["qr", "ean13", "code128"], maxResults: 4, beep: true });

interface Cover {
  scale: number;
  offsetX: number;
  offsetY: number;
  view: Size;
  frame: Size;
  mirror: boolean;
}

function cover(frame: Size): Cover {
  const view = { width: root.clientWidth, height: root.clientHeight };
  const scale = Math.max(view.width / frame.width, view.height / frame.height);
  return {
    scale,
    offsetX: (view.width - frame.width * scale) / 2,
    offsetY: (view.height - frame.height * scale) / 2,
    view,
    frame,
    mirror: scanner.camera.isFront,
  };
}

function toView(p: Point, c: Cover): Point {
  const x = c.offsetX + p.x * c.scale;
  return { x: c.mirror ? c.view.width - x : x, y: c.offsetY + p.y * c.scale };
}

function toScanArea(el: HTMLElement, c: Cover): ScanArea {
  const r = el.getBoundingClientRect();
  const base = root.getBoundingClientRect();
  let x0 = (r.left - base.left - c.offsetX) / c.scale;
  let x1 = (r.right - base.left - c.offsetX) / c.scale;
  if (c.mirror) [x0, x1] = [c.frame.width - x1, c.frame.width - x0];
  const y0 = (r.top - base.top - c.offsetY) / c.scale;
  const y1 = (r.bottom - base.top - c.offsetY) / c.scale;
  const clamp = (n: number) => Math.min(1, Math.max(0, n));
  const x = clamp(x0 / c.frame.width);
  const y = clamp(y0 / c.frame.height);
  return { x, y, width: clamp(x1 / c.frame.width) - x, height: clamp(y1 / c.frame.height) - y };
}

let lastCodes: Barcode[] = [];
let lastSeen = 0;

function draw(barcodes: Barcode[], frame: Size) {
  const now = performance.now();
  if (barcodes.length) {
    lastCodes = barcodes;
    lastSeen = now;
  } else if (now - lastSeen > 300) {
    lastCodes = []; // keep highlights briefly so they don't flicker between frames
  }

  const c = cover(frame);
  const dpr = window.devicePixelRatio || 1;
  if (canvas.width !== Math.round(c.view.width * dpr) || canvas.height !== Math.round(c.view.height * dpr)) {
    canvas.width = Math.round(c.view.width * dpr);
    canvas.height = Math.round(c.view.height * dpr);
  }
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
  ctx.clearRect(0, 0, c.view.width, c.view.height);

  for (const b of lastCodes) {
    const { topLeft, topRight, bottomRight, bottomLeft } = b.location;
    const points = [topLeft, topRight, bottomRight, bottomLeft].map((p) => toView(p, c));
    ctx.beginPath();
    points.forEach((p, i) => (i ? ctx.lineTo(p.x, p.y) : ctx.moveTo(p.x, p.y)));
    ctx.closePath();
    ctx.lineWidth = 3;
    ctx.strokeStyle = "#00e5a0";
    ctx.fillStyle = "rgb(0 229 160 / 0.2)";
    ctx.fill();
    ctx.stroke();
  }
}

function updateScanArea() {
  const { width, height } = scanner.camera.videoSize;
  if (width && height) scanner.setOptions({ scanArea: toScanArea(finder, cover({ width, height })) });
}

scanner.on("frame", ({ barcodes, frameSize }) => draw(barcodes, frameSize));

scanner.on("scan", ({ barcodes }) => {
  result.textContent = `${barcodes[0].symbologyName}: ${barcodes[0].data}`;
});

scanner.on("ready", ({ camera }) => {
  video.classList.toggle("mirror", camera.isFront);
  torchButton.hidden = !camera.capabilities.torch;
  updateScanArea();
});

scanner.on("error", (err) => {
  result.textContent = `${err.code}: ${err.message}`;
});

new ResizeObserver(updateScanArea).observe(root);

document.querySelector("#start")!.addEventListener("click", () => void scanner.start().catch(() => undefined));
torchButton.addEventListener("click", () => void scanner.toggleTorch());
```

This gives you the same behavior as the element: codes are only decoded inside your viewfinder, highlights are drawn where the codes are on screen, and the preview is mirrored for front cameras. From here you can add anything: animations, labels next to each code (`b.data`), sounds (`beep: false` plus your own audio), or batch-mode boxes from the `track` event.

`quadCenter(location)` and `quadBounds(location)` from `qrgen-sdk` return a code's center point and axis-aligned bounding box in frame pixels, handy for placing labels.


---

# JavaScript API

URL: https://rockyljewell.github.io/QR-GEN/docs/api/
Group: Reference

> Reference for every export of the qrgen-sdk package: scanning, camera, generation, parsers, symbologies, engine configuration, utilities and errors, with TypeScript signatures.

Everything on this page is exported from `qrgen-sdk`. `qrgen-sdk/node` re-exports all of it, and the [CDN bundles](../cdn/) expose it as named exports and on the `QRGen` global. Other entry points are summarized at the [end of the page](#other-entry-points).

```ts
import { BarcodeScanner, scanImage, generate, parseContent, configure } from "qrgen-sdk";
```

## Scanning

### BarcodeScanner

Camera scanning with duplicate filtering, feedback and batch tracking. Guide: [JavaScript](../javascript/).

```ts
class BarcodeScanner {
  constructor(options?: BarcodeScannerOptions);

  readonly camera: Camera;
  readonly video: HTMLVideoElement;
  readonly feedback: Feedback;
  readonly tracker: BarcodeTracker;
  readonly stats: { decodeMs: number; fps: number; engine: "" | "worker" | "main" };
  readonly state: ScannerState;
  readonly options: Readonly<BarcodeScannerOptions>; // current options with defaults applied

  start(): Promise<void>;
  stop(): void;
  pause(): void;
  resume(): void;
  setTorch(on: boolean): Promise<boolean>;
  toggleTorch(): Promise<boolean>;
  setZoom(zoom: number): Promise<boolean>;
  switchCamera(): Promise<void>;
  setOptions(partial: Partial<BarcodeScannerOptions>): void;
  destroy(): void;

  on<K extends keyof ScannerEvents>(event: K, listener: (payload: ScannerEvents[K]) => void): () => void;
  once<K extends keyof ScannerEvents>(event: K, listener: (payload: ScannerEvents[K]) => void): () => void;
  off<K extends keyof ScannerEvents>(event: K, listener: (payload: ScannerEvents[K]) => void): void;
  removeAllListeners(): void;
}

interface BarcodeScannerOptions extends ScannerOptions {
  video?: HTMLVideoElement;          // preview element; a detached one is created when omitted
  maxDecodeSize?: number;            // default 1280
  maxFps?: number;                   // default 24
  tryInvert?: boolean | "alternate"; // default "alternate"
}

interface ScannerEvents {
  scan: { barcodes: Barcode[] };
  track: TrackerUpdate;
  frame: FrameEvent;
  error: QRGenError;
  state: ScannerState;
  ready: { engine: "worker" | "main"; camera: Camera };
}

interface FrameEvent {
  barcodes: Barcode[];
  frameSize: Size;
  decodeMs: number;
}

type ScannerState = "idle" | "starting" | "scanning" | "paused" | "stopped" | "error";
```

`ScannerOptions` and every default are listed in [Options, events & errors](../options-events/#scanner-options). `QRGen.createScanner(options)` is a shortcut for `new BarcodeScanner(options)`.

### scanImage

```ts
function scanImage(input: ImageInput, options?: ScanImageOptions): Promise<Barcode[]>;

type ImageInput =
  | Blob | File | ArrayBuffer | Uint8Array | ImageData
  | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement
  | ImageBitmap | OffscreenCanvas
  | string; // URL or data URL

interface ScanImageOptions {
  symbologies?: SymbologyInput[] | string; // default: all
  maxResults?: number;                     // default 255 (1 to 255)
  tryHarder?: boolean;                     // default true
}
```

Guide: [Image scanning](../image-scanning/).

### BarcodeTracker

Assigns stable ids to codes across frames. Used by batch mode; usable on its own. Guide: [Batch scanning](../batch-scanning/#barcodetracker-for-custom-interfaces).

```ts
class BarcodeTracker {
  constructor(options?: TrackerOptions);
  readonly timeout: number;
  readonly maxJump: number;
  readonly size: number;             // number of live tracks
  readonly all: TrackedBarcode[];
  update(detections: readonly Barcode[], now?: number): TrackerUpdate;
  clear(): void;
}

interface TrackerOptions {
  timeout?: number; // ms without a detection before a track is dropped; default 500
  maxJump?: number; // max movement between frames, relative to code size; default 3
}

interface TrackerUpdate {
  tracked: TrackedBarcode[];
  added: TrackedBarcode[];
  updated: TrackedBarcode[];
  removed: TrackedBarcode[];
}
```

### DuplicateFilter

The filter behind the `duplicateFilter` option.

```ts
class DuplicateFilter {
  constructor(window?: number); // ms; default 1000; 0 = accept everything; negative = once until reset()
  window: number;
  accept(barcode: Pick<Barcode, "symbology" | "data">, now?: number): boolean; // true = report it
  reset(): void;
  static key(barcode: Pick<Barcode, "symbology" | "data">): string;
}
```

### Feedback

Beep and vibration. Available as `scanner.feedback`.

```ts
class Feedback {
  constructor(options?: FeedbackOptions);
  options: FeedbackOptions;
  unlock(): void;  // create or resume the audio context; call from a user gesture on iOS
  beep(): void;
  vibrate(pattern?: number | number[]): void; // default 40 ms
  success(): void; // beep + vibrate, as configured
  dispose(): void;
}

interface FeedbackOptions {
  beep?: boolean;
  vibrate?: boolean;
  frequency?: number; // Hz, default 2100
  duration?: number;  // ms, default 90
  volume?: number;    // 0 to 1, default 0.12
}
```

## Camera

A thin wrapper around `getUserMedia` with torch, zoom and camera switching. Available as `scanner.camera`.

```ts
class Camera {
  constructor(options?: CameraOptions);
  static isSupported(): boolean;             // getUserMedia exists
  static list(): Promise<MediaDeviceInfo[]>; // video inputs; labels need permission

  stream: MediaStream | null;
  readonly track: MediaStreamTrack | null;
  readonly isFront: boolean;
  readonly isTorchOn: boolean;
  readonly videoSize: { width: number; height: number };
  readonly capabilities: CameraCapabilities;
  readonly resolution: Resolution;

  start(video: HTMLVideoElement): Promise<void>;
  stop(): void;
  setTorch(on: boolean): Promise<boolean>;
  setZoom(zoom: number): Promise<boolean>;
  switch(): Promise<void>;
}

interface CameraOptions {
  camera?: "back" | "front" | string; // facing mode or deviceId; default "back"
  resolution?: Resolution;            // default "hd"
}

interface CameraCapabilities {
  torch: boolean;
  zoom: { min: number; max: number; step: number } | null;
  focusMode: string[];
}

type Resolution = "sd" | "hd" | "fhd" | "4k"; // 640x480, 1280x720, 1920x1080, 3840x2160
```

## Generation

Guide: [Barcode generation](../barcode-generation/).

```ts
function generate(data: string, options?: GenerateOptions): Promise<GeneratedBarcode>;
function generateSVG(data: string, options?: GenerateOptions): Promise<string>;
function generateDataURL(data: string, options?: GenerateOptions): Promise<string>; // data:image/svg+xml
function styleSvg(svg: string, foreground?: string, background?: string): string;   // recolor generator SVG

interface GenerateOptions {
  symbology?: SymbologyInput;       // default "qr"
  scale?: number;                   // module size in px; default 4
  ecLevel?: "L" | "M" | "Q" | "H" | string;
  gs1?: boolean;
  hrt?: boolean;
  margin?: boolean;                 // quiet zone; default true
  foreground?: string;              // default "#000000"
  background?: string;              // default "#ffffff"; or "transparent"
  rotate?: 0 | 90 | 180 | 270;
  version?: number;                 // 2D symbol size, e.g. QR version 1-40
  extraOptions?: string;            // extra encoder options
}

interface GeneratedBarcode {
  symbology: Symbology;
  data: string;
  svg: string;
  png: Blob | null;
  matrix: { width: number; height: number; modules: Uint8Array }; // 1 = dark
  text: string;
}
```

## Parsers

Guide: [Parsers](../parsers/). Also available from `qrgen-sdk/parsers` without the engine.

```ts
function parseContent(data: string, options?: ParseContentOptions): ParsedContent;
interface ParseContentOptions { symbology?: string; now?: Date }

function parseGS1(input: string): GS1Result | null;
function parseDigitalLink(input: string): GS1Result | null;
function formatGS1(result: Pick<GS1Result, "elements">): string;  // back to "(01)...(10)..."
function gs1Date(yymmdd: string, now?: Date): string | undefined;  // "YYYY-MM-DD"
function isValidCheckDigit(digits: string): boolean;               // GS1 mod-10
function computeCheckDigit(body: string): number;
const GS1_AIS: Record<string, AIDefinition>;

function parseAAMVA(input: string, options?: AamvaOptions): AamvaResult | null;
function parseAamvaDate(value: string | undefined, canadian: boolean): string; // "YYYY-MM-DD" or ""
const AAMVA_FIELDS: Readonly<Record<string, string>>;               // element code -> label
interface AamvaOptions { now?: Date }

interface GS1Result {
  elements: GS1Element[];
  values: Record<string, string>;
  digitalLink?: string;
}

interface GS1Element {
  ai: string;
  title: string;
  description: string;
  value: string;
  date?: string;             // date AIs, ISO
  number?: number;           // decimal AIs
  iso?: string;              // ISO currency or country prefix
  checkDigitValid?: boolean; // AIs with a check digit
}

interface AIDefinition {
  title: string;
  description: string;
  fixed?: number;
  max?: number;
  numeric?: boolean;
  decimal?: boolean;
  date?: boolean;
  check?: boolean;
  isoPrefix?: boolean;
}
```

`ParsedContent` is a union discriminated by `type`; its members are listed in [Parsers](../parsers/#parsecontent). `AamvaResult` is listed in [ID scanning](../id-scanning/#result-fields).

## Symbologies

Reference: [Symbologies](../symbologies/).

```ts
const SYMBOLOGIES: readonly SymbologyInfo[];
const ALL_SYMBOLOGIES: readonly Symbology[];
const WRITABLE_SYMBOLOGIES: readonly Symbology[];
const SYMBOLOGY_GROUPS: Readonly<Record<SymbologyGroup, readonly Symbology[]>>;

function resolveSymbologies(input?: SymbologyInput | readonly SymbologyInput[] | null): Symbology[];
function toSymbology(name: string): Symbology | undefined; // one id, alias or name
function symbologyInfo(id: Symbology): SymbologyInfo;      // throws for an unknown id
function symbologyName(id: Symbology): string;             // display name
function normalizeName(name: string): string;              // lowercase, [a-z0-9] only

interface SymbologyInfo {
  id: Symbology;
  name: string;
  kind: "linear" | "matrix";
  read: string[];   // zxing-cpp reader formats
  write?: string;   // zxing-cpp writer format
  aliases: string[];
  example: string;  // sample payload
}

type Symbology = "qr" | "micro-qr" | "rmqr" | "data-matrix" | "aztec" | "pdf417" | "micro-pdf417" | "maxicode"
  | "ean13" | "ean8" | "upca" | "upce" | "isbn" | "code128" | "code39" | "code93" | "codabar" | "itf" | "itf14"
  | "databar" | "databar-expanded" | "databar-limited" | "code32" | "pzn" | "telepen" | "dx-film-edge";

type SymbologyGroup = "all" | "linear" | "1d" | "matrix" | "2d" | "retail" | "industrial" | "gs1";
type SymbologyInput = Symbology | SymbologyGroup | string;
```

`resolveSymbologies()` accepts arrays or comma, space, semicolon or pipe separated strings, expands groups, removes duplicates and ignores unknown names. With no input it returns every symbology; with only unknown names it returns `[]`.

## Engine configuration

```ts
function configure(config: EngineConfig): void;
const VERSION: string;        // SDK version, e.g. "1.0.0"
const ENGINE_VERSION: string; // zxing-wasm version the SDK is built with

interface EngineConfig {
  readerWasmUrl?: string;
  writerWasmUrl?: string;
  wasmBaseUrl?: string;
  readerWasmBinary?: ArrayBuffer | Uint8Array;
  writerWasmBinary?: ArrayBuffer | Uint8Array;
  worker?: boolean; // default true
}
```

Call `configure()` before the first scan or generate call. Each call merges into the current configuration. `globalThis.QRGEN_WASM_BASE` is used as `wasmBaseUrl` when none is configured. Details: [Installation](../installation/#self-host-the-webassembly-engine).

## Utilities

```ts
function toBase64(bytes: Uint8Array | null | undefined): string;
function fromBase64(input: string): Uint8Array; // also accepts data: URLs
function quadCenter(q: Quadrilateral): Point;
function quadBounds(q: Quadrilateral): { x: number; y: number; width: number; height: number };
```

Use `fromBase64(barcode.rawBytes)` to get a result's raw payload bytes.

## Errors

```ts
class QRGenError extends Error {
  readonly name: "QRGenError";
  readonly code: QRGenErrorCode;
  readonly cause?: unknown;
  toJSON(): { code: QRGenErrorCode; message: string };
}

function toQRGenError(err: unknown): QRGenError; // maps getUserMedia DOMExceptions to codes

type QRGenErrorCode =
  | "camera-permission-denied" | "camera-not-found" | "camera-in-use" | "insecure-context"
  | "engine-load-failed" | "unsupported" | "bad-request" | "unknown";
```

Causes and fixes for each code: [Options, events & errors](../options-events/#error-codes).

## Types

```ts
interface Barcode {
  data: string;
  symbology: Symbology;
  symbologyName: string;
  rawBytes: string; // base64
  contentType: ContentType;
  isGS1: boolean;
  location: Quadrilateral;
  frameSize: Size;
  orientation: number;
  ecLevel: string;
  symbologyIdentifier: string;
  timestamp: number;
}

interface TrackedBarcode extends Barcode {
  id: number;
  firstSeen: number;
  lastSeen: number;
  count: number;
}

type ContentType = "text" | "binary" | "gs1" | "iso15434" | "mixed" | "unknown-eci";
interface Point { x: number; y: number }
interface Quadrilateral { topLeft: Point; topRight: Point; bottomRight: Point; bottomLeft: Point }
interface Size { width: number; height: number }
interface ScanArea { x: number; y: number; width: number; height: number } // normalized 0..1
type ScanMode = "single" | "continuous" | "batch";
type CameraFacing = "back" | "front";
type ViewfinderStyle = "frame" | "line" | "none";
```

The fields are explained in [Core concepts](../concepts/#the-barcode-result).

## The QRGen namespace

The default export (and the `QRGen` named export) groups the most used functions, mirroring the other QRGen SDKs:

```ts
import QRGen from "qrgen-sdk";

QRGen.version;                 // SDK version
QRGen.engineVersion;           // engine version
QRGen.configure(config);
QRGen.scanImage(input, options);
QRGen.generate(data, options);
QRGen.generateSVG(data, options);
QRGen.generateDataURL(data, options);
QRGen.parseContent(data, options);
QRGen.parseGS1(data);
QRGen.parseAAMVA(data, options);
QRGen.resolveSymbologies(input);
QRGen.symbologies;             // SYMBOLOGIES
QRGen.supportedSymbologies();  // { read: Symbology[], write: Symbology[] }
QRGen.createScanner(options);  // new BarcodeScanner(options)
```

## Other entry points

| Entry point | Exports | Reference |
| --- | --- | --- |
| `qrgen-sdk/elements` | `QRGenScannerElement`, `QRGenBarcodeElement`, `defineElements()` (called on import) | [Web Components](../web-components/) |
| `qrgen-sdk/react` | `QRGenScanner`, `QRGenBarcode`, types `QRGenScannerProps`, `QRGenScannerHandle`, `QRGenBarcodeProps` | [React](../react/) |
| `qrgen-sdk/vue` | `QRGenScanner`, `QRGenBarcode`, `QRGenPlugin` | [Vue & Nuxt](../vue/) |
| `qrgen-sdk/parsers` | The parser functions and types above | [Parsers](../parsers/) |
| `qrgen-sdk/node` | Everything above, plus `scanFile`, `scan`, `generatePNG`, `generateToFile`, `useLocalEngine` | [Node.js](../nodejs/) |
| `qrgen-sdk/server` | `createServer(options)`, `createHandler(options)`, type `ServerOptions` | [REST API](../rest-api/#mount-in-your-own-server) |
| `qrgen-sdk/bridge` | `connectBridge`, `parseBridgeMessage`, `postToHost`, `detectChannels`, `attributesFromQuery`, types `BridgeMessage`, `BridgeCommand` | [Embed bridge](../embed-bridge/#qrgen-sdkbridge) |


---

# Symbologies

URL: https://rockyljewell.github.io/QR-GEN/docs/symbologies/
Group: Reference

> All 26 barcode symbologies QRGen reads and writes, with ids, aliases, groups, and per-platform support for the web, Node.js, Python, iOS (Apple Vision) and Android (ML Kit).

QRGen identifies barcode types with the same lowercase ids on every platform. Use them in `symbologies` options, in `generate({ symbology })`, and to read `barcode.symbology` in results.

## Matching rules

Inputs are matched case-insensitively after removing everything except letters and digits, so `QRCode`, `qr-code`, `QR` and `qr` all resolve to `qr`. Display names (`EAN-13`, `Data Matrix`) and the aliases below work too. Unknown names are ignored.

Where a list is expected, you can pass an array or a string separated by commas, spaces, semicolons or pipes, and mix ids with [groups](#groups):

```js
import { resolveSymbologies, toSymbology } from "qrgen-sdk";

resolveSymbologies("retail, qr");  // ["ean13", "ean8", "upca", "upce", "isbn", "databar", "databar-expanded", "databar-limited", "qr"]
toSymbology("GS1-128");            // "code128"
toSymbology("Interleaved 2 of 5"); // "itf"
```

## All symbologies

| id | Name | Type | Aliases | Read | Write | Apple Vision | ML Kit |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `qr` | QR Code | 2D | `qrcode` | Yes | Yes | Yes | Yes |
| `micro-qr` | Micro QR Code | 2D | `microqrcode` | Yes | Yes | Yes | No |
| `rmqr` | rMQR Code | 2D | `rmqrcode` | Yes | Yes | No | No |
| `data-matrix` | Data Matrix | 2D | `datamatrix`, `dm` | Yes | Yes | Yes | Yes |
| `aztec` | Aztec | 2D | `azteccode`, `aztecrune` | Yes | Yes | Yes | Yes |
| `pdf417` | PDF417 | 2D | `compactpdf417`, `pdf` | Yes | Yes | Yes | Yes |
| `micro-pdf417` | MicroPDF417 | 2D | `micropdf417`, `micropdf` | Yes | Yes | Yes | No |
| `maxicode` | MaxiCode | 2D | | Yes | Yes | No | No |
| `ean13` | EAN-13 | Linear | `ean`, `jan`, `gtin13` | Yes | Yes | Yes | Yes |
| `ean8` | EAN-8 | Linear | `gtin8` | Yes | Yes | Yes | Yes |
| `upca` | UPC-A | Linear | `upc`, `gtin12` | Yes | Yes | Yes (as EAN-13 with a leading 0) | Yes |
| `upce` | UPC-E | Linear | | Yes | Yes | Yes | Yes |
| `isbn` | ISBN | Linear | `isbn13`, `bookland` | Yes | Yes | Yes (as EAN-13 with a 978/979 prefix) | Yes (as EAN-13) |
| `code128` | Code 128 | Linear | `gs1128`, `ean128`, `ucc128` | Yes | Yes | Yes | Yes |
| `code39` | Code 39 | Linear | `code3of9`, `code39std`, `code39ext`, `code39extended` | Yes | Yes | Yes | Yes |
| `code93` | Code 93 | Linear | | Yes | Yes | Yes | Yes |
| `codabar` | Codabar | Linear | `nw7`, `code2of7` | Yes | Yes | Yes | Yes |
| `itf` | Interleaved 2 of 5 | Linear | `interleaved2of5`, `i2of5`, `i25` | Yes | Yes | Yes | Yes |
| `itf14` | ITF-14 | Linear | `gtin14` | Yes | Yes | Yes | Yes (as ITF) |
| `databar` | GS1 DataBar | Linear | `rss14`, `databaromni`, `gs1databar`, `rss` | Yes | Yes | Yes | No |
| `databar-expanded` | GS1 DataBar Expanded | Linear | `rssexpanded`, `databarexp`, `gs1databarexpanded` | Yes | Yes | Yes | No |
| `databar-limited` | GS1 DataBar Limited | Linear | `rsslimited`, `databarltd`, `gs1databarlimited` | Yes | Yes | Yes | No |
| `code32` | Code 32 (Italian Pharmacode) | Linear | `italianpharmacode`, `pharmacode32` | Yes | Yes | No | No |
| `pzn` | PZN (Pharmazentralnummer) | Linear | `pharmazentralnummer` | Yes | Yes | No | No |
| `telepen` | Telepen | Linear | `telepenalpha`, `telepennumeric` | Yes | Yes | No | No |
| `dx-film-edge` | DX Film Edge | Linear | `dxfilmedge` | Yes | Yes | No | No |

**Read** and **Write** refer to the JavaScript SDK (web and Node.js), which reads and writes all 26. The Apple Vision and ML Kit columns show which ids the native [iOS](../ios/) and [Android](../android/) scanners can read; see [platform support](#platform-support).

In results, `symbologyName` holds the display name and `symbologyIdentifier` the AIM identifier when the engine reports one (for example `]Q1` for QR, `]C1` for GS1-128, `]E0` for EAN-13).

## Groups

| Group | Expands to |
| --- | --- |
| `all` (also `any`, `everything`) | Every symbology. The default when none is given. |
| `linear` or `1d` | `ean13` `ean8` `upca` `upce` `isbn` `code128` `code39` `code93` `codabar` `itf` `itf14` `databar` `databar-expanded` `databar-limited` `code32` `pzn` `telepen` `dx-film-edge` |
| `matrix` or `2d` | `qr` `micro-qr` `rmqr` `data-matrix` `aztec` `pdf417` `micro-pdf417` `maxicode` |
| `retail` | `ean13` `ean8` `upca` `upce` `isbn` `databar` `databar-expanded` `databar-limited` |
| `industrial` | `code128` `code39` `code93` `codabar` `itf` `itf14` `data-matrix` |
| `gs1` | `code128` `data-matrix` `qr` `databar` `databar-expanded` `databar-limited` |

Groups work wherever a list of symbologies is accepted (scanner options, `scanImage`, the element's `symbologies` attribute, the CLI's `--symbologies`, the REST API). They are not accepted by `generate()`, which needs exactly one symbology.

`SYMBOLOGY_GROUPS` exports this table, and `resolveSymbologies()` expands groups in code.

## Related symbologies

Some symbologies are subsets of others:

- A **UPC-A** is an EAN-13 whose first digit is `0`. An **ISBN** barcode is an EAN-13 that starts with `978` or `979`. **ITF-14** is a 14-digit Interleaved 2 of 5.
- **UPC-A** codes are reported as `upca` with 12 digits whenever `upca` is enabled. If you enable `ean13` without `upca`, they are reported as `ean13` with 13 digits (`0036000291452`).
- **ISBN** and **ITF-14** codes are reported with the parent id (`ean13`, `itf`) when the parent is enabled too, which includes the default `all` and the `retail` and `industrial` groups. Enable `isbn` without `ean13`, or `itf14` without `itf`, to get the specific id.
- Whatever id you get, `parseContent(data, { symbology })` returns the same 14-digit `gtin`, so use that for product lookups. For books, `parseContent` reports `kind: "isbn"` for 13-digit data starting with 978 or 979.

## Platform support

| Platform | Engine | Reads | Writes |
| --- | --- | --- | --- |
| Web (`qrgen-sdk`) | zxing-cpp (WebAssembly) | All 26 | All 26 |
| Node.js (`qrgen-sdk/node`), CLI, REST API | zxing-cpp (WebAssembly) | All 26 | All 26 |
| Python (`qrgen-sdk` on PyPI) | zxing-cpp | All 26 | All 26 |
| iOS and macOS (`QRGenKit`) | Apple Vision | The subset in the Apple Vision column | `qr`, `pdf417`, `aztec`, `code128`; others through the REST API |
| Android (`dev.qrgen:qrgen-android`) | Google ML Kit | The subset in the ML Kit column | See the [Android guide](../android/) |
| WebView platforms (embed page) | zxing-cpp (WebAssembly) | All 26 | Not applicable (scanning only) |

React Native, Flutter and .NET depend on the back end they use; see the [React Native](../react-native/), [Flutter](../flutter/) and [.NET](../dotnet/) guides. Platforms skip ids they can't read, without an error, and report what they support at runtime:

```js
import QRGen from "qrgen-sdk";

QRGen.supportedSymbologies(); // { read: [...26 ids], write: [...26 ids] }
```

The CLI prints the same table with `qrgen symbologies`, and the REST API returns it from `GET /v1/symbologies`.

## Choosing symbologies

Enabling fewer symbologies makes scanning faster and reduces false reads. Recommended sets for common use cases are in [Barcode scanning](../barcode-scanning/#choose-symbologies).


---

# Options, events & errors

URL: https://rockyljewell.github.io/QR-GEN/docs/options-events/
Group: Reference

> Reference tables for QRGen scanner options and their element attributes, BarcodeScanner and element events with payloads, and every error code with its causes and fixes.

This page collects the scanner options, events and error codes in one place. The option names are shared by every QRGen SDK (camelCase in JavaScript, Swift, Kotlin, Dart and C#; snake_case in Python).

## Scanner options

| Option | Element attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `symbologies` | `symbologies` | `string[] \| string` | all | Ids, aliases or [groups](../symbologies/#groups) to look for. |
| `mode` | `mode` | `"single" \| "continuous" \| "batch"` | `"continuous"` | `single` pauses after the first scan; `batch` tracks many codes. See [scan modes](../concepts/#scan-modes). |
| `duplicateFilter` | `duplicate-filter` | `number` (ms) | `1000`; `-1` in batch | Suppress the same symbology and data within this window. `0` reports every frame, `-1` once per session. |
| `beep` | `beep` | `boolean` | `true` | Play a tone on scan. |
| `vibrate` | `vibrate` | `boolean` | `true` | Vibrate on scan, where supported. |
| `camera` | `camera` | `"back" \| "front" \| string` | `"back"` | Facing mode, or a `deviceId` from `Camera.list()`. |
| `torch` | `torch` | `boolean` | `false` | Flashlight. On `BarcodeScanner`, call `setTorch(true)` after `ready` instead. |
| `viewfinder` | `viewfinder` | `"frame" \| "line" \| "none"` | `"frame"`; `"line"` for linear-only sets | Viewfinder style. UI only; `BarcodeScanner` has no viewfinder. |
| `scanArea` | `scan-area` | `{ x, y, width, height }` (0 to 1); attribute `"x,y,w,h"` | Full frame; the element derives it from the viewfinder | Region of the camera frame to decode. |
| `maxResults` | `max-results` | `number` | `1`; `20` in batch | Codes decoded per frame. |
| `tryHarder` | `try-harder` | `boolean` | `false` (single/continuous), `true` (batch) | More CPU per frame for damaged, tiny or low-contrast codes. |
| `resolution` | `resolution` | `"sd" \| "hd" \| "fhd" \| "4k"` | `"hd"` | Requested camera resolution: 640x480, 1280x720, 1920x1080, 3840x2160. |
| `worker` | `worker` | `boolean` | `true` | Decode in a Web Worker. |

`BarcodeScanner` only:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `video` | `HTMLVideoElement` | a detached element | Where the preview plays. |
| `maxDecodeSize` | `number` | `1280` | Longest side, in pixels, of the image handed to the decoder. Lower is faster; higher finds smaller codes. |
| `maxFps` | `number` | `24` | Upper bound for decodes per second. |
| `tryInvert` | `boolean \| "alternate"` | `"alternate"` | Look for white-on-black codes on every frame (`true`), never (`false`), or every other frame. Inverted linear and PDF417 codes cost a second decode, run only when nothing else was found in the frame. |

`<qrgen-scanner>` only:

| Attribute | Default | Description |
| --- | --- | --- |
| `autostart` | `true` | Start when connected. `false` shows a **Start scanning** screen. |
| `controls` | shown | `none` hides the buttons, the batch counter and **Scan again**. |
| `accent` | `#5cc9d6` | Accent color (hex). |
| `hint` | mode-specific | Instruction text; `""` hides it. |
| `toast` | `true` | Success toast with the scanned value. |

Other option sets:

- `scanImage()`: `symbologies`, `maxResults` (default 255), `tryHarder` (default `true`). See [Image scanning](../image-scanning/#options).
- `generate()`: see [Barcode generation](../barcode-generation/#options).
- `configure()`: see [Installation](../installation/#self-host-the-webassembly-engine).
- REST API query and body options: see [REST API](../rest-api/#scan).
- Embed page query string: see [Embed bridge](../embed-bridge/#query-options).

## BarcodeScanner events

Subscribe with `scanner.on(event, listener)`, which returns an unsubscribe function.

| Event | Payload | When |
| --- | --- | --- |
| `scan` | `{ barcodes: Barcode[] }` | New codes passed the duplicate filter. |
| `frame` | `{ barcodes: Barcode[], frameSize: Size, decodeMs: number }` | After every decoded frame, with everything found in it. |
| `track` | `{ tracked, added, updated, removed }` (`TrackedBarcode[]`) | Batch mode, after every decoded frame. |
| `state` | `ScannerState` | `idle`, `starting`, `scanning`, `paused`, `stopped`, `error`. |
| `ready` | `{ engine: "worker" \| "main", camera: Camera }` | Camera open, decoding started. |
| `error` | `QRGenError` | Start failed (also rejects `start()`), or the engine failed while scanning. |

## Element events

`<qrgen-scanner>` dispatches `CustomEvent`s that bubble and are composed. The payload is `event.detail`.

| Event | `detail` | React prop | Vue event |
| --- | --- | --- | --- |
| `scan` | `{ barcodes: Barcode[], barcode: Barcode }` | `onScan(barcodes, barcode)` | `@scan` |
| `track` | `{ tracked, added, removed }` | `onTrack(detail)` | `@track` |
| `select` | `{ barcode: TrackedBarcode \| null, selected: boolean, selection: TrackedBarcode[] }` | `onSelect(detail)` | `@select` |
| `ready` | `{ engine: "worker" \| "main" }` | `onReady(detail)` | `@ready` |
| `statechange` | `{ state: ScannerState }` | `onStateChange(state)` | `@statechange` |
| `error` | `{ code: QRGenErrorCode, message: string }` | `onError(error)` | `@error` |

`<qrgen-barcode>` dispatches:

| Event | `detail` |
| --- | --- |
| `render` | `{ svg: string, symbology: Symbology }` |
| `error` | `{ message: string }` |

The embed page forwards the scanner events as bridge messages; see the [message envelope](../embed-bridge/#message-envelope).

## Error codes

Errors are `QRGenError` instances with a `code`. The element's `error` event and the bridge carry `{ code, message }`.

| Code | Meaning | Common causes | Fix |
| --- | --- | --- | --- |
| `insecure-context` | The page isn't a secure context. | Served over `http://` from a hostname or IP other than `localhost`; opened from an unusual scheme. | Serve over HTTPS (or `http://localhost` in development). |
| `camera-permission-denied` | The browser or OS refused camera access. Mapped from `NotAllowedError`, `PermissionDeniedError` and `SecurityError`. | The user clicked **Block**, or blocked the camera for the site earlier; the OS denies the browser or app (macOS, Windows, iOS and Android privacy settings); an `<iframe>` without `allow="camera"`; a `Permissions-Policy` header without `camera`; a WebView host that doesn't grant camera requests. | Explain why you need the camera and how to re-enable it in the site settings. For iframes add `allow="camera"`. In apps, request the OS permission and grant WebView requests (see [Embed bridge](../embed-bridge/#host-examples)). |
| `camera-not-found` | No camera matched. Mapped from `NotFoundError`, `DevicesNotFoundError` and `OverconstrainedError`. | No camera on the device, or it is disabled; a `deviceId` that no longer exists (the scanner retries with the facing mode first). | Offer image upload with `scanImage()` as a fallback. Refresh the list with `Camera.list()`. |
| `camera-in-use` | The camera couldn't be started. Mapped from `NotReadableError`, `TrackStartError` and `AbortError`. | Another app or tab holds the camera (common on Windows); a driver or hardware error; on Android, the app lacks the runtime permission while the WebView granted the request. | Close other apps using the camera and retry. On Android, request the `CAMERA` permission before starting. |
| `engine-load-failed` | The WebAssembly engine couldn't be downloaded or compiled. | No network; a CSP without `'wasm-unsafe-eval'` or without the wasm origin in `connect-src`; a wrong `wasmBaseUrl` (404); wasm files missing from a serverless deployment. The message includes the URL that failed. | Allow the wasm origin and `'wasm-unsafe-eval'`, or [self-host the wasm](../installation/#self-host-the-webassembly-engine) and check the URL. |
| `unsupported` | The environment lacks a required feature, or the operation isn't possible. | A browser or WebView without `getUserMedia`; no Canvas 2D; a symbology that can't be generated. | Update the browser, open the page in the system browser instead of an in-app one, or fall back to `scanImage()`. |
| `bad-request` | The input is invalid. | `scanImage()` got an image that isn't loaded or a URL that failed; `generate()` got empty data, an unknown symbology, or data the symbology can't encode (the message says why); invalid REST requests. | Fix the input. Validate data before generating, for example digits only for EAN-13. |
| `unknown` | Anything else. | Unexpected browser errors. | Check `error.cause` for the original error. |

Handle errors from the promise or the event:

```js
import "qrgen-sdk/elements";

const scanner = document.querySelector("qrgen-scanner");

scanner.addEventListener("error", ({ detail }) => {
  switch (detail.code) {
    case "camera-permission-denied":
      showHelp("Allow camera access in your browser settings, then tap Try again.");
      break;
    case "camera-not-found":
      showHelp("No camera found. You can upload a photo instead.");
      break;
    case "insecure-context":
      showHelp("The scanner needs a secure (https) connection.");
      break;
    default:
      showHelp(detail.message);
  }
});

function showHelp(text) {
  document.querySelector("#help").textContent = text;
}
```

The element also shows its own error screen with the message and a **Try again** button.

The REST API returns the codes that apply to it (`bad-request`, `unsupported`, `engine-load-failed`, `unknown`), plus `not-found` (404) and `payload-too-large` (413). See [REST API errors](../rest-api/#errors).


---

# Troubleshooting

URL: https://rockyljewell.github.io/QR-GEN/docs/troubleshooting/
Group: Reference

> Fix common QRGen problems: the camera does not start, black video on iOS, slow scanning, codes not found, CSP warnings, blocked wasm and SSR errors.

Start with the error code, if there is one. The element shows it on its error screen, the `error` event carries it, and `start()` rejects with it. The [error code table](../options-events/#error-codes) lists causes for each. The sections below cover the problems that come up most often.

## The camera does not start

Work through these in order:

1. **Secure context.** The page must be served over HTTPS, or from `http://localhost` / `http://127.0.0.1`. A LAN address such as `http://192.168.1.20:5173` is not secure, which is why scanning works on your laptop but not on your phone. Check `window.isSecureContext` in the console. For phone testing, use HTTPS on your dev server (Vite: `@vitejs/plugin-basic-ssl`; Next.js: `next dev --experimental-https`; Angular: `ng serve --ssl`) or a tunnel. Error code: `insecure-context`.
2. **Permission.** If the user blocked the camera once, the browser remembers and won't ask again. They have to allow it in the site settings (the icon next to the address bar on desktop; **Settings > Safari > Camera** or the **aA** menu on iOS; site settings in Chrome on Android). The OS can also block the browser: check **System Settings > Privacy & Security > Camera** on macOS and **Settings > Privacy & security > Camera** on Windows. Error code: `camera-permission-denied`.
3. **Camera in use.** Another app (a video call, the OS camera app) or another tab may hold the camera. On Windows, only one app can use a camera at a time. Close the other app and retry. Error code: `camera-in-use`.
4. **Iframes.** A scanner inside an `<iframe>` needs `allow="camera"` on the iframe, and the parent page must be a secure context too. Without it the error is `camera-permission-denied` with no prompt.
5. **Permissions-Policy.** A `Permissions-Policy` response header that doesn't include `camera` (for example `camera=()`) blocks the camera for the page.
6. **In-app browsers and WebViews.** Some in-app browsers (social and messaging apps) don't support `getUserMedia`, and app WebViews only get the camera if the app grants it. Test in the system browser; for your own apps, see [Capacitor](../capacitor/), [Cordova](../cordova/) or the [embed bridge host examples](../embed-bridge/#host-examples).
7. **No camera.** Desktops without a webcam report `camera-not-found`. Offer [image upload](../image-scanning/) as a fallback.

A quick check in the browser console:

```js
console.log(window.isSecureContext, !!navigator.mediaDevices?.getUserMedia);
navigator.mediaDevices.getUserMedia({ video: true }).then((s) => (s.getTracks().forEach((t) => t.stop()), "camera OK"), (e) => e.name);
```

## Black video on iOS

- **Inline playback.** iOS plays video full screen, or not at all, unless the element has `playsinline` and `muted`. QRGen sets both on the video it uses, including a `video` you pass to `BarcodeScanner`. If you create your own `<video>` for another purpose, add `playsinline muted autoplay`.
- **WKWebView apps.** In a native app, the WebView needs inline media playback enabled: `allowsInlineMediaPlayback = true` on `WKWebViewConfiguration` (Cordova: `<preference name="AllowInlineMediaPlayback" value="true" />`).
- **Hidden or detached video.** Give the preview a size and keep it in the page. A `video` with `display: none`, or one that was never added to the DOM, may never deliver frames on iOS.
- **One camera stream at a time.** iOS Safari allows a single active camera stream. Starting a second scanner (or another page or tab using the camera) turns the first preview black. Call `stop()` or `destroy()` on scanners you no longer show.
- **After switching apps.** iOS suspends the camera when Safari goes to the background. If the preview is black after coming back, restart it on `visibilitychange` (see [JavaScript](../javascript/#clean-up)).
- **Old iOS.** QRGen supports iOS 14.5 and later.

## Scanning is slow

Measure first: `scanner.stats` (on `BarcodeScanner`, or `el.scanner.stats` on the element) shows `decodeMs` per frame, decodes per second (`fps`) and the `engine`.

- **Limit symbologies.** Scanning for all 26 is the biggest cost. Enable only what you need (`symbologies="qr"` or `"retail"`). See [recommended sets](../barcode-scanning/#choose-symbologies).
- **Use the worker.** If `engine` is `"main"`, decoding competes with your UI. See [the worker warning](#decoding-on-the-main-thread-warning).
- **Lower the resolution.** `resolution="sd"` (640x480) is enough for most QR codes and retail barcodes at normal distance.
- **Decode smaller images.** On `BarcodeScanner`, `maxDecodeSize` (default 1280) caps the size handed to the decoder. `960` or `800` is noticeably faster on older phones. On the element: `el.scanner.setOptions({ maxDecodeSize: 960 })` after `ready`.
- **Turn off extra passes.** Set `try-harder="false"` explicitly to disable hard search in batch mode; single/continuous modes already default to false, and set `tryInvert: false` on `BarcodeScanner` if you never scan white-on-black codes.
- **Keep the scan area small.** The element decodes only the viewfinder region; with `viewfinder="none"` or batch mode it decodes everything visible. With `BarcodeScanner`, set `scanArea`.
- **Batch mode.** Lower `max-results` if you never have 20 codes in view.
- **Heat.** Phones throttle the CPU when they get hot. Stop the scanner when it's not on screen.

## Codes are not found

- **Is the symbology enabled?** A Code 39 label won't be found with `symbologies="qr"`. Try without `symbologies` once to see what the code is.
- **Is the code inside the viewfinder?** The element only decodes the viewfinder region (plus a small margin). Aim so the whole code is inside it.
- **Distance and focus.** Minimum focus distance depends on the camera. Move the phone back until the code is sharp, and use `resolution="fhd"` for small codes. Fixed-focus webcams may need the code further away. Try brighter, even lighting and keep the camera steady.
- **Small or dense codes.** Each module needs a few pixels. Use `resolution="fhd"`, zoom in, or take a photo and use `scanImage()`, which works at full resolution.
- **Glare and lighting.** Reflections on glossy labels, screens and laminated cards hide parts of the code: tilt the code or the phone slightly. In the dark, turn on the torch.
- **Motion blur.** Hold still for a moment, especially in low light.
- **Damaged or low-contrast codes.** Turn on `try-harder`. For images, `tryHarder` is already on.
- **Inverted codes.** White-on-black codes are tried on every other frame by default. With `BarcodeScanner`, set `tryInvert: true` to try every frame.
- **Screens.** Codes on monitors can show moire patterns. Lower the screen's brightness, or move closer and zoom less.
- **Reported as a different type.** A book barcode comes back as `ean13` and an ITF-14 as `itf` when the parent symbology is enabled too. See [related symbologies](../symbologies/#related-symbologies).

To separate camera problems from decoding problems, take a photo of the code and try it with `scanImage()` or `qrgen scan photo.jpg`.

## "decoding on the main thread" warning

```text
[qrgen] decoding on the main thread: <reason>
```

The decoder worker couldn't start, so frames are decoded on the main thread. Scanning still works but can make the page less responsive. Common reasons:

- **CSP.** The policy doesn't allow Blob URL workers. Add `blob:` to `worker-src` (or to `script-src` if you have no `worker-src`).
- **The worker couldn't load the engine**, for example because `connect-src` blocks the wasm URL inside the worker. The reason in the message says which.
- **No Worker support** in the environment.

If you prefer the main thread on purpose, set `worker: false` (or `worker="false"` on the element) and the warning goes away.

## The engine fails to load

Error code `engine-load-failed`, with a message like `The barcode engine failed to load (...). Check network access to https://cdn.jsdelivr.net/... or self-host the wasm with configure({ wasmBaseUrl }).`

- **Network filters.** Corporate proxies, firewalls, ad blockers and some countries' networks block or throttle `cdn.jsdelivr.net`. [Self-host the wasm](../installation/#self-host-the-webassembly-engine) on your own origin.
- **CSP.** Check the console for `Refused to connect` (add the origin to `connect-src`) or `Refused to compile or instantiate WebAssembly` (add `'wasm-unsafe-eval'` to `script-src`).
- **Wrong self-hosted path.** Open the URL from the error message in a new tab. A 404 means `wasmBaseUrl` doesn't point at the folder with `zxing_reader.wasm`. Relative URLs resolve against the page, so prefer absolute paths like `/qrgen/`.
- **Version mismatch.** After upgrading `qrgen-sdk`, copy the wasm files again. Old files with new JavaScript fail to instantiate.
- **Offline apps.** An app that must work offline on first launch has to bundle the wasm; see [Capacitor](../capacitor/#offline-apps) or [Electron](../electron/#offline-engine).
- **Serverless.** `ENOENT ... zxing_reader.wasm` in Node means the wasm files weren't deployed. See [Node.js serverless notes](../nodejs/#serverless).

## Server-side rendering errors

QRGen's modules are safe to import on the server: nothing touches `window`, `document` or the camera at import time, and the elements only register in the browser. Errors during SSR usually come from calling browser APIs in render code:

- **`window is not defined`, `document is not defined`, `navigator is not defined`**: code that creates a `BarcodeScanner`, calls `scanImage()` or reads `navigator.mediaDevices` runs on the server. Move it into `useEffect`, `onMounted`, `onMount` or an event handler.
- **Next.js: hook errors such as "useRef only works in Client Components"**: the file that renders `QRGenScanner` needs `"use client"`. See [Next.js](../nextjs/).
- **Nuxt and SvelteKit**: wrap the scanner in `<ClientOnly>` (Nuxt) or import the SDK in `onMount` (SvelteKit) if you want to skip server rendering entirely. See [Vue & Nuxt](../vue/#nuxt) and [Svelte & SvelteKit](../svelte/#sveltekit).
- **Vue warning "Failed to resolve component: qrgen-scanner"**: set `compilerOptions.isCustomElement` when you use the raw element in templates. See [Vue](../vue/#using-the-elements-directly).

## No beep or vibration

- **iOS beep.** Audio only plays after a user gesture. Start the scanner from a tap (`autostart="false"` shows a **Start scanning** button), or accept silence until the first tap.
- **Silent mode.** On iPhone, the ring/silent switch mutes web audio.
- **Vibration.** iOS Safari and iOS WebViews don't support the Vibration API. Android Chrome does, unless the phone is in a mode that disables vibration.
- **Kiosks.** Chromium blocks audio without a gesture; start it with `--autoplay-policy=no-user-gesture-required` (see [Linux kiosk](../linux/#chromium-kiosk)).

## Still stuck?

Search or open an issue on [GitHub](https://github.com/Rockyljewell/QR-GEN/issues) with the browser and OS versions, the error code and message, and `scanner.stats`. For decoding problems, attach a photo of the code if it doesn't contain personal data.


---

# FAQ

URL: https://rockyljewell.github.io/QR-GEN/docs/faq/
Group: Reference

> Answers to common questions about QRGen: licensing, privacy, offline use, browser and platform support, bundle size, ID documents and commercial SDKs.

## Is QRGen free for commercial use?

Yes. QRGen is licensed under the Apache License 2.0: use it in commercial and closed-source products, modify it, and redistribute it. When you ship it, keep the license, the copyright headers and the NOTICE text (see [Credit and attribution](../credit/)). There are no license keys, per-device fees, usage limits or telemetry. The decoding engine is [zxing-cpp](https://github.com/zxing-cpp/zxing-cpp) (Apache-2.0), compiled to WebAssembly by [zxing-wasm](https://github.com/Sec-ant/zxing-wasm) (MIT).

## Do I have to credit QRGen?

If you ship it, yes: include the license, keep the copyright headers and put the NOTICE text wherever your product lists open-source credits. A visible "Powered by QRGen" link is optional. See [Credit and attribution](../credit/) for the text to copy and where it goes on each platform.

## Are camera images uploaded anywhere?

No. Decoding runs on the device, in WebAssembly in the browser or with the native engine on iOS and Android. Frames and images never leave the device unless your own code sends them, and QRGen collects no analytics. The browser SDK's only network requests are the engine download (from jsDelivr unless you self-host it) and image URLs you pass to `scanImage()`. See [privacy](../concepts/#privacy).

## Does it work offline?

Yes, once the engine is available. Browsers cache the wasm after the first download. For guaranteed offline use (installed PWAs, kiosks, desktop and mobile app shells), [self-host the wasm](../installation/#self-host-the-webassembly-engine) and bundle it with your app. The Node.js package reads it from `node_modules` and never needs the network.

## Which browsers are supported?

Current Chrome, Edge, Firefox, Samsung Internet and Safari, on desktop and mobile, with iOS Safari 14.5 or later. Camera scanning needs `getUserMedia` and a secure context (HTTPS or localhost). See [browser support](../installation/#browser-support).

## Why doesn't the camera work on my phone when it works on my laptop?

Almost always because the phone loads the dev server over a LAN address like `http://192.168.1.20:5173`, which isn't a secure context. Use HTTPS or a tunnel. See [Troubleshooting](../troubleshooting/#the-camera-does-not-start).

## How big is it?

The JavaScript is about 60 KB gzipped for the full bundle (less with tree shaking if you only import what you use). The decoder wasm is about 400 KB gzipped and is downloaded once, when scanning starts. The generator wasm (about 340 KB gzipped) is only downloaded if you generate barcodes.

## Which barcode types are supported?

26 symbologies, including QR Code, Micro QR, rMQR, Data Matrix, Aztec, PDF417, MaxiCode, EAN/UPC, Code 128 (including GS1-128), Code 39, Code 93, Codabar, ITF, GS1 DataBar and several pharmaceutical codes. All of them can also be generated. See [Symbologies](../symbologies/).

## Can it scan several barcodes at once?

Yes. [Batch mode](../batch-scanning/) tracks up to 20 codes per frame with stable ids and lets users choose decoded results from a list below the camera preview. `scanImage()` returns every code in an image.

## Can it read driver licenses and passports?

It reads the PDF417 barcode on US and Canadian driver licenses and ID cards, and `parseAAMVA()` extracts the name, birth date, address and expiry. Passports and most other national ID documents use an MRZ (printed text), which needs OCR; QRGen doesn't include OCR. See [ID scanning](../id-scanning/).

## Does it work in React Native, Flutter, Ionic or Electron?

Yes. Capacitor, Ionic, Cordova, Electron and Tauri run the web SDK in their WebView. React Native and Flutter have their own packages, and any other WebView can load the hosted [embed page](../embed-bridge/). See the [platform list](../introduction/#platforms).

## Can I use it on a server or from another language?

Yes. Use [`qrgen-sdk/node`](../nodejs/) in Node.js, the [`qrgen` CLI](../cli/) in scripts, the [Python package](../python/), or run the [REST API](../rest-api/) (also as a Docker image) and call it from any language.

## Do I need QRGen if I have a hardware barcode scanner?

USB and Bluetooth scanners usually act as keyboards and type the code into the focused field, so you don't need a camera SDK to read them. You can still use QRGen's [parsers](../parsers/) on the typed text, for example to extract the GTIN, batch and expiry from a GS1 DataMatrix, or to parse a driver license read by a 2D scanner. To generate labels for them to scan, use the [generator](../barcode-generation/).

## Can I change the look of the scanner?

Yes: accent color, font and corner radius through CSS custom properties, individual pieces through `::part()`, hidden controls with `controls="none"`, or a completely custom UI on `BarcodeScanner`. See [UI customization](../ui-customization/).

## Can I change the beep?

Turn it off with `beep="false"` and play your own sound in the `scan` handler, or tune the built-in tone through `scanner.feedback.options` (`frequency`, `duration`, `volume`). See [feedback](../barcode-scanning/#feedback).

## Why is my ISBN reported as EAN-13?

An ISBN barcode is an EAN-13 that starts with 978 or 979, and an ITF-14 is a 14-digit Interleaved 2 of 5. When the parent symbology is enabled too (as with the default `all`), the result uses the parent id: `ean13` or `itf`. Enable `isbn` without `ean13` to get `isbn`. `parseContent()` reports `kind: "isbn"` either way. See [related symbologies](../symbologies/#related-symbologies).

## How does QRGen compare to Scandit and other commercial SDKs?

QRGen is an independent open-source project and is not affiliated with Scandit or any other vendor. It covers the common needs (fast QR and retail scanning, batch tracking, a pre-built UI, parsers) at no cost and with no lock-in. Commercial SDKs can still outperform it on badly damaged codes, very small or distant codes, and difficult lighting, and they offer features QRGen doesn't have, such as OCR, MRZ reading, AR overlays and vendor support. Test with your own codes and devices. For a concept-by-concept mapping, see [Migrating from other SDKs](../migration/).

## Can coding agents use QRGen?

Yes. The [Agent Skills](../../agent-skills/) teach agents such as Claude Code how to integrate QRGen correctly. Install them with `npx skills add https://github.com/Rockyljewell/QR-GEN`, or in Claude Code with `/plugin marketplace add Rockyljewell/QR-GEN` followed by `/plugin install qrgen-sdk@qrgen-plugins`.

## How do I report a bug or ask for a feature?

Open an issue on [GitHub](https://github.com/Rockyljewell/QR-GEN/issues). Include the platform, browser or OS version, the error code, and if possible a photo of a code that fails (without personal data). Contributions are welcome.


---

# Migrating from other SDKs

URL: https://rockyljewell.github.io/QR-GEN/docs/migration/
Group: Reference

> Move to QRGen from html5-qrcode, @zxing/browser and @zxing/library, QuaggaJS and quagga2, or a commercial SDK such as Scandit, with side-by-side API and concept mappings.

This page maps the APIs and concepts of popular barcode libraries to their QRGen equivalents, with before-and-after code. In most apps the migration is small: replace the scanner setup, rename the format constants to [symbology ids](../symbologies/), and read `barcode.data` instead of the old result's text.

Install QRGen first:

```bash
npm install qrgen-sdk
```

> **Note:** Until the first npm release is published, install the latest build with `npm install https://rockyljewell.github.io/QR-GEN/downloads/qrgen-sdk.tgz`.

## From html5-qrcode

### Pre-built scanner

Before:

```js
import { Html5QrcodeScanner, Html5QrcodeSupportedFormats } from "html5-qrcode";

const scanner = new Html5QrcodeScanner(
  "reader",
  { fps: 10, qrbox: { width: 250, height: 250 }, formatsToSupport: [Html5QrcodeSupportedFormats.QR_CODE, Html5QrcodeSupportedFormats.EAN_13] },
  false
);
scanner.render(
  (decodedText, decodedResult) => console.log(decodedText, decodedResult.result.format.formatName),
  (errorMessage) => {} // called on every frame without a code
);
```

After:

```html
<qrgen-scanner id="reader" symbologies="qr,ean13" style="height: 400px"></qrgen-scanner>

<script type="module">
  import "qrgen-sdk/elements";

  document.getElementById("reader").addEventListener("scan", ({ detail }) => {
    console.log(detail.barcode.data, detail.barcode.symbologyName);
  });
</script>
```

### Camera API

Before:

```js
import { Html5Qrcode } from "html5-qrcode";

const reader = new Html5Qrcode("reader");
await reader.start({ facingMode: "environment" }, { fps: 10, qrbox: 250 }, (text) => console.log(text));
// later
await reader.stop();
```

After:

```js
import { BarcodeScanner } from "qrgen-sdk";

const scanner = new BarcodeScanner({ video: document.querySelector("video"), camera: "back", symbologies: ["qr"] });
scanner.on("scan", ({ barcodes }) => console.log(barcodes[0].data));
await scanner.start();
// later
scanner.stop();
```

### Mapping

| html5-qrcode | QRGen |
| --- | --- |
| `Html5QrcodeScanner(...).render(onSuccess)` | `<qrgen-scanner>` with a `scan` listener, or [`QRGenScanner`](../react/) in React |
| `new Html5Qrcode(id).start(camera, config, onSuccess)` | `new BarcodeScanner({ video, camera }).start()` with `scanner.on("scan", ...)` |
| `stop()`, `clear()` | `stop()`, `destroy()` (the element cleans up when removed) |
| `pause()`, `resume()` | `pause()`, `resume()` |
| `scanFile(file)` | `scanImage(file)`, which returns every code in the image |
| `Html5Qrcode.getCameras()` | `Camera.list()` |
| `{ facingMode: "environment" }` or a camera id | `camera: "back"`, `"front"` or a `deviceId` |
| `formatsToSupport: [Html5QrcodeSupportedFormats.QR_CODE, ...]` | `symbologies: ["qr", ...]` |
| `fps` | `maxFps` (default 24) |
| `qrbox` | The element's viewfinder sets the scan region automatically; `scanArea` for custom regions |
| `decodedText` | `barcode.data` |
| `decodedResult.result.format.formatName` | `barcode.symbology` (id) or `barcode.symbologyName` |
| Torch via `getRunningTrackCameraCapabilities()` | `setTorch(true)`, `toggleTorch()`, or the element's torch button |
| Error callback on every frame | Not needed; `error` fires only for real failures |

Format names: `QR_CODE` is `qr`, `DATA_MATRIX` is `data-matrix`, `EAN_13` is `ean13`, `UPC_A` is `upca`, `CODE_128` is `code128`, `CODE_39` is `code39`, `ITF` is `itf`, `PDF_417` is `pdf417`, `AZTEC` is `aztec`, `RSS_14` is `databar`, `RSS_EXPANDED` is `databar-expanded`.

## From @zxing/browser and @zxing/library

`@zxing/library` is a JavaScript port of the Java ZXing library, and `@zxing/browser` adds camera helpers. QRGen uses zxing-cpp, a separate C++ implementation, compiled to WebAssembly and run in a Web Worker.

Before:

```js
import { BrowserMultiFormatReader } from "@zxing/browser";
import { BarcodeFormat, DecodeHintType } from "@zxing/library";

const hints = new Map([
  [DecodeHintType.POSSIBLE_FORMATS, [BarcodeFormat.QR_CODE, BarcodeFormat.CODE_128]],
  [DecodeHintType.TRY_HARDER, true],
]);
const reader = new BrowserMultiFormatReader(hints);

const controls = await reader.decodeFromVideoDevice(undefined, "preview", (result, error) => {
  if (result) console.log(result.getText(), BarcodeFormat[result.getBarcodeFormat()]);
});
// later
controls.stop();

const fromImage = await reader.decodeFromImageUrl("/label.png");
```

After:

```js
import { BarcodeScanner, scanImage } from "qrgen-sdk";

const scanner = new BarcodeScanner({ video: document.getElementById("preview"), symbologies: ["qr", "code128"], tryHarder: true });
scanner.on("scan", ({ barcodes }) => console.log(barcodes[0].data, barcodes[0].symbology));
await scanner.start();
// later
scanner.stop();

const fromImage = await scanImage("/label.png"); // an array; empty when nothing is found
```

| @zxing/browser, @zxing/library | QRGen |
| --- | --- |
| `BrowserMultiFormatReader`, `BrowserQRCodeReader`, ... | `BarcodeScanner` (one class for all formats) |
| `decodeFromVideoDevice(deviceId, video, callback)` | `new BarcodeScanner({ video, camera: deviceId })`, `on("scan")`, `start()` |
| `IScannerControls.stop()` | `scanner.stop()` |
| `controls.switchTorch(on)` | `scanner.setTorch(on)` |
| `BrowserMultiFormatReader.listVideoInputDevices()` | `Camera.list()` |
| `decodeFromImageUrl`, `decodeFromImageElement`, `decodeFromCanvas` | `scanImage(url \| img \| canvas)` |
| `decodeOnce...` | `mode: "single"` |
| `DecodeHintType.POSSIBLE_FORMATS` | `symbologies` |
| `DecodeHintType.TRY_HARDER` | `tryHarder` |
| `NotFoundException` for frames without a code | No exception; an empty result or no `scan` event |
| `result.getText()` | `barcode.data` |
| `result.getBarcodeFormat()` | `barcode.symbology` |
| `result.getResultPoints()` | `barcode.location` (four corners) |
| `result.getRawBytes()` | `fromBase64(barcode.rawBytes)` |
| `BrowserQRCodeSvgWriter`, `MultiFormatWriter` | `generate()`, `generateSVG()`, `<qrgen-barcode>` |

## From QuaggaJS and quagga2

Quagga reads linear (1D) barcodes. QRGen reads the same linear formats and adds QR, Data Matrix, PDF417 and the other 2D codes.

Before:

```js
import Quagga from "@ericblade/quagga2";

Quagga.init(
  {
    inputStream: { type: "LiveStream", target: document.querySelector("#scanner"), constraints: { facingMode: "environment" } },
    decoder: { readers: ["ean_reader", "upc_reader", "code_128_reader"] },
    locate: true,
  },
  (err) => {
    if (err) return console.error(err);
    Quagga.start();
  }
);
Quagga.onDetected((data) => console.log(data.codeResult.code, data.codeResult.format));
// later
Quagga.stop();
```

After:

```html
<qrgen-scanner id="scanner" symbologies="ean13,upca,code128" style="height: 400px"></qrgen-scanner>

<script type="module">
  import "qrgen-sdk/elements";

  const scanner = document.getElementById("scanner");
  scanner.addEventListener("scan", ({ detail }) => console.log(detail.barcode.data, detail.barcode.symbology));
  // later: scanner.stop(), or remove the element
</script>
```

| Quagga | QRGen |
| --- | --- |
| `Quagga.init(config, cb)` and `Quagga.start()` | Add `<qrgen-scanner>` (starts automatically), or `new BarcodeScanner(options).start()` |
| `Quagga.stop()` | `stop()` |
| `Quagga.onDetected(cb)` | `scan` event |
| `Quagga.onProcessed(cb)` | `frame` event on `BarcodeScanner` (every decoded frame) |
| `Quagga.decodeSingle({ src })` | `scanImage(src)` |
| `inputStream.constraints` | `camera`, `resolution` |
| `inputStream.area` | `scanArea` (normalized 0 to 1) |
| `locate: true` | Always on; codes are found anywhere in the scan area, at any angle |
| `frequency` | `maxFps` |
| `numOfWorkers` | Decoding runs in a Web Worker automatically |
| `data.codeResult.code` | `barcode.data` |
| `data.codeResult.format` | `barcode.symbology` |
| `data.box`, `data.line` | `barcode.location` |

Reader names:

| Quagga reader | QRGen id |
| --- | --- |
| `ean_reader` | `ean13` |
| `ean_8_reader` | `ean8` |
| `upc_reader` | `upca` |
| `upc_e_reader` | `upce` |
| `code_128_reader` | `code128` |
| `code_39_reader`, `code_39_vin_reader` | `code39` |
| `code_93_reader` | `code93` |
| `codabar_reader` | `codabar` |
| `i2of5_reader` | `itf` |
| `code_32_reader` | `code32` |
| `2of5_reader` (Standard 2 of 5) | Not supported |

Quagga apps often filter results by error rate or wait for several identical reads before accepting a code. QRGen's engine verifies check digits and symbol structure, so you can usually remove those heuristics. If you still see misreads, limit `symbologies` to what you actually scan.

## From Scandit and other commercial SDKs

> **Note:** QRGen is an independent open-source project. It is not affiliated with, endorsed by or sponsored by Scandit AG. Scandit, SparkScan and MatrixScan are trademarks of Scandit AG. Product names below are used only to describe equivalent concepts.

Commercial SDKs such as Scandit are built around similar concepts: a capture mode that recognizes barcodes in camera frames, a camera abstraction, overlays and viewfinders, and settings for symbologies, duplicates and feedback. The table maps these concepts to QRGen. API names differ between Scandit SDK versions and platforms, so check their documentation for the exact names in your version.

| Scandit concept | QRGen equivalent |
| --- | --- |
| License key and data capture context | None. No key, no account, no activation. |
| Camera and frame source on/off | `scanner.start()`, `scanner.stop()` |
| Barcode capture (single-barcode scanning) | Continuous mode (`mode="continuous"`, the default) with the `scan` event |
| Disabling capture temporarily | `pause()` and `resume()` |
| Barcode capture settings: enabled symbologies | `symbologies` ([ids](../symbologies/)) |
| Code duplicate filter | `duplicateFilter` (ms; `0` and `-1` behave as in [Core concepts](../concepts/#duplicate-filter)) |
| Location selection (restricting the scan area) | `scanArea`, or automatic from the element's viewfinder |
| Rectangular and laserline viewfinders | `viewfinder="frame"` and `viewfinder="line"` |
| Capture feedback (sound, vibration) | `beep`, `vibrate`, `scanner.feedback` |
| SparkScan (pre-built scanning UI) | `<qrgen-scanner>`, `QRGenScanner` in React and Vue, the [embed page](../embed-bridge/) in WebViews |
| MatrixScan (tracking many barcodes, "BarcodeBatch", previously "BarcodeTracking") | Batch mode (`mode="batch"`) with `track` events and `TrackedBarcode` ids; [`BarcodeTracker`](../batch-scanning/#barcodetracker-for-custom-interfaces) for custom pipelines |
| MatrixScan basic overlay (highlights on tracked codes) | Built into `<qrgen-scanner>` in batch mode, or your own canvas: see [UI customization](../ui-customization/#build-a-fully-custom-ui) |
| Choose tracked codes | The element's accessible results list, `select` event and `selection` |
| ID capture (AAMVA barcode) | [`parseAAMVA()`](../id-scanning/) on a scanned PDF417 |
| ID capture (MRZ, visual inspection zone, OCR) | Not available |
| Barcode generator | [`generate()`](../barcode-generation/), `<qrgen-barcode>` |
| Parsers (GS1, AAMVA, and others) | [`parseContent()`, `parseGS1()`, `parseAAMVA()`](../parsers/) |
| Barcode result: data, symbology, location, GS1 flag | `barcode.data`, `barcode.symbology`, `barcode.location`, `barcode.isGS1` |

Symbology names: an EAN-13/UPC-A setting corresponds to `ean13` and `upca` (QRGen lists them separately; enable both), QR to `qr`, Data Matrix to `data-matrix`, Code 128 to `code128`, PDF417 to `pdf417`, Interleaved 2 of 5 to `itf`, GS1 DataBar to `databar`, `databar-expanded` and `databar-limited`.

A typical "scan a barcode, look up the product" flow in QRGen:

```html
<qrgen-scanner id="scanner" symbologies="ean13,upca,upce,code128" duplicate-filter="2000" style="height: 60vh"></qrgen-scanner>

<script type="module">
  import "qrgen-sdk/elements";
  import { parseContent } from "qrgen-sdk";

  document.getElementById("scanner").addEventListener("scan", ({ detail }) => {
    const content = parseContent(detail.barcode.data, { symbology: detail.barcode.symbology });
    if (content.type === "product") console.log("Look up GTIN", content.gtin);
  });
</script>
```

### Before you switch

Be realistic about the trade-offs:

- **Recognition performance.** Commercial SDKs invest heavily in computer vision. They may still outperform QRGen on badly damaged, blurry or very small codes, at long distances, in poor lighting, at steep angles and on low-end devices. Test QRGen with your real codes, devices and conditions before switching.
- **Features.** QRGen doesn't include OCR, MRZ reading, AR overlays beyond highlights, or item counting and search workflows as ready-made products. You can build some of these on batch mode and your own UI.
- **Support.** QRGen is community supported through [GitHub](https://github.com/Rockyljewell/QR-GEN/issues). There is no SLA.

In return you get an Apache-2.0 licensed SDK with no license keys, per-device fees or telemetry, on-device processing, and the same API across the web, Node.js, Python and native platforms.


---

# Credit and attribution

URL: https://rockyljewell.github.io/QR-GEN/docs/credit/
Group: Reference

> How to credit QRGen when you use it: what the Apache License 2.0 requires, where the NOTICE goes on each platform, a Powered by QRGen badge and how to cite the project.

QRGen was created by [Rockyljewell](https://github.com/Rockyljewell) and is free to use under the
[Apache License 2.0](https://github.com/Rockyljewell/QR-GEN/blob/main/LICENSE), including in commercial
and closed-source products. In return, the license asks you to keep the credit attached when you ship it.

> Tip: This page is a plain-language summary. The [LICENSE](https://github.com/Rockyljewell/QR-GEN/blob/main/LICENSE) text is what applies.

## What the license requires

When you distribute QRGen, or anything that includes it (an app, a website bundle, a Docker image, a fork):

1. **Include the license.** Ship a copy of the Apache License 2.0 with your product.
2. **Include the NOTICE.** Put the text of QRGen's [NOTICE](https://github.com/Rockyljewell/QR-GEN/blob/main/NOTICE)
   file wherever your product shows third-party notices: an "Acknowledgements" or "Open-source licenses"
   screen, a `THIRD_PARTY_NOTICES` file, your documentation, or your own NOTICE file.
3. **Keep the headers.** Every QRGen source file starts with a copyright and license header, and the built
   SDK files start with a `/*! QRGen … */` banner. Leave them in place.
4. **Mark your changes.** If you modify QRGen files, say so in the files you changed.

You don't need to show QRGen in your app's main UI, pay anything or ask permission.

## The NOTICE text

Copy this into your notices file or licenses screen:

```text
QRGen
Copyright 2026 Rockyljewell
Apache License 2.0
https://github.com/Rockyljewell/QR-GEN
```

## Where it goes on each platform

| Platform | Where to put the notice |
| --- | --- |
| Web (npm, CDN) | Your site's third-party notices or licenses page. Common bundlers keep `/*!` comments by default, or move them into a separate license file; don't configure them to drop legal comments. |
| iOS / macOS | An Acknowledgements screen or the Settings bundle. CocoaPods generates an acknowledgements file for you; with Swift Package Manager, add QRGenKit to it yourself. |
| Android | The open-source licenses screen, for example with Google's `oss-licenses-plugin`, which reads the Apache-2.0 license from the QRGen POM. |
| React Native | Your licenses screen or notices file, for example generated from your dependencies with `license-checker`. |
| Flutter | `showLicensePage()` lists QRGen automatically, because Flutter collects each package's LICENSE file. |
| .NET / MAUI | Your `THIRD-PARTY-NOTICES.txt` or About page. The NuGet package carries the Apache-2.0 license expression. |
| Python | Your notices file. The wheel includes QRGen's LICENSE and NOTICE. |
| Docker / REST API | The image contains the license and NOTICE; keep them if you build your own image from it. |

## Say thanks with a badge (optional)

A visible credit isn't required, but it helps other developers find the project.

<a href="https://github.com/Rockyljewell/QR-GEN"><img src="../../badges/powered-by-qrgen.svg" alt="Powered by QRGen" width="146" height="20"></a>

Markdown, for a README:

```md
[![Powered by QRGen](https://rockyljewell.github.io/QR-GEN/badges/powered-by-qrgen.svg)](https://github.com/Rockyljewell/QR-GEN)
```

HTML, for a website footer or an About page:

```html
<a href="https://github.com/Rockyljewell/QR-GEN"><img src="https://rockyljewell.github.io/QR-GEN/badges/powered-by-qrgen.svg" alt="Powered by QRGen" width="146" height="20"></a>
```

Plain text, for an app's About screen:

```text
Barcode scanning by QRGen (https://github.com/Rockyljewell/QR-GEN), created by Rockyljewell.
```

## Cite QRGen

For papers, articles and reports, use the **Cite this repository** button on
[GitHub](https://github.com/Rockyljewell/QR-GEN), which reads the project's `CITATION.cff`. Or:

```text
Rockyljewell. (2026). QRGen: open-source barcode, QR code and ID scanning SDK (Version 1.0.0) [Computer software]. https://github.com/Rockyljewell/QR-GEN
```

## Forks and the QRGen name

You can fork QRGen and publish your fork, as long as you follow the license. The license doesn't cover the
QRGen name or logo, so publish your fork under a different name and don't present it as the official
project. The [name and logo policy](https://github.com/Rockyljewell/QR-GEN/blob/main/TRADEMARKS.md) lists what's fine.

## Spread the word

Share this page with the share button at the top of every page, or
[star QRGen on GitHub](https://github.com/Rockyljewell/QR-GEN).