Overview

In conversational applications, there are moments when you don’t want to process user speech, such as during bot introductions or while executing function calls. Pipecat’s STTMuteFilter lets you selectively “mute” user input based on different conversation states.

When to Use STTMuteFilter

Common scenarios for muting user input include:

  • During introductions: Prevent the bot from being interrupted during its initial greeting
  • While processing functions: Block input while the bot is retrieving external data
  • During bot speech: Reduce false transcriptions while the bot is speaking
  • For guided conversations: Create more structured interactions with clear turn-taking

How It Works

The STTMuteFilter works by blocking specific user-related frames from flowing through your pipeline. When muted, it filters:

  • Voice activity detection (VAD) events
  • Interruption signals
  • Raw audio input frames

This prevents the Speech-to-Text service from receiving and processing the user’s speech during muted periods.

The filter must be placed between your Transport and STT service in the pipeline to work correctly.

Mute Strategies

The STTMuteFilter supports several strategies for determining when to mute user input:

FIRST_SPEECH

Mute only during the bot’s first speech utterance. Useful for introductions when you want the bot to complete its greeting before the user can speak.

MUTE_UNTIL_FIRST_BOT_COMPLETE

Start muted and remain muted until the first bot utterance completes. Ensures the bot’s initial instructions are fully delivered.

FUNCTION_CALL

Mute during function calls. Prevents users from speaking while the bot is processing external data requests.

ALWAYS

Mute whenever the bot is speaking. Creates a strict turn-taking conversation pattern.

CUSTOM

Use custom logic via callback to determine when to mute. Provides maximum flexibility for complex muting rules.

The FIRST_SPEECH and MUTE_UNTIL_FIRST_BOT_COMPLETE strategies should not be used together as they handle the first bot speech differently.

Basic Implementation

Step 1: Configure the Filter

First, create a configuration for the STTMuteFilter:

from pipecat.processors.filters.stt_mute_filter import STTMuteConfig, STTMuteFilter, STTMuteStrategy

# Configure with one or more strategies
stt_mute_processor = STTMuteFilter(
    config=STTMuteConfig(
        strategies={
            STTMuteStrategy.MUTE_UNTIL_FIRST_BOT_COMPLETE,
            STTMuteStrategy.FUNCTION_CALL,
        }
    ),
)

Step 2: Add to Your Pipeline

Place the filter between your transport input and STT service:

pipeline = Pipeline(
    [
        transport.input(),           # Transport user input
        stt_mute_processor,          # Add the mute processor before STT
        stt,                         # Speech-to-text service
        context_aggregator.user(),   # User responses
        llm,                         # LLM
        tts,                         # Text-to-speech
        transport.output(),          # Transport bot output
        context_aggregator.assistant(),  # Assistant spoken responses
    ]
)

Best Practices

  • Place the filter correctly: Always position STTMuteFilter between transport input and STT
  • Choose strategies wisely: Select the minimal set of strategies needed for your use case
  • Test user experience: Excessive muting can frustrate users; balance control with usability
  • Consider feedback: Provide visual cues when the user is muted to improve the experience

Next Steps

Experiment with different muting strategies to find the right balance for your application. For advanced scenarios, try implementing custom muting logic based on specific conversation states or content.