# Speech-to-Speech CLI Commands: Complete Guide to the Hugging Face Toolkit

> Master Hugging Face speech-to-speech CLI commands. Explore run, demo, benchmark, and realtime options for seamless voice interaction. Get started now.

- Repository: [Hugging Face/speech-to-speech](https://github.com/huggingface/speech-to-speech)
- Tags: how-to-guide
- Published: 2026-08-11

---

**The Hugging Face `speech-to-speech` library provides seven primary CLI commands—`run`, `demo`, `benchmark-tts`, `benchmark-stt`, `realtime-server`, `synthetic-conversation-realtime-client`, and `install-smoke`—each exposed through the `speech-to-speech` entry point defined in [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py).**

The Speech-to-Speech CLI is a unified command-line interface for running end-to-end voice pipelines, benchmarking components, and deploying real-time servers. Once installed, the `speech-to-speech` entry point becomes available, using **argparse** to route commands to their respective implementations across the codebase.

## Core Speech-to-Speech CLI Commands

The CLI architecture in [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py) registers sub-commands through a standard argparse subparser pattern. Each command maps to a distinct operational mode of the system.

### `run` — Full Pipeline Execution

The `run` command orchestrates a complete **STT → LM → TTS** pipeline, connecting speech recognition, language modeling, and text-to-speech synthesis in real time.

Typical arguments include:
- `--stt <module>` — STT backend (e.g., `whisper`, `paraformer`)
- `--lm <module>` — Language model (e.g., `gpt4o`, `qwen3`)
- `--tts <module>` — TTS backend (e.g., `facebookmms`, `qwen3`)
- `--host` and `--port` — Network binding configuration

```bash
speech-to-speech run \
  --stt whisper \
  --lm gpt4o \
  --tts facebookmms \
  --host 0.0.0.0 --port 8000

```

Backend-specific arguments are loaded from files in `src/speech_to_speech/arguments_classes/`, such as [`whisper_stt_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/whisper_stt_arguments.py) and [`facebookmms_tts_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/facebookmms_tts_arguments.py).

### `demo` — Interactive Web Interface

The `demo` command launches a browser-based interface for testing the pipeline interactively. It wraps the Gradio server defined in [`demo/server.py`](https://github.com/huggingface/speech-to-speech/blob/main/demo/server.py).

```bash
speech-to-speech demo \
  --host 127.0.0.1 \
  --port 7860 \
  --cors-origins "*"

```

This is useful for rapid prototyping and user testing without writing custom client code.

### `benchmark-tts` — TTS Performance Testing

Measures throughput and latency for any TTS backend. Implemented in [`scripts/benchmark_tts.py`](https://github.com/huggingface/speech-to-speech/blob/main/scripts/benchmark_tts.py).

Key arguments:
- `--tts <module>` — Target TTS backend
- `--text-file <path>` — Input sentences for synthesis
- `--iterations <N>` — Number of benchmark cycles

```bash
speech-to-speech benchmark-tts \
  --tts facebookmms \
  --text-file examples/sample_sentences.txt \
  --iterations 100

```

### `benchmark-stt` — STT Performance Testing

Evaluates speech-to-text backend performance. Implemented in [`scripts/benchmark_stt.py`](https://github.com/huggingface/speech-to-speech/blob/main/scripts/benchmark_stt.py).

Key arguments:
- `--stt <module>` — Target STT backend
- `--audio-dir <path>` — Directory of test audio files
- `--iterations <N>` — Repetition count

```bash
speech-to-speech benchmark-stt \
  --stt whisper \
  --audio-dir test_audio/ \
  --iterations 50

```

### `realtime-server` — OpenAI-Compatible WebSocket Endpoint

Starts a server implementing the OpenAI Realtime API specification over WebSocket. Enables compatibility with existing OpenAI client libraries.

```bash
speech-to-speech realtime-server \
  --host 0.0.0.0 \
  --port 8001 \
  --model qwen3

```

Arguments for this command are defined in [`src/speech_to_speech/arguments_classes/realtime_server_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/arguments_classes/realtime_server_arguments.py).

### `synthetic-conversation-realtime-client` — Load Testing Tool

Runs an automated client that simulates conversational audio against a realtime server. Useful for stress testing and latency measurement. Implemented in [`scripts/synthetic_conversation_realtime_client.py`](https://github.com/huggingface/speech-to-speech/blob/main/scripts/synthetic_conversation_realtime_client.py).

```bash
speech-to-speech synthetic-conversation-realtime-client \
  --config scripts/synthetic_conversation_realtime_client.py \
  --duration 60

```

### `install-smoke` — Dependency Verification

Validates that the library and all optional dependencies install correctly. Takes no arguments.

```bash
speech-to-speech install-smoke

```

This command is referenced in [`tests/test_cli_defaults.py`](https://github.com/huggingface/speech-to-speech/blob/main/tests/test_cli_defaults.py) for CI validation.

## Global CLI Options

All sub-commands inherit common options defined at the top level of [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py):

- `--log-level` — Control verbosity (DEBUG, INFO, WARNING, ERROR)
- `--config` — Path to YAML configuration file for complex setups

These global options merge with backend-specific argument classes loaded dynamically from `src/speech_to_speech/arguments_classes/`.

## Argument Class Architecture

The CLI delegates parameter validation to typed argument classes:

| File | Backend Covered |
|------|---------------|
| [`whisper_stt_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/whisper_stt_arguments.py) | OpenAI Whisper STT |
| [`paraformer_stt_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/paraformer_stt_arguments.py) | Alibaba Paraformer STT |
| [`facebookmms_tts_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/facebookmms_tts_arguments.py) | Meta Facebook-MMS TTS |
| [`qwen3_tts_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/qwen3_tts_arguments.py) | Alibaba Qwen3 TTS |
| [`qwen3_lm_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/qwen3_lm_arguments.py) | Qwen3 language model |
| [`realtime_server_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/realtime_server_arguments.py) | OpenAI-compatible realtime server |

Each file defines a dataclass or argparse group that the main CLI imports and attaches to the relevant sub-command.

## Testing and Validation

The test suite in [`tests/test_cli_defaults.py`](https://github.com/huggingface/speech-to-speech/blob/main/tests/test_cli_defaults.py) validates:

- All sub-commands register without import errors
- Default argument values are correctly assigned
- Required dependencies are checked before execution

Run tests with:

```bash
pytest tests/test_cli_defaults.py -v

```

## Summary

- **Seven CLI commands** provide coverage for pipeline execution (`run`), interactive testing (`demo`), benchmarking (`benchmark-tts`, `benchmark-stt`), production deployment (`realtime-server`), load testing (`synthetic-conversation-realtime-client`), and installation verification (`install-smoke`)

- **Entry point** `speech-to-speech` is defined in [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py) using standard argparse subparsers

- **Modular arguments** are sourced from `src/speech_to_speech/arguments_classes/` for each backend component

- **Global options** like `--log-level` and `--config` apply across all sub-commands

## Frequently Asked Questions

### How do I see all available CLI commands for Speech-to-Speech?

Run `speech-to-speech --help` to list registered sub-commands. Each sub-command also supports `--help` for its specific arguments, populated dynamically from the corresponding argument class in `src/speech_to_speech/arguments_classes/`.

### Where are CLI arguments defined for specific backends like Whisper or Facebook-MMS?

Backend-specific arguments live in `src/speech_to_speech/arguments_classes/`. For example, Whisper STT options are in [`whisper_stt_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/whisper_stt_arguments.py), while Facebook-MMS TTS uses [`facebookmms_tts_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/facebookmms_tts_arguments.py). The main CLI discovers and attaches these at runtime.

### Can I run the Speech-to-Speech pipeline without the CLI?

Yes. The CLI in [`src/speech_to_speech/cli.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/cli.py) is a thin wrapper around underlying classes. Import modules directly from `src/speech_to_speech/` and instantiate STT, LM, and TTS components programmatically. The CLI primarily handles argument parsing and dependency injection.

### What is the difference between `run` and `realtime-server` commands?

**`run`** launches a full local pipeline (STT → LM → TTS) as a single process. **`realtime-server`** starts a WebSocket server compatible with OpenAI's Realtime API, designed for client-server architectures where audio streams arrive from remote connections.