Changelog entry for lazy import fix

Move the LocalSmartTurnAnalyzerV3 import from module level into
__post_init__ so that importing user_turn_strategies no longer eagerly
loads the transformers package. This eliminates the spurious PyTorch
was not found warning for users who don't use the smart turn analyzer.

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "attribution": {
+    "commit": ""
+  }
+}

.claude/skills/changelog/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: changelog
+description: Create changelog files for important commits in a PR
+---
+
+Create changelog files for the important commits in this PR. The PR number is provided as an argument.
+
+## Instructions
+
+1. Skip changelog for: documentation-only, internal refactoring, test-only, CI changes.
+
+2. First, check what commits are on the current branch compared to main:
+   ```
+   git log main..HEAD --oneline
+   ```
+
+3. For each significant change, create a changelog file in the `changelog/` folder using the format:
+   Allowed types: `added`, `changed`, `deprecated`, `removed`, `fixed`, `security`, `performance`, `other`
+   - `{PR_NUMBER}.added.md` - for new features
+   - `{PR_NUMBER}.added.2.md`, `{PR_NUMBER}.added.3.md` - for additional entries of the same type
+   - `{PR_NUMBER}.changed.md` - for changes to existing functionality
+   - `{PR_NUMBER}.fixed.md` - for bug fixes
+   - `{PR_NUMBER}.deprecated.md` - for deprecations
+   - `{PR_NUMBER}.removed.md` - for removed features
+   - `{PR_NUMBER}.security.md` - for security fixes
+   - `{PR_NUMBER}.performance.md` - for performance improvements
+   - `{PR_NUMBER}.other.md` - for other changes
+
+4. Each changelog file should at least contain a main single line starting with `- ` followed by a clear description of the change. No line wrapping.
+
+5. If the change is complicated, changelog files can have indented lines after the main line with additional details or code samples.
+
+6. Use ⚠️ emoji prefix for breaking changes.
+
+## Example
+
+For PR #3519 with a new feature and a bug fix:
+
+`changelog/3519.added.md`:
+```
+- Added `SomeNewFeature` for doing something useful.
+```
+
+`changelog/3519.fixed.md`:
+```
+- Fixed an issue where something was not working correctly.
+```

.claude/skills/cleanup/SKILL.md

@@ -0,0 +1,307 @@
+# Code Cleanup Skill
+
+The **Code Cleanup Skill** reviews, refactors, and documents code changes in your current branch, ensuring alignment with **Pipecat’s architecture, coding standards, and example patterns**.
+It focuses on **readability, correctness, performance, and consistency**, while avoiding breaking changes.
+
+---
+
+## Skill Overview
+
+This skill analyzes all changes introduced in your branch and performs the following actions:
+
+1. **Analyze Branch Changes**
+   - Review uncommitted changes and outgoing commits
+2. **Refactor for Readability**
+   - Improve clarity, naming, structure, and modern Python usage
+3. **Enhance Performance**
+   - Identify safe, conservative optimization opportunities
+4. **Add Documentation**
+   - Apply Pipecat-style, Google-format docstrings
+5. **Ensure Pattern Consistency**
+   - Match existing Pipecat services, pipelines, and examples
+6. **Validate Examples**
+   - Ensure examples follow foundational patterns (e.g. `07-interruptible.py`)
+
+---
+
+## Usage
+
+Invoke the skill using any of the following commands:
+
+- “Clean up my branch code”
+- “Refactor the changes in my branch”
+- “Review and improve my branch code”
+- `/cleanup`
+
+---
+
+## What This Skill Does
+
+### 1. Analyze Branch Changes
+
+The skill retrieves all uncommitted changes and outgoing commits to understand:
+
+- New files added
+- Modified files
+- Code additions and deletions
+- Overall scope and intent of changes
+
+---
+
+### 2. Code Refactoring
+
+#### Readability Improvements
+
+- Replace tuples with named classes or dataclasses
+- Improve variable, method, and class naming
+- Extract complex logic into well-named helper methods
+- Add missing type hints
+- Simplify nested or complex conditionals
+- Replace deprecated methods and features
+- Normalize formatting to match Pipecat style
+
+#### Performance Enhancements
+
+- Identify inefficient loops or repeated work
+- Suggest appropriate data structures
+- Optimize async workflows and I/O
+- Remove redundant operations
+
+> Performance changes are conservative and non-breaking.
+
+---
+
+### 3. Documentation
+
+Documentation follows **Google-style docstrings**, consistent with Pipecat conventions.
+
+#### Class Documentation
+
+```python
+class ExampleService:
+    """Brief one-line description.
+
+    Detailed explanation of the class purpose, responsibilities,
+    and important behaviors.
+
+    Supported features:
+
+    - Feature 1
+    - Feature 2
+    - Feature 3
+    """
+```
+
+#### Method Documentation
+
+```python
+def process_data(self, data: str, options: Optional[dict] = None) -> bool:
+    """Process incoming data with optional configuration.
+
+    Args:
+        data: The input data to process.
+        options: Optional configuration dictionary.
+
+    Returns:
+        True if processing succeeded, False otherwise.
+
+    Raises:
+        ValueError: If data is empty or invalid.
+    """
+```
+
+#### Pydantic Model Parameters
+
+```python
+class InputParams(BaseModel):
+    """Configuration parameters for the service.
+
+    Parameters:
+        timeout: Request timeout in seconds.
+        retry_count: Number of retry attempts.
+        enable_logging: Whether to enable debug logging.
+    """
+
+    timeout: Optional[float] = None
+    retry_count: int = 3
+    enable_logging: bool = False
+```
+
+---
+
+### 4. Pattern Consistency Checks
+
+#### Service Classes
+
+- Correct inheritance (`TTSService`, `STTService`, `LLMService`)
+- Consistent constructor signatures
+- Frame emission patterns
+- Metrics support:
+  - `can_generate_metrics()`
+  - TTFB metrics
+  - Usage metrics
+- Alignment with similar existing services
+
+#### Examples
+
+Validated against `examples/foundational/07-interruptible.py`:
+
+- Proper `create_transport()` usage
+- Correct pipeline structure
+- Task setup and observers
+- Event handler registration
+- Runner and bot entrypoint consistency
+
+---
+
+### 5. Specific Implementation Patterns
+
+#### Service Implementation
+
+```python
+class ExampleTTSService(TTSService):
+
+    def __init__(self, *, api_key: Optional[str] = None, **kwargs):
+        super().__init__(**kwargs)
+        self._api_key = api_key or os.getenv("SERVICE_API_KEY")
+
+    def can_generate_metrics(self) -> bool:
+        return True
+
+    async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
+        try:
+            await self.start_ttfb_metrics()
+            yield TTSStartedFrame()
+            # ... processing ...
+            yield TTSAudioRawFrame(...)
+        finally:
+            await self.stop_ttfb_metrics()
+```
+
+---
+
+#### Example Structure Pattern
+
+```python
+transport_params = {
+    "daily": lambda: DailyParams(...),
+    "twilio": lambda: FastAPIWebsocketParams(...),
+    "webrtc": lambda: TransportParams(...),
+}
+
+async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
+    stt = DeepgramSTTService(...)
+    tts = SomeTTSService(...)
+    llm = OpenAILLMService(...)
+
+    context = LLMContext(messages)
+    user_aggregator, assistant_aggregator = LLMContextAggregatorPair(...)
+
+    pipeline = Pipeline([...])
+    task = PipelineTask(pipeline, params=..., observers=[...])
+
+    @transport.event_handler("on_client_connected")
+    async def on_client_connected(transport, client):
+        await task.queue_frames([LLMRunFrame()])
+
+    runner = PipelineRunner(handle_sigint=runner_args.handle_sigint)
+    await runner.run(task)
+
+async def bot(runner_args: RunnerArguments):
+    """Main bot entry point compatible with Pipecat Cloud."""
+    transport = await create_transport(runner_args, transport_params)
+    await run_bot(transport, runner_args)
+```
+
+---
+
+## Execution Flow
+
+1. Fetch uncommitted and outgoing changes
+2. Categorize files (services, examples, tests, utilities)
+3. Analyze each file:
+   - Readability
+   - Performance
+   - Documentation
+   - Pattern consistency
+4. Generate actionable recommendations
+5. Apply Pipecat standards
+
+---
+
+## Examples
+
+### Before: Tuple Usage
+
+```python
+def get_audio_info(self) -> Tuple[int, int]:
+    return (48000, 1)
+```
+
+### After: Named Class
+
+```python
+class AudioInfo:
+    """Audio configuration information.
+
+    Parameters:
+        sample_rate: Sample rate in Hz.
+        num_channels: Number of audio channels.
+    """
+
+    sample_rate: int
+    num_channels: int
+
+def get_audio_info(self) -> AudioInfo:
+    return AudioInfo(sample_rate=48000, num_channels=1)
+```
+
+---
+
+### Before: Missing Documentation
+
+```python
+class NewTTSService(TTSService):
+    def __init__(self, api_key: str, voice: str):
+        self._api_key = api_key
+        self._voice = voice
+```
+
+### After: Fully Documented
+
+```python
+class NewTTSService(TTSService):
+    """Text-to-speech service using NewProvider API.
+
+    Streams PCM audio and emits TTSAudioRawFrame frames compatible
+    with Pipecat transports.
+
+    Supported features:
+    - Text-to-speech synthesis
+    - Streaming PCM audio
+    - Voice customization
+    - TTFB metrics
+    """
+
+    def __init__(self, *, api_key: str, voice: str, **kwargs):
+        """Initialize the NewTTSService.
+
+        Args:
+            api_key: API key for authentication.
+            voice: Voice identifier to use.
+            **kwargs: Additional arguments passed to the parent service.
+        """
+        super().__init__(**kwargs)
+        self._api_key = api_key
+        self.set_voice(voice)
+```
+
+---
+
+## Notes
+
+- Non-breaking improvements only
+- Backward compatibility preserved
+- Conservative performance changes
+- Google-style docstrings
+- Pattern checks follow recent Pipecat code

.claude/skills/code-review/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: code-review
+description: Automated code review for pull requests using multiple specialized agents
+disable-model-invocation: true
+allowed-tools: Bash(gh issue view:*), Bash(gh search:*), Bash(gh issue list:*), Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*), Bash(gh pr list:*)
+---
+
+Provide a code review for the given pull request.
+
+**Agent assumptions (applies to all agents and subagents):**
+
+- All tools are functional and will work without error. Do not test tools or make exploratory calls. Make sure this is clear to every subagent that is launched.
+- Only call a tool if it is required to complete the task. Every tool call should have a clear purpose.
+
+To do this, follow these steps precisely:
+
+1. Launch a haiku agent to check if any of the following are true:
+   - The pull request is closed
+   - The pull request is a draft
+   - The pull request does not need code review (e.g. automated PR, trivial change that is obviously correct)
+   - Claude has already commented on this PR (check `gh pr view <PR> --comments` for comments left by claude)
+
+   If any condition is true, stop and do not proceed.
+
+Note: Still review Claude generated PR's.
+
+2. Launch a haiku agent to return a list of file paths (not their contents) for all relevant CLAUDE.md files including:
+   - The root CLAUDE.md file, if it exists
+   - Any CLAUDE.md files in directories containing files modified by the pull request
+
+3. Launch a sonnet agent to view the pull request and return a summary of the changes
+
+4. Launch 4 agents in parallel to independently review the changes. Each agent should return the list of issues, where each issue includes a description and the reason it was flagged (e.g. "CLAUDE.md adherence", "bug"). The agents should do the following:
+
+   Agents 1 + 2: CLAUDE.md compliance sonnet agents
+   Audit changes for CLAUDE.md compliance in parallel. Note: When evaluating CLAUDE.md compliance for a file, you should only consider CLAUDE.md files that share a file path with the file or parents.
+
+   Agent 3: Opus bug agent (parallel subagent with agent 4)
+   Scan for obvious bugs. Focus only on the diff itself without reading extra context. Flag only significant bugs; ignore nitpicks and likely false positives. Do not flag issues that you cannot validate without looking at context outside of the git diff.
+
+   Agent 4: Opus bug agent (parallel subagent with agent 3)
+   Look for problems that exist in the introduced code. This could be security issues, incorrect logic, etc. Only look for issues that fall within the changed code.
+
+   **CRITICAL: We only want HIGH SIGNAL issues.** Flag issues where:
+   - The code will fail to compile or parse (syntax errors, type errors, missing imports, unresolved references)
+   - The code will definitely produce wrong results regardless of inputs (clear logic errors)
+   - Clear, unambiguous CLAUDE.md violations where you can quote the exact rule being broken
+
+   Do NOT flag:
+   - Code style or quality concerns
+   - Potential issues that depend on specific inputs or state
+   - Subjective suggestions or improvements
+
+   If you are not certain an issue is real, do not flag it. False positives erode trust and waste reviewer time.
+
+   In addition to the above, each subagent should be told the PR title and description. This will help provide context regarding the author's intent.
+
+5. For each issue found in the previous step by agents 3 and 4, launch parallel subagents to validate the issue. These subagents should get the PR title and description along with a description of the issue. The agent's job is to review the issue to validate that the stated issue is truly an issue with high confidence. For example, if an issue such as "variable is not defined" was flagged, the subagent's job would be to validate that is actually true in the code. Another example would be CLAUDE.md issues. The agent should validate that the CLAUDE.md rule that was violated is scoped for this file and is actually violated. Use Opus subagents for bugs and logic issues, and sonnet agents for CLAUDE.md violations.
+
+6. Filter out any issues that were not validated in step 5. This step will give us our list of high signal issues for our review.
+
+7. If issues were found, skip to step 8 to post comments.
+
+   If NO issues were found, post a summary comment using `gh pr comment` (if `--comment` argument is provided):
+   "No issues found. Checked for bugs and CLAUDE.md compliance."
+
+8. Create a list of all comments that you plan on leaving. This is only for you to make sure you are comfortable with the comments. Do not post this list anywhere.
+
+9. Post inline comments for each issue using `gh pr review` with inline comments. For each comment:
+   - Provide a brief description of the issue
+   - For small, self-contained fixes, include a committable suggestion block
+   - For larger fixes (6+ lines, structural changes, or changes spanning multiple locations), describe the issue and suggested fix without a suggestion block
+   - Never post a committable suggestion UNLESS committing the suggestion fixes the issue entirely. If follow up steps are required, do not leave a committable suggestion.
+
+   **IMPORTANT: Only post ONE comment per unique issue. Do not post duplicate comments.**
+
+Use this list when evaluating issues in Steps 4 and 5 (these are false positives, do NOT flag):
+
+- Pre-existing issues
+- Something that appears to be a bug but is actually correct
+- Pedantic nitpicks that a senior engineer would not flag
+- Issues that a linter will catch (do not run the linter to verify)
+- General code quality concerns (e.g., lack of test coverage, general security issues) unless explicitly required in CLAUDE.md
+- Issues mentioned in CLAUDE.md but explicitly silenced in the code (e.g., via a lint ignore comment)
+
+Notes:
+
+- Use gh CLI to interact with GitHub (e.g., fetch pull requests, create comments). Do not use web fetch.
+- Create a todo list before starting.
+- You must cite and link each issue in inline comments (e.g., if referring to a CLAUDE.md, include a link to it).
+- If no issues are found, post a comment with the following format:
+
+---
+
+## Code review
+
+No issues found. Checked for bugs and CLAUDE.md compliance.
+
+---
+
+- When linking to code in inline comments, follow the following format precisely, otherwise the Markdown preview won't render correctly: `https://github.com/OWNER/REPO/blob/FULL_SHA/path/to/file.py#L10-L15`
+  - Requires full git sha
+  - You must provide the full sha. Commands like `https://github.com/owner/repo/blob/$(git rev-parse HEAD)/foo/bar` will not work, since your comment will be directly rendered in Markdown.
+  - Repo name must match the repo you're code reviewing
+  - # sign after the file name
+  - Line range format is L[start]-L[end]
+  - Provide at least 1 line of context before and after, centered on the line you are commenting about (eg. if you are commenting about lines 5-6, you should link to `L4-7`)

.claude/skills/docstring/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: docstring
+description: Document a Python module and its classes using Google style
+---
+
+Document a Python module and its classes using Google-style docstrings following project conventions. The class name is provided as an argument.
+
+## Instructions
+
+1. First, find the class in the codebase:
+   ```
+   Search for "class ClassName" in src/pipecat/
+   ```
+
+2. If multiple files contain that class name:
+   - List all matches with their file paths
+   - Ask the user which one they want to document
+   - Wait for confirmation before proceeding
+
+3. Once the file is identified, read the module to understand its structure:
+   - Identify all classes, functions, and important type aliases
+   - Understand the purpose of each component
+
+4. Apply documentation in this order:
+   - Module docstring (at top, after imports)
+   - Class docstrings
+   - `__init__` methods (always document constructor parameters)
+   - Public methods (not starting with `_`)
+   - Dataclass/config classes with field descriptions
+
+5. Skip documentation for:
+   - Private methods (starting with `_`)
+   - Simple dunder methods (`__str__`, `__repr__`, `__post_init__`)
+   - Very simple pass-through properties
+   - **Already documented code** - If a class, method, or function already has a complete docstring that follows the project style, do not modify it. A docstring is complete if it has:
+     - A one-line summary
+     - Args section (if it has parameters)
+     - Returns section (if it returns something meaningful)
+   - Only add or improve documentation where it is missing or incomplete
+
+## Module Docstring Format
+
+```python
+"""[One-line description of module purpose].
+
+[Optional: Longer explanation of functionality, key classes, or use cases.]
+"""
+```
+
+Example:
+```python
+"""Neuphonic text-to-speech service implementations.
+
+This module provides WebSocket and HTTP-based integrations with Neuphonic's
+text-to-speech API for real-time audio synthesis.
+"""
+```
+
+## Class Docstring Format
+
+```python
+class ClassName:
+    """One-line summary describing what the class does.
+
+    [Longer description explaining purpose, behavior, and key features.
+    Use action-oriented language.]
+
+    [Optional: Event handlers, usage notes, or important caveats.]
+    """
+```
+
+Example:
+```python
+class FrameProcessor(BaseObject):
+    """Base class for all frame processors in the pipeline.
+
+    Frame processors are the building blocks of Pipecat pipelines, they can be
+    linked to form complex processing pipelines. They receive frames, process
+    them, and pass them to the next or previous processor in the chain.
+
+    Event handlers available:
+
+    - on_before_process_frame: Called before a frame is processed
+    - on_after_process_frame: Called after a frame is processed
+
+    Example::
+
+        @processor.event_handler("on_before_process_frame")
+        async def on_before_process_frame(processor, frame):
+            ...
+
+        @processor.event_handler("on_after_process_frame")
+        async def on_after_process_frame(processor, frame):
+            ...
+    """
+```
+
+Note: When listing event handlers, do NOT use backticks. Include an `Example::` section (with double colon for Sphinx) showing the decorator pattern and function signature for each event.
+
+## Constructor (`__init__`) Format
+
+```python
+def __init__(self, *, param1: Type, param2: Type = default, **kwargs):
+    """Initialize the [ClassName].
+
+    Args:
+        param1: Description of param1 and its purpose.
+        param2: Description of param2. Defaults to [default].
+        **kwargs: Additional arguments passed to parent class.
+    """
+```
+
+Example:
+```python
+def __init__(
+    self,
+    *,
+    api_key: str,
+    voice_id: Optional[str] = None,
+    sample_rate: Optional[int] = 22050,
+    **kwargs,
+):
+    """Initialize the Neuphonic TTS service.
+
+    Args:
+        api_key: Neuphonic API key for authentication.
+        voice_id: ID of the voice to use for synthesis.
+        sample_rate: Audio sample rate in Hz. Defaults to 22050.
+        **kwargs: Additional arguments passed to parent InterruptibleTTSService.
+    """
+```
+
+## Method Docstring Format
+
+```python
+async def method_name(self, param1: Type) -> ReturnType:
+    """One-line summary of what method does.
+
+    [Longer description if behavior isn't obvious.]
+
+    Args:
+        param1: Description of param1.
+
+    Returns:
+        Description of return value.
+
+    Raises:
+        ExceptionType: When this exception is raised.
+    """
+```
+
+Example:
+```python
+async def put(self, item: Tuple[Frame, FrameDirection, FrameCallback]):
+    """Put an item into the priority queue.
+
+    System frames (`SystemFrame`) have higher priority than any other
+    frames. If a non-frame item is provided it will have the highest priority.
+
+    Args:
+        item: The item to enqueue.
+    """
+```
+
+## Dataclass/Config Format
+
+```python
+@dataclass
+class ConfigName:
+    """One-line description of configuration.
+
+    [Explanation of when/how to use this config.]
+
+    Parameters:
+        field1: Description of field1.
+        field2: Description of field2. Defaults to [default].
+    """
+
+    field1: Type
+    field2: Type = default_value
+```
+
+Example:
+```python
+@dataclass
+class FrameProcessorSetup:
+    """Configuration parameters for frame processor initialization.
+
+    Parameters:
+        clock: The clock instance for timing operations.
+        task_manager: The task manager for handling async operations.
+        observer: Optional observer for monitoring frame processing events.
+    """
+
+    clock: BaseClock
+    task_manager: BaseTaskManager
+    observer: Optional[BaseObserver] = None
+```
+
+## Enum Documentation Format
+
+```python
+class EnumName(Enum):
+    """One-line description of the enum purpose.
+
+    [Longer description of how the enum is used.]
+
+    Parameters:
+        VALUE1: Description of VALUE1.
+        VALUE2: Description of VALUE2.
+    """
+
+    VALUE1 = 1
+    VALUE2 = 2
+```
+
+## Writing Style Guidelines
+
+- **Concise and professional** - No casual language or filler words
+- **Action-oriented** - Start with verbs: "Processes...", "Manages...", "Converts..."
+- **Purpose before implementation** - Explain WHY before HOW
+- **Clear parameter descriptions** - Include type hints, defaults, and purpose
+- **No redundant type info** - Type hints are in the signature, don't repeat in description
+- **Use backticks for code references** - Wrap class names, method names, event names, parameter names, and code snippets in backticks
+
+Good: "Neuphonic API key for authentication."
+Bad: "str: The API key (string) that is used for authenticating with Neuphonic."
+
+Good: "Triggers `on_speech_started` when the `VADAnalyzer` detects speech."
+Bad: "Triggers on_speech_started when the VADAnalyzer detects speech."
+
+## Deprecation Notice Format
+
+When documenting deprecated code:
+
+```python
+"""[Description].
+
+.. deprecated:: X.X.X
+    `ClassName` is deprecated and will be removed in a future version.
+    Use `NewClassName` instead.
+"""
+```
+
+## Checklist
+
+Before finishing, verify:
+
+- [ ] Module has a docstring at the top (after copyright header and imports)
+- [ ] All public classes have docstrings
+- [ ] All `__init__` methods document their parameters
+- [ ] All public methods have docstrings with Args/Returns/Raises as needed
+- [ ] Dataclasses use "Parameters:" section for field descriptions
+- [ ] Enums document each value in "Parameters:" section
+- [ ] Writing is concise and action-oriented
+- [ ] No documentation added to private methods (starting with `_`)
+- [ ] Existing complete docstrings were left unchanged

.claude/skills/pr-description/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: pr-description
+description: Update a GitHub PR description with a summary of changes
+---
+
+Update a GitHub pull request description based on the changes in the PR.
+
+## Arguments
+
+```
+/pr-description <PR_NUMBER> [--fixes <ISSUE_NUMBERS>]
+```
+
+- `PR_NUMBER` (required): The pull request number to update
+- `--fixes` (optional): Comma-separated issue numbers that this PR fixes (e.g., `--fixes 123,456`)
+
+Examples:
+- `/pr-description 3534`
+- `/pr-description 3534 --fixes 123`
+- `/pr-description 3534 --fixes 123,456,789`
+
+## Instructions
+
+1. First, gather information about the PR:
+   - Use GitHub plugin to get PR details (title, current description, base branch)
+   - Use local git to get commits: `git log main..HEAD --oneline`
+   - Use local git to get the diff: `git diff main..HEAD`
+   - Parse any `--fixes` argument for issue numbers
+
+2. Check the existing PR description:
+   - If it already has a complete, accurate description that reflects the changes, do nothing
+   - If it's missing sections, incomplete, or outdated compared to the actual changes, proceed to update
+   - If it only has the template placeholder text, generate a full description
+
+3. Analyze the changes:
+   - Understand the purpose of each commit
+   - Identify any breaking changes (API changes, removed features, behavior changes)
+   - Look for new features, bug fixes, refactoring, or documentation changes
+   - Collect issue numbers from:
+     - The `--fixes` argument (if provided)
+     - Commit messages (patterns like "Fixes #123", "Closes #456", "Resolves #789")
+
+4. Generate or update the PR description with these sections:
+
+## PR Description Format
+
+### Summary (always include)
+
+Brief bullet points describing what changed and why. Focus on the *purpose* and *impact*, not implementation details.
+
+```markdown
+## Summary
+
+- Added X to enable Y
+- Fixed bug where Z would happen
+- Refactored W for better maintainability
+```
+
+### Breaking Changes (include only if applicable)
+
+Document any changes that affect existing users or APIs.
+
+```markdown
+## Breaking Changes
+
+- `ClassName.method()` now requires a `param` argument
+- Removed deprecated `old_function()` - use `new_function()` instead
+```
+
+### Testing (include when non-obvious)
+
+How to verify the changes work. Skip for trivial changes.
+
+```markdown
+## Testing
+
+- Run `uv run pytest tests/test_feature.py` to verify the fix
+- Example usage: `uv run examples/new_feature.py`
+```
+
+### Fixes (include if issues are provided or found in commits)
+
+List issues this PR fixes. GitHub will automatically close these issues when the PR is merged.
+
+```markdown
+## Fixes
+
+- Fixes #123
+- Fixes #456
+```
+
+Note: Use "Fixes #X" format (not "Closes" or "Resolves") for consistency. Each issue should be on its own line with "Fixes" to ensure GitHub auto-closes them.
+
+## Guidelines
+
+- **Be concise** - Reviewers should understand the PR in 30 seconds
+- **Focus on why** - The diff shows *what* changed, explain *why*
+- **Skip empty sections** - Only include sections that have content
+- **Use bullet points** - Easier to scan than paragraphs
+- **Don't duplicate the diff** - Avoid listing every file or line changed
+
+## Example Output
+
+```markdown
+## Summary
+
+- Added `/docstring` skill for documenting Python modules with Google-style docstrings
+- Skill finds classes by name and handles conflicts when multiple matches exist
+- Skips already-documented code to avoid unnecessary changes
+
+## Testing
+
+/docstring ClassName
+
+## Fixes
+
+- Fixes #123
+```
+
+## Checklist
+
+Before updating the PR:
+
+- [ ] Verified existing description needs updating (not already complete)
+- [ ] Summary accurately reflects the changes
+- [ ] Breaking changes are clearly documented (if any)
+- [ ] No unnecessary sections included
+- [ ] Description is concise and scannable

.claude/skills/pr-submit/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: pr-submit
+description: Create and submit a GitHub PR from the current branch
+---
+
+Submit the current changes as a GitHub pull request.
+
+## Instructions
+
+1. Check the current state of the repository:
+   - Run `git status` to see staged, unstaged, and untracked changes
+   - Run `git diff` to see current changes
+   - Run `git log --oneline -10` to see recent commits
+
+2. If there are uncommitted changes relevant to the PR:
+   - Ask the user if they want a specific prefix for the branch name (e.g., `alice/`, `fix/`, `feat/`)
+   - Create a new branch based on the current branch
+   - Commit the changes using multiple commits if the changes are unrelated
+
+3. Push the branch and create the PR:
+   - Push with `-u` flag to set upstream tracking
+   - Create the PR using `gh pr create`
+
+4. After the PR is created:
+   - Run `/changelog <pr_number>` to generate changelog files, then commit and push them
+   - Run `/pr-description <pr_number>` to update the PR description
+
+5. Return the PR URL to the user.

.claude/skills/update-docs/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: update-docs
+description: Update documentation pages to match source code changes on the current branch
+---
+
+Update documentation pages to reflect source code changes on the current branch. Analyzes the diff against main, maps changed source files to their corresponding doc pages, and makes targeted edits.
+
+## Arguments
+
+```
+/update-docs [DOCS_PATH]
+```
+
+- `DOCS_PATH` (optional): Path to the docs repository root. If not provided, ask the user.
+
+Examples:
+- `/update-docs /Users/me/src/docs`
+- `/update-docs`
+
+## Instructions
+
+### Step 1: Resolve docs path
+
+If `DOCS_PATH` was provided as an argument, use it. Otherwise, ask the user for the path to their docs repository.
+
+Verify the path exists and contains `server/services/` subdirectory.
+
+### Step 2: Create docs branch
+
+Get the current pipecat branch name:
+```bash
+git rev-parse --abbrev-ref HEAD
+```
+
+In the docs repo, create a new branch off main with a matching name:
+```bash
+cd DOCS_PATH && git checkout main && git pull && git checkout -b {branch-name}-docs
+```
+
+For example, if the pipecat branch is `feat/new-service`, the docs branch becomes `feat/new-service-docs`.
+
+All doc edits in subsequent steps are made on this branch.
+
+### Step 3: Detect changed source files
+
+Run:
+```bash
+git diff main..HEAD --name-only
+```
+
+Filter to files that could affect documentation:
+- `src/pipecat/services/**/*.py` (service implementations)
+- `src/pipecat/transports/**/*.py` (transport implementations)
+- `src/pipecat/serializers/**/*.py` (serializer implementations)
+- `src/pipecat/processors/**/*.py` (processor implementations)
+- `src/pipecat/audio/**/*.py` (audio utilities)
+- `src/pipecat/turns/**/*.py` (turn management)
+- `src/pipecat/observers/**/*.py` (observers)
+- `src/pipecat/pipeline/**/*.py` (pipeline core)
+
+Ignore `__init__.py`, `__pycache__`, test files, and files that only contain type re-exports.
+
+### Step 4: Map source files to doc pages
+
+For each changed source file, find the corresponding doc page. Read the mapping file at `.claude/skills/update-docs/SOURCE_DOC_MAPPING.md` and apply its tiered lookup: tier 1 (known exceptions) → tier 2 (pattern matching) → tier 3 (search fallback). **First match wins.**
+
+### Step 5: Analyze each source-doc pair
+
+For each mapped pair:
+
+1. **Read the full source file** to understand current state
+2. **Read the diff** for that file: `git diff main..HEAD -- <source_file>`
+3. **Read the current doc page** in full
+
+Identify what changed by comparing source to docs:
+
+- **Constructor parameters**: Compare `__init__` signature to the Configuration section's `<ParamField>` entries
+- **InputParams fields**: Compare `InputParams(BaseModel)` class fields to the InputParams table
+- **Event handlers**: Compare `_register_event_handler` calls and event handler definitions to Event Handlers section
+- **Class names / imports**: Check if Usage examples reference correct names
+- **Behavioral changes**: Check if Notes section needs updating
+
+### Step 6: Make targeted edits
+
+For each doc page that needs updates, edit **only the sections that need changes**. Preserve all other content exactly as-is.
+
+#### Rules
+
+- **Never remove content** unless the corresponding source code was removed
+- **Never rewrite sections** that are already accurate
+- **Match existing formatting** — if the page uses `<ParamField>` tags, use them; if it uses tables, use tables
+- **Keep descriptions concise** — match the tone and length of surrounding content
+- **Preserve CardGroup, links, and examples** unless they reference removed functionality
+- **Don't touch frontmatter** unless the class was renamed
+
+#### Section-specific guidance
+
+**Configuration** (constructor params):
+- Use `<ParamField path="name" type="type" default="value">` format if the page already uses it
+- Add new params in logical order (required first, then optional)
+- Remove params that no longer exist in source
+- Update types/defaults that changed
+
+**InputParams** (runtime settings):
+- Use markdown table format: `| Parameter | Type | Default | Description |`
+- Match the field names and types from the `InputParams(BaseModel)` class
+- Include the default values from the source
+
+**Usage** (code examples):
+- Update import paths, class names, and parameter names
+- Only modify examples if they would break or be misleading with the new API
+- Don't rewrite working examples just to add new optional params
+
+**Notes**:
+- Add notes for new behavioral gotchas or breaking changes
+- Remove notes about limitations that were fixed
+- Keep existing notes that are still accurate
+
+**Event Handlers**:
+- Update the event table and example code
+- Add new events, remove deleted ones
+- Update handler signatures if they changed
+
+**Overview / Key Features / Prerequisites**:
+- Only update if the PR fundamentally changes what the service does (new capability, removed capability, renamed class)
+- Most PRs will NOT need changes to these sections
+
+### Step 7: Update guides
+
+Guides at `DOCS_PATH/guides/` reference specific class names, parameters, imports, and code patterns. After completing reference doc edits, check if any guides need updates too.
+
+For each changed source file, collect the class names, renamed parameters, and changed imports from the diff. Search the guides directory:
+```bash
+grep -rl "ClassName\|old_param_name" DOCS_PATH/guides/
+```
+
+For each guide that references changed code:
+1. Read the full guide
+2. Update class names, parameter names, import paths, and code examples that are now incorrect
+3. **Don't rewrite prose** — only fix the specific references that changed
+4. Leave guides alone if they reference the service generally but don't use any changed APIs
+
+Guide directories:
+- `guides/learn/` — conceptual tutorials (pipeline, LLM, STT, TTS, etc.)
+- `guides/fundamentals/` — practical how-tos (metrics, recording, transcripts, etc.)
+- `guides/features/` — feature-specific guides (Gemini Live, OpenAI audio, WhatsApp, etc.)
+- `guides/telephony/` — telephony integration guides (Twilio, Plivo, Telnyx, etc.)
+
+### Step 8: Identify doc gaps
+
+After processing all mapped pairs, check for two kinds of gaps:
+
+**Missing pages**: Source files that had no doc page mapping (neither tier 1, 2, nor 3) and are not marked as "(skip)". For each, tell the user:
+- The source file path
+- The main class(es) it defines
+- Whether a new doc page should be created
+
+**Missing sections**: Mapped doc pages that are missing standard sections compared to the source. For example, a transport page with no Configuration section, or a service page with no InputParams table when the source defines `InputParams(BaseModel)`. Flag these and offer to add the missing sections.
+
+If the user wants a new page, create it using this template structure:
+```
+---
+title: "Service Name"
+description: "Brief description"
+---
+
+## Overview
+
+[Description from class docstring or source analysis]
+
+<CardGroup cols={2}>
+  [Cards for API reference and examples if available]
+</CardGroup>
+
+## Installation
+
+```bash
+pip install "pipecat-ai[package-name]"
+```
+
+## Prerequisites
+
+[Environment variables and account setup]
+
+## Configuration
+
+[ParamField entries for constructor params]
+
+## InputParams
+
+[Table of InputParams fields, if the service has them]
+
+## Usage
+
+### Basic Setup
+
+```python
+[Minimal working example]
+```
+
+## Notes
+
+[Important caveats]
+
+## Event Handlers
+
+[Event table and example code]
+```
+
+### Step 9: Output summary
+
+After all edits are complete, print a summary:
+
+```
+## Documentation Updates
+
+### Updated reference pages
+- `server/services/stt/deepgram.mdx` — Updated Configuration (added `new_param`), InputParams (updated `language` default)
+- `server/services/tts/elevenlabs.mdx` — Updated Event Handlers (added `on_connected`)
+
+### Updated guides
+- `guides/learn/speech-to-text.mdx` — Updated code example (renamed `old_param` → `new_param`)
+
+### Unmapped source files
+- `src/pipecat/services/newprovider/tts.py` — NewProviderTTSService (no doc page exists)
+
+### Skipped files
+- `src/pipecat/services/ai_service.py` — internal base class
+```
+
+## Guidelines
+
+- **Be conservative** — only change what the diff warrants. Don't "improve" docs beyond what changed in source.
+- **Read before editing** — always read the full doc page before making changes so you understand the existing structure.
+- **Preserve voice** — match the writing style of the existing doc page, don't impose a different tone.
+- **One PR at a time** — this skill operates on the current branch's diff against main. Don't look at other branches.
+- **Parallel analysis** — when multiple source files map to different doc pages, analyze and edit them in parallel for efficiency.
+- **Shared source files** — files like `services/google/google.py` are shared bases. Check which services import from them and update all affected doc pages.
+
+## Checklist
+
+Before finishing, verify:
+
+- [ ] All changed source files were checked against the mapping table
+- [ ] Each doc page edit matches the actual source code change (not guessed)
+- [ ] No content was removed unless the corresponding source was removed
+- [ ] New parameters have accurate types and defaults from source
+- [ ] Formatting matches the existing page style
+- [ ] Guides referencing changed APIs were checked and updated
+- [ ] Unmapped files were reported to the user

.claude/skills/update-docs/SOURCE_DOC_MAPPING.md

@@ -0,0 +1,79 @@
+# Source-to-Doc Mapping
+
+Maps pipecat source files to their documentation pages. Source paths are relative to `src/pipecat/`. Doc paths are relative to `DOCS_PATH`.
+
+## Name mismatches
+
+These source paths don't follow the standard `services/{provider}/{type}.py` → `server/services/{type}/{provider}.mdx` pattern.
+
+| Source path | Doc page |
+|---|---|
+| `services/google/llm.py` | `server/services/llm/gemini.mdx` |
+| `services/google/llm_vertex.py` | `server/services/llm/google-vertex.mdx` |
+| `services/google/google.py` | (shared base — check which services use it) |
+| `services/google/gemini_live/**` | `server/services/s2s/gemini-live.mdx` |
+| `services/google/gemini_live/llm_vertex.py` | `server/services/s2s/gemini-live-vertex.mdx` |
+| `services/aws_nova_sonic/**` | `server/services/s2s/aws.mdx` |
+| `services/ultravox/**` | `server/services/s2s/ultravox.mdx` |
+| `services/grok/realtime/**` | `server/services/s2s/grok.mdx` |
+| `services/openai/realtime/**` | `server/services/s2s/openai.mdx` |
+| `processors/frameworks/rtvi.py` | `server/frameworks/rtvi/rtvi-processor.mdx` and `server/frameworks/rtvi/rtvi-observer.mdx` |
+| `processors/transcript_processor.py` | `server/utilities/transcript-processor.mdx` |
+| `processors/user_idle_processor.py` | `server/utilities/user-idle-processor.mdx` |
+| `processors/idle_frame_processor.py` | `server/pipeline/pipeline-idle-detection.mdx` |
+| `pipeline/task.py` | `server/pipeline/pipeline-task.mdx` |
+| `pipeline/runner.py` | `server/utilities/runner/guide.mdx` |
+| `transports/base_transport.py` | `server/services/transport/transport-params.mdx` |
+
+## Skip list
+
+These files should never trigger doc updates.
+
+| Pattern | Reason |
+|---|---|
+| `services/ai_service.py` | Internal base class |
+| `services/stt_service.py` | Internal base class |
+| `services/tts_service.py` | Internal base class |
+| `services/llm_service.py` | Internal base class |
+| `services/websocket_service.py` | Internal base class |
+| `services/openai_realtime_beta/**` | Deprecated |
+| `services/openai_realtime/**` | Deprecated |
+| `services/gemini_multimodal_live/**` | Deprecated |
+| `services/aws/agent_core.py` | Internal |
+| `services/aws/sagemaker/**` | No doc page |
+| `transports/base_input.py` | Internal base class |
+| `transports/base_output.py` | Internal base class |
+| `transports/websocket/client.py` | No doc page |
+| `serializers/base_serializer.py` | Internal base class |
+| `serializers/protobuf.py` | Internal |
+| `processors/audio/**` | Internal |
+| `pipeline/pipeline.py` | Core architecture, not a service doc |
+
+## Pattern matching
+
+For files not in the tables above, apply these patterns. Convert underscores to hyphens in provider names for doc filenames.
+
+| Source pattern | Doc pattern |
+|---|---|
+| `services/{provider}/stt*.py` | `server/services/stt/{provider}.mdx` |
+| `services/{provider}/tts*.py` | `server/services/tts/{provider}.mdx` |
+| `services/{provider}/llm*.py` | `server/services/llm/{provider}.mdx` |
+| `services/{provider}/image*.py` | `server/services/image-generation/{provider}.mdx` |
+| `services/{provider}/video*.py` | `server/services/video/{provider}.mdx` |
+| `services/{provider}/realtime/**` | `server/services/s2s/{provider}.mdx` |
+| `transports/{name}/**` | `server/services/transport/{name}.mdx` |
+| `serializers/{name}.py` | `server/services/serializers/{name}.mdx` |
+| `observers/**` | `server/utilities/observers/` (match by class name) |
+| `audio/vad/**` | `server/utilities/audio/` (match by class name) |
+| `audio/filters/**` | `server/utilities/audio/` (match by class name) |
+| `audio/mixers/**` | `server/utilities/audio/` (match by class name) |
+| `processors/filters/**` | `server/utilities/filters/` (match by class name) |
+
+If the doc file doesn't exist at the resolved path, the file is **unmapped**.
+
+## Search fallback
+
+For files that don't match any table or pattern above:
+1. Extract the main class name(s) from the source file
+2. Search the docs directory for that class name: `grep -r "ClassName" DOCS_PATH/server/`
+3. If found in a doc page, use that as the mapping

.github/workflows/coverage.yaml

@@ -29,11 +29,21 @@ jobs:
 
       - name: Install system packages
         run: |
+          sudo apt-get update
           sudo apt-get install -y portaudio19-dev
 
       - name: Install dependencies
         run: |
-          uv sync --group dev --extra anthropic --extra aws --extra google --extra langchain --extra websocket
+          uv sync --group dev \
+            --extra anthropic \
+            --extra aws \
+            --extra google \
+            --extra langchain \
+            --extra livekit \
+            --extra local-smart-turn-v3 \
+            --extra piper \
+            --extra tracing \
+            --extra websocket
 
       - name: Run tests with coverage
         run: |

.github/workflows/python-compatibility.yaml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.10.18', '3.11.13', '3.12.11', '3.13.5']
+        python-version: ['3.10.19', '3.11.14', '3.12.12', '3.13.12']
 
     name: Python ${{ matrix.python-version }}
     steps:
@@ -40,20 +40,10 @@ jobs:
           uv python install ${{ matrix.python-version }}
           uv python pin ${{ matrix.python-version }}
 
-      - name: Test uv sync with all extras (Python < 3.13)
-        if: "!startsWith(matrix.python-version, '3.13.')"
+      - name: Test uv sync with all extras
         run: |
           uv sync --group dev --all-extras --no-extra krisp
 
-      - name: Test uv sync without PyTorch extras (Python 3.13+)
-        if: startsWith(matrix.python-version, '3.13.')
-        run: |
-          uv sync --group dev --all-extras \
-            --no-extra krisp \
-            --no-extra local-smart-turn \
-            --no-extra moondream \
-            --no-extra mlx-whisper
-
       - name: Verify installation
         run: |
           uv run python --version

.github/workflows/tests.yaml

@@ -33,11 +33,21 @@ jobs:
 
       - name: Install system packages
         run: |
+          sudo apt-get update
           sudo apt-get install -y portaudio19-dev
 
       - name: Install dependencies
         run: |
-          uv sync --group dev --extra anthropic --extra aws --extra google --extra langchain --extra websocket
+          uv sync --group dev \
+            --extra anthropic \
+            --extra aws \
+            --extra google \
+            --extra langchain \
+            --extra livekit \
+            --extra local-smart-turn-v3 \
+            --extra piper \
+            --extra tracing \
+            --extra websocket
 
       - name: Test with pytest
         run: |

.gitignore

@@ -4,7 +4,14 @@ __pycache__/
 *~
 venv
 .venv
-/.idea
+.idea
+.gradle
+.next
+next-env.d.ts
+local.properties
+*.log
+*.lock
+smart_turn_audio_log
 #*#
 
 # Distribution / Packaging
@@ -27,7 +34,7 @@ share/python-wheels/
 *.egg
 MANIFEST
 .DS_Store
-.env
+.env*
 fly.toml
 
 # Examples
@@ -51,4 +58,7 @@ docs/api/_build/
 docs/api/api
 
 # uv
-.python-version
+.python-version
+
+# Pipecat
+whisker_setup.py

CLAUDE.md

@@ -0,0 +1,155 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Pipecat is an open-source Python framework for building real-time voice and multimodal conversational AI agents. It orchestrates audio/video, AI services, transports, and conversation pipelines using a frame-based architecture.
+
+## Common Commands
+
+```bash
+# Setup development environment
+uv sync --group dev --all-extras --no-extra gstreamer --no-extra krisp
+
+# Install pre-commit hooks
+uv run pre-commit install
+
+# Run all tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_name.py
+
+# Run a specific test
+uv run pytest tests/test_name.py::test_function_name
+
+# Preview changelog
+towncrier build --draft --version Unreleased
+
+# Lint and format check
+uv run ruff check
+uv run ruff format --check
+
+# Update dependencies (after editing pyproject.toml)
+uv lock && uv sync
+```
+
+## Architecture
+
+### Frame-Based Pipeline Processing
+
+All data flows as **Frame** objects through a pipeline of **FrameProcessors**:
+
+```
+[Processor1] → [Processor2] → ... → [ProcessorN]
+```
+
+**Key components:**
+
+- **Frames** (`src/pipecat/frames/frames.py`): Data units (audio, text, video) and control signals. Flow DOWNSTREAM (input→output) or UPSTREAM (acknowledgments/errors).
+
+- **FrameProcessor** (`src/pipecat/processors/frame_processor.py`): Base processing unit. Each processor receives frames, processes them, and pushes results downstream.
+
+- **Pipeline** (`src/pipecat/pipeline/pipeline.py`): Chains processors together.
+
+- **ParallelPipeline** (`src/pipecat/pipeline/parallel_pipeline.py`): Runs multiple pipelines in parallel.
+
+- **Transports** (`src/pipecat/transports/`): Transports are frame processors used for external I/O layer (Daily WebRTC, LiveKit WebRTC, WebSocket, Local). Abstract interface via `BaseTransport`, `BaseInputTransport` and `BaseOutputTransport`.
+
+- **Pipeline Task (`src/pipecat/pipeline/task.py`)**: Runs and manages a pipeline. Pipeline tasks send the first frame, `StartFrame`, to the pipeline in order for processors to know they can start processing and pushing frames. Pipeline tasks internally create a pipeline with two additional processors, a source processor before the user-defined pipeline and a sink processor at the end. Those are used for multiple things: error handling, pipeline task level events, heartbeat monitoring, etc.
+
+- **Pipeline Runner (`src/pipecat/pipeline/runner.py`)**: High-level entry point for executing pipeline tasks. Handles signal management (SIGINT/SIGTERM) for graceful shutdown and optional garbage collection. Run a single pipeline task with `await runner.run(task)` or multiple concurrently with `await asyncio.gather(runner.run(task1), runner.run(task2))`.
+
+- **Services** (`src/pipecat/services/`): 60+ AI provider integrations (STT, TTS, LLM, etc.). Extend base classes: `AIService`, `LLMService`, `STTService`, `TTSService`, `VisionService`.
+
+- **Serializers** (`src/pipecat/serializers/`): Convert frames to/from wire formats for WebSocket transports. `FrameSerializer` base class defines `serialize()` and `deserialize()`. Telephony serializers (Twilio, Plivo, Vonage, Telnyx, Exotel, Genesys) handle provider-specific protocols and audio encoding (e.g., μ-law).
+
+- **RTVI** (`src/pipecat/processors/frameworks/rtvi.py`): Real-Time Voice Interface protocol bridging clients and the pipeline. `RTVIProcessor` handles incoming client messages (text input, audio, function call results). `RTVIObserver` converts pipeline frames to outgoing messages: user/bot speaking events, transcriptions, LLM/TTS lifecycle, function calls, metrics, and audio levels.
+
+- **Observers** (`src/pipecat/observers/`): Monitor frame flow without modifying the pipeline. Passed to `PipelineTask` via the `observers` parameter. Implement `on_process_frame()` and `on_push_frame()` callbacks.
+
+### Important Patterns
+
+- **Context Aggregation**: `LLMContext` accumulates messages for LLM calls; `UserResponse` aggregates user input
+
+- **Turn Management**: Turn management is done through `LLMUserAggregator` and
+`LLMAssistantAggregator`, created with `LLMContextAggregatorPair`
+
+- **User turn strategies**: Detection of when the user starts and stops speaking is done via user turn start/stop strategies. They push `UserStartedSpeakingFrame` and `UserStoppedSpeakingFrame` respectively.
+
+- **Interruptions**: Interruptions are usually triggered by a user turn start strategy (e.g. `VADUserTurnStartStrategy`) but they can be triggered by other processors as well, in which case the user turn start strategies don't need to. An `InterruptionFrame` carries an optional `asyncio.Event` that is set when the frame reaches the pipeline sink. If a processor stops an `InterruptionFrame` from propagating downstream (i.e., doesn't push it), it **must** call `frame.complete()` to avoid stalling `push_interruption_task_frame_and_wait()` callers.
+
+- **Uninterruptible Frames**: These are frames that will not be removed from internal queues even if there's an interruption. For example, `EndFrame` and `StopFrame`.
+
+- **Events**: Most classes in Pipecat have `BaseObject` as the very base class. `BaseObject` has support for events. Events can run in the background in an async task (default) or synchronously (`sync=True`) if we want immediate action. Synchronous event handlers need to execute fast.
+
+- **Async Task Management**: Always use `self.create_task(coroutine, name)` instead of raw `asyncio.create_task()`. The `TaskManager` automatically tracks tasks and cleans them up on processor shutdown. Use `await self.cancel_task(task, timeout)` for cancellation.
+
+- **Error Handling**: Use `await self.push_error(msg, exception, fatal)` to push errors upstream. Services should use `fatal=False` (the default) so application code can handle errors and take action (e.g. switch to another service).
+
+### Key Directories
+
+| Directory                 | Purpose                                            |
+|---------------------------|----------------------------------------------------|
+| `src/pipecat/frames/`     | Frame definitions (100+ types)                     |
+| `src/pipecat/processors/` | FrameProcessor base + aggregators, filters, audio  |
+| `src/pipecat/pipeline/`   | Pipeline orchestration                             |
+| `src/pipecat/services/`   | AI service integrations (60+ providers)            |
+| `src/pipecat/transports/` | Transport layer (Daily, LiveKit, WebSocket, Local) |
+| `src/pipecat/serializers/`| Frame serialization for WebSocket protocols        |
+| `src/pipecat/observers/`  | Pipeline observers for monitoring frame flow       |
+| `src/pipecat/audio/`      | VAD, filters, mixers, turn detection, DTMF         |
+| `src/pipecat/turns/`      | User turn management                               |
+
+## Code Style
+
+- **Docstrings**: Google-style. Classes describe purpose; `__init__` has `Args:` section; dataclasses use `Parameters:` section.
+- **Linting**: Ruff (line length 100). Pre-commit hooks enforce formatting.
+- **Type hints**: Required for complex async code.
+
+### Docstring Example
+
+```python
+class MyService(LLMService):
+    """Description of what the service does.
+
+    More detailed description.
+
+    Event handlers available:
+
+    - on_connected: Called when we are connected
+
+    Example::
+
+        @service.event_handler("on_connected")
+        async def on_connected(service, frame):
+            ...
+    """
+
+    def __init__(self, param1: str, **kwargs):
+        """Initialize the service.
+
+        Args:
+            param1: Description of param1.
+            **kwargs: Additional arguments passed to parent.
+        """
+        super().__init__(**kwargs)
+```
+
+## Service Implementation
+
+When adding a new service:
+
+1. Extend the appropriate base class (`STTService`, `TTSService`, `LLMService`, etc.)
+2. Implement required abstract methods
+3. Handle necessary frames
+4. By default, all frames should be pushed in the direction they came
+5. Push `ErrorFrame` on failures
+6. Add metrics tracking via `MetricsData` if relevant
+7. Follow the pattern of existing services in `src/pipecat/services/`
+
+## Testing
+
+Test utilities live in `src/pipecat/tests/utils.py`. Use `run_test()` to send frames through a pipeline and assert expected output frames in each direction. Use `SleepFrame(sleep=N)` to add delays between frames.
+

README.md

@@ -73,15 +73,15 @@ Catch new features, interviews, and how-tos on our [Pipecat TV](https://www.yout
 
 | Category            | Services                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Speech-to-Text      | [AssemblyAI](https://docs.pipecat.ai/server/services/stt/assemblyai), [AWS](https://docs.pipecat.ai/server/services/stt/aws), [Azure](https://docs.pipecat.ai/server/services/stt/azure), [Cartesia](https://docs.pipecat.ai/server/services/stt/cartesia), [Deepgram](https://docs.pipecat.ai/server/services/stt/deepgram), [ElevenLabs](https://docs.pipecat.ai/server/services/stt/elevenlabs), [Fal Wizper](https://docs.pipecat.ai/server/services/stt/fal), [Gladia](https://docs.pipecat.ai/server/services/stt/gladia), [Google](https://docs.pipecat.ai/server/services/stt/google), [Gradium](https://docs.pipecat.ai/server/services/stt/gradium), [Groq (Whisper)](https://docs.pipecat.ai/server/services/stt/groq), [NVIDIA Riva](https://docs.pipecat.ai/server/services/stt/riva), [OpenAI (Whisper)](https://docs.pipecat.ai/server/services/stt/openai), [SambaNova (Whisper)](https://docs.pipecat.ai/server/services/stt/sambanova), [Sarvam](https://docs.pipecat.ai/server/services/stt/sarvam), [Soniox](https://docs.pipecat.ai/server/services/stt/soniox), [Speechmatics](https://docs.pipecat.ai/server/services/stt/speechmatics), [Whisper](https://docs.pipecat.ai/server/services/stt/whisper)                                                                                                                                                                                                                                                            |
+| Speech-to-Text      | [AssemblyAI](https://docs.pipecat.ai/server/services/stt/assemblyai), [AWS](https://docs.pipecat.ai/server/services/stt/aws), [Azure](https://docs.pipecat.ai/server/services/stt/azure), [Cartesia](https://docs.pipecat.ai/server/services/stt/cartesia), [Deepgram](https://docs.pipecat.ai/server/services/stt/deepgram), [ElevenLabs](https://docs.pipecat.ai/server/services/stt/elevenlabs), [Fal Wizper](https://docs.pipecat.ai/server/services/stt/fal), [Gladia](https://docs.pipecat.ai/server/services/stt/gladia), [Google](https://docs.pipecat.ai/server/services/stt/google), [Gradium](https://docs.pipecat.ai/server/services/stt/gradium), [Groq (Whisper)](https://docs.pipecat.ai/server/services/stt/groq), [Hathora](https://docs.pipecat.ai/server/services/stt/hathora), [NVIDIA Riva](https://docs.pipecat.ai/server/services/stt/riva), [OpenAI (Whisper)](https://docs.pipecat.ai/server/services/stt/openai), [SambaNova (Whisper)](https://docs.pipecat.ai/server/services/stt/sambanova), [Sarvam](https://docs.pipecat.ai/server/services/stt/sarvam), [Soniox](https://docs.pipecat.ai/server/services/stt/soniox), [Speechmatics](https://docs.pipecat.ai/server/services/stt/speechmatics), [Whisper](https://docs.pipecat.ai/server/services/stt/whisper)                                                                                                                                                                                                                                                            |
 | LLMs                | [Anthropic](https://docs.pipecat.ai/server/services/llm/anthropic), [AWS](https://docs.pipecat.ai/server/services/llm/aws), [Azure](https://docs.pipecat.ai/server/services/llm/azure), [Cerebras](https://docs.pipecat.ai/server/services/llm/cerebras), [DeepSeek](https://docs.pipecat.ai/server/services/llm/deepseek), [Fireworks AI](https://docs.pipecat.ai/server/services/llm/fireworks), [Gemini](https://docs.pipecat.ai/server/services/llm/gemini), [Grok](https://docs.pipecat.ai/server/services/llm/grok), [Groq](https://docs.pipecat.ai/server/services/llm/groq), [Mistral](https://docs.pipecat.ai/server/services/llm/mistral), [NVIDIA NIM](https://docs.pipecat.ai/server/services/llm/nim), [Ollama](https://docs.pipecat.ai/server/services/llm/ollama), [OpenAI](https://docs.pipecat.ai/server/services/llm/openai), [OpenRouter](https://docs.pipecat.ai/server/services/llm/openrouter), [Perplexity](https://docs.pipecat.ai/server/services/llm/perplexity), [Qwen](https://docs.pipecat.ai/server/services/llm/qwen), [SambaNova](https://docs.pipecat.ai/server/services/llm/sambanova) [Together AI](https://docs.pipecat.ai/server/services/llm/together)                                                                                                                                                                                                                                                                                              |
-| Text-to-Speech      | [Async](https://docs.pipecat.ai/server/services/tts/asyncai), [AWS](https://docs.pipecat.ai/server/services/tts/aws), [Azure](https://docs.pipecat.ai/server/services/tts/azure), [Cartesia](https://docs.pipecat.ai/server/services/tts/cartesia), [Deepgram](https://docs.pipecat.ai/server/services/tts/deepgram), [ElevenLabs](https://docs.pipecat.ai/server/services/tts/elevenlabs), [Fish](https://docs.pipecat.ai/server/services/tts/fish), [Google](https://docs.pipecat.ai/server/services/tts/google), [Gradium](https://docs.pipecat.ai/server/services/tts/gradium), [Groq](https://docs.pipecat.ai/server/services/tts/groq), [Hume](https://docs.pipecat.ai/server/services/tts/hume), [Inworld](https://docs.pipecat.ai/server/services/tts/inworld), [LMNT](https://docs.pipecat.ai/server/services/tts/lmnt), [MiniMax](https://docs.pipecat.ai/server/services/tts/minimax), [Neuphonic](https://docs.pipecat.ai/server/services/tts/neuphonic), [NVIDIA Riva](https://docs.pipecat.ai/server/services/tts/riva), [OpenAI](https://docs.pipecat.ai/server/services/tts/openai), [Piper](https://docs.pipecat.ai/server/services/tts/piper), [PlayHT](https://docs.pipecat.ai/server/services/tts/playht), [Rime](https://docs.pipecat.ai/server/services/tts/rime), [Sarvam](https://docs.pipecat.ai/server/services/tts/sarvam), [Speechmatics](https://docs.pipecat.ai/server/services/tts/speechmatics), [XTTS](https://docs.pipecat.ai/server/services/tts/xtts) |
+| Text-to-Speech      | [Async](https://docs.pipecat.ai/server/services/tts/asyncai), [AWS](https://docs.pipecat.ai/server/services/tts/aws), [Azure](https://docs.pipecat.ai/server/services/tts/azure), [Camb AI](https://docs.pipecat.ai/server/services/tts/camb), [Cartesia](https://docs.pipecat.ai/server/services/tts/cartesia), [Deepgram](https://docs.pipecat.ai/server/services/tts/deepgram), [ElevenLabs](https://docs.pipecat.ai/server/services/tts/elevenlabs), [Fish](https://docs.pipecat.ai/server/services/tts/fish), [Google](https://docs.pipecat.ai/server/services/tts/google), [Gradium](https://docs.pipecat.ai/server/services/tts/gradium), [Groq](https://docs.pipecat.ai/server/services/tts/groq), [Hathora](https://docs.pipecat.ai/server/services/tts/hathora), [Hume](https://docs.pipecat.ai/server/services/tts/hume), [Inworld](https://docs.pipecat.ai/server/services/tts/inworld), [LMNT](https://docs.pipecat.ai/server/services/tts/lmnt), [MiniMax](https://docs.pipecat.ai/server/services/tts/minimax), [Neuphonic](https://docs.pipecat.ai/server/services/tts/neuphonic), [NVIDIA Riva](https://docs.pipecat.ai/server/services/tts/riva), [OpenAI](https://docs.pipecat.ai/server/services/tts/openai), [Piper](https://docs.pipecat.ai/server/services/tts/piper), [PlayHT](https://docs.pipecat.ai/server/services/tts/playht), [Resemble](https://docs.pipecat.ai/server/services/tts/resemble), [Rime](https://docs.pipecat.ai/server/services/tts/rime), [Sarvam](https://docs.pipecat.ai/server/services/tts/sarvam), [Speechmatics](https://docs.pipecat.ai/server/services/tts/speechmatics), [XTTS](https://docs.pipecat.ai/server/services/tts/xtts) |
 | Speech-to-Speech    | [AWS Nova Sonic](https://docs.pipecat.ai/server/services/s2s/aws), [Gemini Multimodal Live](https://docs.pipecat.ai/server/services/s2s/gemini), [Grok Voice Agent](https://docs.pipecat.ai/server/services/s2s/grok), [OpenAI Realtime](https://docs.pipecat.ai/server/services/s2s/openai), [Ultravox](https://docs.pipecat.ai/server/services/s2s/ultravox),                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | Transport           | [Daily (WebRTC)](https://docs.pipecat.ai/server/services/transport/daily), [FastAPI Websocket](https://docs.pipecat.ai/server/services/transport/fastapi-websocket), [SmallWebRTCTransport](https://docs.pipecat.ai/server/services/transport/small-webrtc), [WebSocket Server](https://docs.pipecat.ai/server/services/transport/websocket-server), Local                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| Serializers         | [Plivo](https://docs.pipecat.ai/server/utilities/serializers/plivo), [Twilio](https://docs.pipecat.ai/server/utilities/serializers/twilio), [Telnyx](https://docs.pipecat.ai/server/utilities/serializers/telnyx)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Serializers         | [Exotel](https://docs.pipecat.ai/server/utilities/serializers/exotel), [Plivo](https://docs.pipecat.ai/server/utilities/serializers/plivo), [Twilio](https://docs.pipecat.ai/server/utilities/serializers/twilio), [Telnyx](https://docs.pipecat.ai/server/utilities/serializers/telnyx), [Vonage](https://docs.pipecat.ai/server/utilities/serializers/vonage)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | Video               | [HeyGen](https://docs.pipecat.ai/server/services/video/heygen), [Tavus](https://docs.pipecat.ai/server/services/video/tavus), [Simli](https://docs.pipecat.ai/server/services/video/simli)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Memory              | [mem0](https://docs.pipecat.ai/server/services/memory/mem0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Vision & Image      | [fal](https://docs.pipecat.ai/server/services/image-generation/fal), [Google Imagen](https://docs.pipecat.ai/server/services/image-generation/fal), [Moondream](https://docs.pipecat.ai/server/services/vision/moondream)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Vision & Image      | [fal](https://docs.pipecat.ai/server/services/image-generation/fal), [Google Imagen](https://docs.pipecat.ai/server/services/image-generation/google-imagen), [Moondream](https://docs.pipecat.ai/server/services/vision/moondream)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | Audio Processing    | [Silero VAD](https://docs.pipecat.ai/server/utilities/audio/silero-vad-analyzer), [Krisp](https://docs.pipecat.ai/server/utilities/audio/krisp-filter), [Koala](https://docs.pipecat.ai/server/utilities/audio/koala-filter), [ai-coustics](https://docs.pipecat.ai/server/utilities/audio/aic-filter)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | Analytics & Metrics | [OpenTelemetry](https://docs.pipecat.ai/server/utilities/opentelemetry), [Sentry](https://docs.pipecat.ai/server/services/analytics/sentry)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 

changelog/3045.added.md

@@ -1,42 +0,0 @@
-- Introducing user turn strategies. User turn strategies indicate when the user turn starts or stops. In conversational agents, these are often referred to as start/stop speaking or turn-taking plans or policies.
-
-  User turn start strategies indicate when the user starts speaking (e.g. using VAD events or when a user says one or more words).
-
-  User turn stop strategies indicate when the user stops speaking (e.g. using an end-of-turn detection model or by observing incoming transcriptions).
-
-  A list of strategies can be specified for both strategies; strategies are evaluated in order until one evaluates to true.
-
-  Available user turn start strategies:
-    - VADUserTurnStartStrategy
-    - TranscriptionUserTurnStartStrategy
-    - MinWordsUserTurnStartStrategy
-    - ExternalUserTurnStartStrategy
-
-  Available user turn stop strategies:
-    - TranscriptionUserTurnStopStrategy
-    - TurnAnalyzerUserTurnStopStrategy
-    - ExternalUserTurnStopStrategy
-
-  The default strategies are:
-
-    - start: [VADUserTurnStartStrategy, TranscriptionUserTurnStartStrategy]
-    - stop: [TranscriptionUserTurnStopStrategy]
-
-  Turn strategies are configured when setting up `LLMContextAggregatorPair`. For example:
-
-  ```python
-  context_aggregator = LLMContextAggregatorPair(
-      context,
-      user_params=LLMUserAggregatorParams(
-          user_turn_strategies=UserTurnStrategies(
-              stop=[
-                  TurnAnalyzerUserTurnStopStrategy(
-                      turn_analyzer=LocalSmartTurnAnalyzerV3(params=SmartTurnParams())
-                  )
-              ],
-          )
-      ),
-  )
-  ```
-
-  In order to use the user turn strategies you must update to the new universal `LLMContext` and `LLMContextAggregatorPair`.

changelog/3045.deprecated.2.md

@@ -1 +0,0 @@
-- ⚠️ `TransportParams.turn_analyzer` is deprecated and might result in unexpected behavior, use `LLMUserAggregator`'s new `user_turn_strategies` parameter instead.

changelog/3045.deprecated.3.md

@@ -1 +0,0 @@
-- `FrameProcessor.interruption_strategies` is deprecated, use `LLMUserAggregator`'s new `user_turn_strategies` parameter instead.

changelog/3045.deprecated.4.md

@@ -1 +0,0 @@
-- `EmulateUserStartedSpeakingFrame` and `EmulateUserStoppedSpeakingFrame` frames are deprecated.

changelog/3045.deprecated.5.md

@@ -1 +0,0 @@
-- Deprecated the `emulated` field in the `UserStartedSpeakingFrame` and `UserStoppedSpeakingFrame` frames.

changelog/3045.deprecated.6.md

@@ -1 +0,0 @@
-- The `LLMUserAggregatorParams` and `LLMAssistantAggregatorParams` classes in `pipecat.processors.aggregators.llm_response` are now deprecated. Use the new universal `LLMContext` and `LLMContextAggregatorPair` instead.

changelog/3045.deprecated.md

@@ -1 +0,0 @@
-- `pipecat.audio.interruptions.MinWordsInterruptionStrategy` is deprecated. Use `pipecat.turns.user_start.MinWordsUserTurnStartStrategy` with `LLMUserAggregator`'s new `user_turn_strategies` parameter instead.

changelog/3205.added.md

@@ -1 +0,0 @@
-- Added `RNNoiseFilter` for real-time noise suppression using RNNoise neural network via pyrnnoise library.

changelog/3216.changed.md

@@ -1,7 +0,0 @@
-- Updated `ElevenLabsRealtimeSTTService` to accept the `include_language_detection` parameter to detect language.
-  ```python
-    stt = ElevenLabsRealtimeSTTService(
-        api_key=os.getenv("ELEVENLABS_API_KEY"),
-        include_language_detection=True
-    )
-  ```

changelog/3225.changed.md

@@ -1,15 +0,0 @@
-- Updated `SpeechmaticsSTTService` to use new Python Voice SDK with improved VAD,
-  Smart Turn capabilities, and brings dramatic improvements to latency without
-  any impact on accuracy. Use the `turn_detection_mode` parameter to control the
-  endpointing of speech, with `TurnDetectionMode.EXTERNAL` (default),
-  `TurnDetectionMode.ADAPTIVE`, or `TurnDetectionMode.SMART_TURN`.
-  ```python
-    stt = SpeechmaticsSTTService(
-        api_key=os.getenv("SPEECHMATICS_API_KEY"),
-        params=SpeechmaticsSTTService.InputParams(
-            language=Language.EN,
-            turn_detection_mode=SpeechmaticsSTTService.TurnDetectionMode.ADAPTIVE,
-            speaker_active_format="<{speaker_id}>{text}</{speaker_id}>",
-        ),
-    )
-  ```

changelog/3225.deprecated.md

@@ -1,4 +0,0 @@
-- For `SpeechmaticsSTTService`, the `end_of_utterance_mode` parameter is deprecated.
-  Use the new `turn_detection_mode` parameter instead, with `TurnDetectionMode.EXTERNAL`,
-  `TurnDetectionMode.ADAPTIVE`, or `TurnDetectionMode.SMART_TURN`. The `enable_vad`
-  parameter is also deprecated and is inferred from the `turn_detection_mode`.

changelog/3233.fixed.md

@@ -1,2 +0,0 @@
-- Improved error handling in `ElevenLabsRealtimeSTTService`
-- Fixed an issue in `ElevenLabsRealtimeSTTService` causing an infinite loop that blocks the process if the websocket disconnects due to an error

changelog/3257.changed.2.md

@@ -1 +0,0 @@
-- `TranscriptionFrame` and `InterimTranscriptionFrame` produced by `DailyTransport` now include the transport source (i.e., the originating audio track).

changelog/3257.changed.md

@@ -1 +0,0 @@
-- `daily-python` updated to 0.23.0.

changelog/3263.deprecated.md

@@ -1,15 +0,0 @@
-- `OpenAILLMContext` and its associated things (context aggregators, etc.) are now deprecated in favor of the universal `LLMContext` and its associated things.
-
-  From the developer's point of view, switching to using `LLMContext` machinery will usually be a matter of going from this:
-
-  ```python
-  context = OpenAILLMContext(messages, tools)
-  context_aggregator = llm.create_context_aggregator(context)
-  ```
-
-  To this:
-
-  ```
-  context = LLMContext(messages, tools)
-  context_aggregator = LLMContextAggregatorPair(context)
-  ```

changelog/3267.added.md

@@ -1,8 +0,0 @@
-- Added `GrokRealtimeLLMService` for xAI's Grok Voice Agent API with real-time voice conversations:
-
-  - Support for real-time audio streaming with WebSocket connection
-  - Built-in server-side VAD (Voice Activity Detection)
-  - Multiple voice options: Ara, Rex, Sal, Eve, Leo
-  - Built-in tools support: web_search, x_search, file_search
-  - Custom function calling with standard Pipecat tools schema
-  - Configurable audio formats (PCM at 8kHz-48kHz)

changelog/3268.added.md

@@ -1 +0,0 @@
-- Added an approximation of TTFB for Ultravox.

changelog/3288.changed.md

@@ -1,5 +0,0 @@
-- Updates to Inworld TTS services:
-
-  - Improved `InworldTTSService`'s websocket implementation to better flush and
-    close context to better handle long inputs.
-  - Improved docstrings for `InworldTTSService` and `InworldHttpTTSService`.

changelog/3289.added.md

@@ -1 +0,0 @@
-- Added a new `AudioContextTTSService` to the TTS service base classes. The `AudioContextWordTTSService` now inherits from `AudioContextTTSService` and `WebsocketWordTTSService`.

changelog/3291.added.md

@@ -1,4 +0,0 @@
-- `LLMUserAggregator` now exposes the following events:
-   - `on_user_turn_started`: triggered when a user turn starts
-   - `on_user_turn_stopped`: triggered when a user turn ends
-   - `on_user_turn_stop_timeout`: triggered when a user turn does not stop and times out

changelog/3292.added.md

@@ -1,29 +0,0 @@
-- Introducing user mute strategies. User mute strategies indicate when user input should be muted based on the current system state.
-
-  In conversational agents, user mute strategies are used to prevent user input from interrupting bot speech, tool execution, or other critical system operations.
-
-  A list of strategies can be specified; all strategies are evaluated for every frame so that each strategy can maintain its internal state. A user frame is muted if any of the configured strategies indicates it should be muted.
-
-  Available user mute strategies:
-
-  * `FirstSpeechUserMuteStrategy`
-  * `MuteUntilFirstBotCompleteUserMuteStrategy`
-  * `AlwaysUserMuteStrategy`
-  * `FunctionCallUserMuteStrategy`
-
-  User mute strategies replace the legacy `STTMuteFilter` and provide a more flexible and composable approach to muting user input.
-
-  User mute strategies are configured when setting up the `LLMContextAggregatorPair`. For example:
-
-  ```python
-  context_aggregator = LLMContextAggregatorPair(
-      context,
-      user_params=LLMUserAggregatorParams(
-          user_mute_strategies=[
-              FirstSpeechUserMuteStrategy(),
-          ]
-      ),
-  )
-  ```
-
-  In order to use user mute strategies you should update to the new universal `LLMContext` and `LLMContextAggregatorPair`.

changelog/3292.deprecated.md

@@ -1 +0,0 @@
-- `STTMuteFilter` is deprecated and will be removed in a future version. Use `LLMUserAggregator`'s new `user_mute_strategies` instead.

changelog/3292.fixed.md

@@ -1 +0,0 @@
-- Fixed a bug in `STTMuteFilter` where the user was not always muted during function calls, especially when there were multiple simultaneous calls.

changelog/3297.deprecated.2.md

@@ -1 +0,0 @@
-- `FrameProcessor.interruptions_allowed` is now deprecated, use `LLMUserAggregator`'s new parameter `user_mute_strategies` instead.

changelog/3297.deprecated.md

@@ -1,12 +0,0 @@
-- `PipelineParams.allow_interruptions` is now deprecated, use `LLMUserAggregator`'s new parameter `user_turn_strategies` instead. For example, to disable interruptions but still get user turns you can do:
-
-  ```python
-  context_aggregator = LLMContextAggregatorPair(
-      context,
-      user_params=LLMUserAggregatorParams(
-          user_turn_strategies=UserTurnStrategies(
-              start=[TranscriptionUserTurnStartStrategy(enable_interruptions=False)],
-          ),
-      ),
-  )
-  ```

changelog/3300.added.md

@@ -1 +0,0 @@
-- Added `use_ssl` parameter to `NvidiaSTTService`, `NvidiaSegmentedSTTService` and `NvidiaTTSService`.

changelog/3314.changed.md

@@ -1 +0,0 @@
-- Updated `DeepgramSTTService` to push user started/stopped speaking and interruption frames when `vad_enabled` is set to true. This centralizes the frames into the service, removing the need to have your application code handle Deepgram's events and push these frames.

changelog/3316.added.md

@@ -1 +0,0 @@
-- Added `enable_interruptions` constructor argument to all user turn strategies. This tells the `LLMUserAggregator` to push or not push an `InterruptionFrame`.

changelog/3316.other.md

@@ -1 +0,0 @@
-- Added `52-live-transcription.py` foundational example demonstrating live transcription and translation from English to Spanish. In this example, the bot is not interruptible: as the user continues speaking, English transcriptions are queued, and the bot continuously translates and speaks each queued sentence in Spanish without being interrupted by new user speech.

changelog/3322.fixed.md

@@ -1 +0,0 @@
-- Fixed a `RNNoiseFilter` issue that would cause a "[Errno 12] Cannot allocate memory" error when processing silence audio frames.

changelog/3328.added.md

@@ -1 +0,0 @@
-- Added `split_sentences` parameter to `SpeechmaticsSTTService` to control sentence splitting behavior for finals on sentence boundaries.

changelog/3328.fixed.md

@@ -1,4 +0,0 @@
-- Updated `SpeechmaticsSTTService` for version `0.0.99+`:
-  - Fixed `SpeechmaticsSTTService` to listen for `VADUserStoppedSpeakingFrame` in order to finalize transcription.
-  - Default to `TurnDetectionMode.FIXED` for Pipecat-controlled end of turn detection.
-  - Only emit VAD + interruption frames if VAD is enabled within the plugin (modes other than `TurnDetectionMode.FIXED` or `TurnDetectionMode.EXTERNAL`).

changelog/3329.changed.md

@@ -1 +0,0 @@
-- Added encoding validation to `DeepgramTTSService` to prevent unsupported encodings from reaching the API. The service now raises `ValueError` at initialization with a clear error message.

changelog/3334.added.md

@@ -1,2 +0,0 @@
-- Added word-level timestamp support to `AzureTTSService` for accurate text-to-audio synchronization.
-  

changelog/3336.changed.md

@@ -1 +0,0 @@
-- Updated `read_audio_frame` & `read_video_frame` methods in `SmallWebRTCClient` to check if the track is enabled before logging a warning.

changelog/3343.fixed.md

@@ -1 +0,0 @@
-- Fixed an issue with function calling where a handler failing to invoke its result callback could leave the context stuck in IN_PROGRESS, causing LLM inference for subsequent function call results to block while waiting on the unresolved call.

changelog/3345.fixed.md

@@ -1 +0,0 @@
-- Fixed an issue with DeepgramTTSService where the model would output "Dot" instead of a period in some circumstances.

changelog/3346.added.md

@@ -1 +0,0 @@
-- Added `pronunciation_dict_id` parameter to `CartesiaTTSService.InputParams` and `CartesiaHttpTTSService.InputParams` to support Cartesia's pronunciation dictionary feature for custom pronunciations.

changelog/3356.fixed.md

@@ -1 +0,0 @@
-- Fixed an issue in GeminiLiveLLMService where TranscriptionFrames were occasionally not pushed.

changelog/3357.added.md

@@ -1 +0,0 @@
-- Added support for using the HeyGen LiveAvatar API with the `HeyGenTransport` (see https://www.liveavatar.com/).

changelog/3360.added.md

@@ -1,8 +0,0 @@
-- Added image support to `OpenAIRealtimeLLMService` via `InputImageRawFrame`:
-  - New `start_video_paused` parameter to control initial video input state
-  - New `video_frame_detail` parameter to set image processing quality ("auto",
-    "low", or "high"). This corresponds to OpenAI Realtime's `image_detail`
-    parameter.
-  - `set_video_input_paused()` method to pause/resume video input at runtime
-  - `set_video_frame_detail()` method to adjust video frame quality dynamically
-  - Automatic rate limiting (1 frame per second) to prevent API overload

changelog/3366.changed.md

@@ -1 +0,0 @@
-- Updated `CartesiaTTSService` to support setting `language=None`, resulting in Cartesia auto-detecting the language of the conversation.

changelog/3367.changed.md

@@ -1,3 +0,0 @@
-- The bundled Smart Turn weights are now updated to v3.2, which has better
-  handling of short utterances, and is more robust against background
-  noise.

changelog/3371.changed.md

@@ -1 +0,0 @@
-- Updated `SpeechmaticsSTTService` dependency to `speechmatics-voice[smart]>=0.2.6`

changelog/3372.added.2.md

@@ -1 +0,0 @@
-- Added `UserTurnProcessor`, a frame processor built on `UserTurnController` that pushes `UserStartedSpeakingFrame` and `UserStoppedSpeakingFrame` frames and interruptions based on the controller's user turn strategies.

changelog/3372.added.md

@@ -1 +0,0 @@
-- Added `UserTurnController` to manage user turns. It emits `on_user_turn_started`, `on_user_turn_stopped`, and `on_user_turn_stop_timeout` events, and can be integrated into processors to detect and handle user turns. `LLMUserAggregator` and `UserTurnProcessor` are implemented using this controller.

changelog/3372.other.md

@@ -1 +0,0 @@
-- Added a new foundational example `53-concurrent-llm-evaluation.py` that shows how to use `UserTurnProcessor`.

changelog/3374.added.md

@@ -1 +0,0 @@
-- Added `should_interrupt` property to `DeepgramFluxSTTService`, `DeepgramSTTService`, and `SpeechmaticsSTTService` to configure whether the bot should be interrupted when the external service detects user speech.

changelog/3377.changed.md

@@ -1,5 +0,0 @@
-- Smart Turn now takes into account `vad_start_seconds` when buffering audio,
-  meaning that the start of the turn audio is not cut off. This improves
-  accuracy for short utterances.
-
-- The default value of `pre_speech_ms` is now set to 500ms for Smart Turn.

changelog/3385.added.md

@@ -1,4 +0,0 @@
-- `LLMAssistantAggregator` now exposes the following events:
-   - `on_assistant_turn_started`: triggered when the assistant turn starts
-   - `on_assistant_turn_stopped`: triggered when the assistant turn ends
-   - `on_assistant_thought`: triggered when there's an assistant thought available

changelog/3385.deprecated.md

@@ -1 +0,0 @@
-- `TranscriptProcessor` and related data classes and frames (`TranscriptionMessage`, `ThoughtTranscriptionMessage`, `TranscriptionUpdateFrame`) are deprecated. Use `LLMUserAggregator`'s and `LLMAssistantAggregator`'s new events (`on_user_turn_stopped` and `on_assistant_turn_stopped`) instead.

changelog/3385.other.md

@@ -1 +0,0 @@
-- Added a new foundational example `28-user-assistant-turns.py` that shows how to use the new `LLMUserAggregator` and `LLMAssistantAggregator` events to gather a conversation transcript.

changelog/3386.deprecated.md

@@ -1 +0,0 @@
-- Deprecated support for the `vad_events` `LiveOptions` in `DeepgramSTTService`. Instead, use a local Silero VAD for VAD events. Additionally, deprecated `should_interrupt` which will be removed along with `vad_events` support in a future release.

changelog/3391.added.md

@@ -1 +0,0 @@
-- Added `KrispVivaTurn` analyzer for end of turn detection using the Krisp VIVA SDK (requires `krisp_audio`).

changelog/3391.changed.md

@@ -1 +0,0 @@
-- Improved Krisp SDK management to allow `KrispVivaTurn` and `KrispVivaFilter` to share a single SDK instance within the same process.

changelog/3391.fixed.md

@@ -1 +0,0 @@
-- Fixed potential memory leaks and initialization issues in `KrispVivaFilter` by improving SDK lifecycle management.

changelog/3397.added.md

@@ -1,6 +0,0 @@
-- Added support for setting up a pipeline task from external files. You can now register custom pipeline task setup files by setting the `PIPECAT_SETUP_FILES` environment variable. This variable should contain a colon-separated list of Python files (e.g. `export PIPECAT_SETUP_FILES="setup1.py:setup.py:..."`). Each file must define a function with the following signature:
-
-  ```python
-  async def setup_pipeline_task(task: PipelineTask):
-      ...
-  ```

changelog/3397.deprecated.md

@@ -1 +0,0 @@
-- Loading external observers from files is deprecated, use the new pipeline task setup files and `PIPECAT_SETUP_FILES` environment variable instead.

changelog/3399.changed.md

@@ -1 +0,0 @@
-- Updated default model for `GroqTTSService` to `canopylabs/orpheus-v1-english` and voice ID to `autumn`.

changelog/3400.fixed.md

@@ -1 +0,0 @@
-- Fixed timing issue in `BaseOutputTransport` where the bot speaking flag was set after awaiting, allowing the event loop to re-enter the method before the guard was set.

changelog/3615.fixed.md

@@ -0,0 +1 @@
+- Fixed race condition where `RTVIObserver` could send messages before `DailyTransport` join completed. Outbound messages are now queued & delivered after the transport is ready.

changelog/3625.added.md

@@ -0,0 +1 @@
+- Added `"timestampTransportStrategy": "ASYNC"` to `InworldAITTSService`. This allows timestamps info to trail audio chunks arrival, resulting in much better first audio chunk latency

changelog/3642.added.md

@@ -0,0 +1 @@
+- Added model-specific `InputParams` to `RimeTTSService`: arcana params (`repetition_penalty`, `temperature`, `top_p`) and mistv2 params (`no_text_normalization`, `save_oovs`, `segment`). Model, voice, and param changes now trigger WebSocket reconnection.

changelog/3642.changed.md

@@ -0,0 +1 @@
+- ⚠️ `RimeTTSService` now defaults to `model="arcana"` and the `wss://users-ws.rime.ai/ws3` endpoint. `InputParams` defaults changed from mistv2-specific values to `None` — only explicitly-set params are sent as query params.

changelog/3684.changed.md

@@ -0,0 +1,3 @@
+- `AICFilter` now shares read-only AIC models via a singleton `AICModelManager` in `aic_filter.py`.
+  - Multiple filters using the same model path or `(model_id, model_download_dir)` share one loaded model, with reference counting and concurrent load deduplication. 
+  - Model file I/O runs off the event loop so the filter does not block.

changelog/3698.fixed.md

@@ -0,0 +1 @@
+- Fixed async generator cleanup in OpenAI LLM streaming to prevent `AttributeError` with uvloop on Python 3.12+ (MagicStack/uvloop#699).

changelog/3706.changed.md

@@ -0,0 +1 @@
+- Added `X-User-Agent` and `X-Request-Id` headers to `InworldTTSService` for better traceability.

changelog/3713.fixed.md

@@ -0,0 +1 @@
+- Fixed `SmallWebRTCTransport` input audio resampling to properly handle all sample rates, including 8kHz audio.

changelog/3718.fixed.md

@@ -0,0 +1 @@
+- Fixed a race condition in `RTVIObserver` where bot output messages could be sent before the bot-started-speaking event.

changelog/3719.added.2.md

@@ -0,0 +1 @@
+- Added `write_transport_frame()` hook to `BaseOutputTransport` allowing transport subclasses to handle custom frame types that flow through the audio queue.

changelog/3719.added.md

@@ -0,0 +1 @@
+- Added `DailySIPTransferFrame` and `DailySIPReferFrame` to the Daily transport.  These frames queue SIP transfer and SIP REFER operations with audio, so the operation executes only after the bot finishes its current utterance.

changelog/3719.changed.md

@@ -0,0 +1 @@
+- `DailyUpdateRemoteParticipantsFrame` is no longer deprecated and is now queued with audio like other transport frames.

changelog/3720.fixed.md

@@ -0,0 +1 @@
+- Fixed Grok Realtime `session.updated` event parsing failure caused by the API returning prefixed voice names (e.g. `"human_Ara"` instead of `"Ara"`).

changelog/3728.changed.md

@@ -0,0 +1 @@
+- Bumped Pillow dependency upper bound from `<12` to `<13` to allow Pillow 12.x.

changelog/3729.fixed.2.md

@@ -0,0 +1 @@
+- Fixed context ID reuse issue in `ElevenLabsTTSService`, `InworldTTSService`, `RimeTTSService`, `CartesiaTTSService`, `AsyncAITTSService`, and `PlayHTTTSService`. Services now properly reuse the same context ID across multiple `run_tts()` invocations within a single LLM turn, preventing context tracking issues and incorrect lifecycle signaling.

changelog/3729.fixed.md

@@ -0,0 +1 @@
+- Fixed word timestamp interleaving issue in `ElevenLabsTTSService` when processing multiple sentences within a single LLM turn.

changelog/3730.added.md

@@ -0,0 +1 @@
+- Added keepalive support to `SarvamSTTService` to prevent idle connection timeouts (e.g. when used behind a `ServiceSwitcher`).

changelog/3730.changed.md

@@ -0,0 +1 @@
+- Moved STT keepalive mechanism from `WebsocketSTTService` to the `STTService` base class, allowing any STT service (not just websocket-based ones) to use idle-connection keepalive via the `keepalive_timeout` and `keepalive_interval` parameters.

changelog/3732.changed.md

@@ -0,0 +1,3 @@
+- Improved audio context management in `AudioContextTTSService` by moving context ID tracking to the base class and adding `reuse_context_id_within_turn` parameter to control concurrent TTS request handling.
+  - Added helper methods: `has_active_audio_context()`, `get_active_audio_context_id()`, `remove_active_audio_context()`, `reset_active_audio_context()`
+  - Simplified Cartesia, ElevenLabs, Inworld, Rime, AsyncAI, and Gradium TTS implementations by removing duplicate context management code

changelog/3733.deprecated.md

@@ -0,0 +1 @@
+- Deprecated unused `Traceable`, `@traceable`, `@traced`, and `AttachmentStrategy` in `pipecat.utils.tracing.class_decorators`. This module will be removed in a future release.

changelog/3735.fixed.md

@@ -0,0 +1 @@
+- Fixed tracing service decorators executing the wrapped function twice when the function itself raised an exception (e.g., LLM rate limit, TTS timeout).

changelog/3737.fixed.md

@@ -0,0 +1 @@
+- Fixed `LLMUserAggregator` broadcasting mute events before `StartFrame` reaches downstream processors.

changelog/3744.fixed.md

@@ -0,0 +1 @@
+- Fixed `UserIdleController` false idle triggers caused by gaps between user and bot activity frames. The idle timer now starts only after `BotStoppedSpeakingFrame` and is suppressed during active user turns and function calls.

changelog/3748.added.md

@@ -0,0 +1 @@
+- Added `UserIdleTimeoutUpdateFrame` to enable or disable user idle detection at runtime by updating the timeout dynamically.