| Name | snap-ocr JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | Background tray utility that screenshots and OCRs in one hotkey press. |
| upload_time | 2025-10-20 12:39:29 |
| maintainer | None |
| docs_url | None |
| author | Brandon Johnson |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 James Brandon Johns
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.
|
| keywords |
screenshot
ocr
tray
productivity
macos
windows
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
mss
pynput
Pillow
pytesseract
PyYAML
platformdirs
pystray
plyer
typing-extensions
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Snap OCR
Snap OCR is a cross-platform tray utility that grabs a screenshot in the background, runs Tesseract OCR, and saves both PNG and TXT outputs. The app stays out of the way: press the global hotkey, capture happens, and you keep working.
For a fully detailed reference (including troubleshooting matrices) see `src/snap_ocr/__main__.py`. The highlights below cover the essentials.
## Features
- Global hotkey capture using `pynput` (default `<ctrl>+<shift>+s`, configurable).
- Full screen, fixed region, Windows FancyZones, or macOS MacsyZones capture modes.
- Timestamped filenames with optional overwrite mode that keeps only the most recent capture.
- Background OCR via `pytesseract`, atomic writes, and user-configurable save locations.
- Smart pre-processing (grayscale + contrast boost) for sharper OCR results on dense exam layouts.
- Tray controls for quick actions (Take Screenshot, Toggle Overwrite, open folders, reload config, view logs, quit).
- Zero network access; outputs and logs stay on your machine.
## Release Highlights
### v0.3.0
- Fixed MacsyZones capture so repositioned layouts map 1:1 with on-screen zones.
- Improved OCR fidelity by pre-processing captures and normalizing multi-choice labels (no more duplicated letters).
- Added version metadata and refreshed install instructions for packaged and PyPI deployments.
## Prerequisites
- Python 3.10 or newer.
- Tesseract OCR installed and on your `PATH`, or set `tesseract_cmd` in the config file.
- macOS users must grant Screen Recording + Accessibility rights; Windows users just need Tesseract.
## Installation
### pipx (recommended)
1. Download or clone this repository.
2. In the project root run:
```bash
pipx install .
```
3. Launch with `snap-ocr` (no terminal needs to remain open; the app continues from the tray).
`pipx` isolates the app in its own virtual environment and drops a `snap-ocr` command on your `PATH`. On Windows the shim is placed in `%USERPROFILE%\.local\bin`.
### From a virtual environment
```bash
python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
python -m pip install -r requirements.txt
python -m pip install -e .
python -m snap_ocr
```
To run a one-off capture without starting the tray: `snap-ocr --capture-once`.
## Usage Overview
- **Start the tray app:** `snap-ocr`
- **Global hotkey:** `<ctrl>+<shift>+s` (customize via `config.yaml`).
- **CLI helpers:**
- `snap-ocr --capture-once` – Immediate capture then exit.
- `snap-ocr --show-config-path` – Print the active config file path.
- `snap-ocr --open-config` – Open the config in your default editor/finder.
The tray icon exposes menu items for the capture mode, overwrite toggle, reloading the config, opening output directories, viewing logs, and quitting.
## Configuration
The first launch writes `config.yaml` to the OS-specific config directory (`~/Library/Application Support/snap-ocr/config.yaml` on macOS, `%APPDATA%\snap-ocr\config.yaml` on Windows).
Key fields:
| Setting | Description |
| --- | --- |
| `hotkey` | `pynput` syntax string for the global hotkey (`"<option>+<shift>+s"`, etc.). |
| `save_dir_images`, `save_dir_text` | Output folders for PNG and text files. |
| `filename_pattern` | Naming template; supports `{base}` and `{timestamp}` placeholders. |
| `overwrite_mode` | If `true`, the previous capture files are deleted after each successful save. |
| `capture_mode` | One of `full`, `region`, `fancyzones`, or `macsyzones`. |
| `region` | Coordinates used when `capture_mode: region`. |
| `macsyzones_*` / `fancyzones_*` | Options for their respective zone integrations. |
Validation errors surface immediately with the file path and a suggested fix. After editing, choose **Reload Config** from the tray or restart the app.
## Platform Notes
### macOS
- Grant Screen Recording + Accessibility (and Input Monitoring if prompted) to the Python host or packaged app.
- Optional auto-start: place a `LaunchAgent` pointing to your `pipx` interpreter, then `launchctl load` it.
- **MacsyZones**: Snap OCR reads layouts from `~/Library/Application Support/MeowingCat.MacsyZones/UserLayouts.json`, honoring the zone numbers shown in the MacsyZones editor (1 = top-left, 2 = bottom-left, 3 = top-right, 4 = bottom-right). Captures are taken in raw pixels, so on Retina displays the saved PNG dimensions are 2× the values displayed in MacsyZones; the crop area is identical.
### Windows
- Installing Tesseract (UB Mannheim build recommended) is the only prerequisite; no special capture permissions are required.
- FancyZones mode reads Windows PowerToys configuration to align screenshots with zone layouts.
- You can pin `snap-ocr.exe` (from `%USERPROFILE%\.local\bin`) to the Start menu or drop a shortcut in `shell:startup` for launch-at-login.
## Packaging (macOS)
1. `pipx install pyinstaller` (or `python -m pip install pyinstaller`).
2. Run `scripts/build_mac_app.sh` to generate `dist/Snap OCR.app` (automatically converts the icon to `.icns`).
3. Update `scripts/sign_and_notarize.sh` with your Developer ID and notarytool profile, then execute it to sign/notarize/staple the bundle.
4. Launch the notarised app once to trigger the permission prompts.
## Troubleshooting Quick Hits
- **Hotkey doesn’t fire (macOS):** reopen System Settings → Privacy & Security to confirm Accessibility permission.
- **Black screenshots (macOS):** Screen Recording access missing or revoked.
- **No text output:** verify Tesseract path/language packs and that the captured region contains legible text.
- **Audible “bonk” sound on hotkey:** change `hotkey` to avoid combinations that the focused app doesn’t recognize.
- **Files not overwritten:** confirm `overwrite_mode: true`; the tool deletes the previous PNG/TXT pair immediately before writing the next capture.
---
If you plan to distribute Snap OCR, consider publishing to PyPI so others can install with `pip install snap-ocr`. Until then, installing from this repository via `pipx install .` remains the quickest path.
Raw data
{
"_id": null,
"home_page": null,
"name": "snap-ocr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "screenshot, ocr, tray, productivity, macos, windows",
"author": "Brandon Johnson",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4a/e7/e46fd5d0a4615ca530ada8f141e84d3903771219d4fddceb6ce8bc8b5da8/snap_ocr-0.3.0.tar.gz",
"platform": null,
"description": "# Snap OCR\n\nSnap OCR is a cross-platform tray utility that grabs a screenshot in the background, runs Tesseract OCR, and saves both PNG and TXT outputs. The app stays out of the way: press the global hotkey, capture happens, and you keep working.\n\nFor a fully detailed reference (including troubleshooting matrices) see `src/snap_ocr/__main__.py`. The highlights below cover the essentials.\n\n## Features\n\n- Global hotkey capture using `pynput` (default `<ctrl>+<shift>+s`, configurable).\n- Full screen, fixed region, Windows FancyZones, or macOS MacsyZones capture modes.\n- Timestamped filenames with optional overwrite mode that keeps only the most recent capture.\n- Background OCR via `pytesseract`, atomic writes, and user-configurable save locations.\n- Smart pre-processing (grayscale + contrast boost) for sharper OCR results on dense exam layouts.\n- Tray controls for quick actions (Take Screenshot, Toggle Overwrite, open folders, reload config, view logs, quit).\n- Zero network access; outputs and logs stay on your machine.\n\n## Release Highlights\n\n### v0.3.0\n\n- Fixed MacsyZones capture so repositioned layouts map 1:1 with on-screen zones.\n- Improved OCR fidelity by pre-processing captures and normalizing multi-choice labels (no more duplicated letters).\n- Added version metadata and refreshed install instructions for packaged and PyPI deployments.\n\n## Prerequisites\n\n- Python 3.10 or newer.\n- Tesseract OCR installed and on your `PATH`, or set `tesseract_cmd` in the config file.\n- macOS users must grant Screen Recording + Accessibility rights; Windows users just need Tesseract.\n\n## Installation\n\n### pipx (recommended)\n\n1. Download or clone this repository.\n2. In the project root run:\n ```bash\n pipx install .\n ```\n3. Launch with `snap-ocr` (no terminal needs to remain open; the app continues from the tray).\n\n`pipx` isolates the app in its own virtual environment and drops a `snap-ocr` command on your `PATH`. On Windows the shim is placed in `%USERPROFILE%\\.local\\bin`.\n\n### From a virtual environment\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate # or .venv\\Scripts\\activate on Windows\npython -m pip install -r requirements.txt\npython -m pip install -e .\npython -m snap_ocr\n```\n\nTo run a one-off capture without starting the tray: `snap-ocr --capture-once`.\n\n## Usage Overview\n\n- **Start the tray app:** `snap-ocr`\n- **Global hotkey:** `<ctrl>+<shift>+s` (customize via `config.yaml`).\n- **CLI helpers:**\n - `snap-ocr --capture-once` \u2013 Immediate capture then exit.\n - `snap-ocr --show-config-path` \u2013 Print the active config file path.\n - `snap-ocr --open-config` \u2013 Open the config in your default editor/finder.\n\nThe tray icon exposes menu items for the capture mode, overwrite toggle, reloading the config, opening output directories, viewing logs, and quitting.\n\n## Configuration\n\nThe first launch writes `config.yaml` to the OS-specific config directory (`~/Library/Application Support/snap-ocr/config.yaml` on macOS, `%APPDATA%\\snap-ocr\\config.yaml` on Windows).\n\nKey fields:\n\n| Setting | Description |\n| --- | --- |\n| `hotkey` | `pynput` syntax string for the global hotkey (`\"<option>+<shift>+s\"`, etc.). |\n| `save_dir_images`, `save_dir_text` | Output folders for PNG and text files. |\n| `filename_pattern` | Naming template; supports `{base}` and `{timestamp}` placeholders. |\n| `overwrite_mode` | If `true`, the previous capture files are deleted after each successful save. |\n| `capture_mode` | One of `full`, `region`, `fancyzones`, or `macsyzones`. |\n| `region` | Coordinates used when `capture_mode: region`. |\n| `macsyzones_*` / `fancyzones_*` | Options for their respective zone integrations. |\n\nValidation errors surface immediately with the file path and a suggested fix. After editing, choose **Reload Config** from the tray or restart the app.\n\n## Platform Notes\n\n### macOS\n\n- Grant Screen Recording + Accessibility (and Input Monitoring if prompted) to the Python host or packaged app.\n- Optional auto-start: place a `LaunchAgent` pointing to your `pipx` interpreter, then `launchctl load` it.\n- **MacsyZones**: Snap OCR reads layouts from `~/Library/Application Support/MeowingCat.MacsyZones/UserLayouts.json`, honoring the zone numbers shown in the MacsyZones editor (1\u202f=\u202ftop-left, 2\u202f=\u202fbottom-left, 3\u202f=\u202ftop-right, 4\u202f=\u202fbottom-right). Captures are taken in raw pixels, so on Retina displays the saved PNG dimensions are 2\u00d7 the values displayed in MacsyZones; the crop area is identical.\n\n### Windows\n\n- Installing Tesseract (UB Mannheim build recommended) is the only prerequisite; no special capture permissions are required.\n- FancyZones mode reads Windows PowerToys configuration to align screenshots with zone layouts.\n- You can pin `snap-ocr.exe` (from `%USERPROFILE%\\.local\\bin`) to the Start menu or drop a shortcut in `shell:startup` for launch-at-login.\n\n## Packaging (macOS)\n\n1. `pipx install pyinstaller` (or `python -m pip install pyinstaller`).\n2. Run `scripts/build_mac_app.sh` to generate `dist/Snap OCR.app` (automatically converts the icon to `.icns`).\n3. Update `scripts/sign_and_notarize.sh` with your Developer ID and notarytool profile, then execute it to sign/notarize/staple the bundle.\n4. Launch the notarised app once to trigger the permission prompts.\n\n## Troubleshooting Quick Hits\n\n- **Hotkey doesn\u2019t fire (macOS):** reopen System Settings \u2192 Privacy & Security to confirm Accessibility permission.\n- **Black screenshots (macOS):** Screen Recording access missing or revoked.\n- **No text output:** verify Tesseract path/language packs and that the captured region contains legible text.\n- **Audible \u201cbonk\u201d sound on hotkey:** change `hotkey` to avoid combinations that the focused app doesn\u2019t recognize.\n- **Files not overwritten:** confirm `overwrite_mode: true`; the tool deletes the previous PNG/TXT pair immediately before writing the next capture.\n\n---\n\nIf you plan to distribute Snap OCR, consider publishing to PyPI so others can install with `pip install snap-ocr`. Until then, installing from this repository via `pipx install .` remains the quickest path.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 James Brandon Johns\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Background tray utility that screenshots and OCRs in one hotkey press.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/jbj0005/snap-ocr",
"Issues": "https://github.com/jbj0005/snap-ocr/issues",
"Repository": "https://github.com/jbj0005/snap-ocr"
},
"split_keywords": [
"screenshot",
" ocr",
" tray",
" productivity",
" macos",
" windows"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "844a7a085cac33be186ce128e85429d33943d842b6120d0120040f4abfe9239e",
"md5": "fcac5089d27e04efa5a032fe2da011a2",
"sha256": "7b10b4fe635aac851b3b30de3b9ac97abff3dbc43f7a0d69de0275916f83eb70"
},
"downloads": -1,
"filename": "snap_ocr-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fcac5089d27e04efa5a032fe2da011a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 59516,
"upload_time": "2025-10-20T12:39:28",
"upload_time_iso_8601": "2025-10-20T12:39:28.499575Z",
"url": "https://files.pythonhosted.org/packages/84/4a/7a085cac33be186ce128e85429d33943d842b6120d0120040f4abfe9239e/snap_ocr-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4ae7e46fd5d0a4615ca530ada8f141e84d3903771219d4fddceb6ce8bc8b5da8",
"md5": "203b916a6299d7e924464da818060178",
"sha256": "b3864de43d621988e7b8d1bb3c3a9d5a7888371c5a09dbf36a6074dcb1a623ad"
},
"downloads": -1,
"filename": "snap_ocr-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "203b916a6299d7e924464da818060178",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 61207,
"upload_time": "2025-10-20T12:39:29",
"upload_time_iso_8601": "2025-10-20T12:39:29.660056Z",
"url": "https://files.pythonhosted.org/packages/4a/e7/e46fd5d0a4615ca530ada8f141e84d3903771219d4fddceb6ce8bc8b5da8/snap_ocr-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 12:39:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jbj0005",
"github_project": "snap-ocr",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mss",
"specs": [
[
"==",
"9.0.1"
]
]
},
{
"name": "pynput",
"specs": [
[
"==",
"1.7.6"
]
]
},
{
"name": "Pillow",
"specs": [
[
"==",
"10.4.0"
]
]
},
{
"name": "pytesseract",
"specs": [
[
"==",
"0.3.10"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.2.2"
]
]
},
{
"name": "pystray",
"specs": [
[
"==",
"0.19.5"
]
]
},
{
"name": "plyer",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.12.2"
]
]
}
],
"lcname": "snap-ocr"
}
