How to Change the Default ASR Engine in VoiceStudio

VoiceStudio uses the asr_backend preference key defined in services/asr_backend.py to determine which Automatic Speech Recognition engine loads, defaulting to pytorch-whisper unless you override it via the UI preferences, CLI commands, or the OMNIVOICE_ASR_BACKEND environment variable.

VoiceStudio provides flexible configuration options for its Automatic Speech Recognition (ASR) pipeline, allowing you to change the default ASR engine to suit your performance or accuracy requirements. Whether you prefer the graphical interface, command-line tools, or direct configuration file editing, the repository's modular architecture in debpalash/VoiceStudio makes switching backends straightforward.

Where VoiceStudio Defines the Default ASR Engine

VoiceStudio determines which ASR backend to load by reading the asr_backend preference key at startup. The registry of available backends and the selection logic reside in [services/asr_backend.py](https://github.com/debpalash/VoiceStudio/blob/main/services/asr_backend.py), where the function active_backend_id() queries the settings store and falls back to pytorch-whisper if no user override exists. The test suite in [tests/test_engines.py](https://github.com/debpalash/VoiceStudio/blob/main/tests/test_engines.py) (lines 220-270) validates this backend resolution behavior.

The settings store itself is implemented in [services/settings_store.py](https://github.com/debpalash/VoiceStudio/blob/main/services/settings_store.py) as a thin wrapper around a JSON configuration file. When you change the default ASR engine in VoiceStudio, you are ultimately modifying the value associated with the asr_backend key in this persistent store located at ~/.config/voice-studio/settings.json.

Changing the ASR Engine Through the User Interface

The simplest method to change the default ASR engine involves the graphical preferences panel. Navigate to Settings ▶ Preferences, locate the "ASR Engine" dropdown, and select your desired backend such as moonshine, sherpa-zipformer, or funasr.

Clicking Save persists the selection to the asr_backend key immediately. The system uses this value for all subsequent transcription tasks without requiring a manual restart of the application.

Changing the Default ASR Engine via CLI and Configuration Files

For headless environments or automation scripts, VoiceStudio provides command-line access to the same preference system.

Using the Command-Line Interface

The CLI entry point in [scripts/cli.py](https://github.com/debpalash/VoiceStudio/blob/main/scripts/cli.py) implements a prefs subcommand that writes directly to the settings store. Execute the following to switch backends:

voice-studio prefs set asr_backend moonshine

Replace moonshine with any installed backend identifier. This command updates the JSON configuration file immediately and persists the change for future sessions.

Editing the Configuration File Directly

The raw configuration lives at ~/.config/voice-studio/settings.json. Open this file in a text editor and modify the asr_backend entry:

{
  "asr_backend": "moonshine"
}

Save the file and restart VoiceStudio to apply the change. This approach is useful when batch-configuring deployments or recovering from corrupted settings.

Switching ASR Backends Programmatically in Python

You can manipulate the active backend directly from Python code using the settings store API. This method is ideal for plugin development or runtime configuration changes.

To permanently change the default and force an immediate reload:

from services import settings_store as _prefs
from services import asr_backend as ab

# Persist the new default

_prefs.set_("asr_backend", "moonshine")

# Force reload (optional; next transcription will auto-reload)

ab.reload_active_asr_backend()

To verify which engine is currently active without performing transcription:

from services import asr_backend as ab

print("Active ASR backend ID:", ab.active_backend_id())

# Output: moonshine

To enumerate all installed backends available for selection:

from services import asr_backend as ab

print("Installed ASR backends:", ab.list_backends())

# Returns: [('pytorch-whisper', ...), ('moonshine', ...), ('sherpa-zipformer', ...)]

Temporary Environment Variable Overrides

For temporary switches—particularly useful in CI pipelines or containerized runs—set the OMNIVOICE_ASR_BACKEND environment variable before launching VoiceStudio.

export OMNIVOICE_ASR_BACKEND=sherpa-zipformer
voice-studio

The services/asr_backend.py module checks this variable early in the startup chain via the load_active_asr_backend() helper. This override affects only the current session and does not modify the persistent settings.json file, making it ideal for automated testing scenarios.

Summary

• VoiceStudio stores the default ASR engine preference under the asr_backend key, defaulting to pytorch-whisper when no user preference exists.
• The configuration mechanism is implemented in [services/asr_backend.py](https://github.com/debpalash/VoiceStudio/blob/main/services/asr_backend.py) and persisted via [services/settings_store.py](https://github.com/debpalash/VoiceStudio/blob/main/services/settings_store.py) to ~/.config/voice-studio/settings.json.
• You can change the engine through the Settings ▶ Preferences UI, the voice-studio prefs set CLI command defined in scripts/cli.py, or by editing the JSON configuration directly.
• Use the OMNIVOICE_ASR_BACKEND environment variable for temporary, session-only overrides that do not alter the saved configuration.
• The Python API exposes active_backend_id(), set_(), and reload_active_asr_backend() for runtime inspection and manipulation of the ASR pipeline.

Frequently Asked Questions

What is the default ASR engine in VoiceStudio?

The built-in default is pytorch-whisper, as defined in the active_backend_id() function within services/asr_backend.py. This value is used when no user preference has been set or when the configuration file is missing.

Where does VoiceStudio store the ASR backend preference?

The preference is stored as the asr_backend key in a JSON file located at ~/.config/voice-studio/settings.json. This file is managed by the settings_store.py module, which provides a thin abstraction over the raw JSON storage.

Can I switch ASR engines without restarting VoiceStudio?

Yes, when using the Python API. After calling _prefs.set_("asr_backend", "new-engine"), you can invoke ab.reload_active_asr_backend() to force the system to load the new backend immediately. Changes made via the UI typically apply to the next transcription task without requiring a full application restart.

How do I list all available ASR backends in VoiceStudio?

Import the asr_backend module and call ab.list_backends(), which returns a list of tuples containing the backend identifiers and their metadata. This is useful for scripting installations or verifying that a specific engine like moonshine or sherpa-zipformer is properly registered in the system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}