Native OCR & Barcode Utility
100% On-Device & Offline
Byakugan Scan Monogram
Byakugan Scan白眼 // All-Seeing Vision
SUPPORT CENTER & DOCUMENTATION // v1.0.4

Support & Frequently Asked Questions

Everything you need to configure permissions, master global shortcuts, customize the Byakugan reticle overlay, and troubleshoot on macOS 14+ Sonoma & Sequoia.

Getting StartedScreen Recording SetupKeyboard ShortcutsSupported SymbologiesFrequently Asked QuestionsTroubleshootingContact Support

1. Installation & Quick Start

Recommended • Homebrew Cask

Install via Terminal

Install and receive seamless updates directly from the official Homebrew tap. Automatically removes macOS quarantine attributes during installation.

brew install --cask halcyon-past/tap/byakugan-scan
Standalone • Universal Binary

Direct DMG Installer

Download ByakuganScan.dmg, drag Byakugan Scan.app into your /Applications folder, and launch it from Spotlight or Launchpad.

Download Latest DMG (v1.0.4)View Release Notes

2. Screen Recording Permission & Scan Modes

Granting macOS Screen Recording Permission

macOS requires explicit authorization before any utility can read pixels from your display. Byakugan Scan checks permission status silently via CGPreflightScreenCaptureAccess() so you never encounter recurring permission popup loops.

  1. Step 01
    Open System Settings

    Click the Apple () menu → System Settings → Privacy & Security.

  2. Step 02
    Select Screen Recording

    Scroll down to 'Screen & System Audio Recording' and click to open.

  3. Step 03
    Enable Byakugan Scan

    Find Byakugan Scan in the list and toggle the switch ON.

  4. Step 04
    Quit & Reopen

    Confirm 'Quit & Reopen' if prompted—your status in Settings → Appearance will turn green.

Instant Screen OCR

Press ⌘⇧2, drag the custom-tinted Byakugan reticle around any unselectable text in videos, PDFs, slides, or images, and release. Extracted text is copied straight to your clipboard and shown in a floating HUD pill.

QR Code Decoder

Press ⌘⇧3 and select any QR or MicroQR code on screen. URLs, emails, and phone numbers are automatically detected with one-click contextual actions in the menu bar popover.

Multi-Symbology Barcode

Press ⌘⇧4 to decode retail and industrial barcodes (EAN, UPC, Code 128, PDF417, Aztec, Data Matrix), complete with automatic symbology classification tags.

3. Global Keyboard Shortcuts

ActionDefault ShortcutScopeDescription
Capture Text (OCR)
⌘⇧2
DefaultInteractive screen region selection for instant on-device Vision OCR.
Scan QR Code
⌘⇧3
DefaultDecode URLs, Wi-Fi credentials, vCards, and 2D QR payloads on screen.
Scan Barcode
⌘⇧4
DefaultRecognize EAN-13, UPC-E, Code 128, PDF417, Aztec, Data Matrix, and more.
Cancel Selection
Esc
SystemDismiss the active Byakugan reticle overlay without modifying the clipboard.
Open Settings
⌘,
Menu BarConfigure shortcuts, OCR languages, formatting, and reticle accent colors.

4. Supported Barcode & 2D Symbologies

2D Matrix
QR Code & MicroQR

URLs, authentication, Wi-Fi, vCards, payment links

2D Compact
Aztec Code

Airline boarding passes, rail & transit tickets

2D Stacked
PDF417 & MicroPDF417

Driver licenses, ID cards, shipping manifests

2D Industrial
Data Matrix

Electronics components, medical & pharmaceutical labels

1D Retail
EAN-13 / EAN-8

International retail products, ISBN book codes

1D Retail
UPC-E

Compact North American retail product packaging

1D Logistics
Code 128 / Code 39 / Code 93

Supply chain, asset tracking, warehouse inventory

1D Packaging
ITF-14 / Interleaved 2 of 5

Corrugated freight cartons and outer cases

5. Frequently Asked Questions

Installation & UpdatesHow do I install or update Byakugan Scan on macOS?
You can install Byakugan Scan via Homebrew (`brew install --cask halcyon-past/tap/byakugan-scan`) or by downloading the universal `.dmg` installer directly from our website or GitHub Releases. To update via Homebrew, run `brew upgrade --cask byakugan-scan`.
Privacy & SecurityDoes Byakugan Scan ever upload my screenshots or text to the cloud?
Never. Byakugan Scan operates 100% offline and on-device using Apple's native Vision framework (`VNRecognizeTextRequest` and `VNDetectBarcodesRequest`). The app has zero network entitlements, zero analytics SDKs, and zero telemetry.
PerformanceWhy does Byakugan Scan feel so much faster than other screenshot OCR tools?
Traditional screen capture utilities write temporary `.png` files to `/tmp` on disk, which triggers macOS Spotlight (`mdwrite`) indexing and `MADService` media analysis stalls. Byakugan Scan captures your selected region directly into volatile RAM (`NSPasteboard`) and feeds the `CGImage` buffer straight into the Apple Neural Engine in under 50 milliseconds.
PermissionsWhy does Byakugan Scan require macOS Screen Recording permission?
macOS protects screen pixels under the Screen Recording privacy gate. Byakugan Scan only captures the exact rectangular coordinates you drag-select when you invoke a scan — it never records your screen in the background. It also uses `CGPreflightScreenCaptureAccess()` for silent permission checks so you are never spammed by system dialogs.
PermissionsWhat should I do if Screen Recording permission is already toggled ON, but macOS still says permission is required?
If you rebuilt or replaced the app binary manually, macOS TCC may hold a stale signature entry. Open System Settings → Privacy & Security → Screen Recording, select Byakugan Scan, click the minus (–) button to remove it, and then re-add `/Applications/Byakugan Scan.app` (or run `tccutil reset ScreenCapture cloud.aritro.byakugan-scan` in Terminal) and relaunch.
CustomizationHow do I change the selection box color and backdrop dimming opacity?
Click the Byakugan eye icon in your macOS menu bar → Settings (⌘,) → Appearance. Choose from 5 signature accents (Byakugan Violet, Tenseigan Cyan, Sharingan Crimson, Sage Emerald, or Nine-Tails Amber) and adjust the Overlay Dimming slider. You can preview the reticle live or click 'Test Capture Overlay' right from Settings.
CustomizationCan I customize the global keyboard shortcuts?
Yes! Open Settings (⌘,) → Shortcuts, click 'Record Shortcut' next to Capture Text, Scan QR Code, or Scan Barcode, and press any modifier combination (⌘, ⇧, ⌥, ⌃) plus a key. Press Escape while recording to cancel, or click the clear (×) button to unbind a shortcut.
OCR & FormattingWhich languages are supported for Text OCR, and how does line-break formatting work?
Byakugan Scan supports automatic language detection plus 13+ primary languages including English (US/UK), Japanese, Chinese (Simplified & Traditional), Korean, French, German, Spanish, Italian, Portuguese, Arabic, and Hindi. In Settings → OCR, you can toggle 'Trim Whitespace', 'Preserve Line Breaks', or 'Join Lines with Space' to copy multi-line paragraphs as clean single-line prose.
HistoryWhere is my scan history stored, and how can I pin or clear items?
When enabled, scan history is saved locally in `~/Library/Application Support/ByakuganScan/history.json`. Open the menu bar popover and switch to the History tab to search past scans, filter by Text / QR / Barcode / Starred, star important clips, or delete entries. You can disable or clear history at any time from Settings → General.

6. Quick Troubleshooting Checklist

OCR ACCURACY

Scan returns "No text detected"

  • Verify Screen Recording is Granted in Settings → Appearance.
  • Ensure Accuracy is set to Accurate in Settings → OCR.
  • Leave a small margin around the text when dragging the selection reticle.
  • DRM-protected video streams (e.g., Apple TV+ / Netflix in Safari) blank out screen capture buffers at the OS level.
PERMISSION RESET

Resetting Stale macOS TCC State

If macOS Privacy Settings shows Byakugan Scan enabled but captures still prompt for permission, reset the TCC entry in Terminal:

tccutil reset ScreenCapture cloud.aritro.byakugan-scan
GATEKEEPER & FIRST LAUNCH

Opening Unsigned / Local Builds

If you downloaded the DMG directly from a browser and macOS Gatekeeper warns about an unverified developer, clear the quarantine flag:

xattr -cr "/Applications/Byakugan Scan.app"

7. How Byakugan Scan Compares to Other macOS OCR Tools

FeatureByakugan ScanTextSnipermacOS Live Text
Price & License100% Free & Open Source (MIT)Paid (Proprietary)Built-in to macOS
Capture ArchitectureIn-RAM Pasteboard Buffer (Zero Disk I/O)In-MemoryRequires Screenshot / Preview file
QR & 13+ Industrial BarcodesYes (QR, Aztec, PDF417, Data Matrix, EAN, Code 128)QR & standard barcodesQR in Safari/Preview only
Custom Reticle Colors & Opacity5 Theme Accents + Opacity SliderDefault macOS Grey BoxDefault macOS Grey Box
Searchable Scan History & PinningBuilt-in (Local JSON + Category Filters)Additive clipboard onlyNone
Network Calls / TelemetryZero (100% Offline)License verificationSystem level
Direct Engineering Support

Still running into an issue or have a feature request?

Include your macOS version and Byakugan Scan version (v1.0.4). We respond to all support emails and GitHub issues within 2 business days.

Email SupportOpen GitHub IssuePrivacy Policy →