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

> Learn how to configure live transcription for multi-pipeline deployments on macOS. Avoid MLX global lock issues by managing single pipeline instances or disabling live transcription.

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

---

**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`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/STT/parakeet_tdt_handler.py) to stream transcriptions without resource conflicts.

```bash
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.

```bash
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`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/s2s_pipeline.py) (lines 622-628) with arguments defined in [`module_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/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`](https://github.com/huggingface/speech-to-speech/blob/main/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.