@forgesworn/qr
Version:
Dependency-free QR code encoder and decoder for TypeScript, browsers, workers and Node, with optional WebAssembly and tracked camera scanning.
865 lines (696 loc) • 35.9 kB
Markdown
# @forgesworn/qr
Make and read QR codes in TypeScript, with no dependencies. One small
package encodes text or bytes into a symbol, renders it as SVG, canvas or
terminal text, and decodes symbols from camera frames, screenshots and
photographs. It runs in browsers, workers and Node.
```ts
import { decode, encode, toSvg } from '@forgesworn/qr'
const svg = toSvg(encode('https://example.com/')) // make one
const text = decode(ctx.getImageData(0, 0, w, h))?.text // read one
```
- **Encoder:** versions 1-40, levels L/M/Q/H, and the smallest symbol for
your text: numeric, alphanumeric and byte segments are mixed where that
saves bits.
- **Renderers:** an SVG string, any canvas, or half-block text for a
terminal.
- **Decoder:** takes RGBA or greyscale pixels and reads codes that are
rotated, tilted, mirrored, light on dark, curved or close up. It returns
the text, the raw bytes and where the code is.
- **Careful by design:** the decoder is built to return nothing rather than
a wrong text, which matters for payment links and sign-in codes.
- **Small and plain:** no runtime dependencies, ESM with types, tree
shaking. WebAssembly is available through a separate optional import.
- **Portable:** Kotlin and Rust ports are in this repository, checked
against the same vectors, and [SPEC.md](SPEC.md) with
[test vectors](vectors/README.md) lets other languages match it exactly.
[Documentation](https://forgesworn.github.io/qr/) · [npm](https://www.npmjs.com/package/@forgesworn/qr) · [Releases](https://github.com/forgesworn/qr/releases) · [Choosing QR](docs/CHOOSING.md)
Native Rust: [`forgesworn-qr`](https://crates.io/crates/forgesworn-qr) ·
[Rust API docs](https://docs.rs/forgesworn-qr) · [Rust guide](rust/README.md)
[JSR](https://jsr.io/@forgesworn/qr) · [Kotlin on Maven Central](https://central.sonatype.com/artifact/io.github.forgesworn/qr)
## Why use it?
Generate and read codes with the same typed package, process frames locally,
and choose your own camera UI. The optional WASM backend and tracked sessions
help with repeated frames; the plain TypeScript entry needs no WASM setup.
Accuracy takes priority: speed changes must preserve successful regression
reads and must not introduce incorrect payloads.
The recorded photograph comparison reads **180/184 versus ZXing-WASM's
171/184**, and the positive stress set reads **172/224 versus 150/224**.
Version 0.3.14's qualified curved-image comparison reads **861/1,376 versus
646/1,376**, adding 143 exact reads over 0.3.13 while preserving earlier
successful results. This includes **118/256 versus 77/256** on a separate
synthetic set frozen before evaluation. ZXing still reads 14 curved frames
QR misses, and is faster on the recorded random-noise workload. These finite
sets do not prove superiority on every image or camera. See
[choosing a library](docs/CHOOSING.md) for trade-offs and
[reproducible evidence](benchmarks/2026-11-17-m4/quadratic-mesh-recovery/README.md).
## Contents
- [Install](#install)
- [Recipes: making codes](#recipes-making-codes)
- [Recipes: reading codes](#recipes-reading-codes)
- [API](#api)
- [Common mistakes](#common-mistakes)
- [Migrating from another library](#migrating-from-another-library)
- [How the decoder works](#how-the-decoder-works)
- [How it is tested](#how-it-is-tested)
- [Kotlin](#kotlin)
- [Rust and WebAssembly](#rust-and-webassembly)
- [Development](#development)
## Install
```bash
npm install @forgesworn/qr
```
ESM only (`import`, not `require`). Node.js 22.13 or later, or any browser
with ES2022 modules. Types are included. The API is still pre-1.0, so pin
the version; changes are listed in [CHANGELOG.md](CHANGELOG.md).
JSR uses the same TypeScript API, including the optional WASM entry point:
```ts
import { encode, toSvg } from 'jsr:@forgesworn/qr@0.3.14'
import { loadWasm, wasmUrl } from 'jsr:@forgesworn/qr@0.3.14/wasm'
```
For Deno projects, `deno add jsr:@forgesworn/qr@0.3.14` adds the package to your
configuration. Continue to use npm for the ordinary Node/bundler installation.
See [distribution](docs/DISTRIBUTION.md) for registry publication status and
verification.
## Recipes: making codes
The recipes show the imports and operations needed for each integration.
Browser examples assume the named elements exist in your page.
`encode` is synchronous and returns a plain object; the renderers turn
that object into something to show.
### An SVG in the page
```ts
import { encode, toSvg } from '@forgesworn/qr'
const qr = encode('https://example.com/')
const svg = toSvg(qr, { title: 'Link to example.com' })
document.querySelector('#qr')!.innerHTML = svg
```
The SVG has a `viewBox` and no fixed size, so it fills its container: size
it with CSS. `title` becomes the accessible name. As an image source:
```ts
import { encode, toSvg } from '@forgesworn/qr'
const img = document.querySelector('img')!
img.src = 'data:image/svg+xml;utf8,' + encodeURIComponent(toSvg(encode('https://example.com/')))
```
### A canvas, and a PNG to download
```ts
import { drawCanvas, encode } from '@forgesworn/qr'
const canvas = document.querySelector('canvas')!
drawCanvas(canvas, encode('https://example.com/'), { width: 512 })
canvas.toBlob((png) => {
if (!png) return
const link = document.createElement('a')
link.href = URL.createObjectURL(png)
link.download = 'code.png'
link.click()
setTimeout(() => URL.revokeObjectURL(link.href), 0)
})
```
`drawCanvas` resizes the canvas to exactly `width` pixels square and puts
module edges on whole pixels. `width` must be a whole number of at least
one pixel a module, margin included, or it throws a `RangeError`. It takes
an `OffscreenCanvas` too.
### A terminal, or a file, from Node
```ts
import { writeFileSync } from 'node:fs'
import { encode, toSvg, toTerminal } from '@forgesworn/qr'
const qr = encode('https://example.com/')
console.log(toTerminal(qr)) // dark terminal; { ink: 'dark' } for a light one
writeFileSync('code.svg', toSvg(qr))
```
### Colours, margin and error correction
```ts
import { encode, toSvg } from '@forgesworn/qr'
const qr = encode('https://example.com/', { ecc: 'H' }) // 'L' | 'M' (default) | 'Q' | 'H'
const svg = toSvg(qr, { dark: '#1a1a2e', light: null, margin: 2 }) // light: null leaves the background clear
```
A higher level survives more damage and makes a larger symbol. Keep the
`margin` at 4 modules unless the code sits on a plain background already;
readers need the quiet zone.
### Your own drawing
`modules` is a row-by-row `Uint8Array` of `size * size` entries, 1 for
dark, with no quiet zone. `isDark(qr, x, y)` reads it, and is `false`
outside the symbol.
```ts
import { encode, isDark } from '@forgesworn/qr'
const qr = encode('https://example.com/')
let dots = ''
for (let y = 0; y < qr.size; y++) {
for (let x = 0; x < qr.size; x++) {
if (isDark(qr, x, y)) dots += `<circle cx="${x + 0.5}" cy="${y + 0.5}" r="0.45"/>`
}
}
const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 ${qr.size + 8} ${qr.size + 8}">${dots}</svg>`
```
### The smallest code for a payment link
With no `mode`, text is split into the segments that take the fewest bits.
An uppercase body after a lowercase scheme packs as alphanumeric, so it
fits a smaller symbol than it would as bytes.
```ts
import { encode } from '@forgesworn/qr'
const invoice = 'lightning:LNBC' + '0123456789ACDEFGHJKLMNPQRSTUVWXYZ'.repeat(8) // 278 characters, made up
const qr = encode(invoice)
qr.segments // [{ mode: 'byte', count: 9 }, { mode: 'alphanumeric', count: 269 }]
qr.version // 10, 57 modules a side; as bytes it would be version 12, 65 a side
```
### Bytes, not text
```ts
import { encode } from '@forgesworn/qr'
const qr = encode(new Uint8Array([0xde, 0xad, 0xbe, 0xef])) // always one byte segment
```
### When the data does not fit
```ts
import { encode, QrCapacityError, type ErrorCorrection, type QrCode } from '@forgesworn/qr'
/** The most robust code that still fits, or undefined if none does. */
function fit(text: string): QrCode | undefined {
for (const ecc of ['H', 'Q', 'M', 'L'] as ErrorCorrection[]) {
try {
return encode(text, { ecc })
} catch (error) {
if (!(error instanceof QrCapacityError)) throw error
}
}
return undefined
}
```
`QrCapacityError` extends `RangeError`. Bad options (a version outside
1-40, an unknown level) throw a plain `RangeError`, and data that is
neither a string nor a `Uint8Array` throws a `TypeError`.
## Recipes: reading codes
`decode` takes pixels, not an element: `{ data, width, height }` with RGBA
(what a canvas gives) or one grey byte a pixel. It returns the result, or
`undefined` when it finds no code it is sure of. It manages no camera; the
loop below is all there is to it.
### Scan with the camera
```ts
import { decode } from '@forgesworn/qr'
/** Starts scanning; calls `onRead` once with the first code read. Returns a function that stops the camera. */
async function scan(video: HTMLVideoElement, onRead: (text: string) => void): Promise<() => void> {
const stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'environment' } })
video.srcObject = stream
video.playsInline = true
try {
await video.play()
} catch (error) {
for (const track of stream.getTracks()) track.stop()
video.srcObject = null
throw error
}
const canvas = document.createElement('canvas')
const ctx = canvas.getContext('2d', { willReadFrequently: true })!
let running = true
let last = 0
const stop = () => {
running = false
for (const track of stream.getTracks()) track.stop()
if (video.srcObject === stream) video.srcObject = null
}
const tick = (now: number) => {
if (!running) return
if (now - last >= 100 && video.videoWidth > 0) { // ten looks a second is plenty
last = now
canvas.width = video.videoWidth
canvas.height = video.videoHeight
ctx.drawImage(video, 0, 0)
const found = decode(ctx.getImageData(0, 0, canvas.width, canvas.height))
if (found) {
stop()
onRead(found.text)
return
}
}
requestAnimationFrame(tick)
}
requestAnimationFrame(tick)
return stop
}
const stop = await scan(document.querySelector('video')!, (text) => console.log(text))
```
Cameras need a secure page (HTTPS or localhost) and the user's permission.
Start with a bounded frame size such as 1280×720 and measure on your devices.
Small or distant codes may need more resolution; larger frames cost more time
and memory. Use a worker for decoding when page responsiveness matters.
### Read an uploaded picture or a screenshot
```ts
import { decode } from '@forgesworn/qr'
async function readFile(file: Blob): Promise<string | undefined> {
const bitmap = await createImageBitmap(file)
try {
const canvas = new OffscreenCanvas(bitmap.width, bitmap.height)
const ctx = canvas.getContext('2d')!
ctx.drawImage(bitmap, 0, 0)
return decode(ctx.getImageData(0, 0, bitmap.width, bitmap.height))?.text
} finally {
bitmap.close()
}
}
document.querySelector('input[type=file]')!.addEventListener('change', async (event) => {
const file = (event.target as HTMLInputElement).files?.[0]
if (file) console.log((await readFile(file)) ?? 'no code found')
})
```
### Keep the page smooth: decode in a worker
```ts
// main.ts
const worker = new Worker(new URL('./scan-worker.ts', import.meta.url), { type: 'module' })
worker.onmessage = (event: MessageEvent<string | undefined>) => {
if (event.data !== undefined) console.log(event.data)
}
function look(frame: ImageData): void {
worker.postMessage(frame, [frame.data.buffer]) // moves the pixels, no copy
}
```
```ts
// scan-worker.ts
import { decode } from '@forgesworn/qr'
addEventListener('message', (event: MessageEvent<ImageData>) => {
postMessage(decode(event.data)?.text)
})
```
Most bundlers understand `new Worker(new URL(...), { type: 'module' })`
as written. Send the next frame only when the last has answered, so frames
do not queue.
### Read pixels in Node
Node has no image decoder of its own. Use any that gives raw RGBA or grey
bytes, and hand them over with their size:
```ts
import { decode } from '@forgesworn/qr'
function read(rgba: Uint8Array, width: number, height: number): string | undefined {
return decode({ data: rgba, width, height })?.text
}
```
### Greyscale camera planes
A camera's luminance (Y) plane is already what the decoder wants, and
skips the colour conversion. `rowStride` is the number of pixels from one
row to the next, for planes with padding.
```ts
import { decode } from '@forgesworn/qr'
function readPlane(y: Uint8Array, width: number, height: number, rowStride: number): string | undefined {
return decode({ data: y, width, height }, { channels: 1, rowStride })?.text
}
```
The data must hold at least `rowStride * (height - 1) + width` bytes, and
`rowStride` may not be less than `width`. A Node `Buffer` is a `Uint8Array`
and works as it is. `decode` copies what it needs: it neither changes your
buffer nor keeps it.
### Repeated camera frames
Use an independent decoder for each camera stream:
```ts
import { createDecoder, type ImageLike } from '@forgesworn/qr'
const reader = createDecoder()
function readFrame(frame: ImageLike) {
return reader.decode(frame) // the same image and options as decode()
}
reader.reset() // call when stopping or switching cameras
```
It reuses luminance storage and tries the previous symbol's region first.
When that region misses, it searches the full frame in the same call. Each
call reads fresh pixels; it never returns a cached payload. With several codes
visible, it favours the previous region. Cropping can change the reported
location slightly. `reset()` forgets the region and releases working storage.
Keep using a worker and avoid queueing frames, as in the recipe above.
### Everything a read gives you
```ts
import { decode, type DecodeResult, type ImageLike } from '@forgesworn/qr'
function describe(frame: ImageLike): string {
const found: DecodeResult | undefined = decode(frame)
if (!found) return 'nothing read'
const { topLeft, topRight, bottomLeft } = found.location // finder pattern centres, in pixels
const width = Math.hypot(topRight.x - topLeft.x, topRight.y - topLeft.y)
const height = Math.hypot(bottomLeft.x - topLeft.x, bottomLeft.y - topLeft.y)
return [
`text: ${found.text}`,
`bytes: ${found.bytes.length}`, // the payload as stored, for data that is not text
`version ${found.version}, level ${found.ecc}, ${found.corrected} codewords corrected`,
found.inverted ? 'light on dark' : 'dark on light',
found.mirrored ? 'mirrored' : 'not mirrored',
`about ${Math.round(width)} by ${Math.round(height)} pixels between finders`,
].join('\n')
}
```
The three points of `location` are the centres of the finder patterns,
each 3.5 modules in from a corner of the symbol, so the symbol's outline
lies a little outside them. `alignment` is the alignment pattern's centre
when one was used.
`found.structuredAppend` (`{ index, total, parity }`) is present when the
code is one part of a message split across several, and `found.fnc1` when
it is a GS1 or industry code.
### Only dark-on-light codes
```ts
import { decode, type ImageLike } from '@forgesworn/qr'
const readNormal = (frame: ImageLike) => decode(frame, { inversion: 'normal' }) // 'inverted' | 'both' (default)
```
Naming the polarity avoids searching the other polarity. The saving depends
on the image and which search budgets are reached.
### Check a code you just made
```ts
import { decodeModules, encode } from '@forgesworn/qr'
const qr = encode('https://example.com/')
console.assert(decodeModules(qr.modules, qr.size)?.text === 'https://example.com/')
```
## API
Everything the package exports:
```ts
function encode(data: string | Uint8Array, options?: EncodeOptions): QrCode
function isDark(qr: QrCode, x: number, y: number): boolean
function toSvg(qr: QrCode, options?: SvgOptions): string
function drawCanvas(canvas: CanvasLike, qr: QrCode, options?: CanvasOptions): void
function toTerminal(qr: QrCode, options?: TerminalOptions): string
function decode(image: ImageLike, options?: DecodeOptions): DecodeResult | undefined
function createDecoder(): Decoder
function decodeModules(modules: ArrayLike<number | boolean>, size: number): (Payload & { mirrored: boolean }) | undefined
class QrCapacityError extends RangeError {}
type ErrorCorrection = 'L' | 'M' | 'Q' | 'H'
type Mode = 'numeric' | 'alphanumeric' | 'byte'
interface EncodeOptions {
ecc?: ErrorCorrection // default 'M'
version?: number // 1-40; default: the smallest that fits
minVersion?: number // default 1
mask?: number // 0-7; default: the lowest penalty
mode?: Mode // the whole text as one segment; default: the fewest-bits mix
eci?: boolean // mark byte data as UTF-8; default false
}
interface QrCode {
version: number
ecc: ErrorCorrection
mask: number
mode: Mode // the widest mode among the segments
segments: readonly { mode: Mode; count: number }[]
size: number // modules a side, 17 + 4 * version, no quiet zone
modules: Uint8Array // size * size, row by row, 1 for dark
}
interface SvgOptions { margin?: number; dark?: string; light?: string | null; title?: string }
/** An HTMLCanvasElement, an OffscreenCanvas, or anything shaped like one. */
interface CanvasLike { width: number; height: number; getContext(type: '2d'): { fillStyle: unknown; fillRect(x: number, y: number, width: number, height: number): void } | null }
interface CanvasOptions { width?: number; margin?: number; dark?: string; light?: string | null }
interface TerminalOptions { margin?: number; ink?: 'light' | 'dark' }
interface ImageLike { data: Uint8Array | Uint8ClampedArray; width: number; height: number }
interface Decoder {
decode(image: ImageLike, options?: DecodeOptions): DecodeResult | undefined
reset(): void
}
interface DecodeOptions {
rowStride?: number // pixels from row to row; default width
channels?: 1 | 4 // default: worked out from the data length
inversion?: 'normal' | 'inverted' | 'both' // default 'both'
}
interface Payload {
text: string
bytes: Uint8Array
version: number
ecc: ErrorCorrection
mask: number
eci: readonly number[] // ECI assignments in the order met
corrected: number // codewords error correction put right
structuredAppend?: { index: number; total: number; parity: number }
fnc1?: { position: 'first' | 'second'; applicationIndicator?: string }
}
interface DecodeResult extends Payload {
mirrored: boolean
inverted: boolean
location: { topLeft: Point; topRight: Point; bottomLeft: Point; alignment: Point | undefined }
}
interface Point { x: number; y: number }
```
Defaults worth knowing: `margin` is 4 modules everywhere; `dark` is
`'#000'` and `light` is `'#fff'`; a canvas is 8 pixels a module unless
`width` says otherwise.
**Text.** A string is encoded as UTF-8. When reading, `text` follows the
symbol's ECI if it has one; under an ECI the platform cannot read, what
cannot be read is U+FFFD and never a guess. Without one, byte data is UTF-8 when it is
valid UTF-8, Shift_JIS when it has the shape of Shift_JIS text, and Latin-1
otherwise; kanji and hanzi segments read as text. `bytes` is there for
payloads that are not text. [SPEC.md](SPEC.md) has the detail.
**What `decode` throws.** Nothing for a picture with no code: that is
`undefined`. It throws `TypeError` or `RangeError` only for arguments that
cannot be a picture: data that is not a `Uint8Array` or
`Uint8ClampedArray`, a size that does not match the data, or three bytes a
pixel (pass RGBA or grey).
**Wrong text.** The decoder refuses a block that needed more corrections
than the standard allows, and holds its later, harder searches of a frame
to a stricter check than the first. The tests require damaged symbols to
read as nothing or as exactly what was written.
**Speed.** The recorded M4 Max/native Node 24.21.0 run measures clean 720p
RGBA decoding at 4.661 ms for TypeScript and 1.590 ms for optional WASM.
Random noise takes 55.485 ms and 20.569 ms respectively. These are workload-
and hardware-specific medians, not a latency guarantee or phone measurement.
[PERFORMANCE.md](PERFORMANCE.md) records the inputs, warm-up, competing readers,
medians, tails and limitations. Use a worker and keep only one frame in flight.
## Common mistakes
- **`require('@forgesworn/qr')`:** the package is ESM only. Use `import`.
- **Passing an `<img>` or `<video>` to `decode`:** draw it to a canvas and
pass `getImageData(...)`, as the recipes do.
- **Expecting `null`:** `decode` and `decodeModules` return `undefined`
when nothing reads.
- **`isDark(qr, row, column)`:** the order is `x` then `y`, column then row.
- **Awaiting `encode`:** it is synchronous and returns the code directly.
- **Expecting an element from `toSvg`:** it returns a string.
- **No quiet zone in your own drawing:** `modules` has none; add 4 modules
of margin, as the renderers do.
- **Three bytes a pixel:** RGB without alpha is refused. Convert to RGBA
or grey first.
- **Scanning every animation frame:** it works, and wastes battery.
Throttle as the camera recipe does.
## Migrating from another library
The shapes are close to what most QR libraries use, so a switch is mostly
renaming. Three differences apply whatever you come from: this package is
ESM only, encoding and decoding are synchronous, and a failed read is
`undefined`. Optional WASM initialisation with `loadWasm` is asynchronous.
### From `qrcode` (generating)
| `qrcode` | `@forgesworn/qr` |
|---|---|
| `await QRCode.toString(text, { type: 'svg' })` | `toSvg(encode(text))` |
| `await QRCode.toCanvas(canvas, text, { width })` | `drawCanvas(canvas, encode(text), { width })` |
| `await QRCode.toDataURL(text)` | draw to a canvas, then `canvas.toDataURL()`; or an SVG data URL (see the SVG recipe) |
| `await QRCode.toString(text, { type: 'terminal' })` | `toTerminal(encode(text))` |
| `QRCode.create(text)` | `encode(text)` |
| `errorCorrectionLevel: 'M'` | `ecc: 'M'`, on `encode` |
| `version`, `maskPattern` | `version`, `mask`, on `encode` |
| `margin`, `color: { dark, light }` | `margin`, `dark`, `light`, on the renderer |
| `scale` | `width` on `drawCanvas`; an SVG scales with CSS |
| `qr.modules.get(row, col)` | `isDark(qr, col, row)` |
| `qr.modules.size` | `qr.size` |
```ts
// before
import QRCode from 'qrcode'
const svg = await QRCode.toString('https://example.com/', { type: 'svg', errorCorrectionLevel: 'Q', margin: 2 })
// after
import { encode, toSvg } from '@forgesworn/qr'
const svg = toSvg(encode('https://example.com/', { ecc: 'Q' }), { margin: 2 })
```
Options split in two: what goes into the symbol (`ecc`, `version`, `mask`)
belongs to `encode`, and how it looks (`margin`, colours, size) to the
renderer. There is no PNG or file writer; a canvas or the SVG string covers
both.
### From `qrcode-generator` (generating)
| `qrcode-generator` | `@forgesworn/qr` |
|---|---|
| `const qr = qrcode(0, 'M'); qr.addData(text); qr.make()` | `const qr = encode(text, { ecc: 'M' })` |
| `qrcode(typeNumber, level)` with a fixed type number | `encode(text, { version: typeNumber, ecc: level })` |
| `qr.getModuleCount()` | `qr.size` |
| `qr.isDark(row, col)` | `isDark(qr, col, row)` |
| `qr.createSvgTag()` | `toSvg(qr)` |
| `qr.createDataURL()` | an SVG data URL (see the SVG recipe) |
| `qr.addData(text, 'Alphanumeric')` | `encode(text, { mode: 'alphanumeric' })`, or no `mode` and let it choose |
### From `jsQR` (reading)
| `jsQR` | `@forgesworn/qr` |
|---|---|
| `jsQR(imageData.data, imageData.width, imageData.height)` | `decode(imageData)` |
| `{ inversionAttempts: 'dontInvert' }` | `{ inversion: 'normal' }` |
| `{ inversionAttempts: 'onlyInvert' }` | `{ inversion: 'inverted' }` |
| `{ inversionAttempts: 'attemptBoth' }` | `{ inversion: 'both' }`, the default |
| `null` when nothing reads | `undefined` |
| `code.data` | `found.text` |
| `code.binaryData` (number array) | `found.bytes` (`Uint8Array`) |
| `code.version` | `found.version` |
| `code.location.topLeftFinderPattern` and the other two | `found.location.topLeft`, `.topRight`, `.bottomLeft` |
| `code.location.topLeftCorner` and the other corners | not given: the location is the finder centres |
```ts
// before
import jsQR from 'jsqr'
const code = jsQR(frame.data, frame.width, frame.height, { inversionAttempts: 'dontInvert' })
if (code) handle(code.data)
// after
import { decode } from '@forgesworn/qr'
const found = decode(frame, { inversion: 'normal' })
if (found) handle(found.text)
```
### From a scanner that runs the camera for you
Libraries such as `qr-scanner`, `html5-qrcode` and `@zxing/browser` open
the camera, draw a viewfinder and call you back. This package only reads
pixels, so the camera loop becomes yours: the
[camera recipe](#scan-with-the-camera) is the whole of it, about thirty
lines, and the [worker recipe](#keep-the-page-smooth-decode-in-a-worker)
moves the work off the page. In exchange you choose the frame size, the
scan rate and the interface. Formats other than QR codes are not read.
## How the decoder works
For each frame, in order, stopping at the first read:
1. **Greyscale.** RGBA becomes one grey byte a pixel; a grey plane is used
as it is.
2. **Black and white.** A threshold is taken for every 8 x 8 block from the
blocks around it, so shadows and uneven light do not swallow the code.
3. **Finder patterns.** Rows are scanned for the 1:1:3:1:1 runs of a finder
pattern, each sighting checked down its column, back along its row and
along a diagonal.
4. **Placement.** Three finders that could be the corners of one symbol
give its size and a perspective map; the alignment pattern refines it.
5. **Reading.** Modules are sampled through the map, the format and
version are read, and Reed-Solomon corrects the codewords. A block
needing more corrections than the standard allows is refused.
6. **A second look.** If nothing read, up to four placements whose two
format copies agree are sampled again more carefully, following curved
or bent symbols.
7. **Reduced size.** If still nothing, the picture is searched again shrunk
by 8, 4 and 2, for close-ups and codes shown on screens, with a
stricter check on what counts as a read.
8. **Evidence-directed recovery.** Eligible inverted images get a separate
luminance pass. Independently agreeing version copies can correct a failed
size estimate; agreeing headers can admit previously unselected finder
triples. A final curved-map retry uses an exact version word and consistent
readable format information, then revisits missed alignment nodes. Its
result still needs both final format copies to agree. Candidates from the
inverted-luminance pass retain their own thresholds and run after the
original-image candidates. All these retries share the existing map and
second-look budgets.
9. **Retained grids.** After those paths fail, bounded strict reads can recover
already sampled grids. If the selected refined grid supplies a different
agreed header but cannot be read, the decoder can try that same hypothesis
on the direct alignment mesh captured by the same refinement call. This
adds no image sampling or alignment search and cannot displace an earlier
successful result.
Steps 3 to 5 run for dark-on-light and then light-on-dark unless
`inversion` names one. The work a frame can take is capped, and there are
no thresholds or effort levels to tune: the frame size, the scan rate and
`inversion` are the controls. [SPEC.md](SPEC.md) gives every step exactly.
## How it is tested
- **The encoder** is compared module for module with an independent
encoder on 148 symbols covering every version and mask and mixed
segments, and an independent decoder reads back random payloads and
every renderer's output. Both are test-time oracles; neither ships.
- **The decoder** reads codes drawn through synthetic camera effects
(rotation, perspective, small modules, blur, noise, uneven light,
inversion, mirroring) and must read at least as many of those frames as
an independent decoder does.
- **Real photographs:** a set of 184 from open-source test collections,
fetched by hash and not committed, has a floor on how many are read (180
at present) and a rule that none may decode to the wrong text. A dedicated
CI job downloads the set and requires the TypeScript and Kotlin tests to
run; local runs skip it unless the photographs have been fetched.
- **Damage:** several hundred damaged, bent, close-up and empty frames,
generated from seeds, must read as nothing or as exactly what was
written.
- **Ports:** [vectors/](vectors/README.md) holds what a port checks itself
against, a stage at a time; the Kotlin port passes it unchanged.
CI also compares the WebAssembly decoder's results and options, its
encoder and the native renderings, and checks that repeated reads release
their memory.
## Kotlin
A pure-JVM port of the encoder and decoder lives in `kotlin/` (module `core`,
package `dev.forgesworn.qr`, JVM 17, no dependencies beyond the Kotlin standard
library). It is checked against the same vectors and frames as the TypeScript
library, and gives the same results. The sources are in
`kotlin/core/src/main/kotlin` and are written to be vendored as they stand.
For the Maven Central distribution, configure Gradle with:
```kotlin
repositories { mavenCentral() }
dependencies { implementation("io.github.forgesworn:qr:0.3.14") }
```
See [distribution](docs/DISTRIBUTION.md) for publication status. The Maven group
is `io.github.forgesworn`; the Kotlin import package remains `dev.forgesworn.qr`.
```kotlin
import dev.forgesworn.qr.*
val qr = encode("https://example.com", EncodeOptions(ecc = ErrorCorrection.Q))
qr.isDark(0, 0) // modules are row by row, no quiet zone
// luminance: one byte a pixel, 0 black to 255 white, as a camera's Y plane gives
val found = decode(luminance, width, height, rowStride = stride)
found?.text
```
`decode` returns `null` when it finds no readable code. There is also a
`decode(IntArray, ...)` overload for packed ARGB pixels and
`decodeModules(modules, size)` for a module grid. Run the tests with
`cd kotlin && ./gradlew test`.
## Rust and WebAssembly
A Rust port lives in `rust/`: the encoder, the SVG and terminal renderers
and the whole decoder, with no dependencies. It is held to the same
vectors. Beyond them, its decoder was compared with the TypeScript on 603
pictures kept outside this repository, each at four quarter turns: the
same payload, the same location to the last bit and the same counted work
on all 2,412 in that earlier qualification. Install the native crate with
`cargo add forgesworn-qr@0.3.14`; see the [Rust guide](rust/README.md) and
[API documentation](https://docs.rs/forgesworn-qr) for its input contracts.
The npm package includes an optional WebAssembly backend, imported separately
from the TypeScript entry. The bundled module is about 210 kB (205 KiB) before compression.
Fetch and instantiate it once, then reuse it for frames:
```ts
import { loadWasm, wasmUrl } from '@forgesworn/qr/wasm'
const response = await fetch(wasmUrl)
if (!response.ok) throw new Error(`QR module: HTTP ${response.status}`)
const qr = await loadWasm(await response.arrayBuffer())
try {
const symbol = qr.encode('https://example.com/')
const found = qr.decodeModules(symbol.modules, symbol.size)
console.log(found?.text)
// qr.decode(imageData) accepts the same pixels and options as decode().
} finally {
qr.dispose() // stop using this instance
}
```
In Node, replace the fetch with `readFile(new URL(wasmUrl))` from
`node:fs/promises`. `loadWasm` performs no network or filesystem access. With a
bundler, ensure it copies `new URL('./qr.wasm', import.meta.url)` as an asset,
or supply bytes from your own deployed copy of `@forgesworn/qr/qr.wasm`.
Self-host the module for control over asset delivery. The library chooses no
CDN and adds no runtime dependencies. Your page policy must permit WebAssembly
compilation when using this backend; use the TypeScript entry when it cannot.
The backend exposes `encode`, `decode`, `decodeModules`, `createDecoder`, `reset`, `dispose`
and `memoryBytes`. It copies outputs before freeing native result handles,
so earlier results survive later calls and disposal. Each instance reuses an
input allocation; `reset()` frees that allocation and leaves the instance
usable. WebAssembly memory retains its high-water size until the instance is
collected. `dispose()` releases the instance and rejects further operations;
it is safe to call repeatedly. Use one instance per worker and a worker for
camera frames. `qr.createDecoder()` creates a tracked camera session with the
same region search and same-call fallback as the TypeScript helper. Each
session tracks independently and shares the instance's native input storage.
Reset a session to forget its region; reset the parent to free input storage
and forget all session regions. Disposing the parent invalidates its sessions.
The packaged WASM backend uses the host's character sets, following the same
text rules as TypeScript for kanji, hanzi, ECI and implicit Shift_JIS. It does
this while parsing each segment, preserving mixed encodings and rejecting
invalid hanzi cells. It bundles no character tables. A host lacking a character
set follows the documented platform fallback.
The standalone Rust port and its default WASM build still carry no character
tables: unsupported characters use the documented replacement rules and hanzi
is refused. The packaged module enables Rust's `host-text` feature and uses
ABI 2; the standalone module uses ABI 1. Supply the packaged module to `loadWasm`.
```bash
cd rust
cargo test # the conformance pack and the encoder vectors
cargo build --release --target wasm32-unknown-unknown # the WebAssembly module
```
`rust/bench/` also holds the scripts that compare the module with the
TypeScript and time it.
## Development
```bash
npm install
npm run check # typecheck and tests
npm run build # compile to dist/ and verify/copy the bundled WASM
npm run generate-vectors # regenerate the encode vectors (needs a JDK and network once)
npm run fetch-photos # download the photograph test set (about 13 MB, needs a JDK)
```
The checked-in WASM asset is built from this repository's Rust sources with
Rust 1.96.0. Install that toolchain and its `wasm32-unknown-unknown` target,
then use `npm run build:wasm` after changing Rust. `npm run check:wasm`
rebuilds and compares the exact bytes and provenance; CI does this on Linux.
Normal npm builds need no Rust toolchain. `npm run check:package` installs a
real packed tarball into a temporary consumer and checks both entries.
`npm run bench` runs the local benchmark; [PERFORMANCE.md](PERFORMANCE.md)
records the method, measurements and their limits.
[SPEC.md](SPEC.md) defines the behaviour; a change to behaviour changes it
in the same commit.
## Support
For issues and feature requests, see [GitHub Issues](https://github.com/forgesworn/qr/issues).
If you find this library useful, consider sending a tip:
- **Lightning:** `profusemeat89@walletofsatoshi.com`
- **Nostr zaps:** `npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`
## Licence
MIT
QR Code is a registered trademark of DENSO WAVE INCORPORATED.