# Sythos Barcode Universal

> An open-source MIT-licensed JavaScript and TypeScript SDK for generating and
> reading 1D linear and 2D matrix barcodes, with zero runtime dependencies.

## Identity

- Project: Sythos Barcode Universal
- Publisher and original author: Sythos — https://www.sythos.net
- npm package: `@sythos/js_barcode_universal`
- Current repository release: `1.6.3`
- License: MIT; copyright and attribution: Sythos
- Runtime dependencies: none
- Development tooling: TypeScript is a development-only dependency
- Repository: https://github.com/Sythos/JS_Barcode_Universal
- npm: https://www.npmjs.com/package/@sythos/js_barcode_universal
- Documentation: https://sythos.github.io/JS_Barcode_Universal/
- Documentation source: https://github.com/Sythos/JS_Barcode_Universal/tree/main/docs
- API reference: https://sythos.github.io/JS_Barcode_Universal/api/overview/
- Format catalogue: https://sythos.github.io/JS_Barcode_Universal/formats/overview/
- Recipes: https://sythos.github.io/JS_Barcode_Universal/examples/create-barcode/
- FAQ: https://sythos.github.io/JS_Barcode_Universal/faq/
- Troubleshooting: https://sythos.github.io/JS_Barcode_Universal/troubleshooting/
- Compact project overview: https://github.com/Sythos/JS_Barcode_Universal#readme
- Issue tracker: https://github.com/Sythos/JS_Barcode_Universal/issues

## What this SDK does

Sythos Barcode Universal encodes payloads into barcode symbols and decodes
barcode symbols from matrices or RGBA raster images. It also exposes format
detectors, strict decode helpers, image preprocessing, SVG/PNG/ImageData
renderers, and camera-oriented read profiles. The core image interface is a
plain `{ data, width, height }` RGBA object, so applications can connect it to
`ImageData`, `OffscreenCanvas`, camera frames, Node or Bun image libraries, or their
own image pipeline without requiring a DOM or canvas in the core.

The package is native ESM and provides source-visible JavaScript, TypeScript
sources and declarations, a browser IIFE bundle, and an ESM bundle. It runs in
Node.js 24 or newer (Bun also works as an alternative runtime), modern
browsers, and Web Workers. The published SDK does
not install native addons, WebAssembly, post-install tools, or runtime
packages.

## Supported symbologies

The public `listFormats()` API reports writing and reading separately. A format
marked `write-only` is intentionally not treated as a generic image reader.
At the current checkout it reports 61 writable entries and 60 readable entries;
Pharmacode is the sole intentionally write-only entry, while EAN-2 and EAN-5
remain parent-bound supplements.

### 1D linear formats

- EAN-13 and EAN-8 — write and read
- UPC-A and UPC-E — write and read
- ISBN / Bookland — write and read through the EAN-13 family
- JAN (Japanese Article Number) — write and read through the EAN-13 family, restricted to the 45/49 GS1 prefix range
- Code 128 — write and read, with automatic switching across Code 128 sets A, B and C
- GS1-128 — write and read, including GS1/FNC1 metadata parsing
- Code 39 — write and read
- Code 93 — write and read
- ITF (Interleaved 2 of 5) — write and read
- ITF-14 — write and read through the ITF family
- ITF-6 — write and read; the JIS X 0502 six-digit add-on with a mandatory check digit, kept as its own `itf6` id (reported alongside `itf`, not instead of it)
- Code 25 / Standard 2 of 5 — write and read as `standard2of5` or `code2of5`
- Industrial 2 of 5 — write and read with the canonical Industrial frame
- IATA 2 of 5 — write and read with the shorter IATA guard frame
- Code 2 of 5 Data Logic (China Post) — write and read with a width-modulated digit grammar and the shorter IATA-style guard; the 2:1 wide:narrow ratio is rejected because it collides with a different valid reading once mirrored
- Matrix 2 of 5 — write and read; shares Data Logic 2 of 5's width-modulated digit grammar with its own, longer guard frame; the same 2:1 ratio rejection applies
- Facing Identification Mark (FIM) — write and read one of five fixed USPS-defined nine-position palindrome patterns (A-E); not a general data carrier
- Codabar — write and read
- Code 11 — write and scanline/image read
- MSI Plessey — write and read, with optional check-digit validation
- Plessey Code — write and read; the original format MSI descends from, sixteen-value hex alphabet with a mandatory CRC-8 check (no unchecked mode)
- PostBar.C10, PostBar.D22, PostBar.G12 (Canada Post CPC four-state) — write and read; Reed-Solomon over GF(64) protects the payload (not just a check character), implemented from US Patent 5,602,382A since Canada Post's own spec is unpublished; see docs/formats/postbar.md
- DX Film Edge Barcode — write and read; Kodak's latent-image two-track (clock + data) code printed along 35mm film, distinct from the film cartridge's ordinary ITF barcode; implemented from US Patent 4,965,628A cross-checked against real-film-sample literature since the patent's own high-level summary states a conflicting field width; see docs/formats/dxfilmedge.md
- Code 32 (Italian Pharmacode) — write and read with validated pharmaceutical check digit
- PZN-7 and PZN-8 — write and read; the decoder exposes `pznVariant`
- Telepen — write and read in full seven-bit ASCII mode; explicit Telepen Numeric
  mode handles digit pairs and `X` suffix pairs
- Pharmacode — write-only in the generic image pipeline
- GS1 DataBar Omnidirectional, Truncated, Limited, Stacked, Stacked Omnidirectional and Expanded — write and read through verified physical layers
- USPS POSTNET and PLANET — write and read with operator-specific Mod-10 checks
- Royal Mail 4-State Customer Code (RM4SCC) — write and read with a generated and verified check character
- KIX — write and read with the Dutch four-state alphabet and no check character
- Australia Post 4-State — write and read with FCC/DPID, GF(64) parity and explicit character or numeric customer data
- Japan Post 4-State — write and read with grouped public payloads, padding and Mod-19 validation
- USPS Intelligent Mail Barcode (IMb / OneCode) — write and read for 20-, 25-, 29- and 31-digit payloads with frame-check validation
- EAN-2 and EAN-5 supplements — write and parent-bound read only; they require a validated EAN/UPC parent

**KarTrak ACI (experimental, not in the 57/56 count above)** — colour-coded
(blue/checkerboard/red/black stripe pairs, not bar width), so it cannot go
through `BitMatrix`-based `encode()`/`decode()`/`listFormats()` at all. Write
and read (axis-aligned single-plate detection only, no rotation/perspective
search) through its own subpath, `@sythos/js_barcode_universal/kartrak`. See
`docs/formats/kartrak.md` and `docs/COLOR_PIPELINE_NOTES.md`.

**JAB Code (experimental, not in the count above)** — ISO/IEC 23634:2022,
colour-coded (several bits per module as one of several colours, not bar
width), so it cannot go through `BitMatrix`-based `encode()`/`decode()`/
`listFormats()` either. Implements the reference encoder's own "default
mode" (8 colours, ECC level 3, mask type 7, no metadata Part I/II,
byte-mode-only data encoding, single symbol) — not the full specification.
Write and read (known-geometry decoding, no detector) through its own
subpath, `@sythos/js_barcode_universal/jabcode`. No live reference build was
available to confirm interop beyond this module's own round trip — see
`docs/formats/jabcode.md` and `docs/JABCODE_NOTES.md`.

### 2D stacked formats

Multiple linear-derived rows, not a true grid. GS1 DataBar Stacked and Stacked
Omnidirectional are also physically stacked but are listed above under 1D
linear formats because that is the `kind` the public API reports for them.

- PDF417 — write and read, including direct matrix decoding and camera-oriented detection
- Compact PDF417 — write and read for the truncated PDF417 geometry
- MicroPDF417 — write and read for the fixed MicroPDF417 variants
- Codablock-F — write and read for stacked Code 128 rows with row and overall checks; clean integer-scale detection
- Code 16K — write and read for compact stacked Code 128 A/B/C rows, optional GS1 modes, dual modulo-107 checks and clean integer-scale detection
- GS1 DataBar Composite — write and read for the bounded Sythos profile linking one validated DataBar host to a strict MicroPDF417-derived CC-A or CC-B component; complete ISO/IEC 24723 certification is not claimed

### 2D matrix formats

- QR Code Model 2 — write and read, versions 1–40, standard ECC levels and payload modes.
  "SPARQCode" is not a separate format: it is a text-payload convention written inside an
  ordinary QR code, already covered by this format, see docs/formats/qr-family.md
- Data Matrix ECC 200 — write and read for classic square and rectangular symbols
- Aztec Code — write and read, including compact and full symbols
- Aztec Rune — write and read for the fixed 11×11 rune values
- Micro QR Code — write and read for the supported M1–M4 family; M1 is detection-only
- rMQR Code — write and read for the supported standard rectangular geometries
- Sythos Canvas QR profile — write and read as the non-certified `sythos-canvas-qr/1` profile
- MaxiCode — write and read for fixed 30×33 symbols, Modes 2–5 and ISO-8859-1 Code Sets A–E
- DotCode — write and read for the bounded alternating-dot profile, four masks, GF(113) correction and clean integer-scale detection
- Han Xin Code — write and read for compact alignment-free versions 1–3, numeric/text/byte modes, four masks, GF(256) correction and clean integer-scale detection

The Sythos Canvas QR profile is not DENSO FrameQR® compatible and does not
claim native DENSO interoperability.

Code 25-family aliases (`standard2of5`, `code2of5`, `industrial2of5` and
`iata2of5`) are explicit format selectors. Code 32 and PZN readers validate
their complete carrier and check digit before returning a result; incomplete
or ambiguous camera frames return nothing.

Postal aliases (`usps-postnet`, `usps-planet`, `royalmail`, `royal-mail`,
`australia-post`, `australiapost`, `japan-post`, `onecode` and `usps-onecode`)
resolve to the canonical ids `postnet`, `planet`, `rm4scc`, `auspost`,
`japanpost` and `imb`. Australia Post accepts `customerEncoding: 'character'`
or `'numeric'` (and the compatibility alias `custinfoenc`). Postal camera
reads require a measurable quiet zone and a complete validated symbol.
Han Xin root dispatch accepts both `hanxin` and `han-xin`; its focused
subpath is `@sythos/js_barcode_universal/hanxin`.
GS1 Composite root dispatch accepts `gs1composite`, `gs1-composite` and
`composite`; its focused subpath is `@sythos/js_barcode_universal/composite`.

## Main API

The package root exports `encode`, `decode`, `decodeStrict`, `listFormats`,
format-specific encoders/decoders, error classes, and renderers. Format
subpaths are available for smaller imports, including:

- `@sythos/js_barcode_universal/oned`
- `@sythos/js_barcode_universal/qr`
- `@sythos/js_barcode_universal/datamatrix`
- `@sythos/js_barcode_universal/aztec`
- `@sythos/js_barcode_universal/aztecrune`
- `@sythos/js_barcode_universal/pdf417`
- `@sythos/js_barcode_universal/compactpdf417`
- `@sythos/js_barcode_universal/micropdf417`
- `@sythos/js_barcode_universal/microqr`
- `@sythos/js_barcode_universal/rmqr`
- `@sythos/js_barcode_universal/frameqr`
- `@sythos/js_barcode_universal/databar`
- `@sythos/js_barcode_universal/hanxin`
- `@sythos/js_barcode_universal/composite`
- `@sythos/js_barcode_universal/kartrak` (experimental, colour-coded, not part of `encode()`/`decode()`)
- `@sythos/js_barcode_universal/jabcode` (experimental, colour-coded, not part of `encode()`/`decode()`)
- `@sythos/js_barcode_universal/color` (experimental colour primitives KarTrak and JAB Code are built on; no stability guarantee yet)
- `@sythos/js_barcode_universal/render`

Typical usage:

```js
import { encode, decode, toImageData } from '@sythos/js_barcode_universal';

const symbol = encode('https://www.sythos.net/', { format: 'qr', ecc: 'M' });
const image = toImageData(symbol, { scale: 4 });
const results = decode(image, { formats: ['qr'] });
```

## Reading and camera boundaries

The reader rejects structurally invalid, partial, ambiguous, or low-confidence
results instead of returning guessed payloads. Camera-oriented profiles test
the eight fixed in-plane orientations at 45-degree steps (0°, 45°, 90°,
135°, 180°, 225°, 270° and 315°) where the format detector supports that
profile. This is not a promise of arbitrary perspective, curved-media,
severe-occlusion, glare, or multi-symbol-scene robustness. Format-specific
limitations are documented in `README.md` and `PLAN.md`.

## Deliberate scope boundaries

- Data Matrix Rectangular Extension (DMRE) is not included.
- GS1 DataBar Expanded Stacked remains outside the current release; the linear Expanded variant is supported.
- Micro QR ECI, FNC1/GS1 and Structured Append are outside the current API scope.
- SQRC and Face Authentication SQRC are DENSO-licensed formats and are not
  included in this MIT SDK. A user must obtain the appropriate DENSO licence
  before adapting SDK routines for those formats.
- DENSO FrameQR® is not implemented as a native format; the shipped FrameQR
  name refers only to the separate Sythos Canvas QR profile described above.

## Licensing and provenance

The source and generated runtime are original Sythos work distributed under
the MIT License. No third-party barcode implementation is a runtime
dependency, and no third-party barcode source code or tables are shipped.
Independent libraries and public technical material may be used for
black-box interoperability checks; that does not make them dependencies or
part of the distributed implementation.

The project does not reproduce standards documents. Format-specific
engineering provenance and legal-review notes are recorded in `NOTICE.md` and
the files under `licenses/`, including:

- `licenses/pdf417.license`
- `licenses/micropdf417.license`
- `licenses/maxicode.license`
- `licenses/gs1-databar.license`
- `licenses/code25.license`
- `licenses/code32.license`
- `licenses/pzn.license`
- `licenses/postal.license`
- `licenses/dotcode.license`
- `licenses/hanxin.license`
- `licenses/gs1-composite.license`

Those files are engineering inventories, not legal advice. Patent, copyright,
trademark, standards and jurisdictional questions should receive independent
professional review where required.

## Canonical project files

- Human documentation: `README.md`
- Published documentation: https://sythos.github.io/JS_Barcode_Universal/
- Documentation source tree: `docs/`
- Roadmap and implementation boundaries: `PLAN.md`
- MIT terms: `LICENSE`
- Attribution and provenance: `NOTICE.md`
- Security reporting: `SECURITY.md`
- TypeScript runtime source: `src/ts/`
- Compiled JavaScript runtime: `src/js/`
- Stable package facades: `src/index.js` and `src/index.d.ts`
- Browser and ESM bundles: `bundle/`
- Self-contained examples: `examples/`