Migrating from the Deprecated `--mode` Flag to `serve`, `talk`, and `local` Commands in Hugging Face Speech-to-Speech

The Hugging Face Speech-to-Speech CLI has replaced the legacy --mode flag with explicit sub-commands: use serve instead of --mode realtime, local instead of --mode local, and the new talk command for connecting audio clients to realtime endpoints.

The huggingface/speech-to-speech repository recently restructured its command-line interface to improve clarity and extensibility. If you are migrating from the deprecated --mode flag to the modern sub-command structure, this guide explains the architectural changes in src/speech_to_speech/cli.py and provides exact replacements for your existing scripts.

From Flags to Commands: The New CLI Structure

The Legacy --mode Flag

Previously, users selected operation modes using a top-level --mode flag accepting values like realtime or local. This approach consolidated disparate functionalities under a single entry point, limiting flexibility as the toolkit expanded to support new interaction patterns.

The New Sub-command Architecture

The updated CLI introduces three distinct sub-commands that replace the old flag-based system:

• serve: Runs the Realtime pipeline server (replaces --mode realtime)
• local: Executes the server and audio client together over a loop-back interface (replaces --mode local)
• talk: Connects a microphone and speakers to a Realtime endpoint (new functionality without legacy equivalent)

How the CLI Handles Legacy Mode Migration

In src/speech_to_speech/cli.py, the migration logic preserves backward compatibility while guiding users toward the new interface through explicit parsing stages.

Legacy Mode Extraction

The _extract_legacy_mode function (lines 33-59) scans the raw sys.argv list before sub-parser invocation. It detects single occurrences of --mode or --mode=value, removes the flag from the argument list, and returns the discovered mode for subsequent mapping. This extraction prevents the top-level parser from failing when it encounters the deprecated flag.

Command Mapping and Deprecation Warnings

The _LEGACY_MODE_COMMANDS dictionary maps legacy modes to modern commands:

• realtime → serve
• local → local

When a legacy mode is detected, the CLI prints a deprecation warning to stderr (lines 73-86), informing users of the upcoming removal and recommending the specific replacement command. This warning appears every time the legacy syntax is used, ensuring users notice the required changes.

Error Handling for Invalid Usage

The parser validates legacy mode usage strictly to prevent ambiguity. Supplying --mode multiple times, without a value, or with an unsupported mode (such as socket) triggers immediate parser errors with clear messages pointing to the new command structure. These validation rules are verified in tests/test_cli_defaults.py (lines 16-24).

Practical Migration Examples

Replace your existing commands according to the following patterns.

Realtime server migration:

# Old (deprecated) - emits warning to stderr

speech-to-speech --mode realtime --host 0.0.0.0 --port 8080

# New equivalent

speech-to-speech serve --host 0.0.0.0 --port 8080

Local loop-back migration:

# Old (deprecated)

speech-to-speech --mode local --local_audio_input_device 1

# New equivalent

speech-to-speech local --local_audio_input_device 1

New talk command:

The talk command has no legacy equivalent. It utilizes RealtimeAudioClientConfig from src/speech_to_speech/api/openai_realtime/audio_client.py to stream audio:

speech-to-speech talk --url wss://example.com/realtime --model gpt-audio-1.5

Key Source Files and Implementation Details

Understanding the source code helps clarify the migration path:

• src/speech_to_speech/cli.py: Contains the main parser setup with three sub-parsers (lines 26-30), the _extract_legacy_mode function for backward compatibility, and the warning emission logic.
• tests/test_cli_defaults.py: Validates that legacy modes map correctly to new commands and that appropriate warnings are emitted when deprecated syntax is detected.
• src/speech_to_speech/api/openai_realtime/audio_client.py: Defines RealtimeAudioClientConfig, which powers the new talk command's audio streaming capabilities.

Why Migrate to Sub-commands?

The architectural shift from flags to commands delivers three primary benefits for the speech-to-speech toolkit:

• Self-documenting interface: Command names explicitly state the operation intent, eliminating ambiguity about whether you are starting a server or connecting a client.
• Extensibility: Adding future capabilities (such as batch processing or configuration management) requires new sub-commands rather than overloading a single flag with complex validation logic.
• Clearer error messages: The sub-parser architecture provides immediate, actionable feedback when arguments are missing or incorrect, rather than generic "invalid mode" errors.

Summary

• Replace --mode realtime with the serve sub-command to start the Realtime pipeline server.
• Replace --mode local with the local sub-command for loop-back server-client operation.
• Use the new talk sub-command to connect audio devices to existing Realtime endpoints.
• The _extract_legacy_mode function in src/speech_to_speech/cli.py temporarily preserves backward compatibility but emits deprecation warnings to stderr.
• Update scripts immediately, as the legacy --mode flag will be removed in future releases according to the project's deprecation timeline.

Frequently Asked Questions

What happened to the --mode flag in Speech-to-Speech?

The --mode flag has been deprecated in favor of explicit sub-commands (serve, talk, local). While the CLI still accepts the flag for backward compatibility via the _extract_legacy_mode function, it prints a deprecation warning to stderr and internally maps the value to the appropriate modern command.

How do I migrate a script that uses --mode realtime?

Change speech-to-speech --mode realtime [args] to speech-to-speech serve [args]. All previously supported arguments for the realtime server remain compatible with the serve sub-command, as the underlying s2s_pipeline.py implementation remains unchanged.

Is the --mode flag still supported?

Yes, but only temporarily. The _LEGACY_MODE_COMMANDS mapping in src/speech_to_speech/cli.py processes the flag and redirects it to new commands while emitting a warning. Future versions will remove this compatibility layer entirely, causing the parser to reject --mode as an unrecognized argument.

What is the talk command used for?

The talk command connects local microphone and speaker devices to a remote or local Realtime endpoint using RealtimeAudioClientConfig. This functionality did not exist in the legacy --mode system and provides a dedicated client interface separate from the server operations managed by serve and local.

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