> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# User Mute Strategies

> Control when user input is suppressed during bot operations

## Overview

User mute strategies control whether incoming user input should be suppressed based on the current system state. They determine when user audio and transcriptions should be muted to prevent interruptions during critical bot operations like initial responses or function calls.

By default, user input is never muted. You can configure mute strategies to automatically suppress user input in specific scenarios, such as while the bot is speaking or during function execution. Custom strategies can also be implemented for specific use cases.

## Configuration

User mute strategies are configured via `LLMUserAggregatorParams` when creating an `LLMContextAggregatorPair`:

```python theme={null}
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.turns.user_mute import (
    MuteUntilFirstBotCompleteUserMuteStrategy,
    FunctionCallUserMuteStrategy,
)

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_mute_strategies=[
            MuteUntilFirstBotCompleteUserMuteStrategy(),
            FunctionCallUserMuteStrategy(),
        ],
    ),
)
```

## Available Strategies

### AlwaysUserMuteStrategy

Mutes user input whenever the bot is speaking. This prevents any interruptions during bot speech.

```python theme={null}
from pipecat.turns.user_mute import AlwaysUserMuteStrategy

strategy = AlwaysUserMuteStrategy()
```

**Behavior:**

* Mutes when `BotStartedSpeakingFrame` is received
* Unmutes when `BotStoppedSpeakingFrame` is received

### FirstSpeechUserMuteStrategy

Mutes user input only during the bot's first speech. After the initial response completes, user input is allowed even while the bot is speaking.

```python theme={null}
from pipecat.turns.user_mute import FirstSpeechUserMuteStrategy

strategy = FirstSpeechUserMuteStrategy()
```

**Behavior:**

* Allows user input before bot speaks
* Mutes during the first bot speech only
* Unmutes permanently after first speech completes

<Note>
  Use this strategy when you want to ensure the bot's greeting or initial
  response isn't interrupted, but allow normal interruptions afterward.
</Note>

### MuteUntilFirstBotCompleteUserMuteStrategy

Mutes user input from the start of the interaction until the bot completes its first speech. This ensures the bot maintains full control at the beginning of a conversation.

```python theme={null}
from pipecat.turns.user_mute import MuteUntilFirstBotCompleteUserMuteStrategy

strategy = MuteUntilFirstBotCompleteUserMuteStrategy()
```

**Behavior:**

* Mutes immediately when the pipeline starts (before bot speaks)
* Remains muted until first `BotStoppedSpeakingFrame` is received
* Unmutes permanently after first speech completes

<Note>
  Unlike `FirstSpeechUserMuteStrategy`, this strategy mutes user input even
  before the bot starts speaking. Use this when you don't want to process any
  user input until the bot has delivered its initial message.
</Note>

### FunctionCallUserMuteStrategy

Mutes user input while function calls are executing. This prevents user interruptions during potentially long-running tool operations.

```python theme={null}
from pipecat.turns.user_mute import FunctionCallUserMuteStrategy

strategy = FunctionCallUserMuteStrategy()
```

**Behavior:**

* Mutes when `FunctionCallsStartedFrame` is received
* Tracks multiple concurrent function calls
* Unmutes when all function calls complete (via `FunctionCallResultFrame` or `FunctionCallCancelFrame`)

<Tip>
  This strategy is particularly useful when function calls trigger external API
  requests or database operations that may take several seconds to complete and
  you don't want to the user to interrupt the output.
</Tip>

## Combining Multiple Strategies

Multiple strategies can be combined in a list. The strategies are combined with OR logic—if **any** strategy indicates the user should be muted, user input is suppressed.

```python theme={null}
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_mute_strategies=[
            MuteUntilFirstBotCompleteUserMuteStrategy(),  # Mute until first response
            FunctionCallUserMuteStrategy(),               # Mute during function calls
        ],
    ),
)
```

In this example, user input is muted:

* From pipeline start until the bot completes its first speech
* Whenever function calls are executing (even after first speech)

## Usage Examples

### Prevent Interruptions During Greeting

Ensure the bot's greeting plays completely before accepting user input:

```python theme={null}
from pipecat.turns.user_mute import MuteUntilFirstBotCompleteUserMuteStrategy

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_mute_strategies=[
            MuteUntilFirstBotCompleteUserMuteStrategy(),
        ],
    ),
)
```

### Mute During Function Calls Only

Allow normal interruptions but prevent them during tool execution:

```python theme={null}
from pipecat.turns.user_mute import FunctionCallUserMuteStrategy

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_mute_strategies=[
            FunctionCallUserMuteStrategy(),
        ],
    ),
)
```

### Never Allow Interruptions

Always mute user input while the bot is speaking:

```python theme={null}
from pipecat.turns.user_mute import AlwaysUserMuteStrategy

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_mute_strategies=[
            AlwaysUserMuteStrategy(),
        ],
    ),
)
```

## Building Custom Strategies

For custom mute strategies, see the [User Input Muting guide](/pipecat/fundamentals/user-input-muting#building-custom-strategies), which covers the `BaseUserMuteStrategy` contract, frame visibility, and worked examples.

## Event Handlers

You can register event handlers to be notified when user muting starts or stops. This is useful for observability or providing feedback to users.

### Available Events

#### on\_user\_mute\_started

Called when user input becomes muted due to any active mute strategy.

```python theme={null}
@user_aggregator.event_handler("on_user_mute_started")
async def on_user_mute_started(aggregator):
    logger.info("User mute started")
```

#### on\_user\_mute\_stopped

Called when user input is unmuted (no active mute strategies).

```python theme={null}
@user_aggregator.event_handler("on_user_mute_stopped")
async def on_user_mute_stopped(aggregator):
    logger.info("User mute stopped")
```

<Note>
  These events fire whenever the mute state changes, regardless of which
  strategy triggered the change. Use them to provide consistent feedback across
  all mute scenarios.
</Note>

## Related

* [User Turn Strategies](/api-reference/server/utilities/turn-management/user-turn-strategies) - Configure turn detection behavior
* [User Input Muting Guide](/pipecat/fundamentals/user-input-muting) - Guide for controlling user input