User Input Muting with STTMuteFilter
Learn how to control when user speech is processed in your conversational bot
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
:
Step 2: Add to Your Pipeline
Place the filter between your transport input and STT service:
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
Try the STTMuteFilter Example
Explore a complete working example that demonstrates how to use STTMuteFilter to control user input during bot speech and function calls.
STTMuteFilter Reference
Read the complete API reference documentation for advanced configuration options and muting strategies.
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.