# How to Change the Default ASR Engine in VoiceStudio

> Learn how to change the default ASR engine in VoiceStudio. Customize your speech recognition backend using UI preferences, CLI commands, or environment variables for optimal performance.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: how-to-guide
- Published: 2026-09-10

---

**VoiceStudio uses the `asr_backend` preference key defined in [`services/asr_backend.py`](https://github.com/debpalash/VoiceStudio/blob/main/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)](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)](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)](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)](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:

```bash
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:

```json
{
  "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:

```python
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:

```python
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:

```python
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.

```bash
export OMNIVOICE_ASR_BACKEND=sherpa-zipformer
voice-studio

```

The [`services/asr_backend.py`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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)](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)](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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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.