zxing_ffi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d24681af443b3597c80a351b2393e0a407a364f605eb2f453b030c52f3db7e0
+  data.tar.gz: bee3e1c5d88d45149c7ed4320ddf5b738dd6fea69019ac7b9ec1198cfd774ef3
+SHA512:
+  metadata.gz: 7b334ea1bed486663b38bfaf7e66e3ab2b134fd47c2796e3fb49c6d46143a3f64d4d50f04aa11c481186b14025d5a4ba0d744b1dfc7d1ea2c92a99f3ff46ce17
+  data.tar.gz: 1e59c7e05ac3484c771275274946d619a91832bea1a33be22ecb714fe45500cb1cbf3b65525e5cd5520692a7e53a00c5d4198819aeef6e152ab45f6a5eaa365c

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.0 (2026-10-01)
+
+First release candidate of `zxing_ffi`, a replacement for the unmaintained `zbar` gem.
+
+- **Native core**: libZXing 3.1+ discovery (explicit `ZXING_LIB`, bundled, system, Homebrew/`/usr/local`) with a
+  version gate; FFI bindings for the zxing-cpp C API (GVL released while decoding); runtime format map derived from
+  the library; `ZXingFFI.read`, `ZXingFFI::Image`, `ZXingFFI::Barcode`, `ZXingFFI::LIBRARY_DEFAULTS`,
+  `ZXingFFI.diagnostics`.
+- **Inputs**: magic-byte sniffing; loaders for PDF (Poppler subprocesses, CropBox-accurate, password support,
+  `dpi: :auto` from scan resolution), libvips (rasters; PDF opt-in), ImageMagick (rasters, IM7 or IM6) and PNM
+  (pure Ruby); normalization of EXIF orientation, alpha, 16-bit, CMYK, palette, 1-bit and fax aspect ratios.
+- **Pipeline**: effort levels and custom pass ladders (`base`, `inverted`, `global_binarizer`, `high_res`, `tiles`,
+  `rotated_45`, `denoise`), stop modes, coordinate mapping back to page pixels and PDF points, deduplication,
+  filtering, ordering, `scan` / `scan_pages` with threads, per-page errors and instrumentation.
+- **Safety**: subprocess isolation with timeouts, output caps and memory limits; pixel caps (fractional DPI for
+  absurd page sizes); no format confusion (explicit coders/loaders); untrusted libvips operations refused by default.
+- **Robustness**: a failing escalation pass keeps earlier results (recorded in `skipped_passes`); malformed PDFs
+  (zero or infinite page sizes) raise `RenderError`; interrupts never leak native results; threaded scans stop
+  their workers on early exit; the pure-Ruby PNM decoder works in bounded memory.
+- **CLI**: `zxing-scan` (JSON Lines, `--text-only`, `--diagnose`); one failing file does not stop the batch.
+- **Tooling**: `rake zxing:build` (pinned, checksum-verified zxing-cpp), fixture generators, golden corpus test,
+  `rake bench`.
+- **Platform gems**: prebuilt gems bundling libZXing for x86_64/aarch64 Linux (glibc ≥ 2.28, musl) and macOS (arm64
+  ≥ 11, x86_64 ≥ 10.13); diagnostics report `library.source` (`rake gem:platform`, `rake gem:verify`).
+- **License**: MIT (`LICENSE.txt`, packed in every gem).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,275 @@
+# zxing_ffi
+
+Read QR codes and every other barcode [zxing-cpp](https://github.com/zxing-cpp/zxing-cpp) understands from images and
+PDFs, in any orientation, from Ruby.
+
+```ruby
+require "zxing_ffi"
+
+ZXingFFI.scan("invoice.pdf").each do |barcode|
+  puts "page #{barcode.page}: #{barcode.format} #{barcode.text}"
+end
+# page 1: qr_code https://example.com/invoices/2026-0042
+```
+
+The gem binds the zxing-cpp **C API through the `ffi` gem** (no compiler needed to install) and wraps it in a
+pipeline: detect the input type by its magic bytes, turn every page or frame into a normalized 8-bit grayscale bitmap
+(EXIF orientation, alpha, 16-bit, CMYK, fax resolutions, PDF `/Rotate` and CropBox all handled), run an escalating
+sequence of decode passes, map results back to page coordinates, then deduplicate and order them. It replaces the
+unmaintained `zbar` gem.
+
+Supported inputs: PDF (born-digital and scanned), PNG, JPEG, TIFF (multi-page, fax), GIF, BMP, WebP, HEIF/AVIF (when
+a loader supports them) and PNM. Symbologies: QR, Micro QR, rMQR, Data Matrix, Aztec, PDF417 (incl. Compact/Micro),
+MaxiCode, Code 128, Code 39/93/32, Codabar, ITF, EAN/UPC, DataBar (all variants), Telepen, PZN, DX Film Edge — call
+`ZXingFFI.formats` for the exact list your library supports.
+
+## Requirements
+
+- Ruby ≥ 3.3 (CRuby only; JRuby and TruffleRuby are not supported)
+- **libZXing 3.1+ built with the C API** (the only hard native requirement)
+- For PDFs: Poppler's command-line tools (`pdfinfo`, `pdftoppm`; `pdfimages` optional)
+- For images: libvips with the `ruby-vips` gem (preferred) or ImageMagick; PNM needs nothing
+
+### Installing libZXing 3.x
+
+On x86_64/aarch64 Linux (glibc or musl) and macOS, `gem install zxing_ffi` gets a
+[prebuilt platform gem](#prebuilt-platform-gems) that bundles libZXing, and this step can be skipped. Elsewhere:
+
+Distribution packages often ship zxing-cpp 2.x, whose C API is incompatible. Check with `zxing-scan --diagnose`.
+
+**macOS (Homebrew):**
+
+```sh
+brew install zxing-cpp poppler vips imagemagick
+gem install zxing_ffi ruby-vips
+```
+
+Homebrew's library is found automatically (`/opt/homebrew/lib`).
+
+**Ubuntu / Debian:** build the pinned release from source (needs `cmake` and a C++20 compiler). Ruby ≥ 3.3 is
+required; Ubuntu 24.04's `ruby` package is 3.2, so install a newer Ruby first (e.g. with mise or rbenv).
+
+```sh
+sudo apt-get update
+sudo apt-get install -y git cmake g++ poppler-utils libvips-tools imagemagick
+sudo apt-get install -y libheif-plugin-libde265  # HEIC photos: libheif only suggests its HEVC decoder
+git clone https://github.com/withniva/zxing_ffi && cd zxing_ffi
+rake zxing:build            # downloads zxing-cpp 3.1.1, verifies its SHA-256, builds into vendor/zxing (no Bundler needed)
+sudo cp -P vendor/zxing/lib/libZXing.so* /usr/local/lib && sudo ldconfig   # found automatically from now on
+gem install zxing_ffi ruby-vips   # ruby-vips: in-process image loading with libvips
+```
+
+Instead of copying the library, `export ZXING_LIB=$(rake -s zxing:lib_path)` points at it inside the checkout (for the
+current shell only).
+
+Or build it yourself with `cmake -DBUILD_SHARED_LIBS=ON -DZXING_C_API=ON -DZXING_READERS=ON -DZXING_WRITERS=OFF` and
+point `ZXING_LIB` at the resulting `libZXing.so`.
+
+**Library discovery** tries, in order: `ZXingFFI.config.library_path` / `ENV["ZXING_LIB"]` (if set, nothing else is
+tried), a library bundled with the gem, the dynamic loader's search path (`libZXing.so.4`, `libZXing.dylib`, …), then
+`/opt/homebrew/lib` and `/usr/local/lib`. Versions outside `>= 3.1.0, < 4.0` raise `ZXingFFI::IncompatibleLibrary`.
+
+### Prebuilt platform gems
+
+For these platforms RubyGems installs a gem with a prebuilt libZXing in its `vendor/lib/` (zxing-cpp 3.1.1 with readers
+and the C API, compiled from the checksum-verified release tarball), so no libZXing has to be installed. Poppler and
+libvips or ImageMagick are still needed for PDFs and images. `rake gem:platform` builds them locally.
+
+| Platform gem | Runs on |
+|---|---|
+| `x86_64-linux-gnu`, `aarch64-linux-gnu` | glibc ≥ 2.28: Debian 10+, Ubuntu 20.04+, RHEL/AlmaLinux/Rocky 8+, Amazon Linux 2023 |
+| `x86_64-linux-musl`, `aarch64-linux-musl` | musl: Alpine 3.18+ |
+| `arm64-darwin` | macOS 11+ (Apple silicon) |
+| `x86_64-darwin` | macOS 10.13+ (Intel) |
+
+The Linux libraries link the C++ runtime statically and need only the C library; the macOS ones need only the
+system's libc++. Everywhere else (other CPUs, older glibc) RubyGems picks the plain `ruby` gem, which uses a
+system libZXing installed as described above.
+
+- **Bundler** records platforms in `Gemfile.lock`. A lockfile created by a recent Bundler (2.6 checked) lists every
+  platform the gems ship; for an older one, add those you deploy to, e.g.
+  `bundle lock --add-platform x86_64-linux aarch64-linux-musl` (`x86_64-linux` resolves to the `-gnu` gem). A
+  lockfile with only `ruby` gets the plain gem everywhere.
+- **Override:** `ZXING_LIB` (or `config.library_path`) still wins over the bundled library, e.g. to use a newer
+  zxing-cpp. `zxing-scan --diagnose` shows which library is loaded: `library.path` and `library.source` (`bundled`,
+  `explicit`, `system` or `prefix`). A bundled library that cannot be loaded is skipped in favour of a system one.
+- **Licenses:** the bundled library is zxing-cpp (Apache-2.0) and includes libzueci (BSD-3-Clause). Their notices
+  are installed next to it: `vendor/lib/NOTICE.txt`, `LICENSE-zxing-cpp.txt` and `LICENSE-libzueci.txt`.
+
+## Usage
+
+### Scanning files
+
+```ruby
+ZXingFFI.scan("photo.heic", formats: %i[qr_code data_matrix])
+ZXingFFI.scan(io, effort: :thorough, stop: :exhaustive, pages: 1..3, password: "secret")
+
+ZXingFFI.scan_pages("batch.pdf", threads: 4) do |page|
+  page.page            # 1-based
+  page.barcodes        # Array<ZXingFFI::Barcode>, ordered top-to-bottom, left-to-right
+  page.dpi             # render DPI (PDF)
+  page.passes_run      # [:base, :global_binarizer]
+  page.skipped_passes  # { rotated_45: "no transformer available" }
+  page.duration        # seconds
+end
+```
+
+`scan` returns every page's barcodes ordered by page, then position; `scan_pages` yields a `ZXingFFI::PageResult` per
+page in page order (or returns an Enumerator). Inputs can be a path (`String`/`Pathname`), an IO, or a
+`ZXingFFI::Image`.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `formats` | `:all` | symbols (`:qr_code`, `:ean_13`, …), library names (`"QR Code"`), meta-formats (`:all_linear`, `:all_matrix`) |
+| `effort` | `:normal` | `:fast`, `:normal`, `:thorough` — which decode passes may run (see below) |
+| `passes` | — | explicit ladder, e.g. `%i[base tiles]` (overrides `effort`) |
+| `stop` | `:found` | stop escalating a page after the first pass that finds something; `:exhaustive`; or an Integer: stop once that many distinct codes are found **on the page** (a page with fewer runs every pass) |
+| `dpi` | `:auto` | PDF render DPI: `:auto` uses a scan's native resolution (150–600) or 300 for born-digital pages |
+| `max_dpi` | `600` | upper bound for automatic and high-resolution renders |
+| `pages` | all | `Integer`, `Range` or `Array` of 1-based pages; pages outside the document are ignored |
+| `password` | — | PDF user password (Poppler reads at most 32 bytes: longer ones raise `NotSupported`; use `loader: :vips` with `vips_block_untrusted = false`) |
+| `threads` | `1` | pages processed in parallel (rendering subprocesses and decoding both run concurrently) |
+| `on_page_error` | `:raise` | `:skip` records the exception in `PageResult#error` and continues |
+| `loader` | config order | force a loader: `:poppler`, `:vips`, `:image_magick`, `:pnm` |
+| `min_length` | `{}` | minimum text length per format, e.g. `{itf: 6}` |
+| `timeout` | — | per-page budget in seconds: caps renders (re-renders get what is left) and stops escalation (the first pass always runs) |
+| `instrument` | — | callable receiving `(event, payload)` for `:page_loaded`, `:pass_completed`, `:page_completed` |
+| `max_pixels`, `max_pages` | config | per-call limits |
+
+Every `ZXingFFI.read` option below is accepted too and applies to every pass.
+
+### Effort levels and passes
+
+| Pass | What it does | Effort |
+|---|---|---|
+| `base` | library defaults + your options | fast, normal, thorough |
+| `inverted` | decodes a pixel-inverted copy for white-on-black codes (zxing-cpp's `try_invert` only covers 2D codes, so with it on this pass handles the linear formats) | normal, thorough |
+| `global_binarizer` | global-histogram binarizer | normal, thorough |
+| `high_res` | PDF re-rendered at 2× DPI; small rasters upscaled 2× | normal, thorough |
+| `tiles` | overlapping 1024–1536 px tiles, no downscaling (tiny codes on big pages) | thorough |
+| `rotated_45` | image rotated 45° for linear codes at odd angles (also covers 135°/225°/315°) | thorough |
+| `denoise` | `try_denoise: true` (libZXing built with `ZXING_EXPERIMENTAL_API` only) | thorough |
+
+2D codes are found at any rotation by the base pass; linear codes at 0/90/180/270 too.
+
+### Barcode
+
+```ruby
+barcode.text                 # "https://…" (UTF-8)
+barcode.bytes                # raw payload (BINARY) — authoritative for binary content
+barcode.format               # :qr_code, :ean_13, :code_128, …
+barcode.symbology            # family, e.g. :ean_upc for :ean_13
+barcode.content_type         # :text, :binary, :mixed, :gs1, :iso15434, :unknown_eci
+barcode.position             # ZXingFFI::Quad in base-image pixels (top_left, top_right, bottom_right, bottom_left)
+barcode.page_position        # PDF only: points from the top-left of the displayed page (CropBox, after /Rotate)
+barcode.rotation             # degrees clockwise, 0..359
+barcode.page, barcode.pass, barcode.dpi
+barcode.mirrored?, barcode.inverted?, barcode.eci?, barcode.valid?
+barcode.sequence             # structured append {index:, size:, id:} or nil
+barcode.extra                # symbology metadata, e.g. {"ECLevel" => "M", "Version" => "3"}
+barcode.to_h                 # JSON-friendly (bytes Base64-encoded when not text)
+```
+
+### Decoding raw pixels
+
+```ruby
+image = ZXingFFI::Image.new(gray_bytes, width: 640, height: 480)            # also :rgb, :bgra, … and row_stride:
+ZXingFFI.read(image, formats: :qr_code, try_harder: true)
+image.release!                                                                # free the buffer early
+```
+
+`read` runs a single decode. Options map 1:1 to zxing-cpp's `ReaderOptions`: `formats`, `try_harder`, `try_rotate`,
+`try_invert`, `try_downscale`, `try_denoise`, `pure`, `binarizer`, `max_symbols`, `min_line_count`, `return_errors`,
+`validate_optional_checksum`, `text_mode` (`:plain`, `:eci`, `:hri`, `:escaped`, `:hex`, `:hex_eci`) and `ean_add_on`
+(`:ignore`, `:read`, `:require`). Unset options keep the library's defaults (`ZXingFFI::LIBRARY_DEFAULTS`), except
+that the gem defaults to `text_mode: :plain` and `validate_optional_checksum: true` — the latter drops Code 39 and ITF
+symbols without a valid check digit, which avoids phantom reads on text and tables; pass
+`validate_optional_checksum: false` if your labels carry no check digit.
+
+### Command line
+
+```
+zxing-scan [options] FILE...
+  -f, --formats LIST        comma-separated (default: all)
+  -e, --effort LEVEL        fast|normal|thorough
+      --stop MODE           found|exhaustive|N
+      --dpi N|auto
+  -p, --pages RANGE         e.g. 1-3,7
+      --password PW         (also ZXING_PDF_PASSWORD)
+  -j, --threads N
+      --text-only           print text only, one per line
+      --diagnose            print diagnostics JSON and exit
+```
+
+Output is JSON Lines, one object per barcode: `{file, page, format, text, bytes_b64?, content_type, position,
+page_position, rotation, pass}`. Exit codes: 0 found, 1 none found, 2 usage error (checked before any file is
+read), 3 processing error (reported on stderr per file; the remaining files are still scanned).
+
+### Configuration
+
+```ruby
+ZXingFFI.configure do |c|
+  c.library_path   = ENV["ZXING_LIB"]
+  c.pdf_loaders    = %i[poppler vips]
+  c.image_loaders  = %i[vips image_magick pnm]
+  c.transformers   = %i[vips image_magick]
+  c.default_dpi    = 300
+  c.max_dpi        = 600
+  c.max_pixels     = 64_000_000
+  c.max_pages      = nil
+  c.render_timeout = 60
+  c.subprocess_memory_limit = 2 * 1024**3
+  c.tool_paths     = {pdftoppm: "pdftoppm", pdfinfo: "pdfinfo", pdfimages: "pdfimages", magick: nil}
+  c.vips_block_untrusted = true
+end
+```
+
+Configuration is read at call time; don't change it while a scan is running. `ZXingFFI.diagnostics` (or
+`zxing-scan --diagnose`) reports the library path and version, optional features, defaults, loaders, tools and
+their versions.
+
+## Limits and security
+
+The gem is meant to process untrusted documents:
+
+- **Renderers run in subprocesses** (Poppler, ImageMagick) with an argument array (never a shell), absolute paths,
+  a timeout (`render_timeout`, process group killed with TERM then KILL), a cap on their output, and an address-space
+  limit (`subprocess_memory_limit`, enforced on Linux only — macOS ignores `RLIMIT_AS`). Passwords are only ever passed
+  as the argument after `-upw`.
+- **Pixel cap**: every bitmap is checked against `max_pixels` before it is rendered or decoded. PDF pages that would
+  exceed it are rendered at a lower (possibly fractional) DPI; rasters raise `ZXingFFI::LimitExceeded`.
+- **No format confusion**: inputs are identified by magic bytes, never by extension. ImageMagick always reads with an
+  explicit coder (`png:/path`), never sees PDF, PostScript, SVG, MVG, MSL or text, and gets special characters in
+  paths neutralized. libvips is called with the loader for the sniffed type, and operations libvips flags as
+  *untrusted* (in 8.18: `pdfload`, `magickload`, `ppmload`) are refused while `vips_block_untrusted` is true — so
+  in-process PDF rendering with libvips is opt-in. A crash inside libvips or libZXing takes down the Ruby process.
+- IO inputs are copied to a private (0600) temp file that is always removed.
+- Decoding releases the GVL, so threads decode concurrently; results are identical to serial runs. Interrupts
+  (`Thread#raise`, `Timeout`, signals) are delivered once the native decode has returned and its results are freed;
+  leaving a threaded `scan` early stops the other page workers and kills their renderer processes.
+- Passes after the first never lose results: if one fails (a re-render timing out, a transformer error), the page
+  keeps what earlier passes found and `PageResult#skipped_passes` records `"failed: …"`. Passes whose image would
+  exceed `max_pixels` (`high_res`, `rotated_45`) are skipped the same way.
+
+Errors all inherit from `ZXingFFI::Error`: `LibraryNotFound`, `IncompatibleLibrary`, `NotSupported`,
+`LoaderUnavailable`, `UnsupportedInput`, `PasswordRequired` (and `IncorrectPassword`), `RenderError` (`#stderr`,
+`#exit_status`), `TimeoutError`, `LimitExceeded` (`#limit`, `#value`), `DecodeError`.
+
+## Development
+
+```sh
+mise exec -- bundle install
+mise exec -- bundle exec rake zxing:build   # vendor/zxing (the test helper points ZXING_LIB at it)
+mise exec -- bundle exec rake               # all tests + standardrb
+mise exec -- bundle exec rake test:unit     # also test:native, test:integration, test:corpus
+mise exec -- bundle exec rake bench         # corpus benchmark → docs/benchmark.md with OUT=…
+mise exec -- bundle exec script/generate_fixtures   # regenerate committed fixtures (zint, rqrcode, prawn, vips, magick, poppler)
+mise exec -- bundle exec script/real_corpus         # real documents listed in real_corpus.local.yml → tmp/real_corpus (local only)
+```
+
+## Licensing
+
+zxing_ffi is released under the [MIT License](LICENSE.txt). Third-party components: zxing-cpp is Apache-2.0 and the
+prebuilt libZXing in the platform gems also contains libzueci (BSD-3-Clause); those gems ship both notices in
+`vendor/lib/` (see [Prebuilt platform gems](#prebuilt-platform-gems)). Poppler (GPL) and ImageMagick are only run as
+separate processes; libvips (LGPL) is loaded through your own `ruby-vips` installation.

data/exe/zxing-scan

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "zxing_ffi"
+
+exit ZXingFFI::CLI.new(ARGV).run

data/lib/zxing_ffi/barcode.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ZXingFFI
+  # One decoded barcode. Immutable.
+  #
+  # Fields filled by {ZXingFFI.read}: everything except +page+, +pass+, +dpi+ and +page_position+,
+  # which the scanner adds. Predicates +mirrored?+, +inverted?+, +eci?+ and +valid?+ alias the booleans.
+  #
+  # @!attribute text [String] decoded text (UTF-8), per +text_mode+
+  # @!attribute bytes [String] raw payload bytes (BINARY)
+  # @!attribute format [Symbol] specific format, e.g. +:ean_13+, +:qr_code+
+  # @!attribute symbology [Symbol] symbology family, e.g. +:ean_upc+ for +:ean_13+
+  # @!attribute format_name [String] library name, e.g. "EAN-13"
+  # @!attribute content_type [Symbol] +:text+, +:binary+, +:mixed+, +:gs1+, +:iso15434+, +:unknown_eci+
+  # @!attribute symbology_identifier [String] e.g. "]Q1"
+  # @!attribute position [Quad] corners in base-image pixels
+  # @!attribute page_position [Quad, nil] PDF points from the top-left of the displayed page (PDF input only)
+  # @!attribute rotation [Integer] degrees clockwise, 0..359
+  # @!attribute error [Hash, nil] +{type:, message:}+ (only with +return_errors: true+)
+  # @!attribute line_count [Integer]
+  # @!attribute sequence [Hash, nil] structured append +{index:, size:, id:}+
+  # @!attribute extra_json [String, nil] raw JSON from ZXing_Barcode_extra (see {#extra})
+  # @!attribute page [Integer, nil] 1-based page, nil for {ZXingFFI.read}
+  # @!attribute pass [Symbol, nil] ladder pass that produced it
+  # @!attribute dpi [Integer, nil] base render DPI (PDF)
+  Barcode = Data.define(
+    :text, :bytes, :format, :symbology, :format_name, :content_type, :symbology_identifier,
+    :position, :page_position, :rotation, :mirrored, :inverted, :eci, :valid, :error,
+    :line_count, :sequence, :extra_json, :page, :pass, :dpi
+  ) do
+    def initialize(extra_json: nil, **fields)
+      @extra_cache = {} # mutable holder: the instance itself is frozen by Data
+      super
+    end
+
+    def mirrored? = mirrored
+
+    def inverted? = inverted
+
+    def eci? = eci
+
+    def valid? = valid
+
+    # Symbology-specific metadata (e.g. "ECLevel", "Version" for QR), parsed from the library's JSON
+    # on first access. +{}+ when there is none.
+    # @return [Hash{String => Object}]
+    def extra
+      @extra_cache.fetch(:value) do
+        json = extra_json
+        @extra_cache[:value] = (json.nil? || json.empty?) ? {}.freeze : JSON.parse(json).freeze
+      end
+    end
+
+    # Center of {#position}.
+    # @return [Geometry::Point]
+    def center
+      position.center
+    end
+
+    # JSON-friendly Hash. +bytes+ is Base64-encoded (and +bytes_encoding: "base64"+ added) when the content
+    # is not text or the bytes are not valid UTF-8; quads become nested Hashes.
+    # @return [Hash]
+    def to_h
+      h = super.except(:extra_json).merge(extra: extra, position: position&.to_h, page_position: page_position&.to_h)
+      utf8 = bytes.dup.force_encoding(Encoding::UTF_8)
+      if content_type == :text && utf8.valid_encoding?
+        h[:bytes] = utf8
+      else
+        h[:bytes] = [bytes].pack("m0")
+        h[:bytes_encoding] = "base64"
+      end
+      h
+    end
+  end
+end

data/lib/zxing_ffi/cli.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+module ZXingFFI
+  # The +zxing-scan+ command: scans files and prints one JSON object per barcode (JSON Lines).
+  #
+  # Exit codes: 0 at least one barcode found, 1 none found, 2 usage error, 3 processing error (any file failed).
+  class CLI
+    # Exit status: at least one barcode was found.
+    EXIT_FOUND = 0
+    # Exit status: no barcode was found.
+    EXIT_NONE = 1
+    # Exit status: invalid command line.
+    EXIT_USAGE = 2
+    # Exit status: at least one file could not be processed.
+    EXIT_ERROR = 3
+
+    # @param argv [Array<String>]
+    # @param stdout [IO]
+    # @param stderr [IO]
+    # @param env [Hash] environment (for ZXING_PDF_PASSWORD)
+    def initialize(argv, stdout: $stdout, stderr: $stderr, env: ENV)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @env = env
+      @options = {}
+      @text_only = false
+      @diagnose = false
+    end
+
+    # @return [Integer] exit code
+    def run
+      files = parse!
+      return diagnose if @diagnose
+
+      if files.empty?
+        @stderr.puts parser.banner
+        return EXIT_USAGE
+      end
+
+      begin
+        scanner = ZXingFFI::Scanner.new(**@options) # invalid options are a usage error, before any file is read
+      rescue ArgumentError => e
+        @stderr.puts "zxing-scan: #{e.message}"
+        return EXIT_USAGE
+      end
+
+      found = false
+      failed = false
+      files.each do |file|
+        scanner.scan(file).each do |barcode|
+          found = true
+          @stdout.puts(@text_only ? barcode.text : JSON.generate(record(file, barcode)))
+        end
+      rescue => e # one file failing (unreadable, no such page, …) must not stop the others
+        failed = true
+        @stderr.puts "zxing-scan: #{display(file)}: #{e.class.name.split("::").last}: #{e.message.lines.first&.strip}"
+      end
+      return EXIT_ERROR if failed
+
+      found ? EXIT_FOUND : EXIT_NONE
+    rescue OptionParser::ParseError => e
+      @stderr.puts "zxing-scan: #{e.message}"
+      @stderr.puts parser.banner
+      EXIT_USAGE
+    end
+
+    # The JSON object for one barcode: +{file, page, format, text, bytes_b64?, content_type, position,
+    # page_position, rotation, pass}+. +bytes_b64+ is present only for non-text content.
+    # @return [Hash]
+    def record(file, barcode)
+      record = {file: display(file), page: barcode.page, format: barcode.format, text: barcode.text}
+      record[:bytes_b64] = [barcode.bytes].pack("m0") unless barcode.content_type == :text
+      record.merge(
+        content_type: barcode.content_type,
+        position: corners(barcode.position),
+        page_position: barcode.page_position && corners(barcode.page_position),
+        rotation: barcode.rotation,
+        pass: barcode.pass
+      )
+    end
+
+    private
+
+    # File names are bytes on Linux: make them valid UTF-8 for JSON and messages.
+    def display(file)
+      file.to_s.dup.force_encoding(Encoding::UTF_8).scrub("�")
+    end
+
+    def corners(quad)
+      quad.to_a.map { |point| [point.x, point.y] }
+    end
+
+    def diagnose
+      @stdout.puts JSON.pretty_generate(ZXingFFI.diagnostics)
+      EXIT_FOUND
+    end
+
+    def parse!
+      files = parser.parse(@argv)
+      password = @options[:password] || @env["ZXING_PDF_PASSWORD"]
+      @options[:password] = password if password && !password.empty?
+      files
+    end
+
+    def parser
+      @parser ||= OptionParser.new do |o|
+        o.banner = "Usage: zxing-scan [options] FILE..."
+        o.version = ZXingFFI::VERSION
+        o.on("-f", "--formats LIST", "comma-separated formats (default: all)") { |v| @options[:formats] = v.split(",").map(&:strip) }
+        o.on("-e", "--effort LEVEL", %w[fast normal thorough], "fast|normal|thorough") { |v| @options[:effort] = v.to_sym }
+        o.on("--stop MODE", "found|exhaustive|N") { |v| @options[:stop] = stop(v) }
+        o.on("--dpi N", "render DPI for PDFs, or auto") { |v| @options[:dpi] = dpi(v) }
+        o.on("-p", "--pages RANGE", "e.g. 1-3,7 (1-based)") { |v| @options[:pages] = pages(v) }
+        o.on("--password PW", "PDF password (also ZXING_PDF_PASSWORD)") { |v| @options[:password] = v }
+        o.on("-j", "--threads N", Integer, "pages scanned in parallel") { |v| @options[:threads] = v }
+        o.on("--text-only", "print text only, one per line") { @text_only = true }
+        o.on("--diagnose", "print diagnostics JSON and exit") { @diagnose = true }
+      end
+    end
+
+    def stop(value)
+      return value.to_sym if %w[found exhaustive].include?(value)
+      return Integer(value, 10) if value.match?(/\A\d+\z/)
+
+      raise OptionParser::InvalidArgument, "--stop #{value} (expected found, exhaustive or a number)"
+    end
+
+    def dpi(value)
+      return :auto if value == "auto"
+      return Integer(value, 10) if value.match?(/\A\d+\z/)
+
+      raise OptionParser::InvalidArgument, "--dpi #{value} (expected a number or auto)"
+    end
+
+    # "1-3,7" → [1, 2, 3, 7]; "5-" → 5.. (every page from 5)
+    def pages(value)
+      return Range.new(Integer(Regexp.last_match(1), 10), nil) if value =~ /\A(\d+)-\z/
+
+      value.split(",").flat_map do |token|
+        case token.strip
+        when /\A(\d+)\z/ then [Integer(Regexp.last_match(1), 10)]
+        when /\A(\d+)-(\d+)\z/ then (Integer(Regexp.last_match(1), 10)..Integer(Regexp.last_match(2), 10)).to_a
+        else raise OptionParser::InvalidArgument, "--pages #{value} (expected e.g. 1-3,7)"
+        end
+      end
+    end
+  end
+end