Drop redundant changelog entry for OpenAI Realtime example

The OpenAI Realtime story didn't add any service-level code — just a
new example. The original 4480.added.md entry already describes the
feature as "a realtime service like Gemini Live," which generalizes
to OpenAI Realtime.

.agents/skills/changelog

@@ -0,0 +1 @@
+../../.claude/skills/changelog

.agents/skills/cleanup

@@ -0,0 +1 @@
+../../.claude/skills/cleanup

.agents/skills/code-review

@@ -0,0 +1 @@
+../../.claude/skills/code-review

.agents/skills/docstring

@@ -0,0 +1 @@
+../../.claude/skills/docstring

.agents/skills/pr-description

@@ -0,0 +1 @@
+../../.claude/skills/pr-description

.agents/skills/pr-submit

@@ -0,0 +1 @@
+../../.claude/skills/pr-submit

.agents/skills/update-docs

@@ -0,0 +1 @@
+../../.claude/skills/update-docs

.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "name": "pipecat-dev-skills",
+  "owner": {
+    "name": "Pipecat"
+  },
+  "metadata": {
+    "description": "Development workflow skills for contributing to the Pipecat project",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "pipecat-dev",
+      "description": "Development workflow skills for contributing to the Pipecat project",
+      "version": "1.0.0",
+      "source": "./",
+      "skills": [
+        "./.claude/skills/changelog",
+        "./.claude/skills/cleanup",
+        "./.claude/skills/code-review",
+        "./.claude/skills/docstring",
+        "./.claude/skills/pr-description",
+        "./.claude/skills/pr-submit",
+        "./.claude/skills/update-docs"
+      ]
+    }
+  ]
+}

.claude/skills/changelog/SKILL.md

@@ -32,6 +32,20 @@ Create changelog files for the important commits in this PR. The PR number is pr
 
 6. Use ⚠️ emoji prefix for breaking changes.
 
+7. **Write changes in user-facing terms first.** Lead with what users of the framework will notice: new APIs, changed behavior, new parameters, fixed bugs they might have hit, etc. Implementation details (internal refactoring, how something is wired up under the hood) can be included as secondary context after the user-facing description, but should never be the *only* content of a changelog entry when there is a user-visible effect.
+
+   **Good** (user-facing first, implementation detail as context):
+   ```
+   - Turn completion instructions now persist correctly across full context updates when using `system_instruction`. Previously they were injected as a context system message, which caused warning spam and didn't survive context updates.
+   ```
+
+   **Bad** (implementation detail only, no user-facing framing):
+   ```
+   - Fixed turn completion instructions being injected as a context system message instead of using `system_instruction`.
+   ```
+
+   Ask yourself: "If I'm a developer building on Pipecat, what would I notice changed?" Start there.
+
 ## Example
 
 For PR #3519 with a new feature and a bug fix:
@@ -43,5 +57,5 @@ For PR #3519 with a new feature and a bug fix:
 
 `changelog/3519.fixed.md`:
 ```
-- Fixed an issue where something was not working correctly.
+- Fixed an issue where something was not working correctly in some user-visible scenario. The root cause was an internal implementation detail.
 ```

.claude/skills/cleanup/SKILL.md

@@ -1,6 +1,11 @@
+---
+name: cleanup
+description: Review, refactor, document, and validate code changes in the current branch
+---
+
 # 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**.
+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.
 
 ---
@@ -28,9 +33,9 @@ This skill analyzes all changes introduced in your branch and performs the follo
 
 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”
+- "Clean up my branch code"
+- "Refactor the changes in my branch"
+- "Review and improve my branch code"
 - `/cleanup`
 
 ---
@@ -144,7 +149,7 @@ class InputParams(BaseModel):
 
 #### Examples
 
-Validated against `examples/foundational/07-interruptible.py`:
+Validated against `examples/07-interruptible.py`:
 
 - Proper `create_transport()` usage
 - Correct pipeline structure

.claude/skills/docstring/SKILL.md

@@ -3,21 +3,20 @@ 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.
+Document a Python module or class using Google-style docstrings following project conventions. The argument can be a class name or a module path.
 
 ## Instructions
 
-1. First, find the class in the codebase:
-   ```
-   Search for "class ClassName" in src/pipecat/
-   ```
+1. Determine what to document based on the argument:
 
-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
+   **If a module path is provided** (e.g. `src/pipecat/audio/vad/vad_analyzer.py`):
+   - Use that file directly
 
-3. Once the file is identified, read the module to understand its structure:
+   **If a class name is provided** (e.g. `VADAnalyzer`):
+   - Search for `class ClassName` in `src/pipecat/`
+   - If multiple files contain that class name, list all matches with their file paths, ask the user which one they want to document, and wait for confirmation
+
+2. 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
 

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

@@ -157,7 +157,11 @@ After processing all mapped pairs, check for two kinds of gaps:
 
 **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:
+If the user wants a new page, do all three of the following:
+
+#### 8a: Create the doc page
+
+Create the new `.mdx` file using this template structure:
 ```
 ---
 title: "Service Name"
@@ -207,6 +211,53 @@ pip install "pipecat-ai[package-name]"
 [Event table and example code]
 ```
 
+#### 8b: Add to docs.json
+
+Add the new page path to `DOCS_PATH/docs.json` in the correct navigation group. The path format is `server/services/{category}/{provider}` (without the `.mdx` extension).
+
+Find the matching group in the navigation structure:
+- **STT** → `"group": "Speech-to-Text"` under Services
+- **TTS** → `"group": "Text-to-Speech"` under Services
+- **LLM** → `"group": "LLM"` under Services
+- **S2S** → `"group": "Speech-to-Speech"` under Services
+- **Transport** → `"group": "Transport"` under Services
+- **Serializer** → `"group": "Serializers"` under Services
+- **Image generation** → `"group": "Image Generation"` under Services
+- **Video** → `"group": "Video"` under Services
+- **Memory** → `"group": "Memory"` under Services
+- **Vision** → `"group": "Vision"` under Services
+- **Analytics** → `"group": "Analytics & Monitoring"` under Services
+
+Insert the new entry **alphabetically** within the group's `pages` array. For example, adding a new STT service "foo":
+```json
+{
+  "group": "Speech-to-Text",
+  "pages": [
+    "server/services/stt/assemblyai",
+    "server/services/stt/aws",
+    ...
+    "server/services/stt/foo",
+    ...
+  ]
+}
+```
+
+#### 8c: Add to supported-services.mdx
+
+Add a new row to the correct category table in `DOCS_PATH/server/services/supported-services.mdx`.
+
+Use this format:
+```
+| [DisplayName](/server/services/{category}/{provider}) | `pip install "pipecat-ai[package]"` |
+```
+
+To determine the correct values:
+- **DisplayName**: Use the service's human-readable name (e.g., "ElevenLabs", "AWS Polly", "Google Gemini")
+- **package**: Look at the service's `pyproject.toml` extras or the import pattern in the source code. For example, if the service is in `src/pipecat/services/foo/`, the package is typically `foo`.
+- If no pip dependencies are required, use `No dependencies required` instead.
+
+Insert the new row **alphabetically** within the table. Match the column alignment of the existing rows.
+
 ### Step 9: Output summary
 
 After all edits are complete, print a summary:
@@ -221,6 +272,9 @@ After all edits are complete, print a summary:
 ### Updated guides
 - `guides/learn/speech-to-text.mdx` — Updated code example (renamed `old_param` → `new_param`)
 
+### New service pages
+- `server/services/tts/newprovider.mdx` — Created page, added to docs.json (Text-to-Speech), added to supported-services.mdx
+
 ### Unmapped source files
 - `src/pipecat/services/newprovider/tts.py` — NewProviderTTSService (no doc page exists)
 
@@ -247,4 +301,6 @@ Before finishing, verify:
 - [ ] New parameters have accurate types and defaults from source
 - [ ] Formatting matches the existing page style
 - [ ] Guides referencing changed APIs were checked and updated
+- [ ] New service pages were added to `docs.json` in the correct group, alphabetically
+- [ ] New service pages were added to `supported-services.mdx` in the correct table, alphabetically
 - [ ] Unmapped files were reported to the user

.dockerignore

@@ -1,30 +0,0 @@
-# flyctl launch added from .gitignore
-**/.vscode
-**/env
-**/__pycache__
-**/*~
-**/venv
-#*#
-
-# Distribution / packaging
-**/.Python
-**/build
-**/develop-eggs
-**/dist
-**/downloads
-**/eggs
-**/.eggs
-**/lib
-**/lib64
-**/parts
-**/sdist
-**/var
-**/wheels
-**/share/python-wheels
-**/*.egg-info
-**/.installed.cfg
-**/*.egg
-**/MANIFEST
-**/.DS_Store
-**/.env
-fly.toml

.github/workflows/coverage.yaml

@@ -37,11 +37,13 @@ jobs:
           uv sync --group dev \
             --extra anthropic \
             --extra aws \
+            --extra deepgram \
             --extra google \
             --extra langchain \
             --extra livekit \
-            --extra local-smart-turn-v3 \
             --extra piper \
+            --extra runner \
+            --extra sagemaker \
             --extra tracing \
             --extra websocket
 

.github/workflows/format.yaml

@@ -32,7 +32,9 @@ jobs:
         run: uv python install 3.12
 
       - name: Install development dependencies
-        run: uv sync --group dev
+        # `--all-extras` (matching the dev setup in README.md) so pyright can
+        # resolve types from various optional dependencies.
+        run: uv sync --group dev --all-extras --no-extra gstreamer --no-extra local
 
       - name: Ruff formatter
         id: ruff-format
@@ -41,3 +43,7 @@ jobs:
       - name: Ruff linter (all rules)
         id: ruff-check
         run: uv run ruff check
+
+      - name: Type check (pyright)
+        id: pyright
+        run: uv run pyright

.github/workflows/python-compatibility.yaml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.10.19', '3.11.14', '3.12.12', '3.13.12']
+        python-version: ['3.11.15', '3.12.13', '3.13.12', '3.14.3']
 
     name: Python ${{ matrix.python-version }}
     steps:
@@ -42,7 +42,7 @@ jobs:
 
       - name: Test uv sync with all extras
         run: |
-          uv sync --group dev --all-extras --no-extra krisp
+          uv sync --group dev --all-extras
 
       - name: Verify installation
         run: |

.github/workflows/sync-quickstart.yaml

@@ -1,51 +0,0 @@
-name: Sync Quickstart to pipecat-quickstart repo
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'examples/quickstart/**'
-  workflow_dispatch: # Manual trigger
-
-jobs:
-  sync-quickstart:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout main repo
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Checkout quickstart repo
-        uses: actions/checkout@v4
-        with:
-          repository: pipecat-ai/pipecat-quickstart
-          token: ${{ secrets.QUICKSTART_SYNC_TOKEN }}
-          path: quickstart-repo
-
-      - name: Sync files (excluding uv.lock and README.md)
-        run: |
-          # Copy all files except uv.lock and README.md
-          find examples/quickstart -type f \
-            -not -name "README.md" \
-            -not -name "uv.lock" \
-            -exec cp {} quickstart-repo/ \;
-
-      - name: Commit and push changes
-        run: |
-          cd quickstart-repo
-          git config user.name "GitHub Action"
-          git config user.email "action@github.com"
-          git add .
-
-          # Only commit if there are changes
-          if ! git diff --staged --quiet; then
-            git commit -m "Sync from pipecat main repo
-            
-            Updated files from examples/quickstart/
-            Commit: ${{ github.sha }}
-            "
-            git push
-          else
-            echo "No changes to sync"
-          fi

.github/workflows/tests.yaml

@@ -41,11 +41,13 @@ jobs:
           uv sync --group dev \
             --extra anthropic \
             --extra aws \
+            --extra deepgram \
             --extra google \
             --extra langchain \
             --extra livekit \
-            --extra local-smart-turn-v3 \
             --extra piper \
+            --extra runner \
+            --extra sagemaker \
             --extra tracing \
             --extra websocket
 

.github/workflows/update-docs.yml

@@ -0,0 +1,148 @@
+name: Update Documentation on PR Merge
+
+on:
+  pull_request_target:
+    types: [closed]
+    branches: [main]
+    paths:
+      - "src/pipecat/services/**"
+      - "src/pipecat/transports/**"
+      - "src/pipecat/serializers/**"
+      - "src/pipecat/processors/**"
+      - "src/pipecat/audio/**"
+      - "src/pipecat/turns/**"
+      - "src/pipecat/observers/**"
+      - "src/pipecat/pipeline/**"
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "PR number to generate docs for"
+        required: true
+        type: string
+
+jobs:
+  update-docs:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      pull-requests: read
+      id-token: write
+    steps:
+      - name: Checkout pipecat
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Checkout docs
+        uses: actions/checkout@v4
+        with:
+          repository: pipecat-ai/docs
+          token: ${{ secrets.DOCS_SYNC_TOKEN }}
+          path: _docs
+
+      - name: Resolve PR number
+        id: pr
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "number=${{ inputs.pr_number }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update documentation
+        uses: anthropics/claude-code-action@v1
+        env:
+          DOCS_SYNC_TOKEN: ${{ secrets.DOCS_SYNC_TOKEN }}
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: |
+            You are updating documentation for the pipecat-ai/docs repository based on
+            changes merged in PR #${{ steps.pr.outputs.number }} of pipecat-ai/pipecat.
+
+            ## Setup
+
+            1. Read the skill instructions at `.claude/skills/update-docs/SKILL.md`
+            2. Read the source-to-doc mapping at `.claude/skills/update-docs/SOURCE_DOC_MAPPING.md`
+            3. The docs repository is checked out at `./_docs/`
+
+            ## Get the diff
+
+            Run `gh pr diff ${{ steps.pr.outputs.number }}` to see what changed in the PR.
+            Also run `gh pr diff ${{ steps.pr.outputs.number }} --name-only` to get the list of changed files.
+            Filter to source files matching the directories listed in SKILL.md Step 3.
+
+            If no relevant source files were changed, exit with "No documentation changes needed."
+
+            ## Follow the skill instructions
+
+            Apply the SKILL.md workflow (Steps 3-9) with these adaptations for automation:
+
+            ### Docs path
+            Use `./_docs/` — it's already checked out. Do not ask for a path.
+
+            ### Branch management
+            - Branch name: `docs/pr-${{ steps.pr.outputs.number }}`
+            - Work inside `./_docs/` for all doc edits and git operations
+            - Check if the branch already exists on the remote:
+              ```bash
+              cd _docs && git fetch origin docs/pr-${{ steps.pr.outputs.number }} 2>/dev/null
+              ```
+              - If it exists: check it out (supports workflow re-runs)
+              - If not: create it from main
+
+            ### Git config
+            Before committing in `_docs`, set:
+            ```bash
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            ```
+
+            ### No interactive questions
+            Do not ask questions. If you encounter gaps (unmapped files, missing sections,
+            ambiguous changes), note them in the PR body under "## Gaps identified".
+
+            ### Creating the docs PR
+            After committing all changes in `_docs`, push and create a PR:
+            ```bash
+            cd _docs
+            git push -u origin docs/pr-${{ steps.pr.outputs.number }}
+            GH_TOKEN=$DOCS_SYNC_TOKEN gh pr create \
+              --repo pipecat-ai/docs \
+              --label auto-docs \
+              --label pipecat \
+              --title "docs: update for pipecat PR #${{ steps.pr.outputs.number }}" \
+              --body "$(cat <<'BODY'
+            Automated documentation update for [pipecat PR #${{ steps.pr.outputs.number }}](https://github.com/pipecat-ai/pipecat/pull/${{ steps.pr.outputs.number }}).
+
+            ## Changes
+            <summarize each doc page updated and what changed>
+
+            ## Gaps identified
+            <any unmapped files, missing doc pages, or missing sections — or "None">
+            BODY
+            )"
+            ```
+
+            ### Re-run handling
+            If `gh pr create` fails because a PR from that branch already exists,
+            push the updated commits and use `gh pr edit` to update the body instead.
+
+            ### No-op
+            If after analyzing the diff you determine no documentation changes are needed
+            (e.g., only skip-listed files changed, or changes don't affect public API docs),
+            exit cleanly without creating a branch or PR. Output "No documentation changes needed."
+
+            ## Important rules
+            - Only modify files inside `./_docs/` — never modify pipecat source code
+            - Follow the conservative editing rules from SKILL.md Step 6
+            - Read each doc page fully before editing (SKILL.md Guidelines)
+            - Use `GH_TOKEN=$DOCS_SYNC_TOKEN` for all `gh` commands targeting pipecat-ai/docs
+          claude_args: |
+            --model claude-sonnet-4-5-20250929
+            --max-turns 30
+            --allowedTools "Read,Write,Edit,Glob,Grep,Bash"

.pre-commit-config.yaml

@@ -1,8 +1,13 @@
 repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.1
+  - repo: local
     hooks:
       - id: ruff
-        language_version: python3
-        args: [--fix]
+        name: ruff
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
       - id: ruff-format
+        name: ruff-format
+        entry: uv run ruff format
+        language: system
+        types: [python]

.readthedocs.yaml

@@ -11,7 +11,7 @@ build:
   jobs:
     post_install:
       - pip install uv
-      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --group docs --all-extras --no-extra krisp --no-extra gstreamer --no-extra local_smart_turn --no-extra moondream --no-extra riva --no-extra mlx-whisper
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --group docs --all-extras --no-extra gstreamer --no-extra local_smart_turn --no-extra moondream --no-extra mlx-whisper
 
 sphinx:
   configuration: docs/api/conf.py

AGENTS.md

@@ -0,0 +1,174 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents 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 local
+
+# 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
+uv run 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.
+- **Deprecations**: Use the `.. deprecated:: <version>` Sphinx directive in docstrings (never inline tags like `[DEPRECATED]`), and pair it with a runtime `warnings.warn(..., DeprecationWarning)` at the call site. See `CONTRIBUTING.md` for full conventions.
+- **Linting**: Ruff (line length 100). Pre-commit hooks enforce formatting.
+- **Type hints**: Required for complex async code.
+- **Dataclass vs Pydantic**: Use `@dataclass` for frames and internal pipeline data (high-frequency, no validation needed). Use Pydantic `BaseModel` for configuration, parameters, metrics, and external API data (benefits from validation and serialization). Specifically:
+  - `@dataclass`: Frame types, context aggregator pairs, internal data containers
+  - `BaseModel`: Service `InputParams`, transport/VAD/turn params, metrics data, API request/response models, serializer params
+
+### 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)
+
+
+# Pydantic params class with a deprecated field
+class MyParams(BaseModel):
+    """Configuration parameters for MyService.
+
+    Parameters:
+        new_setting: Replacement for ``old_setting``.
+        old_setting: Legacy setting, no longer used.
+
+            .. deprecated:: 1.2.0
+                Use ``new_setting`` instead. Will be removed in 2.0.0.
+    """
+
+    new_setting: str = "default"
+    old_setting: str | None = None
+```
+
+## 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.

CHANGELOG.md.template

@@ -1,62 +0,0 @@
-# Changelog
-
-All notable changes to the **<project name>** SDK will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-Please make sure to add your changes to the appropriate categories:
-
-## [Unreleased]
-
-### Added
-
-<!-- for new functionality -->
-
-- n/a
-
-### Changed
-
-<!-- for changed functionality -->
-
-- n/a
-
-### Deprecated
-
-<!-- for soon-to-be removed functionality -->
-
-- n/a
-
-### Removed
-
-<!-- for removed functionality -->
-
-- n/a
-
-### Fixed
-
-<!-- for fixed bugs -->
-
-- n/a
-
-### Performance
-
-<!-- for performance-relevant changes -->
-
-- n/a
-
-### Security
-
-<!-- for security-relevant changes -->
-
-- n/a
-
-### Other
-
-<!-- for everything else -->
-
-- n/a
-
-## [0.1.0] - YYYY-MM-DD
-
-Initial release.

CLAUDE.md

@@ -1,155 +1 @@
-# 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.
-
+@AGENTS.md

COMMUNITY_INTEGRATIONS.md

@@ -23,9 +23,8 @@ Create your integration following the patterns and examples shown in the "Integr
 Your repository must contain these components:
 
 - **Source code** - Complete implementation following Pipecat patterns
-- **Foundational example** - Single file example showing basic usage (see [Pipecat examples](https://github.com/pipecat-ai/pipecat/tree/main/examples/foundational))
+- **Foundational example** - Single file example showing basic usage (see [Pipecat examples](https://github.com/pipecat-ai/pipecat/tree/main/examples))
 - **README.md** - Must include:
-
   - Introduction and explanation of your integration
   - Installation instructions
   - Usage instructions with Pipecat Pipeline
@@ -66,12 +65,25 @@ Once your PR is submitted, post in the `#community-integrations` Discord channel
 
 #### Websocket-based Services
 
+**Base class:** `WebsocketSTTService`
+
+**Use for:** Services where you manage the websocket connection directly. Combines `STTService` with `WebsocketService` for automatic reconnection and keepalive support.
+
+**Examples:**
+
+- [CartesiaSTTService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/cartesia/stt.py)
+- [ElevenLabsRealtimeSTTService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/elevenlabs/stt.py)
+
+#### SDK-based Streaming Services
+
 **Base class:** `STTService`
 
+**Use for:** Streaming services where the provider's Python SDK manages the connection internally.
+
 **Examples:**
 
 - [DeepgramSTTService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/deepgram/stt.py)
-- [SpeechmaticsSTTService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/speechmatics/stt.py)
+- [GoogleSTTService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/google/stt.py)
 
 #### File-based Services
 
@@ -109,56 +121,59 @@ Once your PR is submitted, post in the `#community-integrations` Discord channel
 
 #### Key requirements:
 
+- **`_process_context(self, context: LLMContext)`** — The main method that processes an LLM context and generates a response. Each LLM service overrides `process_frame` to extract context from `LLMContextFrame` and calls `_process_context`.
+
+- **`adapter_class`** — Class attribute pointing to a `BaseLLMAdapter` subclass. Defaults to `OpenAILLMAdapter`. Non-OpenAI services must implement their own adapter (see `src/pipecat/adapters/base_llm_adapter.py`) with methods:
+  - `get_llm_invocation_params(context)` — Extract provider-specific params from universal context
+  - `to_provider_tools_format(tools_schema)` — Convert standard tools to provider format
+  - `get_messages_for_logging(context)` — Format messages for logging
+  - Reference adapters: `src/pipecat/adapters/services/` (anthropic, gemini, bedrock, etc.)
+
 - **Frame sequence:** Output must follow this frame sequence pattern:
+  - `LLMFullResponseStartFrame` — Signals the start of an LLM response
+  - `LLMTextFrame` — Contains LLM content, typically streamed as tokens
+  - `LLMFullResponseEndFrame` — Signals the end of an LLM response
 
-  - `LLMFullResponseStartFrame` - Signals the start of an LLM response
-  - `LLMTextFrame` - Contains LLM content, typically streamed as tokens
-  - `LLMFullResponseEndFrame` - Signals the end of an LLM response
+- **Thought frames (reasoning models):** If the model supports extended thinking / chain-of-thought, emit thought frames alongside the response:
+  - `LLMThoughtStartFrame` — Signals the start of a thought
+  - `LLMThoughtTextFrame` — Contains thought content, streamed as tokens
+  - `LLMThoughtEndFrame` — Signals the end of a thought
 
-- **Context aggregation:** Implement context aggregation to collect user and assistant content:
-  - Aggregators come in pairs with a `user()` instance and `assistant()` instance
-  - Context must adhere to the `LLMContext` universal format
-  - Aggregators should handle adding messages, function calls, and images to the context
+- **Context aggregation** is handled by the framework via `LLMContext` + `LLMContextAggregatorPair`. The LLM service just processes context it receives — no need to implement aggregators.
 
 ### TTS (Text-to-Speech) Services
 
-#### AudioContextWordTTSService
+#### WebsocketTTSService
 
-**Use for:** Websocket-based services supporting word/timestamp alignment
+**Use for:** Websocket-based streaming services (with or without word timestamps)
 
-**Example:**
+**Examples:**
 
 - [CartesiaTTSService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/cartesia/tts.py)
+- [ElevenLabsTTSService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/elevenlabs/tts.py)
 
 #### InterruptibleTTSService
 
-**Use for:** Websocket-based services without word/timestamp alignment, requiring disconnection on interruption
+**Use for:** Websocket-based services without word timestamps that reconnect on interruption (e.g. don't support a context ID or interruption message)
 
 **Example:**
 
 - [SarvamTTSService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/sarvam/tts.py)
 
-#### WordTTSService
-
-**Use for:** HTTP-based services supporting word/timestamp alignment
-
-**Example:**
-
-- [ElevenLabsHttpTTSService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/elevenlabs/tts.py)
-
 #### TTSService
 
-**Use for:** HTTP-based services without word/timestamp alignment
+**Use for:** HTTP-based services (word timestamps are supported in the base class)
 
-**Example:**
+**Examples:**
 
 - [GoogleHttpTTSService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/google/tts.py)
+- [OpenAITTSService](https://github.com/pipecat-ai/pipecat/blob/main/src/pipecat/services/openai/tts.py)
 
 #### Key requirements:
 
-- For websocket services, use asyncio WebSocket implementation (required for v13+ support)
+- For websocket services, use asyncio WebSocket implementation
 - Handle idle service timeouts with keepalives
-- TTSServices push both audio (`TTSRawAudioFrame`) and text (`TTSTextFrame`) frames
+- TTS services push both audio (`TTSAudioRawFrame`) and text (`TTSTextFrame`) frames
 
 ### Telephony Serializers
 
@@ -202,14 +217,25 @@ Vision services process images and provide analysis such as descriptions, object
 
 #### Key requirements:
 
-- Must implement `run_vision` method that takes an `LLMContext` and returns an `AsyncGenerator[Frame, None]`
-- The method processes the latest image in the context and yields frames with analysis results
-- Typically yields `TextFrame` objects containing descriptions or answers
+- Must implement `run_vision` method that takes a `UserImageRawFrame` and returns an `AsyncGenerator[Frame, None]`
+- The method processes the image frame and yields frames with analysis results
+- Must yield the frame sequence: `VisionFullResponseStartFrame`, `VisionTextFrame`, `VisionFullResponseEndFrame`
 
 ## Implementation Guidelines
 
 ### Naming Conventions
 
+#### Package and Repository Naming
+
+Use the `pipecat-{vendor}` naming convention for your PyPI package and repository:
+
+- `pipecat-{vendor}` — for single-service integrations (e.g., `pipecat-deepdub`)
+- `pipecat-{vendor}-{type}` — when a vendor offers multiple service types (e.g., `pipecat-upliftai-stt`, `pipecat-upliftai-tts`)
+
+This convention makes community packages easily discoverable via PyPI search and clearly identifies them as part of the Pipecat ecosystem.
+
+#### Class Naming
+
 - **STT:** `VendorSTTService`
 - **LLM:** `VendorLLMService`
 - **TTS:**
@@ -233,24 +259,137 @@ def can_generate_metrics(self) -> bool:
     return True
 ```
 
-### Dynamic Settings Updates
+### Service Settings
 
-STT, LLM, and TTS services support `ServiceUpdateSettingsFrame` for dynamic configuration changes. The base STTService has an `_update_settings()` method that handles settings, and the private `_settings` `Dict` is used to store settings and provide access to the subclass.
+Every AI service (STT, LLM, TTS, image generation, etc.) exposes a **Settings dataclass** that serves two roles:
+
+1. **Store mode** — the service's `self._settings` holds the current value of every runtime-updatable field.
+2. **Delta mode** — an update frame (e.g. `TTSUpdateSettingsFrame`) specifies only the fields that should change; unspecified fields remain `NOT_GIVEN`.
+
+#### Defining your Settings class
+
+Extend `STTSettings`, `TTSSettings`, `LLMSettings`, or `ImageGenSettings` (or, if your service directly subclasses `AIService`, `ServiceSettings`). The base classes already provide common fields (e.g. `model`, `voice`, `language`). You only need to add **service-specific knobs that should be runtime-updatable**:
 
 ```python
-async def set_language(self, language: Language):
-    """Set the recognition language and reconnect.
+from dataclasses import dataclass, field
 
-    Args:
-        language: The language to use for speech recognition.
+from pipecat.services.settings import TTSSettings, NOT_GIVEN
+
+@dataclass
+class MyTTSSettings(TTSSettings):
+    """Settings for MyTTS service.
+
+    Parameters:
+        speaking_rate: Speed multiplier (0.5–2.0).
     """
-    logger.info(f"Switching STT language to: [{language}]")
-    self._settings["language"] = language
-    await self._disconnect()
-    await self._connect()
+
+    speaking_rate: float | None = field(default_factory=lambda: NOT_GIVEN)
 ```
 
-Note that, in this example, Deepgram requires the websocket connection be disconnected and reconnected to reinitialize the service with the new value. Consider if your service requires reconnection.
+**What goes in Settings vs. `__init__` params:**
+
+| Belongs in Settings                                      | Stays as `__init__` params                |
+| -------------------------------------------------------- | ----------------------------------------- |
+| Model name, voice, language                              | API keys, auth tokens                     |
+| Service-specific tuning knobs (rate, pitch, temperature) | Base URLs, endpoint overrides             |
+| Anything users may want to change mid-session            | Audio encoding, sample format             |
+|                                                          | Connection parameters (timeouts, retries) |
+
+The rule of thumb: if a caller might send an update frame to change it at runtime, it belongs in Settings. Everything else is init-only config stored as `self._xxx`.
+
+#### Wiring settings into `__init__`
+
+Accept an **optional** `settings` parameter. Build a `default_settings` object with all fields set to real values, then merge any caller overrides with `apply_update`.
+
+Add a `Settings` **class attribute** that points to your settings dataclass. This lets callers access the settings class through the service itself (e.g. `MyTTSService.Settings(...)`) without a separate import:
+
+```python
+from typing import Optional
+
+class MyTTSService(TTSService):
+    Settings = MyTTSSettings
+    _settings: Settings
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        settings: Optional[Settings] = None,
+        **kwargs,
+    ):
+        # 1. Defaults — every field has a real value (store mode).
+        default_settings = self.Settings(
+            model="my-model-v1",
+            voice="default-voice",
+            language="en",
+            speaking_rate=1.0,
+        )
+
+        # 2. Merge caller overrides (only given fields win).
+        if settings is not None:
+            default_settings.apply_update(settings)
+
+        # 3. Pass the fully-populated settings to the base class.
+        super().__init__(settings=default_settings, **kwargs)
+
+        # 4. Init-only config stored separately.
+        self._api_key = api_key
+```
+
+This pattern lets callers override only what they care about:
+
+```python
+# Uses all defaults
+svc = MyTTSService(api_key="sk-xxx")
+
+# Overrides just the voice — access Settings through the service class
+svc = MyTTSService(
+    api_key="sk-xxx",
+    settings=MyTTSService.Settings(voice="custom-voice"),
+)
+```
+
+#### Reacting to runtime changes
+
+AI services support runtime configuration changes via `*UpdateSettingsFrame`s (e.g. `STTUpdateSettingsFrame`, `TTSUpdateSettingsFrame`, `LLMUpdateSettingsFrame`).
+
+To react to runtime setting changes, override `_update_settings`. The base implementation applies the delta to `self._settings` and returns a `dict` mapping each changed field name to its **pre-update** value. Your override should call `super()` first, then act on the changed fields. A common implementation might look like:
+
+```python
+async def _update_settings(self, update: TTSSettings) -> dict[str, Any]:
+    """Apply a settings update, reconfiguring the connection if needed."""
+    changed = await super()._update_settings(update)
+
+    if not changed:
+        return changed
+
+    await self._disconnect()
+    await self._connect()
+
+    return changed
+```
+
+The dict keys work like a set for membership tests (`"language" in changed`) and truthiness (`if changed`). Use `changed.keys() - {"language"}` for set difference, or `changed["language"]` to inspect the previous value of a field.
+
+Note that, in this example, the service requires a reconnect to apply the new language. Consider, for each setting, whether your service requires reconnection or can apply changes in-place.
+
+If your service can't yet apply certain settings at runtime, call `self._warn_unhandled_updated_settings(changed)` with any unhandled field names so users get a clear log message:
+
+```python
+async def _update_settings(self, update: TTSSettings) -> dict[str, Any]:
+    changed = await super()._update_settings(update)
+
+    if not changed:
+        return changed
+
+    if "language" in changed:
+        await self._update_language()
+    else:
+        # TODO: this should be temporary - handle changes to other settings soon!
+        self._warn_unhandled_updated_settings(changed.keys() - {"language"})
+
+    return changed
+```
 
 ### Sample Rate Handling
 
@@ -260,7 +399,7 @@ Sample rates are set via PipelineParams and passed to each frame processor at in
 async def start(self, frame: StartFrame):
     """Start the service."""
     await super().start(frame)
-    self._settings["output_format"]["sample_rate"] = self.sample_rate
+    self._settings.output_sample_rate = self.sample_rate
     await self._connect()
 ```
 
@@ -270,7 +409,7 @@ Note that `self.sample_rate` is a `@property` set in the TTSService base class,
 
 Use Pipecat's tracing decorators:
 
-- **STT:** `@traced_stt` - decorate a function that handles `transcript`, `is_final`, `language` as args
+- **STT:** `@traced_stt` - decorate `_handle_transcription(self, transcript, is_final, language)` (the standard method name convention)
 - **LLM:** `@traced_llm` - decorate the `_process_context()` method
 - **TTS:** `@traced_tts` - decorate the `run_tts()` method
 
@@ -278,8 +417,9 @@ Use Pipecat's tracing decorators:
 
 ### Packaging and Distribution
 
+- Name your package `pipecat-{vendor}` (see [Naming Conventions](#naming-conventions))
 - Use [uv](https://docs.astral.sh/uv/) for packaging (encouraged)
-- Consider releasing to PyPI for easier installation
+- Publish to PyPI for easier installation
 - Follow semantic versioning principles
 - Maintain a changelog
 
@@ -292,17 +432,15 @@ For REST-based communication, use aiohttp. Pipecat includes this as a required d
 - Wrap API calls in appropriate try/catch blocks
 - Handle rate limits and network failures gracefully
 - Provide meaningful error messages
-- When errors occur, raise exceptions AND push `ErrorFrame`s to notify the pipeline:
+- When errors occur, raise exceptions AND push errors to notify the pipeline:
 
 ```python
-from pipecat.frames.frames import ErrorFrame
-
 try:
     # Your API call
     result = await self._make_api_call()
 except Exception as e:
-    # Push error frame to pipeline
-    await self.push_error(ErrorFrame(error=f"{self} error: {e}"))
+    # Push error upstream to notify the pipeline
+    await self.push_error(f"{self} error: {e}", exception=e)
     # Raise or handle as appropriate
     raise
 ```

CONTRIBUTING.md

@@ -49,12 +49,12 @@ Every pull request that makes a user-facing change should include a changelog en
    ```
 
 2. Choose the appropriate type:
-
    - `added.md` - New features
    - `changed.md` - Changes in existing functionality
    - `deprecated.md` - Soon-to-be removed features
    - `removed.md` - Removed features
    - `fixed.md` - Bug fixes
+   - `performance.md` - Performance improvements
    - `security.md` - Security fixes
    - `other.md` - Other changes (documentation, dependencies, etc.)
 
@@ -80,7 +80,6 @@ Every pull request that makes a user-facing change should include a changelog en
 
 ```markdown
 - Updated service configuration:
-
   - Changed default timeout to 30 seconds
   - Added retry logic for failed connections
 ```
@@ -105,7 +104,6 @@ changelog/1234.changed.2.md
 
 ```markdown
 - Updated service configuration:
-
   - Changed default timeout to 30 seconds
   - Added retry logic for failed connections
 ```

README.md

@@ -8,7 +8,7 @@
 
 **Pipecat** is an open-source Python framework for building real-time voice and multimodal conversational agents. Orchestrate audio and video, AI services, different transports, and conversation pipelines effortlessly—so you can focus on what makes your agent unique.
 
-> Want to dive right in? Try the [quickstart](https://docs.pipecat.ai/getting-started/quickstart).
+> Want to dive right in? Run `pipecat init quickstart` or follow the [quickstart guide](https://docs.pipecat.ai/getting-started/quickstart).
 
 ## 🚀 What You Can Build
 
@@ -28,6 +28,10 @@
 
 ## 🌐 Pipecat Ecosystem
 
+### 🧩 Multi-agent systems
+
+Need multiple AI agents working together? [Pipecat Subagents](https://github.com/pipecat-ai/pipecat-subagents) lets you build distributed multi-agent systems where each agent runs its own pipeline and communicates through a shared message bus. Hand off conversations between specialists, dispatch background tasks, and scale agents across processes or machines.
+
 ### 📱 Client SDKs
 
 Building client applications? You can connect to Pipecat from any platform using our official SDKs:
@@ -55,6 +59,20 @@ Looking for help debugging your pipeline and processors? Check out [Whisker](htt
 
 Love terminal applications? Check out [Tail](https://github.com/pipecat-ai/tail), a terminal dashboard for Pipecat.
 
+### 🤖 Claude Code Skills
+
+Use [Pipecat Skills](https://github.com/pipecat-ai/skills) with [Claude Code](https://claude.ai/code) to scaffold projects, deploy to Pipecat Cloud, and more. Install the marketplace with:
+
+```
+claude plugin marketplace add pipecat-ai/skills
+```
+
+and install any of the available plugins.
+
+### 🧩 Community Integrations
+
+Build and share your own Pipecat service integrations! Browse existing [community integrations](https://docs.pipecat.ai/api-reference/server/services/community-integrations) or check out our [guide](COMMUNITY_INTEGRATIONS.md) to create your own.
+
 ### 📺️ Pipecat TV Channel
 
 Catch new features, interviews, and how-tos on our [Pipecat TV](https://www.youtube.com/playlist?list=PLzU2zoMTQIHjqC3v4q2XVSR3hGSzwKFwH) channel.
@@ -65,27 +83,28 @@ Catch new features, interviews, and how-tos on our [Pipecat TV](https://www.yout
     <a href="https://github.com/pipecat-ai/pipecat-examples/tree/main/simple-chatbot"><img src="https://raw.githubusercontent.com/pipecat-ai/pipecat-examples/main/simple-chatbot/image.png" width="400" /></a>&nbsp;
     <a href="https://github.com/pipecat-ai/pipecat-examples/tree/main/storytelling-chatbot"><img src="https://raw.githubusercontent.com/pipecat-ai/pipecat-examples/main/storytelling-chatbot/image.png" width="400" /></a>
     <br/>
-    <a href="https://github.com/pipecat-ai/pipecat-examples/tree/main/translation-chatbot"><img src="https://raw.githubusercontent.com/pipecat-ai/pipecat-examples/main/translation-chatbot/image.png" width="400" /></a>&nbsp;
-    <a href="https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/12-describe-video.py"><img src="https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/assets/moondream.png" width="400" /></a>
+    <a href="https://github.com/pipecat-ai/pipecat-examples/tree/main/daily-multi-translation"><img src="https://raw.githubusercontent.com/pipecat-ai/pipecat-examples/main/daily-multi-translation/image.png" width="400" /></a>&nbsp;
+    <a href="https://github.com/pipecat-ai/pipecat/blob/main/examples/vision/vision-moondream.py"><img src="https://github.com/pipecat-ai/pipecat/blob/main/examples/assets/moondream.png" width="400" /></a>
 </p>
 
 ## 🧩 Available services
 
-| 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), [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), [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         | [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/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)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Category            | Services                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Speech-to-Text      | [AssemblyAI](https://docs.pipecat.ai/api-reference/server/services/stt/assemblyai), [AWS](https://docs.pipecat.ai/api-reference/server/services/stt/aws), [Azure](https://docs.pipecat.ai/api-reference/server/services/stt/azure), [Cartesia](https://docs.pipecat.ai/api-reference/server/services/stt/cartesia), [Deepgram](https://docs.pipecat.ai/api-reference/server/services/stt/deepgram), [ElevenLabs](https://docs.pipecat.ai/api-reference/server/services/stt/elevenlabs), [Fal Wizper](https://docs.pipecat.ai/api-reference/server/services/stt/fal), [Gladia](https://docs.pipecat.ai/api-reference/server/services/stt/gladia), [Google](https://docs.pipecat.ai/api-reference/server/services/stt/google), [Gradium](https://docs.pipecat.ai/api-reference/server/services/stt/gradium), [Groq (Whisper)](https://docs.pipecat.ai/api-reference/server/services/stt/groq), [Mistral](https://docs.pipecat.ai/api-reference/server/services/stt/mistral), [NVIDIA](https://docs.pipecat.ai/api-reference/server/services/stt/nvidia), [OpenAI (Whisper)](https://docs.pipecat.ai/api-reference/server/services/stt/openai), [Sarvam](https://docs.pipecat.ai/api-reference/server/services/stt/sarvam), [Soniox](https://docs.pipecat.ai/api-reference/server/services/stt/soniox), [Speechmatics](https://docs.pipecat.ai/api-reference/server/services/stt/speechmatics), [Whisper](https://docs.pipecat.ai/api-reference/server/services/stt/whisper), [xAI](https://docs.pipecat.ai/api-reference/server/services/stt/xai)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| LLMs                | [Anthropic](https://docs.pipecat.ai/api-reference/server/services/llm/anthropic), [AWS](https://docs.pipecat.ai/api-reference/server/services/llm/aws), [Azure](https://docs.pipecat.ai/api-reference/server/services/llm/azure), [Cerebras](https://docs.pipecat.ai/api-reference/server/services/llm/cerebras), [DeepSeek](https://docs.pipecat.ai/api-reference/server/services/llm/deepseek), [Fireworks AI](https://docs.pipecat.ai/api-reference/server/services/llm/fireworks), [Gemini](https://docs.pipecat.ai/api-reference/server/services/llm/gemini), [Grok](https://docs.pipecat.ai/api-reference/server/services/llm/grok), [Groq](https://docs.pipecat.ai/api-reference/server/services/llm/groq), [Mistral](https://docs.pipecat.ai/api-reference/server/services/llm/mistral), [Nebius](https://docs.pipecat.ai/api-reference/server/services/llm/nebius), [Novita](https://docs.pipecat.ai/api-reference/server/services/llm/novita), [NVIDIA NIM](https://docs.pipecat.ai/api-reference/server/services/llm/nvidia), [Ollama](https://docs.pipecat.ai/api-reference/server/services/llm/ollama), [OpenAI](https://docs.pipecat.ai/api-reference/server/services/llm/openai), [OpenAI Responses](https://docs.pipecat.ai/api-reference/server/services/llm/openai-responses), [OpenRouter](https://docs.pipecat.ai/api-reference/server/services/llm/openrouter), [Perplexity](https://docs.pipecat.ai/api-reference/server/services/llm/perplexity), [Qwen](https://docs.pipecat.ai/api-reference/server/services/llm/qwen), [SambaNova](https://docs.pipecat.ai/api-reference/server/services/llm/sambanova), [Sarvam](https://docs.pipecat.ai/api-reference/server/services/llm/sarvam), [Together AI](https://docs.pipecat.ai/api-reference/server/services/llm/together)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Text-to-Speech      | [Async](https://docs.pipecat.ai/api-reference/server/services/tts/asyncai), [AWS](https://docs.pipecat.ai/api-reference/server/services/tts/aws), [Azure](https://docs.pipecat.ai/api-reference/server/services/tts/azure), [Camb AI](https://docs.pipecat.ai/api-reference/server/services/tts/camb), [Cartesia](https://docs.pipecat.ai/api-reference/server/services/tts/cartesia), [Deepgram](https://docs.pipecat.ai/api-reference/server/services/tts/deepgram), [ElevenLabs](https://docs.pipecat.ai/api-reference/server/services/tts/elevenlabs), [Fish](https://docs.pipecat.ai/api-reference/server/services/tts/fish), [Google](https://docs.pipecat.ai/api-reference/server/services/tts/google), [Gradium](https://docs.pipecat.ai/api-reference/server/services/tts/gradium), [Groq](https://docs.pipecat.ai/api-reference/server/services/tts/groq), [Hume](https://docs.pipecat.ai/api-reference/server/services/tts/hume), [Inworld](https://docs.pipecat.ai/api-reference/server/services/tts/inworld), [Kokoro](https://docs.pipecat.ai/api-reference/server/services/tts/kokoro), [LMNT](https://docs.pipecat.ai/api-reference/server/services/tts/lmnt), [MiniMax](https://docs.pipecat.ai/api-reference/server/services/tts/minimax), [Mistral](https://docs.pipecat.ai/api-reference/server/services/tts/mistral), [Neuphonic](https://docs.pipecat.ai/api-reference/server/services/tts/neuphonic), [NVIDIA](https://docs.pipecat.ai/api-reference/server/services/tts/nvidia), [OpenAI](https://docs.pipecat.ai/api-reference/server/services/tts/openai), [Piper](https://docs.pipecat.ai/api-reference/server/services/tts/piper), [Resemble](https://docs.pipecat.ai/api-reference/server/services/tts/resemble), [Rime](https://docs.pipecat.ai/api-reference/server/services/tts/rime), [Sarvam](https://docs.pipecat.ai/api-reference/server/services/tts/sarvam), [Smallest](https://docs.pipecat.ai/api-reference/server/services/tts/smallest), [Soniox](https://docs.pipecat.ai/api-reference/server/services/tts/soniox), [Speechmatics](https://docs.pipecat.ai/api-reference/server/services/tts/speechmatics), [xAI](https://docs.pipecat.ai/api-reference/server/services/tts/xai), [XTTS](https://docs.pipecat.ai/api-reference/server/services/tts/xtts) |
+| Speech-to-Speech    | [AWS Nova Sonic](https://docs.pipecat.ai/api-reference/server/services/s2s/aws), [Gemini Multimodal Live](https://docs.pipecat.ai/api-reference/server/services/s2s/gemini), [Grok Voice Agent](https://docs.pipecat.ai/api-reference/server/services/s2s/grok), [OpenAI Realtime](https://docs.pipecat.ai/api-reference/server/services/s2s/openai), [Ultravox](https://docs.pipecat.ai/api-reference/server/services/s2s/ultravox),                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Transport           | [Daily (WebRTC)](https://docs.pipecat.ai/api-reference/server/services/transport/daily), [FastAPI Websocket](https://docs.pipecat.ai/api-reference/server/services/transport/fastapi-websocket), [LiveKit (WebRTC)](https://docs.pipecat.ai/api-reference/server/services/transport/livekit), [SmallWebRTCTransport](https://docs.pipecat.ai/api-reference/server/services/transport/small-webrtc), [WebSocket Server](https://docs.pipecat.ai/api-reference/server/services/transport/websocket-server), [WhatsApp](https://docs.pipecat.ai/api-reference/server/services/transport/whatsapp), Local                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Serializers         | [Exotel](https://docs.pipecat.ai/api-reference/server/services/serializers/exotel), [Genesys](https://docs.pipecat.ai/api-reference/server/services/serializers/genesys), [Plivo](https://docs.pipecat.ai/api-reference/server/services/serializers/plivo), [Twilio](https://docs.pipecat.ai/api-reference/server/services/serializers/twilio), [Telnyx](https://docs.pipecat.ai/api-reference/server/services/serializers/telnyx), [Vonage](https://docs.pipecat.ai/api-reference/server/services/serializers/vonage)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Video               | [HeyGen](https://docs.pipecat.ai/api-reference/server/services/video/heygen), [LemonSlice](https://docs.pipecat.ai/api-reference/server/services/transport/lemonslice), [Tavus](https://docs.pipecat.ai/api-reference/server/services/video/tavus), [Simli](https://docs.pipecat.ai/api-reference/server/services/video/simli)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Memory              | [mem0](https://docs.pipecat.ai/api-reference/server/services/memory/mem0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Vision & Image      | [fal](https://docs.pipecat.ai/api-reference/server/services/image-generation/fal), [Google Imagen](https://docs.pipecat.ai/api-reference/server/services/image-generation/google-imagen), [Moondream](https://docs.pipecat.ai/api-reference/server/services/vision/moondream)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Audio Processing    | [Silero VAD](https://docs.pipecat.ai/api-reference/server/utilities/audio/silero-vad-analyzer), [Krisp Viva](https://docs.pipecat.ai/guides/features/krisp-viva), [Koala](https://docs.pipecat.ai/api-reference/server/utilities/audio/koala-filter), [ai-coustics](https://docs.pipecat.ai/api-reference/server/utilities/audio/aic-filter), [RNNoise](https://docs.pipecat.ai/api-reference/server/utilities/audio/rnnoise-filter)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Analytics & Metrics | [OpenTelemetry](https://docs.pipecat.ai/api-reference/server/utilities/opentelemetry), [Sentry](https://docs.pipecat.ai/api-reference/server/services/analytics/sentry)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Community           | [Browse community integrations →](https://docs.pipecat.ai/api-reference/server/services/community-integrations)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
-📚 [View full services documentation →](https://docs.pipecat.ai/server/services/supported-services)
+📚 [View full services documentation →](https://docs.pipecat.ai/api-reference/server/services/supported-services)
 
 ## ⚡ Getting started
 
@@ -127,15 +146,15 @@ You can get started with Pipecat running on your local machine, then move your a
 
 ## 🧪 Code examples
 
-- [Foundational](https://github.com/pipecat-ai/pipecat/tree/main/examples/foundational) — small snippets that build on each other, introducing one or two concepts at a time
+- [Foundational](https://github.com/pipecat-ai/pipecat/tree/main/examples) — small snippets that build on each other, introducing one or two concepts at a time
 - [Example apps](https://github.com/pipecat-ai/pipecat-examples) — complete applications that you can use as starting points for development
 
 ## 🛠️ Contributing to the framework
 
 ### Prerequisites
 
-**Minimum Python Version:** 3.10
-**Recommended Python Version:** 3.12
+**Minimum Python Version:** 3.11
+**Recommended Python Version:** >= 3.12
 
 ### Setup Steps
 
@@ -151,7 +170,6 @@ You can get started with Pipecat running on your local machine, then move your a
    ```bash
    uv sync --group dev --all-extras \
      --no-extra gstreamer \
-     --no-extra krisp \
      --no-extra local \
    ```
 
@@ -163,6 +181,15 @@ You can get started with Pipecat running on your local machine, then move your a
 
 > **Note**: Some extras (local, gstreamer) require system dependencies. See documentation if you encounter build errors.
 
+### Claude Code Skills
+
+Install development workflow skills for contributing to Pipecat with [Claude Code](https://claude.ai/code):
+
+```
+claude plugin marketplace add pipecat-ai/pipecat
+claude plugin install pipecat-dev@pipecat-dev-skills
+```
+
 ### Running tests
 
 To run all tests, from the root directory:

changelog/3759.performance.md

@@ -1 +0,0 @@
-- Switched `GradiumTTSService` from `InterruptibleWordTTSService` to `AudioContextWordTTSService`, eliminating websocket disconnect/reconnect on every interruption by using `client_req_id`-based multiplexing.

changelog/4385.added.md

@@ -0,0 +1 @@
+- Added a `session_id` field to `RunnerArguments` so bots can log or trace a per-session identifier in local development the same way they can in Pipecat Cloud. The development runner now mints a UUID at every construction site, and paths that already returned a `sessionId` to the caller (Daily `/start`, dial-in webhook) share that same UUID with the runner args instead of generating two. The SmallWebRTC `/api/offer` endpoint also accepts an optional `session_id` query parameter so the `/sessions/{session_id}/...` proxy can thread it through.

changelog/4386.changed.md

@@ -0,0 +1 @@
+- Updated the default `SonioxTTSService` model from `tts-rt-v1-preview` to the generally available `tts-rt-v1`.

changelog/4390.added.md

@@ -0,0 +1 @@
+- Added a `max_buffer_delay_ms` constructor argument to `CartesiaTTSService` for controlling Cartesia's server-side text buffering. When unset, Pipecat picks a sensible default based on `text_aggregation_mode`: `0` in `SENTENCE` mode (custom buffering — avoids stacking client-side aggregation on top of Cartesia's default 3000ms server buffer) and unset in `TOKEN` mode (Cartesia's managed buffering applies). Pass an explicit value (0–5000ms) to override.

changelog/4390.changed.2.md

@@ -0,0 +1 @@
+- Default `cartesia_version` for `CartesiaTTSService` bumped from `2025-04-16` to `2026-03-01`, matching `CartesiaHttpTTSService` and unlocking the `use_normalized_timestamps` and `max_buffer_delay_ms` fields.

changelog/4390.changed.md

@@ -0,0 +1 @@
+- ⚠️ `CartesiaTTSService` now sends `use_normalized_timestamps: true` instead of the deprecated `use_original_timestamps` field. Word timestamps now reflect what was actually spoken (post text-normalization and pronunciation-dictionary substitution), matching the convention Pipecat uses for ElevenLabs. This is a behavior change for `sonic-3` users, who were previously receiving timestamps tied to the input transcript.

changelog/4390.fixed.2.md

@@ -0,0 +1 @@
+- Fixed `CartesiaHttpTTSService` pushing two `ErrorFrame`s on a non-200 response — one with the API's error text and a second, less informative "Unknown error" frame from the outer exception handler. It now pushes a single frame that includes the HTTP status code and returns cleanly.

changelog/4390.fixed.3.md

@@ -0,0 +1 @@
+- Fixed Cartesia tag helpers (`SPELL`, `EMOTION_TAG`, `PAUSE_TAG`, `VOLUME_TAG`, `SPEED_TAG`) raising `TypeError` when called on an instance (e.g. `tts.SPELL("hi")`). They're now `@staticmethod` and callable from both the class and an instance.

changelog/4390.fixed.md

@@ -0,0 +1 @@
+- Fixed `CartesiaTTSService` surfacing `flush_done` messages from Cartesia as `ErrorFrame`s. The latest API emits a `flush_done` per transcript when server-side buffering is disabled; Pipecat now consumes them silently since each turn already has its own `context_id`.

changelog/4393.fixed.md

@@ -0,0 +1 @@
+- Fixed an issue where `LocalSmartTurnAnalyzerV3` was imported unconditionally for user turn stop strategies. It is now only imported when `default_user_turn_stop_strategies()` is called. This improves startup time and removes the `transformers` "PyTorch/TensorFlow/Flax not found" warning when the default stop strategies are not used.

changelog/4395.changed.md

@@ -0,0 +1 @@
+- Broadened `tool_resources` to `app_resources` for easy access not just in tool handlers but in other places like custom `FrameProcessor`s. Three changes: a rename (`tool_resources` → `app_resources`), a new `app_resources` property on `PipelineTask`, and a new `pipeline_task` property on `FrameProcessor`. Tool handlers now read `params.app_resources`; custom processors read `self.pipeline_task.app_resources`. The previous `tool_resources` aliases (on `PipelineTask`, `FunctionCallParams`, and `FrameProcessorSetup`) keep working but are deprecated as of 1.2.0 and emit `DeprecationWarning`s.

changelog/4397.changed.md

@@ -0,0 +1 @@
+- Lowered the per-message log in `SmallWebRTCInputTransport._handle_app_message` from `debug` to `trace`. App messages can be high-frequency and were noisy at debug level; set the loguru level to `TRACE` to see them again.

changelog/4400.added.md

@@ -0,0 +1 @@
+- Added a `mip_opt_out` constructor argument to `DeepgramTTSService` and `DeepgramHttpTTSService` so callers can opt out of the Deepgram Model Improvement Program. When set, the value is forwarded to Deepgram as a query parameter on the speak request. Defaults to `None`, which preserves the existing behavior. See https://dpgr.am/deepgram-mip for pricing implications before enabling.

changelog/4401.changed.md

@@ -0,0 +1 @@
+- Changed the default model for `GrokRealtimeLLMService` to `grok-voice-think-fast-1.0`, xAI's recommended Voice Agent model. The previous default of `grok-voice-fast-1.0` has been deprecated by xAI and is being removed.

changelog/4401.fixed.md

@@ -0,0 +1 @@
+- Fixed `GrokRealtimeLLMService` ignoring the configured model. The model was stored in `Settings` but never sent to xAI, so every session silently fell back to xAI's server-side default. The model is now passed via the `?model=` query parameter on the WebSocket URL as xAI's Voice Agent API requires.

changelog/4404.added.md

@@ -0,0 +1 @@
+- Added an opt-in `add_tool_change_messages` flag to the LLM aggregators (set via `LLMContextAggregatorPair(..., add_tool_change_messages=True)`) that appends a developer-role message to the context whenever `LLMSetToolsFrame` changes the set of advertised standard tools. Helps the LLM stay coherent across mid-conversation tool changes, mitigating several flavors of tool-call-related hallucination: calling tools that have been removed, avoiding tools that have been re-added, and hallucinating output (made-up answers or tool-call-shaped non-tool-calls) when tools are unavailable.

changelog/4405.added.2.md

@@ -0,0 +1 @@
+- Added `LLMTurnCompletionUserTurnStopStrategy` in `pipecat.turns.user_stop`. When installed, the strategy gates `on_user_turn_stopped` on a `UserTurnInferenceCompletedFrame` (a new fieldless system frame emitted by any component that can judge turn completeness — e.g. the `UserTurnCompletionLLMServiceMixin` on `✓`). A `finalization_timeout` provides a safety net if no completion frame ever arrives.

changelog/4405.added.3.md

@@ -0,0 +1 @@
+- Added `deferred(strategy)` and `DeferredUserTurnStopStrategy` in `pipecat.turns.user_stop`. Wraps a stop strategy so it fires only the inference-triggered event and suppresses `on_user_turn_stopped`, leaving finalization to another strategy in the chain such as `LLMTurnCompletionUserTurnStopStrategy`.

changelog/4405.added.4.md

@@ -0,0 +1 @@
+- Added `FilterIncompleteUserTurnStrategies` in `pipecat.turns.user_turn_strategies` — a `UserTurnStrategies` specialization that wraps the detector chain with `deferred(...)` and appends `LLMTurnCompletionUserTurnStopStrategy` as the finalizer. Common case: `user_turn_strategies=FilterIncompleteUserTurnStrategies()`. Pass `config=UserTurnCompletionConfig(...)` to customize timeouts and prompts.

changelog/4405.added.5.md

@@ -0,0 +1 @@
+- Added `ExternalUserTurnCompletionStopStrategy` in `pipecat.turns.user_stop` — a generic stop strategy that finalizes the user turn whenever a `UserTurnInferenceCompletedFrame` arrives, regardless of which component produced it. `LLMTurnCompletionUserTurnStopStrategy` now extends this base; future producers (Flux, custom end-of-turn classifiers, etc.) can use the base directly or subclass it to add producer-specific setup.

changelog/4405.added.md

@@ -0,0 +1 @@
+- Added `on_user_turn_inference_triggered`, a new event on the user turn controller, processor, aggregator and stop strategies that fires when a strategy has enough signal to start LLM inference. By default it fires together with `on_user_turn_stopped`; a gating strategy can fire only the inference-triggered event and defer finalization to a peer.

changelog/4405.deprecated.md

@@ -0,0 +1 @@
+- Deprecated `LLMUserAggregatorParams.filter_incomplete_user_turns`. Use `user_turn_strategies=FilterIncompleteUserTurnStrategies()` (or add `LLMTurnCompletionUserTurnStopStrategy` to a custom `user_turn_strategies.stop`) instead. Setting the legacy flag still works for one release: the aggregator emits a `DeprecationWarning` and rewires the strategies as if you had passed `FilterIncompleteUserTurnStrategies` directly.

changelog/4405.fixed.md

@@ -0,0 +1 @@
+- Fixed `on_user_turn_stopped` firing prematurely when `filter_incomplete_user_turns` was enabled. The event now fires only after the LLM confirms the user turn is complete (`✓`); previously the smart-turn detector's tentative stop was bubbling up before the LLM had a chance to veto it, causing observers, transcript appenders and UI indicators to receive an early — and sometimes duplicated — signal.

changelog/4407.added.md

@@ -0,0 +1,6 @@
+- Added first-class RTVI support for the UI Agent Protocol:
+  - Adds `ui-event`, `ui-snapshot`, and `ui-cancel-task` client-to-server messages, plus `ui-command` and `ui-task` server-to-client messages, with paired `*Data` / `*Message` pydantic models.
+  - Adds built-in command payload models for `Toast`, `Navigate`, `ScrollTo`, `Highlight`, `Focus`, `Click`, `SetInputValue`, and `SelectText`; matching default handlers live in `@pipecat-ai/client-react`.
+  - Adds `RTVIProcessor.on_ui_message` for inbound `ui-event`, `ui-snapshot`, and `ui-cancel-task` messages.
+  - Adds five UI pipeline frames, mirroring the `client-message` frame-and-event pattern: downstream code pushes `RTVIUICommandFrame` / `RTVIUITaskFrame` for the observer to wrap into outbound `UICommandMessage` / `UITaskMessage` envelopes, while the processor pushes inbound `RTVIUIEventFrame`, `RTVIUISnapshotFrame`, and `RTVIUICancelTaskFrame` alongside `on_ui_message`.
+  - Bumps the RTVI `PROTOCOL_VERSION` from `1.2.0` to `1.3.0`.

changelog/4414.fixed.md

@@ -0,0 +1 @@
+- Fixed `TTSSpeakFrame(append_to_context=True)` greetings sometimes splitting across two assistant messages in the LLM context and not surfacing in `on_assistant_turn_stopped`. The `LLMAssistantPushAggregationFrame` emitted at the end of a TTS context now carries a PTS just past the last word so it can't overtake clock-queued `TTSTextFrame`s in the transport's output, and `LLMAssistantAggregator` now triggers `on_assistant_turn_started`/`on_assistant_turn_stopped` when it receives the frame outside an LLM response cycle (restoring v0.0.104 behavior for greeting transcripts).

changelog/4415.fixed.md

@@ -0,0 +1 @@
+- Fixed `ElevenLabsTTSService` and `ElevenLabsHttpTTSService` producing merged words (e.g. `bookLook`) when using Flash models. Flash often splits sentences mid-stream into alignment chunks that begin with a real inter-word space, but the previous fix unconditionally stripped that space from every chunk. Leading spaces are now stripped only on the first alignment chunk of an utterance, so subsequent chunks correctly flush partial words across boundaries.

changelog/4416.added.md

@@ -0,0 +1 @@
+- AWS Transcribe STT, Polly TTS, Bedrock LLM, and the Bedrock AgentCore processor now resolve credentials via the standard boto3 provider chain (EC2 instance profiles, EKS pod roles / IRSA, ECS task roles, SSO, `~/.aws/credentials`) when explicit credentials and `AWS_*` environment variables are absent. Services running with IAM roles no longer need to export static credentials.

changelog/4416.fixed.md

@@ -0,0 +1 @@
+- Fixed AWS Polly TTS, Bedrock LLM, and the Bedrock AgentCore processor erroring out when only one of `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` was set in the environment. The half-populated kwargs are no longer forwarded to aioboto3; partial env-var configurations now fall through to the boto3 credential chain like fully-unset configurations do.

changelog/4417.security.md

@@ -0,0 +1 @@
+- Fixed a path traversal issue in the development runner's `/files/{filename:path}` download endpoint. Previously, when the runner was started with `--folder`, a request like `/files/..%2F..%2Fetc%2Fpasswd` could escape the configured folder because `%2F`-encoded separators bypassed Starlette's path normalisation. The endpoint now resolves the joined path and rejects any filename that escapes the allowed base with a 403, and also returns 404 (instead of an implicit `null` 200) when `--folder` is unset.

changelog/4422.changed.md

@@ -0,0 +1 @@
+- Changed the default Inworld TTS model from `inworld-tts-1.5-max` to `inworld-tts-2` (Realtime TTS-2) across `InworldHttpTTSService`, `InworldTTSService`, and the `InworldRealtimeLLMService` cascade. Existing users can pin the prior model explicitly via the `model`/`tts_model` argument; both `inworld-tts-1.5-max` and `inworld-tts-1.5-mini` remain valid model IDs.

changelog/4424.fixed.md

@@ -0,0 +1 @@
+- Fixed `ElevenLabsTTSService` and `ElevenLabsHttpTTSService` writing romanized/normalized text to the LLM context. With non-Latin input (e.g., Chinese), the assistant transcript was getting populated with pinyin (`Ni Hao !` instead of `你好！`), which then degraded subsequent LLM turns. The services now consume `alignment` by default and only switch to `normalizedAlignment` / `normalized_alignment` when `pronunciation_dictionary_locators` is configured (where `alignment` has overlapping restarts that produce duplicated/garbled words, per #4316). Both fields are read with preferred-with-fallback semantics since each is nullable per the API schema.

changelog/4426.added.md

@@ -0,0 +1 @@
+- Added `keyterms` support to ElevenLabs STT services so Scribe V2 callers can bias transcription for both file-based and realtime transcription.

changelog/4428.deprecated.md

@@ -0,0 +1 @@
+- Deprecated `ResampyResampler` in favor of `SOXRAudioResampler` (or the `create_file_resampler()` / `create_stream_resampler()` factories). Instantiating `ResampyResampler` now emits a `DeprecationWarning`. The class will be removed in Pipecat 2.0 along with the default `resampy` and `numba` dependencies.

changelog/4429.changed.md

@@ -0,0 +1 @@
+- Changed the default model for `GrokLLMService` from `grok-3` to `grok-4.20-non-reasoning`. xAI is retiring `grok-3` on May 15, 2026.

changelog/4430.added.md

@@ -0,0 +1 @@
+- Added `watchdog_min_timeout` parameter to `DeepgramFluxSTT` and `DeepgramFluxSageMakerSTT` (default `0.5` seconds) to control the minimum silence duration before the watchdog sends a silence packet to prevent dangling turns. The actual threshold is `max(chunk_duration * 2, watchdog_min_timeout)`, so it also adapts automatically to the audio chunk size in use.

changelog/4430.changed.md

@@ -0,0 +1 @@
+- `DeepgramFluxSTT` watchdog silence threshold is now dynamic: `max(chunk_duration * 2, watchdog_min_timeout)` instead of a fixed 500 ms. This prevents false silence injections when large audio chunks are sent at lower frequency.

changelog/4431.fixed.md

@@ -0,0 +1 @@
+- Fixed a deadlock in `TTSService` that could permanently stall pipeline processing when all three conditions occurred together: `pause_frame_processing=True`, an interruption arrived before any TTS audio was played, and an `UninterruptibleFrame` (e.g. `TTSUpdateSettingsFrame`, `FunctionCallResultFrame`) was in the processing queue at that moment. The process task would block on `__process_event.wait()` indefinitely because `BotStoppedSpeakingFrame` never arrives (no audio was played) and the interruption handler did not resume processing. Affects services using `pause_frame_processing=True` such as ElevenLabs, Rime, AsyncAI, Gradium, and ResembleAI.

changelog/4433.changed.md

@@ -0,0 +1 @@
+- `ElevenLabsTTSService` now sends `close_context` to the server as soon as the turn is complete (on `on_turn_context_completed`) rather than waiting until all audio has finished playing back. The `isFinal` message from ElevenLabs is now used to signal `TTSStoppedFrame` and clean up the audio context, improving turn transition timing.

changelog/4434.fixed.md

@@ -0,0 +1 @@
+- Fixed interruptions being delayed when a slow non-uninterruptible frame was processing and an uninterruptible frame was waiting in the queue. The bot would stall until the slow frame finished instead of cancelling it immediately on interruption.

changelog/4435.fixed.md

@@ -0,0 +1 @@
+- Fixed `TTSService` dropping uninterruptible frames (e.g. `FunctionCallResultFrame`) from its internal serialization queue when an interruption occurs. Previously, the queue was recreated on every interruption, silently discarding any queued frames. The queue is now reset instead of recreated, preserving uninterruptible frames so they are always delivered downstream.

changelog/4440.fixed.md

@@ -0,0 +1 @@
+- Fixed a race condition in the Daily transport that caused `AttributeError: 'NoneType' object has no attribute 'send_app_message'` when tearing down a pipeline. Both `DailyInputTransport` and `DailyOutputTransport` share the same `DailyTransportClient` and both call `cleanup()`, which was releasing the underlying `CallClient` on the first call — leaving the second caller with a `None` client.

changelog/4441.fixed.md

@@ -0,0 +1 @@
+- Restored `cancel_on_interruption=False` support for `AWSNovaSonicLLMService` and `OpenAIRealtimeLLMService`. These services previously honored the flag by simply not cancelling in-flight function calls on interruption; the introduction of the new async-tool mechanism (which threads started/intermediate/final messages through the LLM context) broke that path because the realtime services didn't know how to interpret those messages. Note that new-style streamed intermediate results (`FunctionCallResultProperties(is_final=False)`) are not supported on these realtime services. Similar fixes for other impacted realtime services are forthcoming.

changelog/4443.fixed.md

@@ -0,0 +1 @@
+- Fixed two misspelled Gemini TTS voice names in `GeminiTTSService.AVAILABLE_VOICES`.

changelog/4446.change.md

@@ -0,0 +1 @@
+- Updated `InworldHttpTTSService` and `InworldTTSService` to use PCM audio encoding by default, which returns audio bytes without headers.

changelog/4447.fixed.md

@@ -0,0 +1 @@
+- Extended the `cancel_on_interruption=False` regression fix to `GrokRealtimeLLMService`, `AzureRealtimeLLMService`, and `UltravoxRealtimeLLMService`. Grok and Azure use the same approach as in #4441 (each service detects async-tool messages in the LLM context and routes the final result to its formal tool-result channel; Azure inherits transitively from `OpenAIRealtimeLLMService`). Ultravox needed a different approach because its API freezes the conversation between `client_tool_invocation` and the matching `client_tool_result` — for async-registered functions it now ships a placeholder `client_tool_result` immediately when the function is invoked (to unfreeze the conversation), then injects the real result as user-side text once the tool finishes. Streamed intermediate results (`FunctionCallResultProperties(is_final=False)`) are still not supported on any of these realtime services. `GeminiLiveLLMService` and `InworldRealtimeLLMService` are excluded for now: Gemini Live's async-tool path needs deeper investigation, and Inworld appears to have a pre-existing problem with even simple tool calling on its Realtime API.

changelog/4448.added.md

@@ -0,0 +1 @@
+- Added `cancel_on_interruption=False` support for `GeminiLiveLLMService` on models that support Gemini's NON_BLOCKING tool mechanism (currently Gemini 2.x); the conversation now continues while the tool runs. On models that don't yet support NON_BLOCKING (Gemini 3.x), the service surfaces a one-time warning explaining the limitation. (Note: an intermittent 1008 error can occasionally fire on Gemini 2.5 during long-running tool calls; we auto-reconnect.)

changelog/4449.changed.md

@@ -0,0 +1 @@
+- Moved `create_task`, `cancel_task`, the `task_manager` property, and `setup(task_manager)` up from `FrameProcessor` to `BaseObject`. Custom `BaseObject` subclasses (turn strategies, controllers, etc.) now inherit these methods directly instead of reimplementing the task manager wiring. Owners propagate the task manager to their child `BaseObject`s via `await child.setup(task_manager)`.

changelog/4450.changed.md

@@ -0,0 +1 @@
+- Changed the default OpenAI Realtime input audio transcription model from `gpt-4o-transcribe` to `gpt-realtime-whisper` for both `OpenAIRealtimeSTTService` and `OpenAIRealtimeLLMService`. The new model does not accept the `prompt` parameter; if a prompt is supplied alongside `gpt-realtime-whisper`, it is dropped automatically and a warning is logged. To keep using prompt hints, explicitly pin `model="gpt-4o-transcribe"` (or `"gpt-4o-mini-transcribe"`).

changelog/4462.changed.md

@@ -0,0 +1 @@
+- Updated the default model for `CartesiaTTSService` and `CartesiaHttpTTSService` from `sonic-3` to `sonic-3.5`.

changelog/4464.added.2.md

@@ -0,0 +1 @@
+- Added NVIDIA Magpie TTS services via AWS SageMaker: `NvidiaSageMakerHTTPTTSService` (single HTTP invocation, streams raw PCM back) and `NvidiaSageMakerWebsocketTTSService` (persistent HTTP/2 bidi-stream with full interruption support via `InterruptibleTTSService`).

changelog/4464.added.md

@@ -0,0 +1 @@
+- Added `NvidiaSageMakerWebsocketSTTService` for streaming speech recognition using NVIDIA Nemotron ASR via an AWS SageMaker bidirectional-stream endpoint. Produces `InterimTranscriptionFrame` and `TranscriptionFrame` frames, is VAD-aware, and automatically reconnects on error.

changelog/4465.fixed.md

@@ -0,0 +1 @@
+- Fixed `OpenAIRealtimeLLMService` handling of multi-output-item responses (observed with `gpt-realtime-2`). A single response can now contain more than one audio item, and the first item's `audio.done` may arrive after the second item's deltas have started. Deltas still arrive strictly in playback order, so we continue to forward them as received (matching OpenAI's reference implementation). The fix removes spurious warnings, ensures truncation always targets the latest audio item, and emits a single bracketing `TTSStartedFrame`/`TTSStoppedFrame` pair per assistant turn (the Stopped is now pushed on `response.done`).

changelog/4470.added.md

@@ -0,0 +1 @@
+- Added support for `reasoning` configuration on `OpenAIRealtimeLLMService`, for use with reasoning-capable Realtime models such as `gpt-realtime-2`.

changelog/4472.changed.md

@@ -0,0 +1 @@
+- Changed the default model for `OpenAIRealtimeLLMService` from `gpt-realtime-1.5` to `gpt-realtime-2`.

changelog/4480.added.md

@@ -0,0 +1 @@
+- Added `wait_for_transcript_to_end_user_turn` on `LLMUserAggregatorParams` for pipelines where local turn detection drives a realtime service like Gemini Live. Set it to False to avoid unnecessary latency from transcript delay — the realtime service consumes user audio directly, so we don't need user transcripts in context before it can respond. The option makes it so that (1) turn strategies do not consider user transcripts, letting the user turn end sooner, and (2) user transcripts are then handled by the aggregator: a simple timer gives it time to gather those transcripts after the user turn ends, and once gathered, the aggregator emits a new `on_user_turn_message_finalized` event with the new user context message. The new event also fires in the default mode (coinciding with `on_user_turn_stopped`), so consumers that want the populated user transcript can subscribe to it uniformly. See `examples/realtime/realtime-gemini-live-local-vad.py` for the full pattern.

changelog/_template.md.j2

@@ -5,7 +5,7 @@
 
 {% for text, values in sections[section][category].items() %}
 {{ text }}
-(PR {{ values|join(', ') }})
+  (PR {{ values|join(', ') }})
 
 {% endfor %}
 {% endfor %}

docs/api/README.md

@@ -1,109 +1,60 @@
-# Pipecat Documentation
+# Pipecat API Documentation
 
-This directory contains the source files for auto-generating Pipecat's server API reference documentation.
-
-## Setup
-
-1. Install documentation dependencies:
-
-```bash
-pip install -r requirements.txt
-```
-
-2. Make the build scripts executable:
-
-```bash
-chmod +x build-docs.sh rtd-test.py
-```
+This directory contains the source files for auto-generating Pipecat's API reference documentation.
 
 ## Building Documentation
 
-From this directory, you can build the documentation in several ways:
-
-### Local Build
+From this directory:
 
 ```bash
-# Using the build script (automatically opens docs when done)
-./build-docs.sh
+# Build docs (warnings shown but don't fail the build)
+cd docs/api && uv run ./build-docs.sh
 
-# Or directly with sphinx-build
-sphinx-build -b html . _build/html -W --keep-going
+# Build with strict mode (warnings treated as errors)
+cd docs/api && uv run ./build-docs.sh --strict
 ```
 
-### ReadTheDocs Test Build
+The build script will:
 
-To test the documentation build process exactly as it would run on ReadTheDocs:
-
-```bash
-./rtd-test.py
-```
-
-This script:
-
-- Creates a fresh virtual environment
-- Installs all dependencies as specified in requirements files
-- Handles conflicting dependencies (like grpcio versions for Riva and PlayHT)
-- Builds the documentation in an isolated environment
-- Provides detailed logging of the build process
-
-Use this script to verify your documentation will build correctly on ReadTheDocs before pushing changes.
-
-## Viewing Documentation
-
-The built documentation will be available at `_build/html/index.html`. To open:
-
-```bash
-# On MacOS
-open _build/html/index.html
-
-# On Linux
-xdg-open _build/html/index.html
-
-# On Windows
-start _build/html/index.html
-```
+1. Install documentation dependencies via `uv sync --group docs`
+2. Clean previous build output
+3. Run `sphinx-build` to generate HTML documentation
+4. Open the result in your browser (macOS)
 
 ## Directory Structure
 
 ```
 .
-├── api/            # Auto-generated API documentation
-├── _build/         # Built documentation
-├── _static/        # Static files (images, css, etc.)
-├── conf.py         # Sphinx configuration
+├── api/            # Auto-generated API documentation (created during build)
+├── _build/         # Built documentation output
+├── conf.py         # Sphinx configuration (mock imports, extensions, etc.)
 ├── index.rst       # Main documentation entry point
-├── requirements-base.txt    # Base documentation dependencies
-├── requirements-riva.txt    # Riva-specific dependencies
-├── requirements-playht.txt  # PlayHT-specific dependencies
 ├── build-docs.sh   # Local build script
-└── rtd-test.py     # ReadTheDocs test build script
+└── rtd-test.sh     # ReadTheDocs test build script (uses pip, not uv)
 ```
 
-## Notes
+## How It Works
 
-- Documentation is auto-generated from Python docstrings
-- Service modules are automatically detected and included
-- The build process matches our ReadTheDocs configuration
-- Warnings are treated as errors (-W flag) to maintain consistency
-- The --keep-going flag ensures all errors are reported
-- Dependencies are split into multiple requirements files to handle version conflicts
+- `conf.py` runs `sphinx-apidoc` during Sphinx's `setup()` phase to generate `.rst` files from Python source
+- Sphinx autodoc imports each module to extract docstrings
+- Modules with unavailable dependencies are listed in `autodoc_mock_imports` in `conf.py`
+- Napoleon extension converts Google-style docstrings to reStructuredText
 
 ## Troubleshooting
 
-If you encounter missing service modules:
+**Module not appearing in docs:**
 
-1. Verify the service is installed with its extras: `pip install pipecat-ai[service-name]`
-2. Check the build logs for import errors
-3. Ensure the service module is properly initialized in the package
-4. Run `./rtd-test.py` to test in an isolated environment matching ReadTheDocs
+1. Check the build output for `autodoc: failed to import` warnings
+2. If the module has an unresolvable import dependency, add it to `autodoc_mock_imports` in `conf.py`
+3. Verify the module is importable: `uv run python -c "import pipecat.module.name"`
 
-For dependency conflicts:
+**Duplicate object warnings:**
 
-1. Check the requirements files for version specifications
-2. Use `rtd-test.py` to verify dependency resolution
-3. Consider adding service-specific requirements files if needed
+These come from re-export modules or Sphinx discovering the same class through multiple import paths. Usually cosmetic.
 
-For more information:
+**Docstring formatting warnings:**
 
-- [ReadTheDocs Configuration](.readthedocs.yaml)
-- [Sphinx Documentation](https://www.sphinx-doc.org/)
+Docstrings use reStructuredText, not Markdown. Common issues:
+- Use `Example::` with indented code blocks, not `` ```python ``
+- Ensure blank lines between directive content and subsequent sections
+- Use `Parameters:` (not `Attributes:`) for dataclass field documentation to avoid duplicate entries

docs/api/build-docs.sh

@@ -1,8 +1,16 @@
 #!/bin/bash
 
+# Usage: ./build-docs.sh [--strict]
+#   --strict: Treat warnings as errors (default: warnings only)
+
+SPHINX_OPTS=""
+if [ "$1" = "--strict" ]; then
+    SPHINX_OPTS="-W --keep-going"
+fi
+
 # Build docs using uv
 echo "Installing dependencies with uv..."
-uv sync --group docs --all-extras --no-extra krisp --no-extra gstreamer --no-extra local_smart_turn --no-extra moondream --no-extra riva --no-extra mlx-whisper
+uv sync --group docs --all-extras --no-extra gstreamer --no-extra local_smart_turn --no-extra moondream --no-extra mlx-whisper
 
 # Check if sphinx-build is available
 if ! uv run sphinx-build --version &> /dev/null; then
@@ -14,8 +22,7 @@ fi
 rm -rf _build
 
 echo "Building documentation..."
-# Build docs matching ReadTheDocs configuration
-uv run sphinx-build -b html -d _build/doctrees . _build/html -W --keep-going
+uv run sphinx-build -b html -d _build/doctrees . _build/html $SPHINX_OPTS
 
 if [ $? -eq 0 ]; then
     echo "Documentation built successfully!"

docs/api/conf.py

@@ -4,6 +4,19 @@ import sys
 from datetime import datetime
 from pathlib import Path
 
+# Fix Pydantic v2 + Sphinx autodoc incompatibility: ConfigDict(extra="allow") fails
+# during Sphinx's import because __pydantic_extra__ annotation on BaseModel resolves to
+# `Dict[str, Any] | None` whose get_origin() is Union, not dict. Patch the check to
+# accept Union-wrapped dict types (i.e., Optional[Dict[str, Any]]).
+import pydantic._internal._generate_schema as _pydantic_gs
+
+_ORIG_DICT_TYPES = _pydantic_gs.DICT_TYPES
+# Expand the accepted types to include Union (Optional[Dict[str, Any]])
+import types
+import typing
+
+_pydantic_gs.DICT_TYPES = [*_ORIG_DICT_TYPES, typing.Union, types.UnionType]
+
 # Configure logging
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger("sphinx-build")
@@ -48,8 +61,6 @@ autodoc_default_options = {
 # Mock imports for optional dependencies
 autodoc_mock_imports = [
     # Krisp - has build issues on some platforms
-    "pipecat_ai_krisp",
-    "krisp",
     "krisp_audio",
     # System-specific GUI libraries
     "_tkinter",
@@ -78,16 +89,6 @@ autodoc_mock_imports = [
     "einops",
     "intel_extension_for_pytorch",
     "huggingface_hub",
-    # riva dependencies
-    "riva",
-    "riva.client",
-    "riva.client.Auth",
-    "riva.client.ASRService",
-    "riva.client.StreamingRecognitionConfig",
-    "riva.client.RecognitionConfig",
-    "riva.client.AudioEncoding",
-    "riva.client.proto.riva_tts_pb2",
-    "riva.client.SpeechSynthesisService",
     # MLX dependencies (Apple Silicon specific)
     "mlx",
     "mlx_whisper",  # Note: might need underscore format too
@@ -98,7 +99,6 @@ autodoc_mock_imports = [
     "cartesia",
     "camb",
     "sarvamai",
-    "openpipe",
     "openai.types.beta.realtime",
     "langchain_core",
     "langchain_core.messages",
@@ -110,6 +110,8 @@ autodoc_mock_imports = [
     "fastapi.middleware",
     "fastapi.responses",
     "uvicorn",
+    # Deepgram dependencies
+    "deepgram",
 ]
 
 # HTML output settings
@@ -136,6 +138,8 @@ def import_core_modules():
         "pipecat.runner",
         "pipecat.serializers",
         "pipecat.transcriptions",
+        "pipecat.turns",
+        "pipecat.extensions",
         "pipecat.utils",
     ]
 
@@ -180,7 +184,6 @@ def setup(app):
     logger.info(f"Source directory: {source_dir}")
 
     excludes = [
-        str(project_root / "src/pipecat/pipeline/to_be_updated"),
         str(project_root / "src/pipecat/examples"),
         str(project_root / "src/pipecat/tests"),
         "**/test_*.py",

docs/api/index.rst

@@ -32,4 +32,5 @@ Quick Links
    Services <api/pipecat.services>
    Transcriptions <api/pipecat.transcriptions>
    Transports <api/pipecat.transports>
+   Turns <api/pipecat.turns>
    Utils <api/pipecat.utils>

env.example

@@ -1,5 +1,5 @@
 # AI-COUSTICS
-AICOUSTICS_LICENSE_KEY=...
+AIC_LICENSE_KEY=...
 
 # Anthropic
 ANTHROPIC_API_KEY=...
@@ -80,15 +80,9 @@ GOOGLE_TEST_CREDENTIALS=...
 # Gradium
 GRAPDIUM_API_KEY=...
 
-# Grok
-GROK_API_KEY=...
-
 # Groq
 GROQ_API_KEY=...
 
-# Hathora
-HATHORA_API_KEY=...
-
 # Heygen
 HEYGEN_API_KEY=...
 HEYGEN_LIVE_AVATAR_API_KEY=...
@@ -104,9 +98,14 @@ INWORLD_API_KEY=...
 KRISP_MODEL_PATH=...
 
 # Krisp Viva
+KRISP_VIVA_API_KEY=...
 KRISP_VIVA_FILTER_MODEL_PATH=...
 KRISP_VIVA_TURN_MODEL_PATH=...
 
+# LemonSlice
+LEMONSLICE_API_KEY=...
+LEMONSLICE_AGENT_ID=...
+
 # LiveKit
 LIVEKIT_API_KEY=...
 LIVEKIT_API_SECRET=...
@@ -122,18 +121,25 @@ MINIMAX_GROUP_ID=...
 # Mistral
 MISTRAL_API_KEY=...
 
+# Nebius
+NEBIUS_API_KEY=...
+
 # Neuphonic
 NEUPHONIC_API_KEY=...
 
+# Novita
+NOVITA_API_KEY=...
+
 # NVIDIA
 NVIDIA_API_KEY=...
+# For a full example of how to deploy to SageMaker, see:
+# https://github.com/pipecat-ai/pipecat-examples/tree/main/nvidia_sagemaker_example/deployment/aws-sagemaker-nvidia
+SAGEMAKER_ASR_ENDPOINT_NAME=...
+SAGEMAKER_MAGPIE_ENDPOINT_NAME=...
 
 # OpenAI
 OPENAI_API_KEY=...
 
-# OpenPipe
-OPENPIPE_API_KEY=...
-
 # OpenRouter
 OPENROUTER_API_KEY=...
 
@@ -146,10 +152,6 @@ KOALA_ACCESS_KEY=...
 # Piper
 PIPER_BASE_URL=...
 
-# PlayHT
-PLAYHT_USER_ID=...
-PLAYHT_API_KEY=...
-
 # Plivo
 PLIVO_AUTH_ID=...
 PLIVO_AUTH_TOKEN=...
@@ -178,6 +180,9 @@ SENTRY_DSN=...
 SIMLI_API_KEY=...
 SIMLI_FACE_ID=...
 
+# Smallest
+SMALLEST_API_KEY=...
+
 # Smart turn
 LOCAL_SMART_TURN_MODEL_PATH=...
 FAL_SMART_TURN_API_KEY=...
@@ -211,3 +216,12 @@ WHATSAPP_TOKEN=...
 WHATSAPP_WEBHOOK_VERIFICATION_TOKEN=...
 WHATSAPP_PHONE_NUMBER_ID=...
 WHATSAPP_APP_SECRET=...
+
+# xAI / Grok
+XAI_API_KEY=...
+
+# PIPECAT_SCTP_MAX_CHUNK_SIZE controls the maximum SCTP DATA-chunk payload
+# size (bytes) used by aiortc's data channel. The default is 1100.
+# All the details here:
+# https://docs.pipecat.ai/api-reference/server/services/transport/small-webrtc#pipecat_sctp_max_chunk_size
+#PIPECAT_SCTP_MAX_CHUNK_SIZE=1100

examples/README.md

@@ -1,31 +1,150 @@
 # Pipecat Examples
 
-This directory contains examples to help you learn how to build with Pipecat.
+This directory contains examples showing how to build voice and multimodal agents with Pipecat.
 
-## Getting Started
+## Setup
 
-New to Pipecat? Start here:
+1. Follow the [README](https://github.com/pipecat-ai/pipecat/blob/main/README.md#%EF%B8%8F-contributing-to-the-framework) steps to get your local environment configured.
 
-- **[Quickstart](quickstart/)** - Get your first voice AI bot running in 5 minutes _(coming soon)_
-- **[Client/Server Web](client-server-web/)** - Learn to build web applications with Pipecat's client SDKs _(coming soon)_
-- **[Phone Bot with Twilio](phone-bot-twilio/)** - Connect your bot to a phone number _(coming soon)_
+   > **Run from root directory**: Make sure you are running the steps from the root directory.
 
-## Foundational Examples
+   > **Using local audio?**: The `LocalAudioTransport` requires a system dependency for `portaudio`. Install the dependency to use the transport.
 
-Single-file examples that introduce core Pipecat concepts one at a time. These examples:
+2. Copy the [`env.example`](../env.example) file and add API keys for services you plan to use:
 
-- Build on each other progressively
-- Focus on specific features or integrations
-- Are used for testing with every Pipecat release
+   ```bash
+   cp env.example .env
+   # Edit .env with your API keys
+   ```
 
-See the **[Foundational Examples README](foundational/)** for the complete list.
+3. Run any example:
 
-## More Advanced Examples
+   ```bash
+   uv run python getting-started/01-say-one-thing.py
+   ```
 
-Ready to explore complex use cases? Visit **[pipecat-examples](https://github.com/pipecat-ai/pipecat-examples)** for:
+4. Open the web interface at http://localhost:7860/client/ and click "Connect"
 
-- Production-ready applications
-- Multi-platform client implementations
-- Telephony integrations
-- Multimodal and creative applications
-- Deployment and monitoring examples
+## Running examples with other transports
+
+Most examples support running with other transports, like Twilio or Daily.
+
+### Daily
+
+You need to create a Daily account at https://dashboard.daily.co/u/signup. Once signed up, you can create your own room from the dashboard and set the environment variables `DAILY_ROOM_URL` and `DAILY_API_KEY`. Alternatively, you can let the example create a room for you (still needs `DAILY_API_KEY` environment variable). Then, start any example with `-t daily`:
+
+```bash
+uv run getting-started/06-voice-agent.py -t daily
+```
+
+### Twilio
+
+It is also possible to run the example through a Twilio phone number. You will need to setup a few things:
+
+1. Install and run [ngrok](https://ngrok.com/download).
+
+```bash
+ngrok http 7860
+```
+
+2. Configure your Twilio phone number. One way is to setup a TwiML app and set the request URL to the ngrok URL from step (1). Then, set your phone number to use the new TwiML app.
+
+Then, run the example with:
+
+```bash
+uv run getting-started/06-voice-agent.py -t twilio -x NGROK_HOST_NAME
+```
+
+## Directory Structure
+
+### [`getting-started/`](./getting-started/)
+
+Progressive introduction to Pipecat, from minimal TTS to a full voice agent with function calling.
+
+### [`voice/`](./voice/)
+
+Full STT + LLM + TTS voice agent pipelines showcasing different speech service providers (Deepgram, ElevenLabs, Cartesia, etc.)
+
+### [`function-calling/`](./function-calling/)
+
+Function calling with different LLM providers (OpenAI, Anthropic, Google, etc.)
+
+### [`transcription/`](./transcription/)
+
+Speech-to-text examples with various STT providers.
+
+### [`vision/`](./vision/)
+
+Image description and vision capabilities with different multimodal LLMs.
+
+### [`realtime/`](./realtime/)
+
+Realtime and multimodal live APIs (OpenAI Realtime, Gemini Live, AWS Nova Sonic, Ultravox, Grok).
+
+### [`persistent-context/`](./persistent-context/)
+
+Maintaining conversation context across sessions with different providers.
+
+### [`context-summarization/`](./context-summarization/)
+
+Summarizing conversation context to manage token limits.
+
+### [`update-settings/`](./update-settings/)
+
+Changing service settings at runtime, organized by service type:
+
+- **[`stt/`](./update-settings/stt/)** — Speech-to-text settings
+- **[`tts/`](./update-settings/tts/)** — Text-to-speech settings
+- **[`llm/`](./update-settings/llm/)** — LLM settings
+
+### [`turn-management/`](./turn-management/)
+
+Turn detection, interruption handling, and user input management.
+
+### [`thinking-and-mcp/`](./thinking-and-mcp/)
+
+LLM thinking/reasoning modes and MCP (Model Context Protocol) tool server integration.
+
+### [`transports/`](./transports/)
+
+Transport layer examples (WebRTC, Daily, LiveKit).
+
+### [`video-avatar/`](./video-avatar/)
+
+Video avatar integrations (Tavus, HeyGen, Simli, LemonSlice).
+
+### [`video-processing/`](./video-processing/)
+
+Video processing, mirroring, GStreamer, and custom video tracks.
+
+### [`audio/`](./audio/)
+
+Audio recording, background sounds, and sound effects.
+
+### [`observability/`](./observability/)
+
+Pipeline monitoring: observers, heartbeats, and Sentry metrics.
+
+### [`rag/`](./rag/)
+
+Retrieval-augmented generation, grounding, and long-term memory (Mem0, Gemini).
+
+### [`features/`](./features/)
+
+Miscellaneous features: wake phrases, live translation, service switching, voice switching, and more.
+
+## Advanced Usage
+
+### Customizing Network Settings
+
+```bash
+uv run python <example-name> --host 0.0.0.0 --port 8080
+```
+
+### Troubleshooting
+
+- **No audio/video**: Check browser permissions for microphone and camera
+- **Connection errors**: Verify API keys in `.env` file
+- **Port conflicts**: Use `--port` to change the port
+
+For more examples, visit the [pipecat-examples repository](https://github.com/pipecat-ai/pipecat-examples).