feat(android): replace ML Kit with zxing-cpp

[wodoro]

Closes #60.

Android now decodes with io.github.zxing-cpp:android (Apache 2.0) instead of
com.google.mlkit:barcode-scanning, so every dependency is open source and KScan
can be used in apps published on F-Droid.

Two commits, no new modules. The measurement that justifies it, the corpus generator and the full per-frame data live in #61, which is kept only as the record of how the decision was made; this one is
just the change.

What it costs and what it buys

Measured over 468 generated frames, all thirteen formats KScan exposes across
distance, in- and out-of-plane rotation, lighting, contrast, defocus and noise,
on an API 37 x86_64 emulator:

	ML Kit	zxing-cpp
Read correctly	89.1%	79.9%
Misread	0.6%	0.9%
Median decode	60.7 ms	8.1 ms

9.2 points worse overall, ~7x faster, and 14.6 MB smaller (sample debug APK
44.3 MB -> 29.7 MB; ML Kit's bundled libbarhopper_v3.so is 20.2 MB across four
ABIs against zxing-cpp's 6.6 MB).

The average hides the shape. zxing-cpp is ahead on QR, Data Matrix and Aztec
(94.4% against 89.6%), on inverted and coloured symbols, and dramatically on small
ones: where the symbol spans 12% of the frame ML Kit reads 23.1% and zxing-cpp
100%. It is behind on one thing, linear barcodes rotated off axis, which
accounts for 47 of the 72 frames it lost. Right angles are fine; 15 degrees costs
it, 45 costs it badly. Excluding those conditions it is 1.0 point ahead overall.

Replaying every scene as a second of hand-held video rather than a single frame
does not rescue it: sensor noise turns out to be entirely transient (both reach
100%), but the rotation loss is persistent. A user holding a linear barcode at 30
degrees will watch it fail to scan. That is the honest cost of the switch.

Breaking

• ScannerView's autoZoom is removed. It was ML Kit's
  ZoomSuggestionOptions, which zxing-cpp has no equivalent for, and it never did
  anything on iOS, desktop or web. ScannerController still drives zoom. Callers
  passing arguments positionally should note that result moves up a place. ABI
  dumps are regenerated and the sample's Auto zoom toggle goes with it.

0.10.0 is already an unreleased breaking version, so this rides along with the
existing ScannerView changes rather than adding a second migration.

Behaviour worth knowing

Decoding moved off the main thread. zxing-cpp decodes on the thread that calls
it, so analysis runs on a thread of the library's own. filter and result are
still called on the main thread, unchanged.

FrameInverter had to stay. zxing-cpp's tryInvert is only offered to readers
declaring support for reversed reflectance, which is QR, Data Matrix and Aztec but
never a linear one or PDF417 (MultiFormatReader skips readers without
supportsInversion on an inverted image). Dropping the explicit negative pass
would have silently lost inverted linear barcodes, which work today. It now
produces an eight bit alpha bitmap that zxing-cpp reads as a luminance plane, so
it costs one byte per pixel rather than four.

Misread profile differs. zxing-cpp's four misreads are all truncated ITF, which
has no mandatory check digit; it returned 1234 for 1234567890 on rotated or
tilted frames. RepeatedDetection requires the same value on two frames before
reporting, so real exposure is lower than the single-frame 0.9%, but
validateOptionalChecksum could be exposed if you want it stricter.

Dependency audit

io.github.zxing-cpp:android:3.1.1, checked before adopting:

• SHA-1/256/512 of the AAR match Maven Central's published checksums; .asc
  signature present; release cut by the upstream maintainer.
• Upstream is Apache-2.0, active since 2016, ~2k stars.
• The AAR manifest declares no permissions and no services, receivers or
  providers.
• The native library links only libc, libm, libdl, liblog and
  libjnigraphics. No socket, connect, getaddrinfo, exec, fork, popen,
  system or ptrace in its import table, and no URLs in its strings. It exports
  exactly two JNI entry points, readBitmap and readYBuffer.
• Transitive dependencies are androidx.camera:camera-core and kotlin-stdlib.
  No Play Services.

Also in here

The pre-commit hook called ./tools/ktlint, which is no longer in the tree, so
committing a Kotlin file failed. It now calls spotlessApply, which is where the
ktlint version, the Compose rule set and the editorconfig overrides already live
and what CI checks.

[ismai117]

Great! @wodoro i will test this out on my side

[Copilot]

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Replaces Android ML Kit barcode decoding with open-source zxing-cpp while preserving KScan’s multiplatform API aside from removing autoZoom.

Changes:

• Added zxing-cpp decoding, format mapping, inversion, and background camera analysis.
• Removed ScannerView.autoZoom and updated samples, APIs, documentation, and changelog.
• Updated dependencies, ProGuard rules, tests, and pre-commit formatting.

File summaries

File	Description
sample/shared/src/commonMain/kotlin/org/ncgroup/kscan/settings/SettingsScreen.kt	Updated as part of this pull request.
sample/shared/src/commonMain/kotlin/org/ncgroup/kscan/scanner/ScannerState.kt	Updated as part of this pull request.
sample/shared/src/commonMain/kotlin/org/ncgroup/kscan/scanner/ScannerScreen.kt	Updated as part of this pull request.
README.md	Updated as part of this pull request.
kscan/src/webMain/kotlin/org/ncgroup/kscan/view/ScannerViewImpl.web.kt	Updated as part of this pull request.
kscan/src/jvmMain/kotlin/org/ncgroup/kscan/view/ScannerViewImpl.jvm.kt	Updated as part of this pull request.
kscan/src/iosMain/kotlin/org/ncgroup/kscan/view/ScannerViewImpl.ios.kt	Updated as part of this pull request.
kscan/src/commonTest/kotlin/org/ncgroup/kscan/format/BarcodeSelectionTest.kt	Updated as part of this pull request.
kscan/src/commonMain/kotlin/org/ncgroup/kscan/view/ScannerViewImpl.kt	Updated as part of this pull request.
kscan/src/commonMain/kotlin/org/ncgroup/kscan/ScannerView.kt	Updated as part of this pull request.
kscan/src/commonMain/kotlin/org/ncgroup/kscan/format/BarcodeSelection.kt	Updated as part of this pull request.
kscan/src/commonMain/kotlin/org/ncgroup/kscan/BarcodeFormat.kt	Updated as part of this pull request.
kscan/src/androidMain/kotlin/org/ncgroup/kscan/view/ScannerViewImpl.android.kt	Updated as part of this pull request.
kscan/src/androidMain/kotlin/org/ncgroup/kscan/scanner/ZxingCppBarcode.kt	Updated as part of this pull request.
kscan/src/androidMain/kotlin/org/ncgroup/kscan/scanner/ScannerOptions.kt	Updated as part of this pull request.
kscan/src/androidMain/kotlin/org/ncgroup/kscan/scanner/FrameInverter.kt	Updated as part of this pull request.
kscan/src/androidMain/kotlin/org/ncgroup/kscan/scanner/BarcodeAnalyzer.kt	Updated as part of this pull request.
kscan/src/androidMain/kotlin/org/ncgroup/kscan/ImageScanner.android.kt	Updated as part of this pull request.
kscan/src/androidMain/kotlin/org/ncgroup/kscan/format/BarcodeFormatMapper.kt	Updated as part of this pull request.
kscan/src/androidHostTest/kotlin/org/ncgroup/kscan/scanner/InvertLuminanceTest.kt	Updated as part of this pull request.
kscan/src/androidHostTest/kotlin/org/ncgroup/kscan/format/BarcodeFormatMapperTest.kt	Updated as part of this pull request.
kscan/build.gradle.kts	Updated as part of this pull request.
kscan/api/kscan.klib.api	Updated as part of this pull request.
kscan/api/jvm/kscan.api	Updated as part of this pull request.
gradle/libs.versions.toml	Updated as part of this pull request.
consumer-rules.pro	Updated as part of this pull request.
CHANGELOG.md	Updated as part of this pull request.
.hooks/pre-commit	Updated as part of this pull request.

Review details

Suppressed comments (3)

.hooks/pre-commit:22

• git add "$file" stages the entire file after spotlessApply. If a Kotlin file has both staged and unstaged edits, the unstaged edits are silently included in the commit; formatting the whole tree makes this easier to encounter. Preserve the staged patch or avoid re-adding complete files so the hook cannot expand the commit.

echo "$CHANGED_FILES" | while read -r file; do
  if [ -f "$file" ]; then
    git add "$file"

kscan/src/androidMain/kotlin/org/ncgroup/kscan/format/BarcodeFormatMapper.kt:29

• When codeTypes contains only TYPE_UNKNOWN, this returns an empty set. zxing-cpp treats an empty Options.formats as unrestricted, so the analyzer still performs a full decode (and periodic inversion) only to discard every result, contrary to the new no-match behavior. Short-circuit this request or pass an explicit no-format configuration to avoid the unnecessary work.

    // Named rather than left empty for every format: an empty set asks zxing-cpp
    // for every symbology it knows, including the ones KScan has no name for,
    // which would only be decoded to be reported as TYPE_UNKNOWN and dropped.
    fun toZxingCppFormats(appFormats: List<BarcodeFormat>): Set<BarcodeReader.Format> = formats.platformFormats(appFormats).toSet()

kscan/src/androidMain/kotlin/org/ncgroup/kscan/scanner/BarcodeAnalyzer.kt:53

• This callback is queued after the proxy has already been closed, so the analysis executor can enqueue a decode failure after an earlier barcode's report callback has already succeeded. Because this guard only checks closed (which is not set until disposal), callers can receive OnFailed after OnSuccess; also suppress failures once hasSuccessfullyProcessedBarcode is true.

                callbackExecutor.execute { if (!closed) onFailed(e) }

• Files reviewed: 28/28 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ismai117]

🚀