screenshot-monitor-pro/README.md

A Node.js package for automated screenshot monitoring with SQLite database storage and configurable capture intervals

# Screenshot Monitor Pro

A Node.js package for automated screenshot monitoring with SQLite database storage and configurable capture intervals. Perfect for activity tracking, surveillance, and automated screen recording.

## Features

- 📸 **Multi-Monitor Screenshot Capture**: Takes screenshots from all attached monitors
- 🖼️ **Thumbnail Generation**: Automatically creates thumbnails for easy browsing
- 💾 **SQLite Database**: Stores all screenshot metadata and file paths
- ⚙️ **Configurable**: Customizable capture frequency, quality, and storage paths
- 🔍 **Query Interface**: Easy API to retrieve and manage screenshots
- 📊 **Statistics**: Get insights about your screenshot collection
- 🗂️ **Organized Storage**: Separate folders for screenshots and thumbnails
- 🆔 **Unique Filenames**: Format: `<Monitor ID>-<Timestamp>-<UUID>.<ext>`

## Installation

```bash
npm install screenshot-monitor-pro
```

### Global Installation (CLI Tool)

```bash
npm install -g screenshot-monitor-pro
```

After global installation, you can use the CLI tool directly:

```bash
screenshot-monitor start --frequency 60000
screenshot-monitor capture
screenshot-monitor list --limit 5
```

## Quick Start

### Using the CLI Tool

```bash
# Start monitoring with default settings (30-second intervals)
npm start

# Start monitoring with custom frequency
npm run cli start --frequency 60000

# Capture screenshots from all monitors
npm run capture

# Capture from specific monitor
npm run cli capture --monitor 0

# List recent screenshots
npm run list

# List screenshots from specific monitor
npm run cli list --monitor 0

# Show statistics
npm run stats

# Show statistics for specific monitor
npm run cli stats --monitor 0

# Show available monitors
npm run monitors
```

### Using the JavaScript API

```javascript
const ScreenshotMonitor = require('screenshot-monitor-pro');

// Initialize with custom configuration
const monitor = new ScreenshotMonitor({
  frequency: 60000, // Take screenshot every 60 seconds
  screenshotQuality: 90,
  thumbnailWidth: 300,
  thumbnailHeight: 200
});

// Start monitoring
async function startMonitoring() {
  await monitor.init();
  await monitor.start();
  
  // Monitor will continue running in the background
  console.log('Screenshot monitoring started!');
}

startMonitoring();
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `frequency` | number | 30000 | Interval between screenshots (milliseconds) |
| `screenshotQuality` | number | 90 | PNG quality (1-100) |
| `thumbnailWidth` | number | 300 | Thumbnail width in pixels |
| `thumbnailHeight` | number | 200 | Thumbnail height in pixels |
| `userDataPath` | string | `~/.screenshot-monitor-pro` | Base directory for storage |

## API Reference

### Constructor

```javascript
const monitor = new ScreenshotMonitor(config);
```

### Methods

#### `async init()`
Initialize the monitor, create directories, and set up the database.

```javascript
await monitor.init();
```

#### `async start()`
Start the screenshot monitoring process.

```javascript
await monitor.start();
```

#### `stop()`
Stop the screenshot monitoring process.

```javascript
monitor.stop();
```

#### `async captureScreenshot(monitor)`
Manually capture a screenshot from a specific monitor.

```javascript
// Capture from all monitors
const results = await monitor.captureAllScreenshots();

// Capture from specific monitor
const monitors = monitor.getMonitors();
const result = await monitor.captureScreenshot(monitors[0]);

console.log(result);
// Output: { filename, thumbnailFilename, filePath, thumbnailPath, monitorId, monitorName, uuid }
```

#### `async getScreenshots(limit, offset, monitorId)`
Retrieve screenshot entries from the database.

```javascript
// Get last 10 screenshots from all monitors
const screenshots = await monitor.getScreenshots(10);

// Get screenshots with pagination
const screenshots = await monitor.getScreenshots(20, 40); // 20 items, skip first 40

// Get screenshots from specific monitor
const screenshots = await monitor.getScreenshots(10, 0, 0); // 10 items from monitor 0

// Get screenshots by monitor ID
const screenshots = await monitor.getScreenshotsByMonitor(0, 10);
```

#### `async getScreenshotById(id)`
Get a specific screenshot by its database ID.

```javascript
const screenshot = await monitor.getScreenshotById(1);
```

#### `async deleteScreenshot(id)`
Delete a screenshot and its thumbnail from storage and database.

```javascript
await monitor.deleteScreenshot(1);
```

#### `async getStats(monitorId)`
Get statistics about the screenshot collection.

```javascript
// Get overall statistics
const stats = await monitor.getStats();
console.log(stats);
// Output: { total_screenshots, total_size, first_screenshot, last_screenshot }

// Get statistics for specific monitor
const stats = await monitor.getStats(0);

// Get per-monitor statistics
const monitorStats = await monitor.getMonitorStats();
// Output: Array of stats per monitor
```

#### `updateConfig(newConfig)`
Update the monitor configuration.

```javascript
monitor.updateConfig({
  frequency: 45000, // Change to 45 seconds
  thumbnailWidth: 400
});
```

#### `getMonitors()`
Get information about available monitors.

```javascript
const monitors = monitor.getMonitors();
// Output: Array of monitor objects with id, name, width, height, x, y, index
```

#### `getConfig()`
Get the current configuration.

```javascript
const config = monitor.getConfig();
```

#### `async close()`
Close the database connection.

```javascript
await monitor.close();
```

## Complete Example

```javascript
const ScreenshotMonitor = require('screenshot-monitor-pro');

async function example() {
  // Create monitor instance
  const monitor = new ScreenshotMonitor({
    frequency: 30000, // 30 seconds
    screenshotQuality: 95,
    thumbnailWidth: 400,
    thumbnailHeight: 300,
    userDataPath: './my-screenshots'
  });

  try {
    // Initialize
    await monitor.init();
    console.log('Monitor initialized');

    // Start monitoring
    await monitor.start();
    console.log('Monitoring started');

    // Let it run for 2 minutes
    setTimeout(async () => {
      // Get statistics
      const stats = await monitor.getStats();
      console.log('Statistics:', stats);

      // Get recent screenshots
      const screenshots = await monitor.getScreenshots(5);
      console.log('Recent screenshots:', screenshots);

      // Stop monitoring
      monitor.stop();
      console.log('Monitoring stopped');

      // Close database
      await monitor.close();
      console.log('Database closed');
    }, 120000);

  } catch (error) {
    console.error('Error:', error);
  }
}

example();
```

## File Structure

The package creates the following directory structure:

```
~/.screenshot-monitor-pro/
├── screenshots/
│   ├── 0-2024-01-15T10-30-00-000Z-550e8400-e29b-41d4-a716-446655440000.png
│   ├── 1-2024-01-15T10-30-00-000Z-550e8400-e29b-41d4-a716-446655440001.png
│   └── ...
├── thumbnails/
│   ├── thumb-0-2024-01-15T10-30-00-000Z-550e8400-e29b-41d4-a716-446655440000.png
│   ├── thumb-1-2024-01-15T10-30-00-000Z-550e8400-e29b-41d4-a716-446655440001.png
│   └── ...
└── screenshots.db
```

### Filename Format

Screenshots are saved with the format: `<Monitor ID>-<Timestamp>-<UUID>.<ext>`

- **Monitor ID**: The ID of the monitor (0, 1, 2, etc.)
- **Timestamp**: ISO timestamp when the screenshot was taken
- **UUID**: Unique identifier to prevent filename collisions
- **Extension**: PNG format for screenshots, PNG for thumbnails

## Database Schema

The SQLite database contains a `screenshots` table with the following columns:

- `id`: Primary key
- `filename`: Original screenshot filename
- `thumbnail_filename`: Thumbnail filename
- `timestamp`: Capture timestamp
- `monitor_id`: ID of the monitor that was captured
- `monitor_name`: Name of the monitor
- `screen_width`: Original image width
- `screen_height`: Original image height
- `file_size`: File size in bytes
- `file_path`: Full path to screenshot file
- `thumbnail_path`: Full path to thumbnail file
- `uuid`: Unique identifier for the screenshot

## Error Handling

The package includes comprehensive error handling:

```javascript
try {
  await monitor.init();
  await monitor.start();
} catch (error) {
  console.error('Monitor error:', error.message);
  // Handle specific error types
  if (error.code === 'ENOENT') {
    console.error('Directory creation failed');
  }
}
```

## Performance Considerations

- **Memory Usage**: Screenshots are processed in memory and immediately written to disk
- **Storage**: Monitor disk space usage, especially with high-frequency captures
- **Database**: SQLite database grows with each screenshot entry
- **CPU**: Image processing for thumbnails uses CPU resources

## CLI Commands

| Command | Description | Example |
|---------|-------------|---------|
| `start` | Start screenshot monitoring | `screenshot-monitor start --frequency 60000` |
| `capture` | Capture screenshots from all monitors | `screenshot-monitor capture` |
| `capture` | Capture from specific monitor | `screenshot-monitor capture --monitor 0` |
| `list` | List recent screenshots | `screenshot-monitor list --limit 10` |
| `list` | List from specific monitor | `screenshot-monitor list --monitor 0` |
| `stats` | Show overall statistics | `screenshot-monitor stats` |
| `stats` | Show monitor-specific stats | `screenshot-monitor stats --monitor 0` |
| `monitors` | Show available monitors | `screenshot-monitor monitors` |
| `config` | Show current configuration | `screenshot-monitor config` |

### CLI Options

- `--frequency <ms>`: Screenshot interval in milliseconds
- `--quality <1-100>`: Screenshot quality percentage
- `--thumb-width <px>`: Thumbnail width in pixels
- `--thumb-height <px>`: Thumbnail height in pixels
- `--path <directory>`: Custom storage directory
- `--limit <number>`: Number of screenshots to list
- `--monitor <id>`: Specific monitor ID to target

## Platform Support

- ✅ Windows
- ✅ macOS
- ✅ Linux

## Dependencies

- `screenshot-desktop`: Cross-platform screenshot capture
- `sqlite3`: Database operations
- `sharp`: Image processing and thumbnail generation
- `fs-extra`: Enhanced file system operations

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## Support

For issues and questions, please open an issue on GitHub.