Screeny

A lightweight macOS menu bar screenshot utility with global hotkeys, preview window, and clipboard support.

Features

• Full Screen Capture: Press Cmd+Shift+1 to capture the entire screen
• Region Capture: Press Cmd+Shift+2 to select and capture a region
• Preview Window: Review screenshots before saving or copying
• Clipboard Support: Copy screenshots directly to clipboard
• Menu Bar App: Quick access to all features from the menu bar
• Configurable: Choose save location and image format (PNG/JPEG)
• Native macOS: Uses native macOS APIs for best performance

Requirements

• macOS 12 (Monterey) or later
• Python 3.11+
• Xcode Command Line Tools (for building)

Permissions Required

• Screen Recording: Required to capture screenshots
• Accessibility: Required for global hotkeys to work

Quick Start

Download Pre-built App

Download the latest Screeny.app from the Releases page, move it to your Applications folder, and double-click to run.

Build from Source

# Clone the repository
git clone https://github.com/yourusername/screeny.git
cd screeny

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run directly
pip install -e .
screeny

Building the Standalone App (.app Bundle)

Prerequisites

1. Python 3.11+ - Install via Homebrew or python.org

   brew install python@3.11

2. Create a virtual environment (recommended)

   python3.11 -m venv venv
   source venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt
   pip install -r requirements-dev.txt
   pip install pyinstaller

Build with PyInstaller

1. Build the app:

   pyinstaller Screeny.spec --clean -y

2. The app will be created at:

   dist/Screeny.app
   

3. Install the app:

   # Copy to Applications folder
   cp -r dist/Screeny.app /Applications/
   
   # Or open directly
   open dist/Screeny.app

Build Options

The Screeny.spec file contains all build configuration. Key settings:

• LSUIElement: True - App runs in menu bar only (no Dock icon)
• NSScreenCaptureUsageDescription - Permission description for Screen Recording
• Hidden imports for PyObjC frameworks (AppKit, Foundation, Quartz)

Troubleshooting Build Issues

Import errors when running the built app:

# Run from terminal to see error messages
dist/Screeny.app/Contents/MacOS/Screeny

Missing modules: Add missing modules to hiddenimports in Screeny.spec and rebuild.

Code signing issues:

# Sign the app (optional, for distribution)
codesign --force --deep --sign - dist/Screeny.app

Usage

Keyboard Shortcuts

Shortcut	Action
Cmd+Shift+1	Capture full screen
Cmd+Shift+2	Capture selected region

Preview Window Shortcuts

Shortcut	Action
Enter or click Save	Save screenshot
Click Copy	Copy to clipboard
Escape	Discard screenshot

Menu Bar

Click the Screeny icon in the menu bar to:

• Take screenshots manually
• Change save location
• Switch between PNG and JPEG formats
• Quit the application

Configuration

Settings are stored at:

~/Library/Application Support/Screeny/config.json

Default Settings

Setting	Default Value
Save Location	~/Desktop
Format	PNG
JPEG Quality	90
Filename Pattern	Screeny_{YYYY}-{MM}-{DD}_{HH}-{mm}-{ss}
Full Screen Hotkey	Cmd+Shift+1
Region Hotkey	Cmd+Shift+2

Granting Permissions

Screen Recording Permission

1. Open System Settings → Privacy & Security → Screen Recording
2. Click the + button and add Screeny.app
3. Toggle the switch to enable
4. Restart Screeny if prompted

Accessibility Permission

1. Open System Settings → Privacy & Security → Accessibility
2. Click the + button and add Screeny.app
3. Toggle the switch to enable
4. Restart Screeny if prompted

Note: If running from source with screeny command, you may need to grant permissions to your Terminal app instead.

Auto-Start on Login

To have Screeny start automatically when you log in:

1. Open System Settings → General → Login Items
2. Under "Open at Login", click +
3. Navigate to and select Screeny.app

Troubleshooting

Hotkeys not working

1. Check that Accessibility permission is granted to Screeny
2. Restart Screeny after granting permission
3. Make sure another app isn't using the same hotkey combination

Screenshots are blank or black

1. Check that Screen Recording permission is granted
2. Restart Screeny after granting permission
3. On first capture, macOS may prompt for permission

App doesn't appear in menu bar

1. Try running from terminal to see any error messages:

   /Applications/Screeny.app/Contents/MacOS/Screeny

2. Check Console.app for crash logs

Can't copy to clipboard

1. Some apps may not accept certain image formats
2. Try saving the screenshot and opening it manually

Save location errors

1. Ensure the save directory exists and is writable
2. Check disk space if getting "disk full" errors
3. Screeny will fall back to Desktop if the configured location is invalid

Development

Project Structure

screeny/
├── src/screeny/
│   ├── __init__.py         # Package version and exports
│   ├── main.py             # Entry point
│   ├── app.py              # Main application coordinator
│   ├── menu_bar.py         # Menu bar UI (rumps)
│   ├── hotkeys.py          # Global hotkey listener (pynput)
│   ├── capture.py          # Screenshot capture logic
│   ├── preview.py          # Preview window (PyObjC)
│   ├── settings.py         # Settings management
│   ├── notifications.py    # macOS notifications
│   ├── permissions.py      # Permission checking
│   └── resources/
│       ├── icon.png            # Original icon
│       └── iconTemplate.png    # Menu bar template icon
├── tests/                  # Test suite
├── Screeny.spec           # PyInstaller build configuration
├── pyproject.toml         # Project metadata
├── requirements.txt       # Runtime dependencies
└── requirements-dev.txt   # Development dependencies

Setting Up Development Environment

# Clone repository
git clone https://github.com/yourusername/screeny.git
cd screeny

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate

# Install in editable mode with dev dependencies
pip install -e .
pip install -r requirements-dev.txt

# Run the app
screeny

Running Tests

pytest

Linting

ruff check .

Type Checking

mypy src/screeny

Dependencies

Runtime Dependencies

Package	Purpose
rumps	Menu bar app framework
pynput	Global hotkey listener
Pillow	Image processing
pyobjc-framework-Cocoa	macOS Cocoa APIs
pyobjc-framework-Quartz	Screen capture APIs

Build Dependencies

Package	Purpose
pyinstaller	Create standalone .app bundle

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

• rumps - Ridiculously Uncomplicated macOS Python Statusbar apps
• pynput - Python library to monitor and control input devices
• PyObjC - Python to Objective-C bridge