Add Windows Support for Electron App: Replace Linux PipeWire Implementation

[jiangzhuo]

Overview

The Sokuji Electron desktop app currently only supports virtual audio devices on Linux via PulseAudio/PipeWire. To expand platform support, we need to implement Windows-compatible virtual audio functionality to replace the Linux-specific implementation.

Current State Analysis

Linux Implementation (Current)

• Location: electron/pulseaudio-utils.js
• Dependencies: PulseAudio (pactl) and PipeWire (pw-link) commands
• Features:
  • Creates virtual audio sink (sokuji_virtual_output)
  • Creates virtual microphone source (sokuji_virtual_mic)
  • System-level audio routing between applications
  • Enables other apps to use Sokuji's translated audio as input
  • Auto-cleanup of orphaned devices

Cross-Platform Core Audio

• ✅ Web Audio API: Already works on all platforms via ModernBrowserAudioService
• ✅ Audio Processing: Echo cancellation, device switching, real-time processing
• ✅ Event-Driven Pipeline: ModernAudioRecorder/ModernAudioPlayer classes
• ❌ Virtual Devices: Linux-only via PulseAudio/PipeWire

Platform Support Status

• Linux: ✅ Full support with virtual audio devices
• Windows: ⚠️ Core functionality only, no virtual devices
• macOS: ⚠️ Core functionality only, no virtual devices

Problem Statement

Windows users cannot:

1. Use Sokuji's translated output as microphone input in other applications
2. Route audio between applications through Sokuji
3. Access advanced system-level audio integration features

Requirements

Primary Goals

• Windows Virtual Audio: Implement Windows equivalent of Linux virtual devices
• Cross-Platform API: Unified interface for virtual audio across platforms
• Backward Compatibility: Maintain existing Linux functionality
• Feature Parity: Same capabilities on Windows as Linux

Technical Requirements

• Support Windows 10/11
• No additional driver installations required for basic functionality
• Graceful fallback when virtual audio unavailable
• Clean resource management and cleanup

Implementation Options

Option 1: VB-Audio Virtual Cable Integration

Pros:

• Well-established Windows virtual audio solution
• Reliable performance
• Wide compatibility

Cons:

• Requires separate software installation
• External dependency
• Not bundled with application

Option 2: Windows Audio Session API (WASAPI) + Virtual Audio Driver

Pros:

• Native Windows integration
• No external dependencies
• Full control over audio routing

Cons:

• Complex implementation
• May require elevated permissions
• Windows-specific code

Option 3: NAudio Library Integration

Pros:

• .NET-based audio library for Windows
• Good community support
• Easier than raw WASAPI

Cons:

• Requires .NET runtime
• Additional dependency
• May need native bridge from Node.js

Option 4: Virtual Audio Cable (VAC) SDK

Pros:

• Professional-grade virtual audio
• SDK available for integration
• High performance

Cons:

• Commercial licensing required
• Cost implications
• Complex integration

Recommended Approach

Phase 1: Architecture Refactor

1. Abstract Virtual Audio Interface

   // Create platform-agnostic interface
   interface VirtualAudioProvider {
     createVirtualDevices(): Promise<boolean>
     removeVirtualDevices(): void
     isAvailable(): Promise<boolean>
     getVirtualSinkName(): string
     getVirtualSourceName(): string
   }

2. Platform Detection & Factory

   • Detect current platform (win32, linux, darwin)
   • Create appropriate virtual audio provider
   • Fallback to no-op provider if unsupported

Phase 2: Windows Implementation

1. Research & Prototype

   • Evaluate WASAPI capabilities for virtual devices
   • Test NAudio library integration
   • Prototype virtual cable solution

2. Windows Virtual Audio Provider

   • Implement Windows-specific virtual audio creation
   • Handle Windows audio session management
   • Ensure clean cleanup on app exit

Phase 3: Integration & Testing

1. Update Main Process

   • Modify electron/main.js to use platform factory
   • Update IPC handlers for cross-platform compatibility
   • Add Windows-specific initialization

2. Testing Matrix

   • Windows 10/11 compatibility
   • Audio device enumeration
   • Virtual device creation/cleanup
   • Cross-application audio routing

Technical Implementation Tasks

Core Architecture

• Create VirtualAudioProvider interface
• Implement LinuxVirtualAudioProvider (refactor existing code)
• Create WindowsVirtualAudioProvider skeleton
• Add platform detection and factory pattern
• Update electron/main.js to use new architecture

Windows Implementation

• Research Windows virtual audio solutions
• Choose optimal implementation approach
• Implement Windows virtual device creation
• Add Windows audio session management
• Handle Windows-specific permissions and security

Integration

• Update IPC communication for cross-platform compatibility
• Modify cleanup procedures for Windows
• Add platform-specific error handling
• Update logging for Windows audio operations

Testing & Documentation

• Test on Windows 10/11 systems
• Verify audio routing functionality
• Test cleanup on abnormal app termination
• Update CLAUDE.md with Windows requirements
• Document Windows-specific limitations or requirements

Success Criteria

• ✅ Sokuji runs on Windows with core audio functionality
• ✅ Virtual audio devices work on Windows (system-level routing)
• ✅ Other Windows applications can use Sokuji audio as microphone input
• ✅ Clean startup and shutdown on Windows
• ✅ Existing Linux functionality remains unchanged
• ✅ Graceful fallback when virtual audio unavailable

Platform Requirements

Windows

• Windows 10 version 1903 or later
• No additional driver requirements for basic functionality
• Optional: Enhanced virtual audio capabilities

Linux (Existing)

• PulseAudio or PipeWire
• pactl and pw-link commands available

Future: macOS

• Core Audio framework integration
• AudioUnit virtual devices

Priority

High - Windows is a major desktop platform and lack of support limits user adoption

Labels

enhancement, cross-platform, windows, electron, audio, breaking-change

Related Issues

• Windows build/packaging requirements
• Cross-platform testing automation
• Audio driver compatibility matrix