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:

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.

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.

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

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

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.

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

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.

FunctionCallUserMuteStrategy

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

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)

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.

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.

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:

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:

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:

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

@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).

@user_aggregator.event_handler("on_user_mute_stopped")
async def on_user_mute_stopped(aggregator):
    logger.info("User mute stopped")

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.

Related

• User Turn Strategies - Configure turn detection behavior
• User Input Muting Guide - Guide for controlling user input