← Back to Documentation

macOS Installation Guide

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

Download for macOS

System Requirements

  • macOS 10.15 (Catalina) or later
  • 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.

The PKG installer is unsigned, which means you'll need to take special steps to install it (covered in the next step).

Step 2: Prepare for Installation

Because the PKG installer is unsigned, macOS will block it by default. You need to remove the quarantine attribute before installation.

Remove Quarantine Attribute (Required)

  1. Open Terminal (Applications → Utilities → Terminal)
  2. Type or paste the following command (replace x.x.x with your version number):

    sudo xattr -d com.apple.quarantine ~/Downloads/Sokuji-x.x.x-arm64.pkg

    For Intel Macs, use: sudo xattr -d com.apple.quarantine ~/Downloads/Sokuji-x.x.x-x64.pkg

  3. Press Enter and type your administrator password when prompted
  4. The command will complete silently (no output means success)

What does this do? This command removes the quarantine flag that macOS adds to downloaded files. It's safe and necessary for unsigned PKG installers.

This step is critical! Without removing the quarantine attribute, the PKG installer will fail to open or install.

Step 3: Install PKG

Now that you've prepared the installer, you can 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 4: First Launch

After installation, you may need to grant Sokuji permission to run since it's downloaded from outside the App Store.

Opening Sokuji for the First Time

  1. Navigate to your Applications folder
  2. Find Sokuji in the list
  3. Right-click (or Control-click) on Sokuji
  4. Select "Open" from the context menu
  5. When the security dialog appears, click "Open" to confirm

Note: If you completed Step 2 correctly, you may not see any security warnings.

Alternative Method

If macOS still blocks Sokuji:
  1. Open System Preferences → Security & Privacy
  2. Go to the General tab
  3. You should see a message about Sokuji being blocked
  4. Click "Open Anyway"
This security warning only appears on first launch. After that, you can open Sokuji normally from Launchpad or Applications.

Step 5: 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. Choose your audio devices (you should see "Sokuji Virtual Audio" in the list)
  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

"The package is damaged and can't be opened" or PKG won't install

This happens when the quarantine attribute hasn't been removed from the PKG file:
  1. Open Terminal (Applications → Utilities → Terminal)
  2. Run: sudo xattr -d com.apple.quarantine ~/Downloads/Sokuji-*.pkg
  3. Enter your password when prompted
  4. Try installing the PKG again
This is the most common installation issue with unsigned PKG installers.

"Sokuji can't be opened because it is from an unidentified developer"

This happens if you didn't run the xattr command before installing:
  1. Right-click the Sokuji app in Applications
  2. Select "Open" from the menu
  3. Click "Open" in the dialog that appears
You only need to do this once. Better approach: uninstall and reinstall after removing the quarantine attribute.

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, verify the correct output device is selected

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 "Sokuji Virtual Audio" in your audio devices:
  1. Check if the driver is installed: ls /Library/Audio/Plug-Ins/HAL/
  2. If not present, you may need to reinstall Sokuji
  3. If present, try restarting CoreAudio: sudo killall coreaudiod
  4. Check System Preferences → 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