# How to Get Decoded Barcode Data from CodexBar: A Complete Guide

> Access decoded barcode data from CodexBar using the BarcodeScanner.decode method. This guide shows how to extract raw string data from QR codes with Apple's Vision framework.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-10

---

**The `BarcodeScanner.decode(image:)` method in [`Sources/CodexBar/BarcodeScanner.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/BarcodeScanner.swift) extracts the decoded barcode payload using Apple's Vision framework, returning the raw string data from any QR code generated by the steipete/CodexBar application.**

The steipete/CodexBar repository provides a macOS menu bar application that generates usage-summary QR codes. When you need to programmatically access the decoded barcode data from CodexBar, the app leverages the Vision framework's barcode detection capabilities to convert generated QR images back into readable JSON payloads or URLs.

## Understanding the Barcode Decoding Architecture

### The BarcodeScanner Swift Implementation

Located in [`Sources/CodexBar/BarcodeScanner.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/BarcodeScanner.swift), the **BarcodeScanner** class encapsulates the Vision framework logic. It creates a `VNImageRequestHandler` and executes a `VNDetectBarcodesRequest` limited to the QR symbology to process `NSImage` instances. The class provides a static `decode(image:)` method that accepts a completion handler, returning either the decoded string or an error through a `Result` type.

### Integration with CodexBarWidgetProvider

The **CodexBarWidgetProvider** class in [`Sources/CodexBarWidget/CodexBarWidgetProvider.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarWidget/CodexBarWidgetProvider.swift) orchestrates the user-facing workflow. It generates the QR code image via `encodeUsageAsQRCode` and handles the menu command that triggers the decoding process through `handleDecodedBarcode(_:)`. This provider bridges the UI layer with the underlying Vision-based decoding engine.

## How to Access Decoded Barcode Data from CodexBar

To retrieve the decoded barcode data programmatically, invoke the `decode(image:)` method with a valid `NSImage` containing a QR code.

```swift
import Cocoa
import Vision

// Example: Decoding a QR code image from CodexBar
let qrImage: NSImage = // Your QR code image from CodexBarWidgetProvider.encodeUsageAsQRCode()

BarcodeScanner.decode(image: qrImage) { result in
    switch result {
    case .success(let payload):
        // payload contains the decoded barcode data
        print("Decoded barcode payload:", payload)
        
        // Copy to clipboard example
        let pasteboard = NSPasteboard.general
        pasteboard.clearContents()
        pasteboard.setString(payload, forType: .string)
    case .failure(let error):
        print("Failed to decode barcode:", error.localizedDescription)
    }
}

```

## Step-by-Step Decoding Process

Breaking down the internal flow when accessing decoded data from CodexBar:

1. **Image Capture**: The `CodexBarWidgetProvider` creates an `NSImage` representation of the QR code using the usage data model from [`Sources/CodexBarCore/WidgetSnapshot.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/WidgetSnapshot.swift).

2. **Vision Request**: `BarcodeScanner.decode(image:)` initializes a `VNImageRequestHandler` with the captured image, processing it through the Vision framework.

3. **Barcode Detection**: The system executes a `VNDetectBarcodesRequest` configured specifically for QR symbology, returning a `VNBarcodeObservation` when a valid code is detected.

4. **Payload Extraction**: The scanner extracts `payloadStringValue` from the observation, which contains the decoded JSON or URL string originally encoded by the widget provider.

5. **Result Propagation**: The decoded string propagates to `handleDecodedBarcode(_:)` for clipboard copying or display in the CombinedBurnDownWidgetViews UI layer.

## Working with the Decoded Payload

The decoded barcode data typically contains usage statistics or configuration JSON. Once extracted via `payloadStringValue`, you can parse the string as structured data or interface with macOS system services.

Example of JSON parsing from decoded data:

```swift
BarcodeScanner.decode(image: qrImage) { result in
    switch result {
    case .success(let payload):
        // Parse JSON if the payload contains usage data
        if let data = payload.data(using: .utf8),
           let json = try? JSONDecoder().decode(WidgetSnapshot.self, from: data) {
            print("Usage data:", json)
        }
    case .failure(let error):
        print("Decoding failed:", error)
    }
}

```

## Summary

- The **BarcodeScanner** class in [`Sources/CodexBar/BarcodeScanner.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/BarcodeScanner.swift) provides the `decode(image:)` method for extracting barcode data using Vision framework APIs.
- Apple's **Vision framework** (`VNDetectBarcodesRequest`) powers the QR code recognition, specifically targeting `VNBarcodeObservation` objects.
- The **CodexBarWidgetProvider** in [`Sources/CodexBarWidget/CodexBarWidgetProvider.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarWidget/CodexBarWidgetProvider.swift) manages the UI flow and triggers decoding via menu commands.
- Decoded data is accessible through the `payloadStringValue` property of `VNBarcodeObservation`.
- Results can be programmatically copied to the clipboard using `NSPasteboard` or parsed as JSON using standard Swift `JSONDecoder`.

## Frequently Asked Questions

### Where is the barcode decoding logic implemented in CodexBar?

The decoding logic resides in [`Sources/CodexBar/BarcodeScanner.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/BarcodeScanner.swift), which uses Apple's Vision framework to perform `VNDetectBarcodesRequest` operations on QR code images generated by the widget provider. This file contains the static `decode(image:)` method that handles the Vision request handler setup and result processing.

### What format does the decoded barcode data return?

The `BarcodeScanner.decode(image:)` method returns a `String` containing the raw payload, typically JSON usage data or URLs, extracted from the `payloadStringValue` property of the Vision framework's `VNBarcodeObservation` object. The exact structure depends on what was originally encoded by `CodexBarWidgetProvider.encodeUsageAsQRCode()`.

### Can I use the CodexBar decoder for QR codes generated outside the app?

Yes, the `BarcodeScanner.decode(image:)` method accepts any `NSImage` containing a valid QR code, regardless of whether it was generated by `CodexBarWidgetProvider.encodeUsageAsQRCode()` or external sources, as long as it uses standard QR symbology recognized by the Vision framework's `VNDetectBarcodesRequest`.

### How do I trigger the decode functionality from the CodexBar menu?

Selecting "Decode Barcode" from the CodexBar menu invokes the `handleDecodedBarcode(_:)` method in [`Sources/CodexBarWidget/CodexBarWidgetProvider.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarWidget/CodexBarWidgetProvider.swift), which captures the current QR code image displayed in `CombinedBurnDownWidgetViews` and passes it to the `BarcodeScanner` for processing. The result is then displayed in a popup or copied to the system clipboard.