logitech-brio-zoom-control/README.md

Cross-platform native library for controlling Logitech MX Brio camera zoom with 4K video support in Electron applications

# Logitech MX Brio Zoom Control

A native C library for controlling Logitech MX Brio camera zoom functionality in Electron applications. This library provides cross-platform zoom control using platform-specific camera APIs:

- **Windows**: DirectShow API
- **Linux**: Video4Linux2 (V4L2) API  
- **macOS**: AVFoundation framework

## Features

- 🎥 **Cross-platform support** for Windows, Linux, and macOS
- 🔍 **Device discovery** - Find all connected Logitech BRIO cameras
- 📏 **Zoom capabilities** - Query min/max zoom levels and current settings
- 🎛️ **Absolute zoom control** - Set specific zoom values
- ⚡ **Relative zoom control** - Zoom in/out by increments
- 🔧 **Easy integration** with Electron applications
- 📦 **Native performance** with C++ implementation

## Supported Devices

- Logitech MX Brio (4K)
- Logitech BRIO (4K Ultra HD)
- Other UVC-compatible Logitech cameras (may work with limited functionality)

## Installation

```bash
npm install
```

This will automatically compile the native addon for your platform.

### Prerequisites

#### Windows
- Visual Studio Build Tools or Visual Studio with C++ workload
- Windows SDK

#### Linux
- Build essentials: `sudo apt-get install build-essential`
- Video4Linux2 development headers: `sudo apt-get install libv4l-dev`
- libudev development headers: `sudo apt-get install libudev-dev`

#### macOS
- Xcode Command Line Tools: `xcode-select --install`

## Usage

### Basic Example

```javascript
const LogitechBrioZoomControl = require('logitech-brio-zoom-control');

const control = new LogitechBrioZoomControl();

// Discover available devices
const devices = control.discoverDevices();
console.log('Found devices:', devices);

// Initialize the first device
if (devices.length > 0) {
    const success = control.initializeDevice(devices[0].id);
    if (success) {
        // Get zoom capabilities
        const caps = control.getZoomCapabilities();
        console.log('Zoom range:', caps.min, '-', caps.max);
        
        // Set zoom to 200
        control.setZoomAbsolute(200);
        
        // Zoom in by 10 units
        control.zoomIn(10);
        
        // Get current zoom value
        console.log('Current zoom:', control.getZoomValue());
        
        // Cleanup
        control.releaseDevice();
    }
}
```

### Electron Integration

```javascript
// In your Electron main process
const { ipcMain } = require('electron');
const LogitechBrioZoomControl = require('logitech-brio-zoom-control');

const control = new LogitechBrioZoomControl();

ipcMain.handle('camera:discover', () => {
    return control.discoverDevices();
});

ipcMain.handle('camera:initialize', (event, deviceId) => {
    return control.initializeDevice(deviceId);
});

ipcMain.handle('camera:zoom:set', (event, zoomValue) => {
    return control.setZoomAbsolute(zoomValue);
});

ipcMain.handle('camera:zoom:get', () => {
    return control.getZoomValue();
});

// In your renderer process
const { ipcRenderer } = require('electron');

// Discover cameras
const devices = await ipcRenderer.invoke('camera:discover');

// Initialize camera
await ipcRenderer.invoke('camera:initialize', devices[0].id);

// Control zoom
await ipcRenderer.invoke('camera:zoom:set', 300);
const currentZoom = await ipcRenderer.invoke('camera:zoom:get');
```

## API Reference

### Class: LogitechBrioZoomControl

#### Methods

##### `discoverDevices()`
Returns an array of available Logitech BRIO devices.

**Returns:** `Array<Device>`
```javascript
[
  {
    name: "Logitech MX Brio",
    id: "device_id_string",
    vendorId: 0x046d,
    productId: 0x085e
  }
]
```

##### `initializeDevice(deviceId)`
Initialize a specific device for zoom control.

**Parameters:**
- `deviceId` (string): Device ID from `discoverDevices()`

**Returns:** `boolean` - True if successful

##### `initializeFirstDevice()`
Initialize the first available device.

**Returns:** `boolean` - True if successful

##### `releaseDevice()`
Release the current device and cleanup resources.

##### `getZoomCapabilities()`
Get zoom capabilities of the current device.

**Returns:** `Object`
```javascript
{
  min: 100,              // Minimum zoom value
  max: 500,              // Maximum zoom value  
  step: 1,               // Step size
  current: 100,          // Current zoom value
  supportsAbsolute: true, // Supports absolute zoom control
  supportsRelative: true  // Supports relative zoom control
}
```

##### `setZoomAbsolute(zoomValue)`
Set absolute zoom value.

**Parameters:**
- `zoomValue` (number): Zoom value within device capabilities

**Returns:** `boolean` - True if successful

##### `setZoomRelative(zoomDelta)`
Adjust zoom by relative amount.

**Parameters:**
- `zoomDelta` (number): Change in zoom (positive = zoom in, negative = zoom out)

**Returns:** `boolean` - True if successful

##### `getZoomValue()`
Get current zoom value.

**Returns:** `number` - Current zoom value

##### `zoomIn(amount = 10)`
Zoom in by specified amount.

**Parameters:**
- `amount` (number): Amount to zoom in (default: 10)

**Returns:** `boolean` - True if successful

##### `zoomOut(amount = 10)`
Zoom out by specified amount.

**Parameters:**
- `amount` (number): Amount to zoom out (default: 10)

**Returns:** `boolean` - True if successful

##### `resetZoom()`
Reset zoom to minimum value.

**Returns:** `boolean` - True if successful

##### `maxZoom()`
Set zoom to maximum value.

**Returns:** `boolean` - True if successful

#### Static Methods

##### `LogitechBrioZoomControl.getInfo()`
Get library information.

**Returns:** `Object`
```javascript
{
  name: "logitech-brio-zoom-control",
  version: "1.0.0", 
  platform: "win32",
  arch: "x64",
  nodeVersion: "v16.14.0"
}
```

## Testing

Run the test suite to verify functionality:

```bash
npm test
```

This will:
1. Discover available devices
2. Initialize the first device found
3. Test all zoom control functions
4. Verify zoom capabilities
5. Perform cleanup

## Troubleshooting

### No devices found
- Ensure your Logitech MX Brio is connected and recognized by the system
- On Linux, check that your user has access to video devices: `sudo usermod -a -G video $USER`
- Verify the camera works with other applications first

### Permission errors (Linux)
```bash
# Add user to video group
sudo usermod -a -G video $USER

# Or create udev rule for the device
echo 'SUBSYSTEM=="video4linux", GROUP="video", MODE="0664"' | sudo tee /etc/udev/rules.d/99-video.rules
sudo udevadm control --reload-rules
```

### Build errors
- Ensure all prerequisites are installed for your platform
- Try cleaning and rebuilding: `npm run clean && npm run build`
- On Windows, ensure Visual Studio Build Tools are properly installed

### Camera not responding
- Close other applications that might be using the camera
- Try reconnecting the camera
- Restart the application

## Platform-Specific Notes

### Windows
- Uses DirectShow `IAMCameraControl` interface
- Requires camera drivers that support UVC controls
- Some zoom controls may require manual camera control flags

### Linux  
- Uses Video4Linux2 (V4L2) API
- Zoom controls: `V4L2_CID_ZOOM_ABSOLUTE`, `V4L2_CID_ZOOM_RELATIVE`
- Requires proper udev permissions for video devices

### macOS
- Uses AVFoundation `AVCaptureDevice.videoZoomFactor`
- Zoom values are converted from factor (1.0-5.0) to integer (100-500)
- Requires camera access permissions

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Check the troubleshooting section above
- Review closed issues on GitHub
- Create a new issue with detailed information about your setup and the problem

## Changelog

### v1.0.0
- Initial release
- Cross-platform zoom control support
- Device discovery and initialization
- Comprehensive test suite
- Electron integration examples