Prism-Notes-Main/tools/screen-record/README.md

# Screen Record Tool

A standalone utility for recording the user's screen using the native Browser Screen Capture API and MediaRecorder API.

## Features

- 🎬 Record user-selected screen/window
- ⏱️ Configurable duration limits (default 5 minutes)
- 🎯 No external dependencies
- ⚡ Fine-grained control with start/stop callbacks
- 🛡️ Graceful error handling
- ♿ Respects user permissions

## Installation

Copy the `screen-record` folder to your project:

```
your-project/
├── tools/
│   └── screen-record/
│       ├── index.js
│       └── README.md
```

## Usage

### Basic Screen Recording

```javascript
import { recordScreen } from './tools/screen-record/index.js';

const recorder = await recordScreen();
if (recorder) {
  // User is recording...
  
  // Stop after 10 seconds
  setTimeout(async () => {
    const file = await recorder.stop();
    console.log('Recording saved:', file.name);
  }, 10000);
}
```

### With Duration Limit

```javascript
const recorder = await recordScreen({
  maxDuration: 60000 // 1 minute instead of default 5 minutes
});
```

### With Callbacks

```javascript
const recorder = await recordScreen({
  onStart: () => console.log('Recording started'),
  onStop: () => console.log('Recording stopped')
});
```

### Quick Recording (Auto-stop)

```javascript
import { recordScreenFor } from './tools/screen-record/index.js';

const file = await recordScreenFor(10000); // Record for 10 seconds
console.log('Recording saved:', file.name);
```

## API Reference

### `recordScreen(options?)`

**Parameters:**
- `options` (Object, optional):
  - `maxDuration` (number): Max recording time in ms. Default: 300000 (5 min)
  - `mimeType` (string): MIME type. Default: 'video/webm'
  - `onStart` (Function): Called when recording starts
  - `onStop` (Function): Called when recording stops

**Returns:** `Promise<RecorderObject | null>`

Opens native browser dialog for user to select screen/window to record. Returns a recorder controller object with methods to stop and manage the recording.

**Recorder Object Methods:**
- `stop()` - Stops recording and returns File object
- `isRecording()` - Returns boolean for current status
- `getDuration()` - Returns duration in milliseconds
- `mediaStream` - Reference to underlying MediaStream

**Example:**
```javascript
const recorder = await recordScreen();
const file = await recorder.stop();
```

### `recordScreenFor(duration)`

**Parameters:**
- `duration` (number): Recording duration in milliseconds

**Returns:** `Promise<File>`

Convenience function that automatically stops recording after specified duration.

**Example:**
```javascript
const file = await recordScreenFor(30000); // 30 second recording
```

## Browser Support

Requires browsers supporting Screen Capture and MediaRecorder APIs:
- Chrome 72+
- Edge 79+
- Firefox 66+
- Safari 13+

Note: User must grant permission for each recording request.

## Error Handling

The tool gracefully handles:
- User cancellation of the capture dialog
- Browser permission denial
- Browser incompatibility
- Recording stream interruption
- Max duration timeout

All errors are logged to console and return null.

## Examples

### React Component with UI

```jsx
import { recordScreen } from './tools/screen-record/index.js';
import { useState } from 'react';

export function ScreenRecorderButton() {
  const [isRecording, setIsRecording] = useState(false);
  const [recorder, setRecorder] = useState(null);

  const startRecording = async () => {
    const rec = await recordScreen({
      onStart: () => setIsRecording(true),
      onStop: () => setIsRecording(false)
    });
    setRecorder(rec);
  };

  const stopRecording = async () => {
    if (recorder) {
      const file = await recorder.stop();
      console.log('Recording saved:', file.name);
    }
  };

  return (
    <div>
      {!isRecording ? (
        <button onClick={startRecording}>Start Recording</button>
      ) : (
        <button onClick={stopRecording}>Stop Recording</button>
      )}
    </div>
  );
}
```

### With File Upload

```javascript
import { recordScreen } from './tools/screen-record/index.js';

const recorder = await recordScreen();
if (recorder) {
  // Wait 15 seconds then stop
  setTimeout(async () => {
    const file = await recorder.stop();
    
    const formData = new FormData();
    formData.append('video', file);
    
    await fetch('/api/upload-video', { 
      method: 'POST', 
      body: formData 
    });
  }, 15000);
}
```

### Auto-stop after Duration

```javascript
import { recordScreenFor } from './tools/screen-record/index.js';

// Record for exactly 5 seconds
const file = await recordScreenFor(5000);
const formData = new FormData();
formData.append('video', file);

await fetch('/api/save-recording', {
  method: 'POST',
  body: formData
});
```

## File Output

Both functions return WebM video files with standardized naming:
- Filename format: `screen-recording-{timestamp}.webm`
- MIME type: `video/webm`
- Compatible with most video players and uploads

## License

MIT - Use freely in your projects