av-kit/README.md

AVFoundation Recorder kit for Node.js

# AV-Kit

A high-quality screen and camera recording library for Node.js based on macOS AVFoundation.

![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)

## Features

- 📹 Screen recording with cursor capture
- 🎥 Webcam recording
- 🎤 Audio recording from microphones
- ⚡ Promise-based API with TypeScript support

## Requirements

- **macOS**: Uses AVFoundation (macOS-only)
- **Node.js**: 16.x or higher

## Installation

```bash
npm install av-kit
# or
yarn add av-kit
# or
pnpm add av-kit
```

## Quick Example

```typescript
import { Recorder, getDisplays, getCameras } from "av-kit";
import path from "path";
import os from "os";

async function main() {
  try {
    // Get available devices
    const displays = await getDisplays();
    const cameras = await getCameras();

    // Create recorder with display and webcam
    const recorder = new Recorder({
      output_directory: path.join(
        os.homedir(),
        "Videos",
        "recording-" + new Date().toISOString()
      ),
      items: [
        {
          type: "display",
          display: displays[0],
          shows_cursor: true,
        },
        {
          type: "webcam",
          camera: cameras[0],
        },
      ],
    });

    // Start recording
    await recorder.start();

    console.log("Recording started! Will stop in 5 seconds...");
    await new Promise((resolve) => setTimeout(resolve, 5000));

    // Stop recording and get results
    const result = await recorder.stop();
    console.log("Recording stopped!");

    // Show recording file paths
    result.files.forEach((file) => {
      console.log(`${file.type} recording: ${file.path}`);
    });
  } catch (error) {
    console.error("Recording error:", error);
  }
}

main();
```

## API Reference

### Types

```typescript
// Types
type DeviceType = "display" | "camera" | "microphone";

type RecordingMode = "display" | "webcam";

// Device interfaces
interface Display {
  id: string; // Device identifier
  name: string; // Display name
}

interface Camera {
  id: string; // Device identifier
  name: string; // Camera name
}

interface Microphone {
  id: string; // Device identifier
  name: string; // Microphone name
}

// Recording configuration
type DisplayRecordingItem = {
  type: "display";
  display: Display; // Display to record
  microphone?: Microphone; // Optional audio source
  shows_cursor?: boolean; // Show cursor in recording (default: false)
};

type WebcamRecordingItem = {
  type: "webcam";
  camera: Camera; // Camera to record
  microphone?: Microphone; // Optional audio source
};

type RecordingItem = DisplayRecordingItem | WebcamRecordingItem;

// Recorder options
interface RecorderOptions {
  output_directory: string; // Where to save recordings
  items: RecordingItem[]; // Displays/cameras to record
}

// Recording results
interface FileResult {
  path: string; // Path to recorded file
  type: RecordingMode; // Type of recording
  deviceName?: string; // Name of recorded device
  dimensions?: {
    // Video dimensions
    width: number;
    height: number;
  };
  durationInSeconds?: number; // Duration of recording
}

interface RecordingResult {
  files: FileResult[]; // Array of recorded files
}
```

### Core Functions

```typescript
// Device detection
async function getDisplays(): Promise<Display[]>;
async function getCameras(): Promise<Camera[]>;
async function getMicrophones(): Promise<Microphone[]>;

// Recorder class
class Recorder {
  constructor(options: RecorderOptions);

  // Optional preparation step (automatically called by start if not called)
  async prepare(): Promise<void>;

  // Start recording
  async start(): Promise<void>;

  // Stop recording and get results
  async stop(): Promise<RecordingResult>;
}
```

## Usage in Electron

When using av-kit in an Electron application, configure your build to handle FFmpeg dependencies:

```javascript
// In forge.config.js or similar
module.exports = {
  // Unpack FFmpeg binaries from asar
  asar: {
    unpack: "**/node_modules/@ffmpeg-installer/**",
  },

  // Include required plugins
  plugins: [
    {
      name: "@electron-forge/plugin-auto-unpack-natives",
      config: {},
    },
    // Other plugins...
  ],
};
```

## License

MIT