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:

# 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)

# 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

# Configure
cmake --preset windows-release

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

---

📝 Step-by-Step Build Guide

Step 1: Clone the Repository

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

Step 2: Create .env File

# Copy template
copy .env.example .env

# Edit with your API keys
notepad .env

Add your API keys:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Step 3: Build the Project

Using build.bat (easier):

build.bat --release

Using CMake (manual):

# 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

cd build\windows-release\Release
SecondVoice.exe

---

🔧 Build Options

Debug vs Release

Debug (with debugging symbols):

build.bat --debug

Release (optimized, no debug symbols):

build.bat --release

Clean Build

To rebuild from scratch:

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:

# 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:

# 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

# 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:

dir build\windows-release\Release\SecondVoice.exe

Should show:

SecondVoice.exe    ~5-10 MB

Test Run

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):

   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):

   # 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:

# 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:

cmake --build build/windows-release --config Release -- /m

Watch Build Progress

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
• CMake Visual Studio Generator
• Windows Audio APIs

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