How to Configure Live Transcription for Multi-Pipeline Deployments on macOS

To configure live transcription for multi-pipeline deployments on macOS, you must either restrict the deployment to a single pipeline instance or explicitly disable live transcription when running multiple pipelines, due to MLX global lock contention on Apple Silicon.

The huggingface/speech-to-speech library supports real-time progressive speech-to-text through the enable_live_transcription flag, but macOS deployments face unique constraints when scaling beyond single-pipeline configurations. The MLX inference engine utilizes a global lock mechanism that creates resource contention when multiple pipeline instances attempt concurrent access, forcing specific configuration patterns for stable operation.

Understanding the MLX Lock Contention on macOS

On Apple Silicon (darwin), the library implements a global MLX lock in src/speech_to_speech/utils/mlx_lock.py to manage exclusive access to the inference engine. When you configure multiple pipelines using --num_pipelines greater than 1, this lock becomes a critical contention point.

The core pipeline runner detects this conflict in src/speech_to_speech/s2s_pipeline.py within the run_pipeline_command() function (lines 622-628). On macOS, when args.module_kwargs.num_pipelines > 1, the library automatically disables live transcription to prevent dropped work and maintain clean logs. This safeguard ensures that the progressive STT path does not attempt to share the MLX lock across concurrent pipeline instances.

Configuration Options for Live Transcription

You have two distinct configuration paths depending on your concurrency requirements and real-time transcription needs.

Option 1: Single Pipeline with Live Transcription Enabled

To maintain live transcription capabilities, restrict your deployment to a single pipeline instance. This configuration avoids MLX lock contention entirely, allowing the progressive STT handler in src/speech_to_speech/STT/parakeet_tdt_handler.py to stream transcriptions without resource conflicts.

speech-to-speech serve --mac-optimal-settings \
    --num_pipelines 1 \
    --enable_live_transcription true

Option 2: Multiple Pipelines with Live Transcription Disabled

When you require higher concurrency through multiple pipelines, you must disable live transcription. While the library automatically applies this behavior on macOS when --num_pipelines exceeds 1, you should explicitly set the flag for clarity.

speech-to-speech serve --mac-optimal-settings \
    --num_pipelines 4 \
    --enable_live_transcription false

The enable_live_transcription argument is defined in src/speech_to_speech/arguments_classes/module_arguments.py (lines 53-58) as part of the ModuleArguments class.

Automatic Disabling Behavior

If you omit the --enable_live_transcription flag while running multiple pipelines on macOS, the library intervenes automatically. The run_pipeline_command() function checks for darwin platform detection and pipeline count, then generates a log message explaining the restriction:

MLX contention: --num_pipelines=4 > 1 on Apple Silicon → disabling live transcription (progressive STT contends on the global MLX lock)

You cannot override this automatic disabling while maintaining multiple pipelines. The only method to suppress this behavior and retain live transcription is keeping --num_pipelines at 1.

Summary

• MLX global lock: The utils/mlx_lock.py implementation creates unavoidable contention on Apple Silicon when multiple pipelines attempt concurrent inference.
• Single-pipeline requirement: Live transcription requires --num_pipelines 1 on macOS to prevent lock conflicts.
• Explicit configuration: Set --enable_live_transcription false when running multiple pipelines for clarity, though the library auto-disables it.
• Source locations: The logic resides in s2s_pipeline.py (lines 622-628) with arguments defined in module_arguments.py (lines 53-58).

Frequently Asked Questions

Why does live transcription disable automatically on macOS with multiple pipelines?

The progressive STT implementation cannot safely share the global MLX lock across multiple pipeline instances. According to the source code in s2s_pipeline.py, the library detects when --num_pipelines exceeds 1 on darwin and automatically disables live transcription to prevent dropped work and resource contention.

Can I force live transcription with multiple pipelines on Apple Silicon?

No. The MLX lock contention makes it unsafe to run progressive STT across multiple concurrent pipelines. You must choose between a single pipeline with live transcription enabled or multiple pipelines with the feature disabled. There is no configuration override to bypass this restriction.

Where is the live transcription logic implemented in the codebase?

The enabling logic resides in src/speech_to_speech/arguments_classes/module_arguments.py where enable_live_transcription is defined. The runtime enforcement occurs in src/speech_to_speech/s2s_pipeline.py within run_pipeline_command(). The actual streaming handler implementation lives in src/speech_to_speech/STT/parakeet_tdt_handler.py.

What is the default behavior for live transcription on macOS?

When running a single pipeline (--num_pipelines 1), live transcription functions normally if enabled. However, when multiple pipelines are configured on macOS, the library automatically disables live transcription regardless of the flag setting, logging a notification about MLX contention to inform you of the configuration change.

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