logitech-brio-zoom-control/BUILD.md

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

# Build Guide - Logitech MX Brio Zoom Control

This guide walks you through compiling and running the Logitech MX Brio Zoom Control library on different platforms.

## Quick Start

1. **Run the verification test** (no compilation needed):
   ```bash
   node test/simple-test.js
   ```

2. **Install dependencies and compile**:
   ```bash
   chmod +x setup.sh
   ./setup.sh
   ```

3. **Test with your camera**:
   ```bash
   npm test
   ```

## Platform-Specific Instructions

### 🐧 Linux (Ubuntu/Debian)

#### Prerequisites
```bash
# Update package list
sudo apt-get update

# Install build tools
sudo apt-get install -y build-essential

# Install Video4Linux2 development headers
sudo apt-get install -y libv4l-dev

# Install udev development headers  
sudo apt-get install -y libudev-dev
```

#### Compile and Install
```bash
# Install Node.js dependencies and compile native addon
npm install

# Run tests
npm test
```

#### Troubleshooting Linux
- **Permission denied for video devices**:
  ```bash
  sudo usermod -a -G video $USER
  # Log out and back in, or:
  newgrp video
  ```

- **Camera not detected**:
  ```bash
  # Check if camera is recognized
  lsusb | grep Logitech
  
  # Check video devices
  ls -la /dev/video*
  
  # Test camera with v4l2
  v4l2-ctl --list-devices
  ```

### 💻 Windows

#### Prerequisites
1. **Install Node.js** from [nodejs.org](https://nodejs.org/)

2. **Install Visual Studio Build Tools**:
   - Download from [Microsoft](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)
   - Or install via chocolatey: `choco install visualstudio2022buildtools`
   - Make sure to include C++ build tools

3. **Install Windows SDK** (usually included with Build Tools)

#### Compile and Install
```cmd
# Install dependencies
npm install

# Run tests  
npm test
```

#### Troubleshooting Windows
- **MSBuild errors**: Ensure Visual Studio Build Tools are properly installed
- **Python errors**: Install Python 3.x and ensure it's in PATH
- **Camera not detected**: Check Device Manager for Logitech MX Brio

### 🍎 macOS

#### Prerequisites
```bash
# Install Xcode Command Line Tools
xcode-select --install

# Verify installation
xcode-select -p
```

#### Compile and Install
```bash
# Install dependencies
npm install

# Run tests
npm test
```

#### Troubleshooting macOS
- **Camera permissions**: Grant camera access in System Preferences > Security & Privacy
- **Xcode license**: Run `sudo xcodebuild -license accept`

## Manual Build Process

If the automated build fails, you can build manually:

### 1. Clean Previous Builds
```bash
npm run clean
# or manually:
rm -rf build/
rm -rf node_modules/
```

### 2. Install Dependencies
```bash
npm install --only=dev
```

### 3. Configure Build
```bash
npx node-gyp configure
```

### 4. Build
```bash
npx node-gyp build
```

### 5. Test
```bash
node test/test.js
```

## Build Configuration

The build is controlled by `binding.gyp`:

```json
{
  "targets": [
    {
      "target_name": "brio_zoom_control",
      "sources": [
        "src/binding.cpp",
        "src/camera_control.cpp"
      ],
      "conditions": [
        ["OS=='win'", {
          "sources": ["src/windows/directshow_control.cpp"],
          "libraries": ["-lole32", "-loleaut32", "-lstrmiids", "-luuid"]
        }],
        ["OS=='linux'", {
          "sources": ["src/linux/v4l2_control.cpp"],
          "libraries": ["-lv4l2"]
        }],
        ["OS=='mac'", {
          "sources": ["src/macos/avfoundation_control.mm"],
          "libraries": [
            "-framework Foundation",
            "-framework AVFoundation", 
            "-framework CoreMedia"
          ]
        }]
      ]
    }
  ]
}
```

## Testing Without Camera

You can verify the library structure without a camera:

```bash
node test/simple-test.js
```

This will check:
- ✅ All source files are present
- ✅ Configuration files are correct
- ✅ Dependencies are listed properly

## Integration Testing

### Basic Node.js Test
```javascript
const LogitechBrioZoomControl = require('./index.js');
const control = new LogitechBrioZoomControl();

// This will work after successful compilation
const devices = control.discoverDevices();
console.log('Found devices:', devices);
```

### Electron Integration Test
See `examples/` folder for complete Electron integration examples.

## Common Issues

### 1. "gyp: not found"
- Install node-gyp globally: `npm install -g node-gyp`

### 2. "make: not found" (Linux)
- Install build-essential: `sudo apt-get install build-essential`

### 3. "MSBuild not found" (Windows)  
- Install Visual Studio Build Tools with C++ support

### 4. Camera permission denied
- Linux: Add user to video group
- macOS: Grant camera permissions in System Preferences
- Windows: Check camera is not in use by other applications

### 5. Library loading fails
- Ensure all system dependencies are installed
- Check that the native module was compiled for the correct Node.js version
- For Electron: Rebuild for Electron using `@electron/rebuild`

## Rebuilding for Electron

If using with Electron, rebuild the native module:

```bash
# Install electron rebuild
npm install --save-dev @electron/rebuild

# Rebuild for Electron
npx electron-rebuild

# Or using electron-builder
npx electron-builder install-app-deps
```

## Distribution

For distributing your app with this library:

1. **Include prebuilt binaries** for target platforms
2. **Use electron-builder** with native dependencies support
3. **Test on all target platforms** before release

## Getting Help

If you encounter issues:

1. **Check this build guide** for platform-specific solutions
2. **Run the verification test**: `node test/simple-test.js`
3. **Check the main README.md** for usage examples
4. **Review error logs** carefully for specific error messages

## Success Indicators

✅ **Compilation successful** when you see:
```
gyp info ok 
```

✅ **Library ready** when test shows:
```
🎉 All tests completed successfully!
```

✅ **Camera detected** when you see:
```
Found 1 device(s):
  1. Logitech MX Brio (ID: ...)
```