# Product Requirements Document: ClickRecorder

## 1. Overview
**Product Name**: ClickRecorder  
**Purpose**: A Python-based desktop application for Windows that records mouse clicks across the entire screen, captures screenshots, and allows playback of recorded clicks with human-like timing. The application features a draggable, always-visible GUI with always-on-top behavior during recording, stores click data in an SQLite database organized into playlists, and supports JSON export of playlists.

**Target Audience**: Windows users needing to record and replay mouse interactions for automation, testing, or demonstrations.

**Platform**: Windows 10/11

## 2. Objectives
- Record mouse clicks and screenshots across the entire screen.
- Provide a draggable, always-visible GUI with controls for recording, playback, and playlist management.
- Store click data, screenshot paths, and logs in an SQLite database, grouped into user-named playlists.
- Simulate mouse clicks during playback with original timing.
- Support playlist creation, editing, and JSON export.
- Handle errors with on-screen alerts and prevent loops by limiting repeated clicks.

## 3. Functional Requirements

### 3.1 Recording
- **Click Capture**:
  - Record left mouse clicks across the entire screen.
  - Store click coordinates (x, y) and timestamp (seconds since recording start).
- **Screenshot Capture**:
  - Automatically capture a screenshot of the entire screen at each click.
  - Allow manual screenshot capture via a GUI button.
  - Save screenshots as PNG files in a playlist-specific folder (e.g., `./screenshots/<playlist_name>/`).
  - Store screenshot paths in a separate SQLite table linked to the playlist.
- **Recording Control**:
  - Start and stop recording via GUI buttons (“Start Recording”, “Stop Recording”).
  - Display recording status (e.g., “Recording” or “Idle”) in the GUI.
- **Loop Prevention**:
  - Detect 3 consecutive clicks at identical (x, y) coordinates within a playlist.
  - Display an on-screen alert and stop recording if a loop is detected.

### 3.2 Playback
- **Click Playback**:
  - Simulate mouse clicks at recorded coordinates with original timing (human speed, preserving intervals between clicks).
- **Visualization**:
  - Optionally display associated screenshots in a separate window during playback.
- **Control**:
  - Start playback via a “Play Playlist” button.
  - Pause playback via a “Pause Playlist” button.
  - Stop playback by pausing and resetting to the start.
- **Assumptions**:
  - Playback occurs in the same order and timing as recorded.
  - GUI remains visible but not always-on-top during playback.

### 3.3 Playlist Management
- **Definition**: A playlist is a named group of clicks and screenshots from a recording session.
- **Features**:
  - Create a new playlist with a user-defined name via an “Add Playlist” button.
  - Edit playlist name via an “Edit Playlist” button.
  - Save a recording session as a playlist.
  - Load a playlist for playback or review.
  - List all playlists in a GUI dropdown for selection.
  - Delete playlists via a GUI button.
  - Export playlists to JSON, including playlist name, created date, clicks (x, y, timestamp), and screenshot paths.
- **Assumptions**:
  - Playlists are stored indefinitely unless deleted.
  - JSON export saves to a user-specified file (default: `./exports/<playlist_name>.json`).

### 3.4 GUI
- **Design**:
  - Compact, draggable window, always visible during recording and playback.
  - Always-on-top during recording only.
  - Transparent background with minimalistic design for unobtrusive use.
- **Controls**:
  - **Start Recording**: Begins capturing clicks and screenshots.
  - **Stop Recording**: Stops recording and prompts for a playlist name.
  - **Play Playlist**: Starts playback of the selected playlist.
  - **Pause Playlist**: Pauses playback, allowing resumption.
  - **Add Playlist**: Creates a new playlist with a user-defined name.
  - **Edit Playlist**: Renames the selected playlist.
  - **Delete Playlist**: Removes the selected playlist.
  - **Manual Screenshot**: Captures and saves a screenshot to the current playlist’s folder.
  - **Playlist Dropdown**: Lists all playlists for selection.
  - **Export JSON**: Exports the selected playlist to a JSON file.
  - **Status Label**: Displays current state (e.g., “Recording”, “Playing”, “Idle”).
- **Assumptions**:
  - Uses Tkinter for simplicity and Windows compatibility.
  - Manual screenshots are linked to the current playlist, if any.

### 3.5 Data Storage
- **Database**: SQLite database (`clicks.db`) in the application directory.
- **Schema**:
  - **Table: Playlists**
    - `id`: Integer, primary key, auto-increment.
    - `name`: Text, user-defined playlist name.
    - `created_date`: Text, ISO 8601 format (e.g., “2025-07-08T14:58:00”).
  - **Table: Clicks**
    - `id`: Integer, primary key, auto-increment.
    - `playlist_id`: Integer, foreign key referencing Playlists(id).
    - `x`: Integer, x-coordinate of the click.
    - `y`: Integer, y-coordinate of the click.
    - `timestamp`: Float, time of click (seconds since recording start).
  - **Table: Screenshots**
    - `id`: Integer, primary key, auto-increment.
    - `playlist_id`: Integer, foreign key referencing Playlists(id).
    - `path`: Text, file path to the screenshot (e.g., `./screenshots/xero_login/click_1.png`).
    - `is_manual`: Boolean, indicates if screenshot was taken manually (1) or automatically (0).
- **Assumptions**:
  - Screenshot paths are relative to the application directory.
  - Database is created automatically on first run.

### 3.6 Error Handling
- **On-Screen Alerts**:
  - Display alerts for:
    - Insufficient permissions for screenshot capture.
    - Disk full or write errors when saving screenshots.
    - Database access issues.
    - Detection of 3 identical clicks (loop prevention).
- **Logging**:
  - Log errors to a file (`clickrecorder.log`) for debugging.

## 4. Non-Functional Requirements
- **Performance**:
  - Minimal CPU/memory usage during recording and playback.
  - Handle up to 1,000 clicks per playlist without performance degradation.
- **Compatibility**:
  - Runs on Windows 10/11.
  - Uses Python 3.8+ with libraries: `pyautogui`, `tkinter`, `sqlite3`, `pillow`.
- **Usability**:
  - Intuitive GUI requiring minimal training.
  - Clear feedback for all actions (e.g., “Playlist saved”, “Loop detected”).
- **Security**:
  - No network calls or file access beyond the application directory, screenshot folders, and export files.
  - Rely on Windows’ native screenshot functionality to avoid capturing sensitive data.

## 5. Technical Stack
- **Language**: Python 3.8+
- **Libraries**:
  - `tkinter`: GUI.
  - `pyautogui`: Mouse click capture and playback.
  - `pillow`: Screenshot capture and processing.
  - `sqlite3`: Database operations.
  - `json`: JSON export.
- **Database**: SQLite (local file-based).
- **File Storage**: PNG screenshots in playlist-specific folders.

## 6. Future Considerations
- Support for keyboard input recording.
- JSON import functionality.
- Cross-platform support (macOS, Linux).
- Option to record clicks within a specific window.

## 7. Risks and Mitigations
- **Risk**: Permission issues for screenshot capture.
  - **Mitigation**: Check permissions on startup and display alerts.
- **Risk**: Large screenshot files consuming disk space.
  - **Mitigation**: Warn users if disk space is low during recording.
- **Risk**: Playback clicks misaligned due to screen resolution changes.
  - **Mitigation**: Alert users to maintain consistent screen settings.
- **Risk**: Loop detection falsely triggered by intentional repeated clicks.
  - **Mitigation**: Allow users to override the loop alert via a confirmation dialog.

## 8. Milestones
- **Phase 1**: Core recording, playback, and SQLite storage.
- **Phase 2**: GUI with playlist management and JSON export.
- **Phase 3**: Error handling, loop prevention, and logging.
- **Phase 4**: User testing and refinements.