docs: close gaps surfaced by Kapa source analytics (batch 2)#961
Open
jamsea wants to merge 3 commits into
Open
docs: close gaps surfaced by Kapa source analytics (batch 2)#961jamsea wants to merge 3 commits into
jamsea wants to merge 3 commits into
Conversation
Edits backed by recurring user questions in the Kapa source analytics export, each cited 3+ times: - scaling + active-sessions: state that each instance runs one session at a time, so concurrency equals instance count, and a larger compute profile does not raise per-instance concurrency. Cross-link capacity planning. - small-webrtc + runner guide: document that the default runner only supports enableDefaultIceServers (Google STUN) and cannot inject a custom TURN server; custom TURN requires your own signaling server. Plus a warning that webrtc_connection only exists on SmallWebRTCRunnerArguments (the most-repeated runner error). - stt-latency-tuning: add the default P99 TTFS table, the stop_secs=0.2 assumption and warning, runnable stt-benchmark commands, and a cross-link to the Metrics guide for live latency. - frames overview: add a Creating a Custom Frame section and cross-link Pipeline Termination from Ending a Conversation.
Contributor
|
🔍 Mintlify preview for this branch: https://daily-docs-source-analytics-user-turn-strategies.mintlify.app |
The per-service values change often, so an inline table would drift. Point readers to the source file as the single source of truth.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Pipecat and Pipecat Cloud documentation to address recurring user questions identified in Kapa source analytics, focusing on session concurrency, WebRTC ICE/TURN configuration in the development runner, STT TTFS latency guidance, and frame authoring/termination concepts.
Changes:
- Clarifies that Pipecat Cloud concurrency is “one active session per instance” and ties capacity to instance pool size (not compute profile size).
- Documents limitations of the default development runner around ICE servers (only
enableDefaultIceServers) and clarifieswebrtc_connectionavailability/type constraints. - Expands STT latency tuning guidance with source-of-truth pointers, assumptions, benchmark commands, and observability links; adds a “Creating a Custom Frame” section and a cross-link to pipeline termination.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| pipecat/fundamentals/stt-latency-tuning.mdx | Adds runtime observability pointers, clarifies TTFS defaults/assumptions, and includes runnable benchmarking commands. |
| pipecat-cloud/fundamentals/scaling.mdx | Clarifies that each instance runs one active session; concurrency equals instance count. |
| pipecat-cloud/fundamentals/active-sessions.mdx | Reinforces one-session-per-instance in capacity guidance and adds links to scaling/capacity planning. |
| api-reference/server/utilities/runner/guide.mdx | Warns about webrtc_connection type/availability and documents runner ICE limitations with cross-links. |
| api-reference/server/services/transport/small-webrtc.mdx | Adds a runner-specific ICE/TURN subsection clarifying what’s possible with the default runner. |
| api-reference/server/frames/overview.mdx | Adds guidance and examples for creating custom frames plus a pipeline-termination cross-link. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documentation edits across 6 pages, each backed by recurring real user questions in the Kapa source analytics export (citation logs). Every change addresses a cluster of 3+ questions where Kapa had to guess, read raw source, or hedged with "the knowledge sources do not contain...".
Changes by cluster
One session per instance (asked 8x on scaling, 4x on active-sessions)
pipecat-cloud/fundamentals/scaling.mdx: Note in Instances stating each instance runs one active session, concurrency equals instance count, and a larger compute profile (agent-2x/3x) gives one session more resources, not more sessions.pipecat-cloud/fundamentals/active-sessions.mdx: same point in Agent capacity, plus a cross-link to Capacity Planning.Custom ICE/TURN with the default runner (asked 9x on small-webrtc, 4x on runner guide)
api-reference/server/services/transport/small-webrtc.mdx: new "Using ICE servers with the development runner" subsection. The runner only supportsenableDefaultIceServers(Google STUN); custom TURN needs your own signaling server.api-reference/server/utilities/runner/guide.mdx: matching Note nearenableDefaultIceServers, plus a Warning thatwebrtc_connectiononly exists onSmallWebRTCRunnerArguments(the most-repeated runner error, 6x).pipecat/src/pipecat/runner/run.py.STT latency tuning (4 clusters on
pipecat/fundamentals/stt-latency-tuning.mdx)stt_latency.py), with that file named as the source of truth.VADParams.stop_secs=0.2and that changing it logs a warning.stt-benchmarkcommands (verified against the tool's README).Frames overview (
api-reference/server/frames/overview.mdx)Notes
🤖 Generated with Claude Code