VoiceSnap: Deployment and Usage Guide

This guide provides comprehensive instructions for deploying and using VoiceSnap, an open-source offline voice dictation tool.

1. Prerequisites

For Users

• Windows 10/11: No specific prerequisites beyond the operating system.
• Windows 7: No specific prerequisites beyond the operating system.
• macOS: macOS 10.15 (Catalina) or newer.

For Developers

• Go: Version 1.22+ (Go 1.20 for Windows 7 build).
• Node.js: Version 20+.
• CGO Compiler:
  • Windows: LLVM MinGW UCRT.
  • macOS: Xcode Command Line Tools.

2. Installation

For Users

1. Download: Obtain the latest release from the VoiceSnap Releases page.
2. Extract/Install:
   • Windows 10/11: Download the .zip archive, extract its contents to any directory, and double-click voicesnap.exe.
   • Windows 7: Download the dedicated VoiceSnap_Setup.exe (a 7z self-extracting archive), and double-click it to extract and run.
   • macOS: Open the downloaded .dmg file and drag VoiceSnap.app into your Applications folder.
3. Initial Setup:
   • On first launch, VoiceSnap will automatically download the required SenseVoice speech model (~152 MB). Ensure you have an internet connection for this one-time download.
   • macOS only: You will be prompted to grant accessibility permissions for VoiceSnap to function correctly. Follow the system prompts to enable this in System Settings.
4. Ready: Once the model is downloaded and the application is running, a VoiceSnap icon will appear in your system tray (Windows) or menu bar (macOS).

For Developers

1. Clone the Repository:

   git clone https://github.com/vorojar/VoiceSnap.git
   cd VoiceSnap/VoiceSnapGo
   

2. Install Frontend Dependencies:

   cd frontend && npm install && cd ..
   

3. Configuration

VoiceSnap is designed to be largely plug-and-play with minimal configuration. Most settings are managed through the application's graphical interface.

• Hotkey: The default hotkey for dictation is Right Ctrl on Windows and Right Command on macOS. This can be customized within the application settings.
• Microphone: You can select your preferred audio input device from a dropdown menu in the settings.
• Recording Sound Effects: Marimba-style prompt sounds are enabled by default and can be toggled off in settings.
• Autostart: VoiceSnap can be configured to launch automatically when your system starts.
• Model Download: The ~152 MB SenseVoice model is automatically downloaded on the first run. No manual configuration is required for this.
• Overlay Position: The floating indicator's position can be dragged and will be remembered across sessions.

4. Build & Run

Development Mode

To run VoiceSnap in development mode (with live reloading for frontend changes):

# Ensure you are in the VoiceSnapGo directory
cd VoiceSnap/VoiceSnapGo
wails dev

Production Build

Windows (10/11)

# Ensure you are in the VoiceSnapGo directory
cd VoiceSnap/VoiceSnapGo
windres voicesnap.rc -o voicesnap.syso
CGO_ENABLED=1 go build -ldflags "-H windowsgui -s -w" -o voicesnap.exe .

This will generate voicesnap.exe in the VoiceSnapGo directory.

macOS

# Ensure you are in the VoiceSnapGo directory
cd VoiceSnap/VoiceSnapGo
CGO_ENABLED=1 go build -o voicesnap .

This will generate an executable voicesnap in the VoiceSnapGo directory. For a full .app bundle, you would typically use wails build which handles packaging.

Windows 7 (Specialized Build)

The Windows 7 version uses a different project structure (VoiceSnapWin7) and Go 1.20.

# Navigate to the Windows 7 specific project directory
cd VoiceSnap/VoiceSnapWin7

# Compile the resource file
windres voicesnap.rc -o voicesnap.syso

# Build the executable using Go 1.20
# Replace /path/to/go1.20 with your Go 1.20 installation path
GOROOT=/path/to/go1.20 CGO_ENABLED=1 go build -ldflags "-H windowsgui -s -w" -o voicesnap_win7.exe .

# Generate the 7z self-extracting package
bash build_sfx.sh portable

This will produce voicesnap_win7.exe and then package it into a self-extracting 7z archive.

5. Deployment

VoiceSnap is designed as a standalone desktop application, not a server-side service. "Deployment" in this context refers to distributing the compiled application to end-users.

Distribution to Users

1. Build Production Binaries: Follow the "Production Build" steps above for your target operating system (Windows 10/11, Windows 7, macOS).
2. Package for Distribution:
   • Windows 10/11: The voicesnap.exe (and associated onnxruntime.dll, sherpa-onnx-c-api.dll, sherpa-onnx-cxx-api.dll) should be bundled together. The models/sensevoice/ directory will be downloaded on first run. You can provide these files in a .zip archive.
   • Windows 7: Use the build_sfx.sh portable script to create the VoiceSnap_Setup.exe self-extracting archive, which includes all necessary DLLs.
   • macOS: Use wails build -platform darwin/amd64 -output VoiceSnap.app (or similar for arm64) to create a .app bundle, which can then be packaged into a .dmg for easy distribution.
3. Release: Upload the packaged binaries to a platform like GitHub Releases for public access.

VoiceSnap is 100% local and requires no internet connection after the initial model download, making it suitable for air-gapped or classified environments.

6. Troubleshooting

Common Issues and Solutions

• Model Download Failure:
  • Issue: VoiceSnap fails to download the SenseVoice model on first launch.
  • Solution: Ensure your device has an active internet connection. Check firewall settings to ensure VoiceSnap is not blocked from accessing the internet for the initial download.
• Hotkey Not Working:
  • Issue: Pressing the hotkey does not initiate recording.
  • Solution:
    1. Verify VoiceSnap is running and the icon is visible in the system tray/menu bar.
    2. Check VoiceSnap settings to confirm the correct hotkey is configured.
    3. Ensure no other application is conflicting with the chosen hotkey. Try changing the hotkey in VoiceSnap settings.
    4. macOS: Confirm VoiceSnap has been granted "Accessibility" permissions in System Settings > Privacy & Security > Accessibility.
• No Audio Input/Recognition:
  • Issue: VoiceSnap records but doesn't recognize speech, or the volume bars don't react.
  • Solution:
    1. In VoiceSnap settings, select the correct microphone from the dropdown list.
    2. Check your system's sound settings to ensure the microphone is enabled, not muted, and has adequate input volume.
    3. Ensure your microphone is properly connected and functioning.
• "Application is already running" Error:
  • Issue: Attempting to launch VoiceSnap results in a message indicating it's already running.
  • Solution: VoiceSnap is designed to run as a single instance. Check your system tray (Windows) or menu bar (macOS) for the VoiceSnap icon. If it's there, the application is already active. You can right-click the icon to open settings or exit.
• Overlay Indicator Not Appearing/Dragging:
  • Issue: The floating recording indicator doesn't show up or cannot be dragged.
  • Solution:
    1. Ensure VoiceSnap is running. The indicator only appears during active recording.
    2. Restart VoiceSnap.
    3. Windows: Check for display scaling issues. VoiceSnap's indicator is DPI adaptive, but extreme or unusual scaling might cause rendering glitches.
• Windows 7 Specific Issues:
  • Issue: The standard voicesnap.exe for Windows 10/11 does not run on Windows 7.
  • Solution: You must use the VoiceSnap_Setup.exe version specifically built for Windows 7. This version includes additional compatibility components.
• Slow Recognition / High CPU Usage:
  • Issue: Recognition is slow, or the application consumes excessive CPU.
  • Solution: VoiceSnap leverages DirectML for GPU acceleration on Windows. Ensure your graphics drivers are up to date. If no compatible GPU is found, it will fall back to CPU, which might be slower depending on your processor. macOS uses Core ML or CPU.