secondvoice/docs/build_windows.md

# Building SecondVoice on Windows

**Platform**: Windows 10/11
**Compiler**: Visual Studio 2019 or later
**Package Manager**: vcpkg

---

## 📋 Prerequisites

### 1. Install Visual Studio

Download and install **Visual Studio 2022 Community** (free):
- URL: https://visualstudio.microsoft.com/downloads/
- During installation, select:
  - ✅ **Desktop development with C++**
  - ✅ **C++ CMake tools for Windows**
  - ✅ **C++ Clang tools for Windows** (optional)

### 2. Install vcpkg

Open **PowerShell** or **Command Prompt** and run:

```powershell
# Clone vcpkg
cd C:\
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg

# Bootstrap vcpkg
.\bootstrap-vcpkg.bat

# Set environment variable (requires Admin or restart)
setx VCPKG_ROOT "C:\vcpkg"
```

**Important**: After setting `VCPKG_ROOT`, restart your terminal or IDE.

### 3. Install Git (if not already installed)

Download from: https://git-scm.com/download/win

---

## 🚀 Quick Build

### Option 1: Using build.bat (Recommended)

```batch
# Navigate to project directory
cd "E:\Users\Alexis Trouvé\Documents\Projets\secondvoice"

# Build release version
build.bat --release

# Or build debug version
build.bat --debug

# Clean build
build.bat --clean --release
```

### Option 2: Using CMake Directly

```batch
# Configure
cmake --preset windows-release

# Build
cmake --build build/windows-release --config Release
```

---

## 📝 Step-by-Step Build Guide

### Step 1: Clone the Repository

```batch
cd "E:\Users\Alexis Trouvé\Documents\Projets"
git clone <repository-url> secondvoice
cd secondvoice
```

### Step 2: Create .env File

```batch
# Copy template
copy .env.example .env

# Edit with your API keys
notepad .env
```

Add your API keys:
```env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

### Step 3: Build the Project

**Using build.bat** (easier):
```batch
build.bat --release
```

**Using CMake** (manual):
```batch
# Configure
cmake -B build/windows-release ^
  -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake ^
  -DCMAKE_BUILD_TYPE=Release ^
  -G Ninja

# Build
cmake --build build/windows-release --config Release
```

### Step 4: Run the Application

```batch
cd build\windows-release\Release
SecondVoice.exe
```

---

## 🔧 Build Options

### Debug vs Release

**Debug** (with debugging symbols):
```batch
build.bat --debug
```

**Release** (optimized, no debug symbols):
```batch
build.bat --release
```

### Clean Build

To rebuild from scratch:
```batch
build.bat --clean --release
```

---

## 📦 Dependencies (Installed Automatically)

vcpkg will automatically download and build:

- **portaudio** - Audio capture
- **cpp-httplib** - HTTP client
- **nlohmann-json** - JSON parsing
- **imgui** - UI framework
- **glfw3** - Window management
- **opengl** - Graphics

**First build will take 5-15 minutes** as vcpkg compiles all dependencies.

Subsequent builds are much faster (incremental).

---

## 🎯 Output Locations

### Release Build
```
build/windows-release/Release/SecondVoice.exe
```

### Debug Build
```
build/windows-debug/Debug/SecondVoice.exe
```

### Dependencies
```
build/windows-release/vcpkg_installed/x64-windows/
```

---

## 🐛 Troubleshooting

### Error: "VCPKG_ROOT not set"

**Solution**:
```batch
# Set environment variable
setx VCPKG_ROOT "C:\vcpkg"

# Restart terminal
# Verify
echo %VCPKG_ROOT%
```

### Error: "cl.exe not found"

**Solution**: Visual Studio not in PATH
1. Open **Visual Studio Developer Command Prompt**
2. Or run: `"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"`
3. Then run `build.bat`

### Error: "Ninja not found"

**Solution**:
```batch
# Install ninja via vcpkg
%VCPKG_ROOT%\vcpkg install ninja

# Or install manually
# Download from: https://github.com/ninja-build/ninja/releases
# Add to PATH
```

### Error: "portaudio not found"

**Solution**: vcpkg integration issue
```batch
# Reset vcpkg integration
%VCPKG_ROOT%\vcpkg integrate remove
%VCPKG_ROOT%\vcpkg integrate install

# Clean and rebuild
build.bat --clean --release
```

### Error: "No audio device found"

**Causes**:
- No microphone connected
- Microphone disabled in Windows settings
- Audio drivers not installed

**Solution**:
1. Connect a microphone
2. Check **Settings → System → Sound → Input**
3. Verify device shows in **Device Manager**

### Error: "Failed to open window"

**Causes**:
- Graphics drivers outdated
- OpenGL not supported

**Solution**:
1. Update graphics drivers (NVIDIA/AMD/Intel)
2. Test OpenGL: Run `glxinfo` or similar tool
3. Check Windows Event Viewer for errors

---

## 🔍 Verification

### Check Build Success

After successful build:
```batch
dir build\windows-release\Release\SecondVoice.exe
```

Should show:
```
SecondVoice.exe    ~5-10 MB
```

### Test Run

```batch
cd build\windows-release\Release

# Copy config.json if not present
copy ..\..\..\config.json .

# Copy .env if not present
copy ..\..\..\.env .

# Run
SecondVoice.exe
```

**Expected behavior**:
1. Console window opens
2. ImGui window appears
3. "Recording..." message shows
4. No immediate errors

---

## 📊 Build Performance

### First Build
- **Duration**: 5-15 minutes (vcpkg downloads + compiles dependencies)
- **Disk Space**: ~2 GB (vcpkg cache + build artifacts)

### Incremental Build
- **Duration**: 10-30 seconds (only changed files)
- **Disk Space**: +50 MB per build

### Clean Build
- **Duration**: 1-2 minutes (no dependency recompilation)

---

## 🚀 Distribution

### Creating Portable .exe

To distribute to other Windows machines:

1. **Build Release** (not Debug):
   ```batch
   build.bat --release
   ```

2. **Collect Files**:
   ```
   SecondVoice/
   ├── SecondVoice.exe
   ├── config.json
   ├── .env.example  (for user to fill)
   └── recordings/   (empty folder)
   ```

3. **Include DLLs** (if not statically linked):
   ```batch
   # Copy vcpkg DLLs
   copy build\windows-release\vcpkg_installed\x64-windows\bin\*.dll .
   ```

4. **Test on Clean Machine**:
   - No vcpkg required
   - No Visual Studio required
   - Only needs Windows 10/11 + microphone

### Dependencies to Include

If dynamic linking (check with `dumpbin /dependents SecondVoice.exe`):
- `portaudio.dll`
- `glfw3.dll`
- MSVC Runtime (usually pre-installed on Windows 10/11)

---

## 💡 Tips & Tricks

### Use CMakePresets (Recommended)

The project includes `CMakePresets.json` with optimized settings:

```batch
# List available presets
cmake --list-presets

# Use preset
cmake --preset windows-release
cmake --build --preset windows-release
```

### Use Visual Studio GUI

1. Open **Visual Studio 2022**
2. **File → Open → Folder** → Select `secondvoice/`
3. Visual Studio auto-detects CMake
4. Select **windows-release** configuration
5. **Build → Build All**

### Enable Parallel Builds

In `build.bat`, CMake automatically uses all cores with Ninja.

For Visual Studio:
```batch
cmake --build build/windows-release --config Release -- /m
```

### Watch Build Progress

```batch
cmake --build build/windows-release --config Release --verbose
```

---

## 🔐 Security Considerations

### API Keys

- ⚠️ **Never commit .env** to git (already in .gitignore)
- ⚠️ Store .env securely (not in cloud sync folders)
- ⚠️ Use environment variables for production

### Recordings

- Audio files saved to `recordings/` by default
- Contains sensitive conversations
- Consider encryption or secure storage
- Regular cleanup recommended

---

## 📚 Additional Resources

### Windows-Specific Documentation

- [vcpkg on Windows](https://vcpkg.io/en/getting-started.html)
- [CMake Visual Studio Generator](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2017%202022.html)
- [Windows Audio APIs](https://docs.microsoft.com/en-us/windows/win32/coreaudio/core-audio-apis-in-windows-vista)

### Visual Studio Tips

- Use **Ctrl+Shift+B** to build
- Use **F5** to build + run (debug mode)
- Use **Ctrl+F5** to run without debugging
- Check **Output** window for build logs

---

## 🎯 Next Steps

After successful build:

1. ✅ Test audio capture with microphone
2. ✅ Verify API keys in `.env`
3. ✅ Run first test with sample Chinese audio
4. ✅ Check transcription quality
5. ✅ Test in real meeting scenario

See `docs/next_steps.md` for testing guide.

---

*Last updated: 20 novembre 2025*
*Platform: Windows 10/11 x64*
*Build System: CMake + vcpkg + Ninja*