Metadata-Version: 2.4
Name: wm-screenshooter
Version: 1.0.8
Summary: A sophisticated cross-platform screenshot tool with timer support and organization features
Project-URL: Homepage, https://gitlab.com/workmaster/screenshooter
Author: Conor Ryan
License: # MIT License
        
        Copyright (c) 2025 Conor Ryan
        
        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.
License-File: LICENCE.md
Keywords: cli,client management,cloudflare kv,email delivery,project management,report generation,s3 storage,screenshooter,screenshot,time tracking
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: <3.15,>=3.10
Requires-Dist: boto3>=1.29.2
Requires-Dist: click>=8.1.3
Requires-Dist: mss>=9.0.0
Requires-Dist: packaging>=21.0
Requires-Dist: pathlib>=1.0.1
Requires-Dist: pillow>=10.1.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pyzipper>=0.3.6
Requires-Dist: reportlab>=4.0.9
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.7.0
Provides-Extra: snippet-gui
Requires-Dist: pyside6-essentials>=6.7.0; extra == 'snippet-gui'
Description-Content-Type: text/markdown

# WorkMaster ScreenShooter

Screenshooter is a sophisticated cross-platform screenshot TUI application with timer support and organisation features. This modular Python application helps freelancers document their work with automatic (or manual) screenshots and pairs this with contemporaneous notes and the ability to create and email a PDF report to their clients.

## Why?

"As a freelance developer I love to code and help solve my clients' problems. Much of my work is hourly requiring me to keep accurate logs and notes. I created ScreenShooter to keep track of sessions, projects and notes for clients allowing me to focus on the fun parts of coding and not the admin."

- [Conor Ryan - ScreenShooter Creator](https://www.conorjwryan.com)

**Note:** ScreenShooter supports macOS (Linux and Windows are supported but are under beta testing).

## Features

- Application lives in your terminal and can be left in the background tracking time while you focus on work
- Screenshot capture can be done automatically at regular intervals or manually when the user requests them.
- Flexibility in screenshot capture all displays, specific display or a dedicated window.
- Produce captions (which appear under given screenshots) or notes for communicating ideas to clients
- Ability to pause / resume when doing sensitive work
- Session based reporting system allows for flexibility and time management
- Built in client management features for sending reports and archiving finished projects
- Ability to generate and send reports to client after every session, day or when needed
- Upload reports to S3 bucket and generate link for clients to view
- Optional CLI for quicker session start
- Backup functionality to backup settings, database, and screenshots directory

## Requirements

- Python 3.10 - 3.14
- macOS, Linux, or Windows
- For snippet drag-selection (`w` command):
  - `PySide6-Essentials` is optional and only required for GUI drag-selection.
- For desktop notifications (optional):
  - macOS: `terminal-notifier` (`brew install terminal-notifier`)
  - Linux: `notify-send` (usually pre-installed)
  - Windows: PowerShell (built-in)
- Email sending system (e.g. Brevo, SendGrid, Mailgun, etc.)
- S3 bucket (for remote report storage to make it easier to send reports to clients)
- Cloudflare KV (for custom link generation to make it easier to send reports to clients) (optional)

## Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install wm-screenshooter
screenshooter --version
```

To enable GUI snippet drag-selection (`w`) on top of the base install:

```bash
pip install "wm-screenshooter[snippet-gui]"
```

### Option 2: Install from source (using uv)

1. Clone the repository and install the application using `uv`:

   ```bash
   git clone https://gitlab.com/workmaster/screenshooter.git
   cd screenshooter
   uv tool install .
   screenshooter --version
   ```

2. (Optional) enable GUI snippet drag-selection dependency:

   ```bash
   uv sync --extra snippet-gui
   ```

### (Optional) Install notification support

Notification support is optional and will be disabled if not installed.

**macOS:**

```bash
brew install terminal-notifier # macOS
```

**Linux:** (Debian/Ubuntu)

```bash
sudo apt install libnotify-bin  # Debian/Ubuntu
```

**Windows:**

Not required as already built in.

## Usage

Screenshooter can be used either via the command-line interface or via the interactive menu. Until you have created a client and project, you will need to use the interactive menu to set up your project and client.

### Interactive Menu (first time use)

Below is the general flow for performing some of the common actions in the ScreenShooter program. Below will

#### How to take screenshots

TLDR; Skip to step 3 if you have already created a client and project.

1. On the main ScreenShooter screen press option 1.

2. As this is your first time using the application you will be prompted to create a client and a project. Do the following:

    - Enter the name of your client (no spaces) - eg: "Testing"
    - Press n for no to create a custom directory name for your client
    - Enter the Company Name - eg: "Testing Ltd"
    - Contact Name - eg: "John Doe"
    - Contact Email - eg: "<john.doe@testing.com>"
    - Screenshot delivery method [local/email/cloud] (enter):
    - Notification preferences [all/important/none] (enter):
    - Reporting frequency [daily/weekly/monthly/none] (enter):
    - PDF security [none/password] (enter):
    - PDF page size [A4/letter] (enter):
    - Press enter to save the client information

3. You will now be asked to create a project. Do the following:

    - Enter the name of your project (no spaces) - eg: "BigProject"

4. (Start of Session)

    - Choose the display mode you want to use (press enter to use all):
    - Enter the timer duration in minutes - eg: 15
    - Type a note to start the session - eg: "Started working on BigProject"
    - Press enter to start the session

    A Countdown will start to take the first screenshot. (10 seconds).

    - The session is now running, the timer is counting down to the next screenshot.

    - Refer to the in-session commands below on how to interact with the session.

    - When you are finished with the session you can press 'q' to quit and take a final screenshot.

#### In-session commands

```bash
'n' - to add a note to the log
'c' - to add a caption to the last screenshot
's' - to take a manual screenshot now and reset timer
'o' - to open the last screenshot in Preview
'q' - to quit and take final screenshot
't' - to change the timer duration
'd' - to change the display mode
'p' - to pause the session for sensitive activities
'm' - to switch to manual mode (no timer)
'r' - to archive the last action (screenshot or note)
'e' - to list the last 5 actions
'l' - to open the current session log in TextEdit
'i' - to show time in session, today, and project total
'h' - for help
'z' - to cancel active countdowns 
```

### CLI Command Structure

ScreenShooter uses a command-line interface with nested commands:

```bash
screenshooter                                   # Interactive menu
screenshooter client                            # List all clients
screenshooter client "ClientName"               # Manage specific client
screenshooter client "ClientName" projects      # List projects
screenshooter shoot --client "Name" --project "Project" [options]
screenshooter report                            # Interactive report generator
screenshooter report generate --client "Name" --project "Project"
screenshooter open logs|config                  # Open logs or config directories
screenshooter settings                          # Manage settings
screenshooter backup <settings|db|all> [--outputdir PATH]  # Create backups
screenshooter help                              # Show help information
```

For more information on the commands and options available, run `screenshooter command --help` for more information.

## Directory Structure and Screenshot Storage

Screenshots are organized in the following structure:

```tree
~/WorkMaster_Screenshooter/
└── CLIENT_NAME/
    ├── client.json     # Client information and preferences
    └── PROJECT_NAME/
        ├── project.json
        ├── PROJECT_NAME_log.txt
        ├── reports/
        │   └── PROJECT_NAME_Report_YYYYMMDD_HHMMSS.pdf
        └── sessions/
            └── YYYY-MM-DD_HH-MM-SS/
                ├── session.log
                ├── session.json
                └── screenshots/
                    └── PROJECT_NAME_YYYY-MM-DD_HH-MM-SS_*.jpg
```

Above is the general structure of the application.

## Notes

### Email Support and Remote Report Storage

If you want to send the screenshot reports to your client via email this requires you to set use a bulk email sending system. ScreenShooter supports this via the `email` setting in the settings menu.

`Brevo` is recommended as it has a generous free tier and is easy to set up. The one catch with these bulk email senders is that they often don't allow for large attachments. This is why ScreenShooter allows you to upload the report to an S3 bucket and then generate a link to the report.

You can set up an S3 bucket and configure ScreenShooter to use it via the `s3` setting in the settings menu. The S3 bucket will be used to store the screenshot reports and the link to the report will be generated and sent to your client via email.

### Updates

Updates to ScreenShooter are checked for automatically at startup (cached for 7 days) or can be checked manually with `screenshooter settings upgrade-check`.

You can also skip or pin specific versions of ScreenShooter to prevent notifications for these or future versions.

```bash
screenshooter settings upgrade-check # Check for updates
screenshooter settings skip-upgrade <version> # Skip notifications for a specific version
screenshooter settings pin-version <version> # Pin to a specific version
```

The upgrade itself is not automatically installed and requires you to manually download the latest version and install it.

If installing from PyPI:

```bash
pip install --upgrade wm-screenshooter
screenshooter --version
```

If installing from GitLab you can use the following command to install the latest version:

```bash
git pull
uv tool install .
screenshooter --version
```

## Who Made This?

ScreenShooter is being developed by [@conorjwryan](https://gitlab.com/conorjwryan) as a part of the [WorkMaster](https://workmaster.app) project. WorkMaster is a platform for freelancers to manage their work and clients. ScreenShooter is its companion application for capturing screenshots of their work when requested by clients.

The WorkMaster site is under closed development at the moment and is not ready for public use. More information will be available soon.

In the meantime, please checkout [Conor's website](https://www.conorjwryan.com) and his [GitLab](https://gitlab.com/conorjwryan) for more of his projects.
