Phraser

This is a personal fork of Melvynx/Parler by newblacc, which itself is a fork of cjpais/Handy. It adds custom features on top of the original while keeping full compatibility with upstream.

Custom Additions

• Conditional model switching: Automatically use a different (larger) model when audio recordings exceed a configurable duration threshold (default: 10 seconds). This lets you use a fast lightweight model for short recordings and a more accurate model for longer ones.
• Security dependency hardening: Updated Rust transitive dependencies in Cargo.lock to address current cargo audit vulnerability findings (bytes, rkyv, time).
• Stronger history-path validation: Hardened audio history file-name validation (including empty-name rejection) and expanded unit test coverage for history/settings command logic.
• Project quality gate hook: Added .project-hooks/pre-commit with format, lint, Rust check, and Rust test checks, plus documented usage in the README.
• Branding and app identity refresh: Updated repository and app identity to newblacc and regenerated the Tauri app icon set.
• Claude Desktop workflow defaults: Tuned speech output defaults and submit behavior for faster dictation-to-send workflows.

---

A free, open source, and extensible speech-to-text application that works completely offline.

Phraser is a cross-platform desktop application that provides simple, privacy-focused speech transcription. Press a shortcut, speak, and have your words appear in any text field. This happens on your own computer without sending any information to the cloud.

Why Phraser?

Phraser was created to fill the gap for a truly open source, extensible speech-to-text tool:

• Free: Accessibility tooling belongs in everyone's hands, not behind a paywall
• Open Source: Together we can build further. Extend Phraser for yourself and contribute to something bigger
• Private: Your voice stays on your computer. Get transcriptions without sending audio to the cloud
• Simple: One tool, one job. Transcribe what you say and put it into a text box

Phraser isn't trying to be the best speech-to-text app—it's trying to be the most forkable one.

How It Works

1. Press a configurable keyboard shortcut to start/stop recording (or use push-to-talk mode)
2. Speak your words while the shortcut is active
3. Release and Phraser processes your speech using Whisper
4. Get your transcribed text pasted directly into whatever app you're using

The process is entirely local:

• Silence is filtered using VAD (Voice Activity Detection) with Silero
• Transcription uses your choice of models:
  • Whisper models (Small/Medium/Turbo/Large) with GPU acceleration when available
  • Parakeet V3 - CPU-optimized model with excellent performance and automatic language detection
• Works on Windows, macOS, and Linux

Quick Start

Installation

1. Download the latest release from the releases page
2. Install the application
3. Launch Phraser and grant necessary system permissions (microphone, accessibility)
4. Configure your preferred keyboard shortcuts in Settings
5. Start transcribing!

Development Setup

For detailed build instructions including platform-specific requirements, see BUILD.md.

Create a local macOS app bundle from source:

bun run app:create

The generated app is placed at:

src-tauri/target/release/bundle/macos/Phraser.app

Quality & Security Checks

Before committing, run the same checks we used in the ship pipeline:

# Frontend/JS dependency audit
bun audit

# Rust dependency advisories
(cd src-tauri && cargo audit)

# Rust tests
(cd src-tauri && cargo test)

# Frontend build validation
bun run build

This repository also includes a local project hook:

.project-hooks/pre-commit

It runs formatting checks, frontend lint, Rust compile checks, and Rust tests. If you want to use it as your git hook for this repo:

git config core.hooksPath .project-hooks

Architecture

Phraser is built as a Tauri application combining:

• Frontend: React + TypeScript with Tailwind CSS for the settings UI
• Backend: Rust for system integration, audio processing, and ML inference
• Core Libraries:
  • whisper-rs: Local speech recognition with Whisper models
  • transcription-rs: CPU-optimized speech recognition with Parakeet models
  • cpal: Cross-platform audio I/O
  • vad-rs: Voice Activity Detection
  • rdev: Global keyboard shortcuts and system events
  • rubato: Audio resampling

Debug Mode

Phraser includes an advanced debug mode for development and troubleshooting. Access it by pressing:

• macOS: Cmd+Shift+D
• Windows/Linux: Ctrl+Shift+D

CLI Parameters

Phraser supports command-line flags for controlling a running instance and customizing startup behavior. These work on all platforms (macOS, Windows, Linux).

Remote control flags (sent to an already-running instance via the single-instance plugin):

phraser --toggle-transcription    # Toggle recording on/off
phraser --toggle-post-process     # Toggle recording with post-processing on/off
phraser --cancel                  # Cancel the current operation

Startup flags:

phraser --start-hidden            # Start without showing the main window
phraser --no-tray                 # Start without the system tray icon
phraser --debug                   # Enable debug mode with verbose logging
phraser --help                    # Show all available flags

Flags can be combined for autostart scenarios:

phraser --start-hidden --no-tray

macOS tip: When Phraser is installed as an app bundle, invoke the binary directly:

/Applications/Phraser.app/Contents/MacOS/Phraser --toggle-transcription

Known Issues & Current Limitations

This project is actively being developed and has some known issues. We believe in transparency about the current state:

Major Issues (Help Wanted)

Whisper Model Crashes:

• Whisper models crash on certain system configurations (Windows and Linux)
• Does not affect all systems - issue is configuration-dependent
  • If you experience crashes and are a developer, please help to fix and provide debug logs!

Wayland Support (Linux):

• Limited support for Wayland display server
• Requires wtype or dotool for text input to work correctly (see Linux Notes below for installation)

Linux Notes

Text Input Tools:

For reliable text input on Linux, install the appropriate tool for your display server:

Display Server	Recommended Tool	Install Command
X11	xdotool	sudo apt install xdotool
Wayland	wtype	sudo apt install wtype
Both	dotool	sudo apt install dotool (requires input group)

• X11: Install xdotool for both direct typing and clipboard paste shortcuts
• Wayland: Install wtype (preferred) or dotool for text input to work correctly
• dotool setup: Requires adding your user to the input group: sudo usermod -aG input $USER (then log out and back in)

Without these tools, Phraser falls back to enigo which may have limited compatibility, especially on Wayland.

Other Notes:

• Runtime library dependency (libgtk-layer-shell.so.0):

  • Phraser links gtk-layer-shell on Linux. If startup fails with error while loading shared libraries: libgtk-layer-shell.so.0, install the runtime package for your distro:

    Distro	Package to install	Example command
    Ubuntu/Debian	libgtk-layer-shell0	sudo apt install libgtk-layer-shell0
    Fedora/RHEL	gtk-layer-shell	sudo dnf install gtk-layer-shell
    Arch Linux	gtk-layer-shell	sudo pacman -S gtk-layer-shell

  • For building from source on Ubuntu/Debian, you may also need libgtk-layer-shell-dev.

• The recording overlay is disabled by default on Linux (Overlay Position: None) because certain compositors treat it as the active window. When the overlay is visible it can steal focus, which prevents Phraser from pasting back into the application that triggered transcription. If you enable the overlay anyway, be aware that clipboard-based pasting might fail or end up in the wrong window.

• If you are having trouble with the app, running with the environment variable WEBKIT_DISABLE_DMABUF_RENDERER=1 may help

• Global keyboard shortcuts (Wayland): On Wayland, system-level shortcuts must be configured through your desktop environment or window manager. Use the CLI flags as the command for your custom shortcut.

  GNOME:

  1. Open Settings > Keyboard > Keyboard Shortcuts > Custom Shortcuts
  2. Click the + button to add a new shortcut
  3. Set the Name to Toggle Phraser Transcription
  4. Set the Command to phraser --toggle-transcription
  5. Click Set Shortcut and press your desired key combination (e.g., Super+O)

  KDE Plasma:

  1. Open System Settings > Shortcuts > Custom Shortcuts
  2. Click Edit > New > Global Shortcut > Command/URL
  3. Name it Toggle Phraser Transcription
  4. In the Trigger tab, set your desired key combination
  5. In the Action tab, set the command to phraser --toggle-transcription

  Sway / i3:

  Add to your config file (~/.config/sway/config or ~/.config/i3/config):

  bindsym $mod+o exec phraser --toggle-transcription

  Hyprland:

  Add to your config file (~/.config/hypr/hyprland.conf):

  bind = $mainMod, O, exec, phraser --toggle-transcription

• You can also manage global shortcuts outside of Phraser via Unix signals, which lets Wayland window managers or other hotkey daemons keep ownership of keybindings:

  Signal	Action	Example
  SIGUSR2	Toggle transcription	pkill -USR2 -n phraser
  SIGUSR1	Toggle transcription with post-processing	pkill -USR1 -n phraser

  Example Sway config:

  bindsym $mod+o exec pkill -USR2 -n phraser
  bindsym $mod+p exec pkill -USR1 -n phraser

  pkill here simply delivers the signal—it does not terminate the process.

Platform Support

• macOS (both Intel and Apple Silicon)
• x64 Windows
• x64 Linux

System Requirements/Recommendations

The following are recommendations for running Phraser on your own machine. If you don't meet the system requirements, the performance of the application may be degraded. We are working on improving the performance across all kinds of computers and hardware.

For Whisper Models:

• macOS: M series Mac, Intel Mac
• Windows: Intel, AMD, or NVIDIA GPU
• Linux: Intel, AMD, or NVIDIA GPU
  • Ubuntu 22.04, 24.04

For Parakeet V3 Model:

• CPU-only operation - runs on a wide variety of hardware
• Minimum: Intel Skylake (6th gen) or equivalent AMD processors
• Performance: ~5x real-time speed on mid-range hardware (tested on i5)
• Automatic language detection - no manual language selection required

Roadmap & Active Development

We're actively working on several features and improvements. Contributions and feedback are welcome!

In Progress

Debug Logging:

• Adding debug logging to a file to help diagnose issues

macOS Keyboard Improvements:

• Support for Globe key as transcription trigger
• A rewrite of global shortcut handling for MacOS, and potentially other OS's too.

Opt-in Analytics:

• Collect anonymous usage data to help improve Phraser
• Privacy-first approach with clear opt-in

Settings Refactoring:

• Cleanup and refactor settings system which is becoming bloated and messy
• Implement better abstractions for settings management

Tauri Commands Cleanup:

• Abstract and organize Tauri command patterns
• Investigate tauri-specta for improved type safety and organization

Troubleshooting

Manual Model Installation (For Proxy Users or Network Restrictions)

If you're behind a proxy, firewall, or in a restricted network environment where Phraser cannot download models automatically, you can manually download and install them. The URLs are publicly accessible from any browser.

Step 1: Find Your App Data Directory

1. Open Phraser settings
2. Navigate to the About section
3. Copy the "App Data Directory" path shown there, or use the shortcuts:
   • macOS: Cmd+Shift+D to open debug menu
   • Windows/Linux: Ctrl+Shift+D to open debug menu

The typical paths are:

• macOS: ~/Library/Application Support/com.newblacc.phraser/
• Windows: C:\Users\{username}\AppData\Roaming\com.newblacc.phraser\
• Linux: ~/.config/com.newblacc.phraser/

Step 2: Create Models Directory

Inside your app data directory, create a models folder if it doesn't already exist:

# macOS/Linux
mkdir -p ~/Library/Application\ Support/com.newblacc.phraser/models

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\com.newblacc.phraser\models"

Step 3: Download Model Files

Download the models you want from below

Whisper Models (single .bin files):

• Small (487 MB): https://blob.handy.computer/ggml-small.bin
• Medium (492 MB): https://blob.handy.computer/whisper-medium-q4_1.bin
• Turbo (1600 MB): https://blob.handy.computer/ggml-large-v3-turbo.bin
• Large (1100 MB): https://blob.handy.computer/ggml-large-v3-q5_0.bin

Parakeet Models (compressed archives):

• V2 (473 MB): https://blob.handy.computer/parakeet-v2-int8.tar.gz
• V3 (478 MB): https://blob.handy.computer/parakeet-v3-int8.tar.gz

Step 4: Install Models

For Whisper Models (.bin files):

Simply place the .bin file directly into the models directory:

{app_data_dir}/models/
├── ggml-small.bin
├── whisper-medium-q4_1.bin
├── ggml-large-v3-turbo.bin
└── ggml-large-v3-q5_0.bin

For Parakeet Models (.tar.gz archives):

1. Extract the .tar.gz file
2. Place the extracted directory into the models folder
3. The directory must be named exactly as follows:
   • Parakeet V2: parakeet-tdt-0.6b-v2-int8
   • Parakeet V3: parakeet-tdt-0.6b-v3-int8

Final structure should look like:

{app_data_dir}/models/
├── parakeet-tdt-0.6b-v2-int8/     (directory with model files inside)
│   ├── (model files)
│   └── (config files)
└── parakeet-tdt-0.6b-v3-int8/     (directory with model files inside)
    ├── (model files)
    └── (config files)

Important Notes:

• For Parakeet models, the extracted directory name must match exactly as shown above
• Do not rename the .bin files for Whisper models—use the exact filenames from the download URLs
• After placing the files, restart Phraser to detect the new models

Step 5: Verify Installation

1. Restart Phraser
2. Open Settings → Models
3. Your manually installed models should now appear as "Downloaded"
4. Select the model you want to use and test transcription

Custom Whisper Models

Phraser can auto-discover custom Whisper GGML models placed in the models directory. This is useful for users who want to use fine-tuned or community models not included in the default model list.

How to use:

1. Obtain a Whisper model in GGML .bin format (e.g., from Hugging Face)
2. Place the .bin file in your models directory (see paths above)
3. Restart Phraser to discover the new model
4. The model will appear in the "Custom Models" section of the Models settings page

Important:

• Community models are user-provided and may not receive troubleshooting assistance
• The model must be a valid Whisper GGML format (.bin file)
• Model name is derived from the filename (e.g., my-custom-model.bin → "My Custom Model")

How to Contribute

1. Check existing issues at github.com/newblacc/Phraser/issues
2. Fork the repository and create a feature branch
3. Test thoroughly on your target platform
4. Submit a pull request with clear description of changes
5. Join the discussion on GitHub Issues

The goal is to create both a useful tool and a foundation for others to build upon—a well-patterned, simple codebase that serves the community.

Sponsors

We're grateful for the support of our sponsors who help make Phraser possible:

             

Related Projects

• Parler - The direct upstream fork Phraser is based on
• Handy - The original project by cjpais

License

MIT License - see LICENSE file for details.

Acknowledgments

• Whisper by OpenAI for the speech recognition model
• whisper.cpp and ggml for amazing cross-platform whisper inference/acceleration
• Silero for great lightweight VAD
• Tauri team for the excellent Rust-based app framework
• Community contributors helping make Phraser better

---

"Your search for the right speech-to-text tool can end here—not because Phraser is perfect, but because you can make it perfect for you."