Skip to content
Get packs

Guide · Agent skill

How to use the sherpa-onnx-tts agent skill for local speech

Updated · written with AI from the project's own documentation and checked against our catalogue data

The sherpa-onnx-tts skill lets an AI agent write spoken audio from text as a WAV file on your own computer, without sending the text to a cloud service. It is aimed at creators who want private narration drafts, and at developers who need offline speech output. By the end of this guide you will know what the skill does, how to install it, how to point it at its runtime and voice model, and how to ask the agent for audio.

Local Text-to-Speechspinabot/brigade · MIT

Quick start

  1. 1Install the skill folder. Unzip the skill into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload the ZIP under Settings, Capabilities, Skills.
  2. 2Download the runtime. Get the sherpa-onnx runtime for your OS from the k2-fsa/sherpa-onnx GitHub releases and extract it into the tools/sherpa-onnx-tts/runtime folder.
  3. 3Download the voice model. Get the Piper en_US lessac (high) model and extract it into the tools/sherpa-onnx-tts/models folder.
  4. 4Set the config paths. Add SHERPA_ONNX_RUNTIME_DIR and SHERPA_ONNX_MODEL_DIR under skills, entries, sherpa-onnx-tts in your Brigade config file.
  5. 5Run a test. Run the wrapper with -o and a quoted sentence, then open the WAV file to check the output.

What a skill is and what this one does

An agent skill is a folder containing a SKILL.md file and any supporting scripts. When a skill is installed, the agent can read its instructions and use its tools when a request matches what the skill is for.

This skill is a local text-to-speech tool. It runs a bundled wrapper command, which uses the open-source sherpa-onnx speech engine and a downloadable voice model to generate a WAV file on your machine.

  • Works on macOS, Linux and Windows.
  • Generates audio offline once the runtime and voice model are in place.
  • Uses a single English (US) Piper voice model, the en_US lessac (high) voice.
  • Licence: MIT.

Install the skill folder

Download the skill ZIP from this page and unzip it. You can install it in one of two ways.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. Alternatively, upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills

Download the runtime and a voice model

The skill needs two downloads. The runtime is the sherpa-onnx program for your operating system, fetched from the k2-fsa/sherpa-onnx GitHub releases. The voice model is the Piper en_US lessac (high) model, fetched from the same project's tts-models release.

By default the runtime extracts into ~/.brigade/tools/sherpa-onnx-tts/runtime and the model into ~/.brigade/tools/sherpa-onnx-tts/models. If you set BRIGADE_STATE_DIR, the paths use that folder instead. Resolve the state directory first with this line:

  • macOS: universal build of the runtime
  • Linux: x64 build of the runtime
  • Windows: x64 build of the runtime
  • Voice model: vits-piper-en_US-lessac-high
STATE_DIR="${BRIGADE_STATE_DIR:-$HOME/.brigade}"

Point the skill at the runtime and model

Write the resolved paths into your Brigade config file. This is $BRIGADE_CONFIG_PATH if it is set, otherwise ~/.brigade/brigade.json. Under skills, entries, sherpa-onnx-tts, add an env block with two values: SHERPA_ONNX_RUNTIME_DIR pointing at the runtime folder, and SHERPA_ONNX_MODEL_DIR pointing at the lessac model folder. Replace the placeholder paths with your real ones.

Optionally, add the wrapper folder to your PATH so you can run it by name. Otherwise run it by its full path inside the skill folder.

  • Replace /path/to/your/state-dir with your actual state directory.
  • The model folder is the vits-piper-en_US-lessac-high folder inside models.
{ skills: { entries: { "sherpa-onnx-tts": { env: { SHERPA_ONNX_RUNTIME_DIR: "/path/to/your/state-dir/tools/sherpa-onnx-tts/runtime", SHERPA_ONNX_MODEL_DIR: "/path/to/your/state-dir/tools/sherpa-onnx-tts/models/vits-piper-en_US-lessac-high" } } } } }

Run the wrapper to create a WAV file

The wrapper is called sherpa-onnx-tts and lives in the bin folder of the skill. Pass an output path with -o and the text in quotes. The example below writes tts.wav to the current folder.

On Windows, run the wrapper with node instead. The source gives this as its Windows example.

  • If the model folder contains more than one .onnx file, set SHERPA_ONNX_MODEL_FILE or pass --model-file.
  • You can override the defaults with --tokens-file or --data-dir.
  • To try another voice, pick a different model from the sherpa-onnx tts-models release.
{baseDir}/bin/sherpa-onnx-tts -o ./tts.wav "Hello from local TTS."

Safety notes: scripts and network

This skill runs scripts. The wrapper executes the sherpa-onnx runtime on your machine, so review the skill folder before installing it if you do not know its source.

The skill uses the network during setup. The install steps download large archives from GitHub. After the runtime and model are in place, the source describes generation as offline, and the text is not sent to a cloud service.

  • Downloads come from GitHub, so expect large files and a wait.
  • Audio is written to the output path you give.

What people use it for

  • Drafting narration or voiceover scripts as WAV files you can review privately.
  • Generating short spoken prompts for an app or agent during development without a per-request fee.
  • Creating audio versions of notes or documents on a machine where text should not leave the device.

Frequently asked questions

How do I install the sherpa-onnx-tts skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills. Then download the runtime and voice model and set the config paths.

What do I need to run it?

You need the sherpa-onnx runtime for your OS, the Piper en_US lessac (high) voice model, the environment variables SHERPA_ONNX_RUNTIME_DIR and SHERPA_ONNX_MODEL_DIR, and a Brigade config file to store the paths. Node.js is needed for the Windows usage example.

Is it free, and what licence does it use?

The skill is listed under the MIT licence. The source does not state prices, and it does not mention per-request charges, so check the terms of the sherpa-onnx runtime and the voice model before commercial use.

Does it send my text to the cloud?

The skill describes itself as offline with no cloud. The network is used to download the runtime and model during setup, and the wrapper generates audio locally.

Can I use a different voice?

Yes, you can pick another model from the sherpa-onnx tts-models release. The skill is set up around the single English (US) Piper voice, so other voices may need more configuration. If the model folder has several .onnx files, set SHERPA_ONNX_MODEL_FILE or pass --model-file.

What if the skill does not work or the paths are wrong?

Check that the two environment variables point at the runtime folder and the vits-piper-en_US-lessac-high model folder in your Brigade config file. If there are several .onnx files, set SHERPA_ONNX_MODEL_FILE or pass --model-file. Confirm your OS is macOS, Linux or Windows, since other systems are not supported.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you want private, offline English narration on macOS, Linux or Windows and you are comfortable editing a config file and setting paths. Pick something else if you need expressive, emotional or multilingual voices, or a one-click install.

Download the skill