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

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.

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 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

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 and 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.

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.

Key arguments:

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

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.

Key arguments:

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

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.

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.

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.

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.

speech-to-speech install-smoke

This command is referenced in 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:

• --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	OpenAI Whisper STT
paraformer_stt_arguments.py	Alibaba Paraformer STT
facebookmms_tts_arguments.py	Meta Facebook-MMS TTS
qwen3_tts_arguments.py	Alibaba Qwen3 TTS
qwen3_lm_arguments.py	Qwen3 language model
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 validates:

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

Run tests with:

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 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, while Facebook-MMS TTS uses 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 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.

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