Quickstart: Get started with the Azure AI Speech CLI

In this article, you learn how to use the Azure AI Speech CLI (also called SPX) to access Speech services such as speech to text, text to speech, and speech translation, without having to write any code. The Speech CLI is production ready, and you can use it to automate simple workflows in the Speech service by using .bat or shell scripts.

This article assumes that you have working knowledge of the Command Prompt window, terminal, or PowerShell.

Note

In PowerShell, the stop-parsing token (--%) should follow spx. For example, run spx --% config @region to view the current region config value.

Download and install

Windows

Follow these steps to install the Speech CLI on Windows:

1. Install the Microsoft Visual C++ Redistributable for Visual Studio 2019 for your platform. Installing it for the first time might require a restart.

2. Install .NET 6.

3. Install the Speech CLI via the .NET CLI by entering this command:

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   To update the Speech CLI, enter this command:

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

Enter spx or spx help to see help for the Speech CLI.

Font limitations

On Windows, the Speech CLI can show only fonts that are available to the command prompt on the local computer. Windows Terminal supports all fonts that the Speech CLI produces interactively.

If you output to a file, a text editor like Notepad or a web browser like Microsoft Edge can also show all fonts.

Linux

The following Linux distributions are supported for x64 architectures that use the Speech CLI:

• Ubuntu 20.04/22.04/24.04
• Debian 11/12

Note

The Speech SDK (not the Speech CLI) supports additional architectures. For more information, see About the Speech SDK.

Follow these steps to install the Speech CLI on Linux on an x64 CPU:

1. Install the .NET 6.

2. Install the Speech CLI via the .NET CLI by entering this command:

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   To update the Speech CLI, enter this command:

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

3. Install GStreamer for compressed audio support.

Enter spx to see help for the Speech CLI.

macOS

Follow these steps to install the Speech CLI on macOS 10.14 or later:

1. Install .NET 6.

2. Install the Speech CLI via the .NET CLI by entering this command:

   dotnet tool install --global Microsoft.CognitiveServices.Speech.CLI
   

   To update the Speech CLI, enter this command:

   dotnet tool update --global Microsoft.CognitiveServices.Speech.CLI
   

Enter spx or spx help to see help for the Speech CLI.

Docker (Windows, Linux, macOS)

The following example pulls a public container image from Docker Hub. We recommend that you authenticate with your Docker Hub account (docker login) first instead of making an anonymous pull request. To improve reliability when you're using public content, import and manage the image in a private Azure container registry. Learn more about working with public images.

Follow these steps to install the Speech CLI in a Docker container:

1. Install Docker Desktop for your platform if it isn't already installed.
2. In a new command prompt or terminal, enter this command:

   docker pull msftspeech/spx
   

Enter this command to display help information for the Speech CLI:

docker run -it --rm msftspeech/spx help

Mount a directory in the container

The Speech CLI tool saves configuration settings as files. It loads these files when you're performing any command (except help commands).

When you're using the Speech CLI within a Docker container, you must mount a local directory from the container, so the tool can:

• Store or find the configuration settings.
• Read or write any files that the command requires, such as audio files of speech.

On Windows, enter this command to create a local directory that the Speech CLI can use from within the container:

mkdir c:\spx-data

On Linux or macOS, enter this command in a terminal to create a directory and see its absolute path:

mkdir ~/spx-data
cd ~/spx-data
pwd

You'll use the absolute path when you call the Speech CLI.

Run the Speech CLI in the container

This documentation shows the Speech CLI spx command used in non-Docker installations. When you're calling the spx command in a Docker container, you must mount a directory in the container to your file system where the Speech CLI can store and find configuration values and read and write files.

On Windows, your commands start like this:

docker run -it -v c:\spx-data:/data --rm msftspeech/spx

On Linux or macOS, your commands look like the following sample. Replace ABSOLUTE_PATH with the absolute path for your mounted directory. The pwd command returned this path in the previous section. If you run this command before setting your key and region, you'll get an error that tells you to set your key and region.

sudo docker run -it -v ABSOLUTE_PATH:/data --rm msftspeech/spx

To use the spx command installed in a container, always enter the full command as shown in the preceding sample, followed by the parameters of your request. For example, on Windows, this command sets your key:

docker run -it -v c:\spx-data:/data --rm msftspeech/spx config @key --set SUBSCRIPTION-KEY

For more extended interaction with the command-line tool, you can start a container with an interactive Bash shell by adding an entrypoint parameter. On Windows, enter this command to start a container that exposes an interactive command-line interface where you can enter multiple spx commands:

docker run -it --entrypoint=/bin/bash -v c:\spx-data:/data --rm msftspeech/spx

You can combine that with AZ Login and have SPX Init guide you through creating the speech keys and selecting a matching data region without having to use the Azure portal. The keys will automatically be stored for later use.

docker run -it --rm --entrypoint /bin/bash -v c:\spx-data:/data msftspeech/spx

az login
spx init

Create a resource configuration

Terminal

To get started, you need a Speech resource key and region identifier (for example, eastus, westus). Create a Speech resource on the Azure portal. For more information, see Create an Azure AI services resource.

To configure your resource key and region identifier, run the following commands:

spx config @key --set SPEECH-KEY
spx config @region --set SPEECH-REGION

The key and region are stored for future Speech CLI commands. To view the current configuration, run the following commands:

spx config @key
spx config @region

As needed, include the clear option to remove either stored value:

spx config @key --clear
spx config @region --clear

PowerShell

To get started, you need a Speech resource key and region identifier (for example, eastus, westus). Create a Speech resource on the Azure portal.

To configure your Speech resource key and region identifier, run the following commands in PowerShell:

spx --% config @key --set SPEECH-KEY
spx --% config @region --set SPEECH-REGION

The key and region are stored for future SPX commands. To view the current configuration, run the following commands:

spx --% config @key
spx --% config @region

As needed, include the clear option to remove either stored value:

spx --% config @key --clear
spx --% config @region --clear

Basic usage

Important

When you use the Speech CLI in a container, include the --host option. You must also specify --key none to ensure that the CLI doesn't try to use a Speech key for authentication. For example, run spx recognize --key none --host wss://localhost:5000/ --file myaudio.wav to recognize speech from an audio file in a speech to text container.

This section shows a few basic SPX commands that are often useful for first-time testing and experimentation. Run the following command to view the in-tool help:

spx

You can search help topics by keyword. For example, to see a list of Speech CLI usage examples, run the following command:

spx help find --topics "examples"

To see options for the recognize command, run the following command:

spx help recognize

More help commands are listed in the console output. You can enter these commands to get detailed help about subcommands.

Speech to text (speech recognition)

Note

You can't use your computer's microphone when you run the Speech CLI within a Docker container. However, you can read from and save audio files in your local mounted directory.

To convert speech to text (speech recognition) by using your system's default microphone, run the following command:

spx recognize --microphone

After you run the command, SPX begins listening for audio on the current active input device. It stops listening when you select Enter. The spoken audio is then recognized and converted to text in the console output.

With the Speech CLI, you can also recognize speech from an audio file. Run the following command:

spx recognize --file /path/to/file.wav

Tip

If you get stuck or want to learn more about the Speech CLI recognition options, you can run spx help recognize.

Text to speech (speech synthesis)

The following command takes text as input and then outputs the synthesized speech to the current active output device (for example, your computer speakers).

spx synthesize --text "Testing synthesis using the Speech CLI" --speakers

You can also save the synthesized output to a file. In this example, let's create a file named my-sample.wav in the directory where you're running the command.

spx synthesize --text "Enjoy using the Speech CLI." --audio output my-sample.wav

These examples presume that you're testing in English. However, Speech service supports speech synthesis in many languages. You can pull down a full list of voices either by running the following command or by visiting the language support page.

spx synthesize --voices

Here's a command for using one of the voices you discovered.

spx synthesize --text "Bienvenue chez moi." --voice fr-FR-AlainNeural --speakers

Tip

If you get stuck or want to learn more about the Speech CLI recognition options, you can run spx help synthesize.

Speech to text translation

With the Speech CLI, you can also do speech to text translation. Run the following command to capture audio from your default microphone and output the translation as text. Keep in mind that you need to supply the source and target language with the translate command.

spx translate --microphone --source en-US --target ru-RU

When you're translating into multiple languages, separate the language codes with a semicolon (;).

spx translate --microphone --source en-US --target 'ru-RU;fr-FR;es-ES'

If you want to save the output of your translation, use the --output flag. In this example, you also read from a file.

spx translate --file /some/file/path/input.wav --source en-US --target ru-RU --output file /some/file/path/russian_translation.txt

Tip

If you get stuck or want to learn more about the Speech CLI recognition options, you can run spx help translate.

Next steps

• Install GStreamer to use the Speech CLI with MP3 and other formats
• Configuration options for the Speech CLI
• Batch operations with the Speech CLI