OpenSuperWhisper Documentation

OpenSuperWhisper is a macOS application designed for real-time audio transcription using the Whisper model. It is optimized for Apple Silicon (ARM64) and provides several advanced features for seamless recording:

• Transcription Engines: Supports Whisper and Parakeet.
• Trigger Methods: Use global keyboard shortcuts (including single modifier keys like Left ⌘, Right ⌥, or Fn), mouse button triggers (middle or extra/thumb buttons), or a 'Hold-to-record' mode.
• Audio Input: Select between built-in, external, Bluetooth, or iPhone (via Apple Continuity) microphones from the menu bar.
• File Processing: Supports drag-and-drop audio files for queue-based transcription.
• Language Support: Includes auto-detection and Asian language autocorrect via autocorrect.

To integrate Whisper into a custom project, build it as a static library (.a). After building, you must move the resulting library file and the header files into your project directory. Ensure that you also include the C++ standard library and any other required libraries in your project's linking configuration.

cd ../.. && rm -rf build && mkdir build && cd build && cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DCMAKE_CXX_STANDARD=11 -DCMAKE_CXX_FLAGS="-fvisibility=hidden" -DWHISPER_BUILD_EXAMPLES=OFF -DWHISPER_BUILD_TESTS=OFF ..

make -j$(sysctl -n hw.ncpu)

You can install OpenSuperWhisper on macOS using Homebrew or by downloading a release from GitHub.

Using Homebrew:

brew update # Optional
brew install opensuperwhisper

Manual Installation: Download the latest release from the GitHub releases page.

To build the application from source, ensure you have the necessary dependencies installed and follow these steps:

1. Clone the repository and initialize submodules.
2. Install system dependencies via Homebrew (cmake, libomp, rust, ruby).
3. Install xcpretty via RubyGems.
4. Run the build script.

If you encounter build issues, refer to the .github/workflows/build.yml file to see the configuration used in the official GitHub CI workflow.

git clone git@github.com:Starmel/OpenSuperWhisper.git
cd OpenSuperWhisper
git submodule update --init --recursive
brew install cmake libomp rust ruby
gem install xcpretty
./run.sh build

OpenSuperWhisper uses Whisper model files (.bin).

• Automatic Setup: On the first launch, the app attempts to copy a default model automatically.
• Manual Setup: You can download additional .bin model files from the Whisper.cpp Hugging Face repository and place them manually in the app's models directory.
• Transcription Engines: The app supports both Whisper and Parakeet engines. Models can be downloaded directly within the application.

For optimized Hebrew transcription, use the "Turbo V3 Hebrew" model. This is a fine-tuned version of whisper-large-v3-turbo provided by ivrit.ai.

Setup Steps:

1. Navigate to Settings → Model within the app.
2. Download the "Turbo V3 Hebrew" model.
3. Selecting this model automatically sets the input language to Hebrew, which is a requirement for these specific models.

To use OpenRouter services with the agent, set the OPENROUTER_API_KEY environment variable. This key should follow the format sk-or-v1-....

OPENROUTER_API_KEY=sk-or-v1-your-key-here