← Back to Documentation

macOS Installation Guide

This guide will walk you through installing Sokuji on macOS systems. Sokuji is available as a signed and notarized .pkg installer that includes a virtual audio driver for enhanced audio processing capabilities.

Download for macOS

System Requirements

  • macOS 13 (Ventura) or later (since v0.42.2; on macOS 12, keep using v0.42.1)
  • Apple Silicon (M1/M2/M3/M4) or Intel (x86_64) processor
  • 4GB RAM minimum (8GB recommended)
  • 200MB available disk space
  • Administrator privileges (required for virtual audio driver installation)
  • Internet connection for AI translation services
  • Microphone and speakers/headphones

Installation Steps

Step 1: Download Sokuji

Visit the official GitHub releases page to download the latest version of Sokuji for macOS.

Download the PKG Installer

  • Sokuji-x.x.x-arm64.pkg - For Apple Silicon Macs (M1/M2/M3/M4)
  • Sokuji-x.x.x-x64.pkg - For Intel Macs
  • Each installer includes the Sokuji app and the virtual audio driver
  • File size is approximately 150-200MB

Tip: Not sure which one to download? Click the Apple menu () → "About This Mac" to check your chip type. If you see "Apple M1/M2/M3/M4", choose the arm64 version. If you see "Intel", choose the x64 version.

Since version 0.46.5 the PKG installer is signed and notarized, so macOS opens it without any extra steps.

Step 2: Install PKG

Install Sokuji and its virtual audio driver.

Installation Process

  1. Locate the downloaded .pkg file in your Downloads folder (e.g., Sokuji-x.x.x-arm64.pkg or Sokuji-x.x.x-x64.pkg)
  2. Double-click the PKG file to start the installation
  3. The macOS Installer will open - click "Continue" to proceed
  4. Review the installation details and click "Install"
  5. Enter your administrator password when prompted (required for driver installation)
  6. Wait for the installation to complete (usually 1-2 minutes)
  7. Click "Close" when installation is finished

What Gets Installed

  • Sokuji.app - Installed to /Applications
  • SokujiVirtualAudio.driver - Virtual audio driver installed to /Library/Audio/Plug-Ins/HAL
  • The installer will automatically restart CoreAudio to load the driver
Administrator password is required because the installer needs to install a system-level audio driver. The virtual audio driver enables advanced audio processing features.

Step 3: First Launch

Open Sokuji from your Applications folder. No security workaround is needed.

Step 4: Configure Sokuji

Now that Sokuji is running, let's configure it for first use:

Initial Setup

  1. Grant microphone permissions when macOS prompts you
  2. Select your preferred interface language
  3. Choose your AI provider (OpenAI, Google Gemini, etc.)
  4. Enter your API key for the selected provider
  5. Select source and target languages for translation
  6. Select your microphone, and in the Speech block choose your speakers or headphones as the Default playback device. Sokuji does not list its own virtual audio device there: Translation the other side hears sends your translation into it, as the virtual microphone your meeting app picks
  7. Test your microphone and speaker setup
Congratulations! Sokuji is now ready to use. The virtual audio driver has been installed and is available in your audio device list. Click the microphone button to start real-time translation.

Troubleshooting

Microphone not working

If Sokuji can't access your microphone:
  1. Open System Preferences → Security & Privacy → Privacy
  2. Select Microphone from the left sidebar
  3. Make sure Sokuji is checked in the list
  4. If it's not listed, restart Sokuji and grant permission when prompted

No audio output

If you can't hear the translated audio:
  1. Open System Preferences → Sound → Output
  2. Select your preferred output device
  3. Check the output volume is not muted
  4. In Sokuji's Speech block, check the device of the row you expect to hear: I hear it too for your own translation (off by default), Translation I hear for the other side's, and the Default playback device for everything else

App crashes on Intel Macs or performance issues

Make sure you downloaded the correct installer for your Mac:
  • Apple Silicon (M1/M2/M3/M4): Use Sokuji-x.x.x-arm64.pkg
  • Intel: Use Sokuji-x.x.x-x64.pkg
  • Check your chip type: Apple menu () → "About This Mac"
  • If you used the wrong installer, download the correct version from the releases page
  • If crashes persist with the correct installer, check Console.app for crash logs and report them on GitHub

Virtual audio driver not showing up

If you don't see "SokujiVirtualAudio" in your audio devices:
  1. Let Sokuji repair it first: when the driver is installed but macOS has not loaded it, Sokuji says so at startup and offers Repair. Enter your administrator password and Sokuji restarts Core Audio to load the driver, with no restart of Sokuji needed
  2. Check if the driver is installed: ls /Library/Audio/Plug-Ins/HAL/
  3. If not present, you may need to reinstall Sokuji
  4. If present and Repair did not help, try restarting CoreAudio: sudo killall coreaudiod, or restart the Mac
  5. Check System Settings → Sound to see if the device appears

Installation requires administrator password

This is normal and required:
  • The PKG installer needs to install a system-level audio driver
  • System audio drivers require administrator privileges to install
  • Enter your password when prompted - this is safe and expected
  • If you don't have administrator access, contact your system administrator