Fix barcode scanner on iOS Safari

iOS WebKit does not provide a reliable native Barcode Detection API, and
ZXing often failed due to strict camera constraints and video startup timing.

- Install @undecaf/barcode-detector-polyfill (ZBar WASM) on Apple devices
- Fall back through progressively looser getUserMedia constraints
- Wait for video metadata/playback before decoding frames
- Throttle native scans on iOS and tune ZXing retry intervals
- Defer scanner startup until the modal video element is mounted

Co-authored-by: Ned Halksworth <hello@nedhalksworth.com>

package-lock.json

@@ -9,6 +9,7 @@
       "version": "1.0.0",
       "license": "MIT",
       "dependencies": {
+        "@undecaf/barcode-detector-polyfill": "^0.9.23",
         "@vitejs/plugin-react": "^4.3.4",
         "@zxing/browser": "^0.2.0",
         "appwrite": "^25.0.0",
@@ -1160,9 +1161,6 @@
       "cpu": [
         "arm"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1176,9 +1174,6 @@
       "cpu": [
         "arm"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1192,9 +1187,6 @@
       "cpu": [
         "arm64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1208,9 +1200,6 @@
       "cpu": [
         "arm64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1224,9 +1213,6 @@
       "cpu": [
         "loong64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1240,9 +1226,6 @@
       "cpu": [
         "loong64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1256,9 +1239,6 @@
       "cpu": [
         "ppc64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1272,9 +1252,6 @@
       "cpu": [
         "ppc64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1288,9 +1265,6 @@
       "cpu": [
         "riscv64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1304,9 +1278,6 @@
       "cpu": [
         "riscv64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1320,9 +1291,6 @@
       "cpu": [
         "s390x"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1336,9 +1304,6 @@
       "cpu": [
         "x64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1352,9 +1317,6 @@
       "cpu": [
         "x64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1880,6 +1842,24 @@
         "url": "https://opencollective.com/eslint"
       }
     },
+    "node_modules/@undecaf/barcode-detector-polyfill": {
+      "version": "0.9.23",
+      "resolved": "https://registry.npmjs.org/@undecaf/barcode-detector-polyfill/-/barcode-detector-polyfill-0.9.23.tgz",
+      "integrity": "sha512-qVr7jSUbE5a30X9dByDym2NzsqyH+MFwyFiu4QSHDQMLCImTJj/et7pEcOtGqlL4UB5J6J3d0hK4/5d4MMowYA==",
+      "license": "MIT",
+      "dependencies": {
+        "@undecaf/zbar-wasm": "^0.9.16"
+      }
+    },
+    "node_modules/@undecaf/zbar-wasm": {
+      "version": "0.9.16",
+      "resolved": "https://registry.npmjs.org/@undecaf/zbar-wasm/-/zbar-wasm-0.9.16.tgz",
+      "integrity": "sha512-T5PcT6g+tLScGjR4WmnRErNvfKqEc3kRg2ux14wHmIDNbvNeXa0BkFK19PRK/jb6zGy5NyWtn4ko6KeNuZc/fQ==",
+      "license": "LGPL-2.1+",
+      "dependencies": {
+        "jschardet": "^3.0.0"
+      }
+    },
     "node_modules/@vitejs/plugin-react": {
       "version": "4.7.0",
       "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-4.7.0.tgz",
@@ -3622,6 +3602,15 @@
         "js-yaml": "bin/js-yaml.js"
       }
     },
+    "node_modules/jschardet": {
+      "version": "3.1.4",
+      "resolved": "https://registry.npmjs.org/jschardet/-/jschardet-3.1.4.tgz",
+      "integrity": "sha512-/kmVISmrwVwtyYU40iQUOp3SUPk2dhNCMsZBQX0R1/jZ8maaXJ/oZIzUOiyOqcgtLnETFKYChbJ5iDC/eWmFHg==",
+      "license": "LGPL-2.1+",
+      "engines": {
+        "node": ">=0.1.90"
+      }
+    },
     "node_modules/jsesc": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",

package.json

@@ -12,6 +12,7 @@
     "setup:appwrite": "node scripts/setup-appwrite.mjs"
   },
   "dependencies": {
+    "@undecaf/barcode-detector-polyfill": "^0.9.23",
     "@vitejs/plugin-react": "^4.3.4",
     "@zxing/browser": "^0.2.0",
     "appwrite": "^25.0.0",

src/components/BarcodeScannerModal.tsx

@@ -191,8 +191,11 @@ export function BarcodeScannerModal({
     window.setTimeout(() => closeButtonRef.current?.focus(), 80);
 
     let active = true;
+    let frameId = 0;
+
+    const startScanner = () => {
       const video = videoRef.current;
-    if (!video) return undefined;
+      if (!video || !active) return;
 
       void startBarcodeScanner(video, handleScannerResult, handleScannerError)
         .then((controller) => {
@@ -209,6 +212,11 @@ export function BarcodeScannerModal({
           setScannerError(error);
           setPhase("error");
         });
+    };
+
+    frameId = window.requestAnimationFrame(() => {
+      window.requestAnimationFrame(startScanner);
+    });
 
     void listBarcodeCatalog()
       .then((catalog) => {
@@ -224,6 +232,7 @@ export function BarcodeScannerModal({
 
     return () => {
       active = false;
+      window.cancelAnimationFrame(frameId);
       stopScanner();
     };
   }, [applyManualDefaults, handleScannerError, handleScannerResult, open, stopScanner, userId]);
@@ -335,6 +344,7 @@ export function BarcodeScannerModal({
                   <video
                     ref={videoRef}
                     className="aspect-[3/4] w-full bg-black object-cover sm:aspect-video"
+                    autoPlay
                     muted
                     playsInline
                     aria-label="Live camera preview"

src/lib/barcodeDetectorSupport.ts

@@ -0,0 +1,35 @@
+import { BarcodeDetectorPolyfill } from "@undecaf/barcode-detector-polyfill";
+
+type WindowWithBarcodeDetector = Window & {
+  BarcodeDetector?: typeof BarcodeDetectorPolyfill;
+};
+
+let detectorReady: Promise<void> | null = null;
+
+export function isAppleMobileDevice() {
+  if (typeof navigator === "undefined") return false;
+  const ua = navigator.userAgent;
+  return /iPad|iPhone|iPod/i.test(ua) || (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);
+}
+
+export function ensureBarcodeDetector() {
+  if (detectorReady) return detectorReady;
+
+  detectorReady = (async () => {
+    const globalWindow = window as WindowWithBarcodeDetector;
+    const shouldForcePolyfill = isAppleMobileDevice();
+
+    if (shouldForcePolyfill) {
+      globalWindow.BarcodeDetector = BarcodeDetectorPolyfill;
+      return;
+    }
+
+    try {
+      await globalWindow.BarcodeDetector?.getSupportedFormats();
+    } catch {
+      globalWindow.BarcodeDetector = BarcodeDetectorPolyfill;
+    }
+  })();
+
+  return detectorReady;
+}

src/lib/barcodeScanner.ts

@@ -4,6 +4,7 @@ import {
   BrowserMultiFormatReader,
   type IScannerControls,
 } from "@zxing/browser";
+import { ensureBarcodeDetector, isAppleMobileDevice } from "./barcodeDetectorSupport";
 import { normalizeBarcode } from "./barcodeLookup";
 
 export type BarcodeScannerErrorCode =
@@ -54,7 +55,7 @@ const ZXING_FORMATS = [
   BarcodeFormat.UPC_A,
   BarcodeFormat.UPC_E,
 ];
-const SCAN_CONSTRAINTS: MediaStreamConstraints = {
+const PREFERRED_SCAN_CONSTRAINTS: MediaStreamConstraints = {
   video: {
     facingMode: { ideal: "environment" },
     width: { ideal: 1280 },
@@ -62,6 +63,7 @@ const SCAN_CONSTRAINTS: MediaStreamConstraints = {
   },
   audio: false,
 };
+const IOS_NATIVE_SCAN_INTERVAL_MS = 150;
 
 export async function startBarcodeScanner(
   videoElement: HTMLVideoElement,
@@ -72,6 +74,8 @@ export async function startBarcodeScanner(
     throw toScannerError(new Error("Camera access is not supported in this browser."));
   }
 
+  await ensureBarcodeDetector();
+
   if (await supportsNativeBarcodeDetector()) {
     try {
       return await startNativeBarcodeScanner(videoElement, onResult);
@@ -121,15 +125,14 @@ function startNativeBarcodeScanner(
   return new Promise((resolve, reject) => {
     let stopped = false;
     let animationFrame = 0;
+    let scanInterval = 0;
     let stream: MediaStream | null = null;
 
     async function start() {
       try {
-        stream = await navigator.mediaDevices.getUserMedia(SCAN_CONSTRAINTS);
+        stream = await getCameraStream();
-        videoElement.srcObject = stream;
+        prepareVideoElement(videoElement, stream);
-        videoElement.setAttribute("playsinline", "true");
+        await waitForVideoReady(videoElement);
-        videoElement.muted = true;
-        await videoElement.play();
 
         const Detector = (window as WindowWithBarcodeDetector).BarcodeDetector;
         if (!Detector) {
@@ -140,13 +143,14 @@ function startNativeBarcodeScanner(
         const stop = () => {
           stopped = true;
           window.cancelAnimationFrame(animationFrame);
+          window.clearInterval(scanInterval);
           stopVideoStream(videoElement);
         };
 
         const scan = async () => {
           if (stopped) return;
           try {
-            if (videoElement.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) {
+            if (videoElement.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA && videoElement.videoWidth > 0) {
               const barcodes = await detector.detect(videoElement);
               const barcode = barcodes.find((item) => normalizeBarcode(item.rawValue ?? ""));
               if (barcode?.rawValue) {
@@ -156,12 +160,24 @@ function startNativeBarcodeScanner(
                 });
               }
             }
-          } finally {
+          } catch {
-            if (!stopped) animationFrame = window.requestAnimationFrame(() => void scan());
+            // Keep scanning; transient frame errors are common on mobile Safari.
           }
         };
 
-        animationFrame = window.requestAnimationFrame(() => void scan());
+        const scheduleScan = () => {
+          if (stopped) return;
+          void scan().finally(() => {
+            if (!stopped) animationFrame = window.requestAnimationFrame(scheduleScan);
+          });
+        };
+
+        if (isAppleMobileDevice()) {
+          scanInterval = window.setInterval(() => void scan(), IOS_NATIVE_SCAN_INTERVAL_MS);
+        } else {
+          animationFrame = window.requestAnimationFrame(scheduleScan);
+        }
+
         resolve({ mode: "native", stop });
       } catch (error) {
         if (stream) stream.getTracks().forEach((track) => track.stop());
@@ -178,14 +194,17 @@ async function startZxingBarcodeScanner(
   onResult: (result: BarcodeScanResult) => void,
   onError: (error: BarcodeScannerError) => void,
 ): Promise<BarcodeScannerController> {
-  const reader = new BrowserMultiFormatReader();
+  const reader = new BrowserMultiFormatReader(undefined, {
+    delayBetweenScanAttempts: isAppleMobileDevice() ? 150 : 500,
+  });
   reader.possibleFormats = ZXING_FORMATS;
 
   try {
-    const controls = await reader.decodeFromConstraints(
+    const stream = await getCameraStream();
-      SCAN_CONSTRAINTS,
+    prepareVideoElement(videoElement, stream);
-      videoElement,
+    await waitForVideoReady(videoElement);
-      (result, error) => {
+
+    const controls = await reader.decodeFromStream(stream, videoElement, (result, error) => {
       if (result) {
         onResult({
           value: normalizeBarcode(result.getText()),
@@ -196,8 +215,7 @@ async function startZxingBarcodeScanner(
       if (error && !/not.?found/i.test(error.name) && !/not.?found/i.test(error.message)) {
         onError(toScannerError(error));
       }
-      },
+    });
-    );
 
     return {
       mode: "zxing",
@@ -229,6 +247,72 @@ async function supportsNativeBarcodeDetector() {
   }
 }
 
+async function getCameraStream() {
+  const attempts: MediaStreamConstraints[] = [
+    PREFERRED_SCAN_CONSTRAINTS,
+    { video: { facingMode: { ideal: "environment" } }, audio: false },
+    { video: { facingMode: "environment" }, audio: false },
+    { video: true, audio: false },
+  ];
+
+  let lastError: unknown;
+  for (const constraints of attempts) {
+    try {
+      return await navigator.mediaDevices.getUserMedia(constraints);
+    } catch (error) {
+      lastError = error;
+      if (isCameraAccessError(error) && !(error instanceof DOMException && error.name === "OverconstrainedError")) {
+        throw error;
+      }
+    }
+  }
+
+  throw lastError ?? new Error("Could not access the camera.");
+}
+
+function prepareVideoElement(videoElement: HTMLVideoElement, stream: MediaStream) {
+  videoElement.srcObject = stream;
+  videoElement.setAttribute("playsinline", "true");
+  videoElement.setAttribute("webkit-playsinline", "true");
+  videoElement.setAttribute("autoplay", "true");
+  videoElement.muted = true;
+}
+
+async function waitForVideoReady(videoElement: HTMLVideoElement) {
+  if (videoElement.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA && videoElement.videoWidth > 0) {
+    await playVideoElement(videoElement);
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const onReady = () => {
+      cleanup();
+      void playVideoElement(videoElement).then(resolve).catch(reject);
+    };
+    const onError = () => {
+      cleanup();
+      reject(new Error("Camera preview failed to start."));
+    };
+    const cleanup = () => {
+      videoElement.removeEventListener("loadedmetadata", onReady);
+      videoElement.removeEventListener("error", onError);
+    };
+
+    videoElement.addEventListener("loadedmetadata", onReady, { once: true });
+    videoElement.addEventListener("error", onError, { once: true });
+  });
+}
+
+async function playVideoElement(videoElement: HTMLVideoElement) {
+  try {
+    await videoElement.play();
+  } catch (error) {
+    if (videoElement.paused) {
+      throw error;
+    }
+  }
+}
+
 function isCameraAccessError(error: unknown) {
   if (!(error instanceof DOMException)) return false;
   return ["NotAllowedError", "NotFoundError", "NotReadableError", "OverconstrainedError"].includes(error.name);

vite.config.ts

@@ -13,6 +13,7 @@ export default defineConfig(({ command }) => ({
           charts: ["recharts"],
           motion: ["framer-motion"],
           icons: ["lucide-react"],
+          barcode: ["@undecaf/barcode-detector-polyfill"],
         },
       },
     },