From fd900fb3666e4566fb047488f624dd049d772e55 Mon Sep 17 00:00:00 2001 From: James Hush Date: Tue, 28 Jul 2026 11:42:55 +0800 Subject: [PATCH 1/3] Document Pipecat Cloud session recordings The session detail view plays back a Daily cloud recording of the room the agent ran in. Nothing said so publicly, and nothing covered retention, so customers had no way to answer basic compliance questions about it. Adds a Session Recordings page covering: - the Daily transport requirement, and that Pipecat Cloud adds no recording defaults of its own - how to start a recording (token auto-start, transport calls, audio only) - that user audio is captured before any in-pipeline audio filter such as Krisp VIVA, because the recording is made from what participants publish - that cloud recording and AudioBufferProcessor are alternatives, not a pair - retention: recordings are kept until deleted, there is no automatic expiry - storing recordings in your own S3 bucket for lifecycle control Raised by support ticket T-2978. --- docs.json | 1 + pipecat-cloud/fundamentals/logging.mdx | 4 + .../fundamentals/session-recordings.mdx | 116 ++++++++++++++++++ 3 files changed, 121 insertions(+) create mode 100644 pipecat-cloud/fundamentals/session-recordings.mdx diff --git a/docs.json b/docs.json index 5cf1b7249..d24a53fd5 100644 --- a/docs.json +++ b/docs.json @@ -247,6 +247,7 @@ "pipecat-cloud/fundamentals/scaling", "pipecat-cloud/fundamentals/health-checks", "pipecat-cloud/fundamentals/logging", + "pipecat-cloud/fundamentals/session-recordings", "pipecat-cloud/fundamentals/error-codes" ] }, diff --git a/pipecat-cloud/fundamentals/logging.mdx b/pipecat-cloud/fundamentals/logging.mdx index 8b2c0357c..f50bf1118 100644 --- a/pipecat-cloud/fundamentals/logging.mdx +++ b/pipecat-cloud/fundamentals/logging.mdx @@ -61,6 +61,10 @@ async def bot(args: PipecatRunnerArguments): more additional SessionArgument types. +## Session recordings + +The session detail view can also play back a session's audio. That audio comes from a Daily cloud recording of the room your agent ran in, which you control yourself. See [Session Recordings](/pipecat-cloud/fundamentals/session-recordings) for how to turn it on and how to control storage and retention. + ## CPU and memory metrics Pipecat Cloud tracks CPU and memory usage for each session, which can be helpful for troubleshooting performance issues. You can view these metrics in two ways: diff --git a/pipecat-cloud/fundamentals/session-recordings.mdx b/pipecat-cloud/fundamentals/session-recordings.mdx new file mode 100644 index 000000000..a3481dac2 --- /dev/null +++ b/pipecat-cloud/fundamentals/session-recordings.mdx @@ -0,0 +1,116 @@ +--- +title: Session Recordings +description: "Where the session audio comes from, how to turn it on, and how to control storage and retention" +--- + +The session detail view in the Pipecat Cloud dashboard can play back the audio of a session. That audio is a [Daily cloud recording](https://docs.daily.co/docs/guides/features/recording) of the room your agent ran in. It is not a separate Pipecat Cloud recording feature, and Pipecat Cloud does not turn it on for you. + +Knowing that answers most questions about it: what the audio contains, where it is stored, and how long it lasts are all Daily cloud recording behavior. + +## What you need for a recording to appear + +Two things: + +1. **Your agent runs on the Daily transport.** Cloud recording is a feature of the Daily room your agent is in. An agent on a non-Daily transport (a Twilio or generic WebSocket leg, for example) has no room to record, so no recording is made and no player appears on its session page. +2. **A cloud recording is actually started for that room.** Pipecat Cloud does not start one on your behalf. See the next section. + +Nothing else is required. You do not need to enable the dashboard player separately, and you do not need an `AudioBufferProcessor` in your pipeline (see [Choosing one recording approach](#choosing-one-recording-approach)). + +## Turning recording on + +The [`/start` endpoint](/api-reference/pipecat-cloud/rest-reference/endpoint/start) passes `dailyRoomProperties` and `dailyMeetingTokenProperties` through to Daily unchanged. Pipecat Cloud adds no recording defaults of its own, so if you do not ask for a recording, none is made. + +### Start automatically when the agent joins + +Set `start_cloud_recording` on the meeting token. Daily starts the recording as soon as that token holder joins the room: + +```bash +curl --location --request POST 'https://api.pipecat.daily.co/v1/public/my-agent-name/start' \ + --header 'Authorization: Bearer YOUR_API_KEY' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "createDailyRoom": true, + "dailyRoomProperties": { + "enable_recording": "cloud" + }, + "dailyMeetingTokenProperties": { + "start_cloud_recording": true + } + }' +``` + +### Start and stop it from your pipeline + +If you want control over when recording runs, call `start_recording()` and `stop_recording()` on the transport instead. See [DailyTransport recording](/api-reference/server/services/transport/daily#recording). + +### Record audio only + +Set `enable_recording` to `cloud-audio-only` in `dailyRoomProperties` to produce an `.m4a` audio file instead of video. Auto-start still applies, so you keep the dashboard player. See [DailyRoomProperties](/api-reference/server/utilities/daily/rest-helper#dailyroomproperties). + +## What the recording contains + +A cloud recording is produced on the media server, from what each participant **publishes** into the room. + +That has one consequence worth understanding: **user audio in the recording is the raw microphone audio, before any in-pipeline audio filter**. If your agent uses an input audio filter such as [Krisp VIVA](/pipecat-cloud/guides/krisp-viva), that filter runs inside your pipeline on inbound frames, so it only cleans the copy that feeds your STT and VAD. It does not change what the user publishes, so it never affects the recording. + +If you need audio that reflects your filtering, record it in the pipeline instead, using the `AudioBufferProcessor`. + +## Choosing one recording approach + +Pipecat gives you [two ways to record a conversation](/pipecat/fundamentals/recording-audio), and they are alternatives rather than a pair: + +| | Daily cloud recording | `AudioBufferProcessor` | +| --- | --- | --- | +| Where it runs | Daily's media server | Inside your pipeline | +| Output | One room-level file | Composite, per-track, or per-turn audio | +| User audio | Before your input audio filter | After your input audio filter | +| Storage | Daily storage or your own S3 bucket | Wherever your code uploads it | +| Dashboard player | Yes | No | +| Code required | None | You write the upload and storage | + +If you already have a Daily cloud recording and you only need session audio for observability, the `AudioBufferProcessor` is duplicate work and duplicate storage. Use one or the other unless you specifically need both the pre-filter and post-filter audio. + +## Storage and retention + +By default, cloud recordings are stored by Daily, on the Daily domain that Pipecat Cloud manages for your organization. List them, fetch access links, and delete them with the [Daily recordings REST API](https://docs.daily.co/reference/rest-api/recordings). + + + **Recordings are kept until you delete them.** There is no automatic expiry, + so cleanup is yours to run. Recording storage is billed per minute per month + stored (see [pricing](https://www.daily.co/pricing/pipecat-cloud/#recording)), + so it is worth building deletion into your workflow early rather than letting + recordings accumulate. + + +### Store recordings in your own S3 bucket + +If you have retention or data residency requirements, the cleanest option is to keep recordings out of Daily's storage entirely. Set `recordings_bucket` in `dailyRoomProperties` and Daily writes recordings straight to your bucket: + +```bash +curl --location --request POST 'https://api.pipecat.daily.co/v1/public/my-agent-name/start' \ + --header 'Authorization: Bearer YOUR_API_KEY' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "createDailyRoom": true, + "dailyRoomProperties": { + "enable_recording": "cloud", + "recordings_bucket": { + "bucket_name": "my-recordings-bucket", + "bucket_region": "us-west-2", + "assume_role_arn": "arn:aws:iam::123456789012:role/DailyRecordingsRole", + "allow_api_access": true + } + }, + "dailyMeetingTokenProperties": { + "start_cloud_recording": true + } + }' +``` + +Your own S3 lifecycle rules then control retention. Set `allow_api_access` to `true` if you want the dashboard and the Daily access-link API to be able to play recordings back from your bucket. + +You can also configure the bucket once at the domain level instead of per room. For IAM role setup and the full property reference, see [Storing recordings in a custom S3 bucket](https://docs.daily.co/docs/guides/features/recording/custom-s3-storage). + +### Turn recording off + +Leave `start_cloud_recording` out of your `/start` call and no cloud recording is made. Nothing in Pipecat Cloud will add it back. You lose the dashboard player, and no recording storage is billed. From fbaab27e040707c00cc2af61659f9370e799659e Mon Sep 17 00:00:00 2001 From: James Hush Date: Tue, 28 Jul 2026 11:48:33 +0800 Subject: [PATCH 2/3] Trim session recordings page Drop the audio-only section and the cloud recording vs AudioBufferProcessor comparison table. Keep the page focused on where the session audio comes from, storage, and retention. Also drop the now-dangling anchor link to the removed comparison section. --- .../fundamentals/session-recordings.mdx | 23 ++----------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/pipecat-cloud/fundamentals/session-recordings.mdx b/pipecat-cloud/fundamentals/session-recordings.mdx index a3481dac2..f2e62febf 100644 --- a/pipecat-cloud/fundamentals/session-recordings.mdx +++ b/pipecat-cloud/fundamentals/session-recordings.mdx @@ -14,7 +14,7 @@ Two things: 1. **Your agent runs on the Daily transport.** Cloud recording is a feature of the Daily room your agent is in. An agent on a non-Daily transport (a Twilio or generic WebSocket leg, for example) has no room to record, so no recording is made and no player appears on its session page. 2. **A cloud recording is actually started for that room.** Pipecat Cloud does not start one on your behalf. See the next section. -Nothing else is required. You do not need to enable the dashboard player separately, and you do not need an `AudioBufferProcessor` in your pipeline (see [Choosing one recording approach](#choosing-one-recording-approach)). +Nothing else is required. You do not need to enable the dashboard player separately. ## Turning recording on @@ -43,32 +43,13 @@ curl --location --request POST 'https://api.pipecat.daily.co/v1/public/my-agent- If you want control over when recording runs, call `start_recording()` and `stop_recording()` on the transport instead. See [DailyTransport recording](/api-reference/server/services/transport/daily#recording). -### Record audio only - -Set `enable_recording` to `cloud-audio-only` in `dailyRoomProperties` to produce an `.m4a` audio file instead of video. Auto-start still applies, so you keep the dashboard player. See [DailyRoomProperties](/api-reference/server/utilities/daily/rest-helper#dailyroomproperties). - ## What the recording contains A cloud recording is produced on the media server, from what each participant **publishes** into the room. That has one consequence worth understanding: **user audio in the recording is the raw microphone audio, before any in-pipeline audio filter**. If your agent uses an input audio filter such as [Krisp VIVA](/pipecat-cloud/guides/krisp-viva), that filter runs inside your pipeline on inbound frames, so it only cleans the copy that feeds your STT and VAD. It does not change what the user publishes, so it never affects the recording. -If you need audio that reflects your filtering, record it in the pipeline instead, using the `AudioBufferProcessor`. - -## Choosing one recording approach - -Pipecat gives you [two ways to record a conversation](/pipecat/fundamentals/recording-audio), and they are alternatives rather than a pair: - -| | Daily cloud recording | `AudioBufferProcessor` | -| --- | --- | --- | -| Where it runs | Daily's media server | Inside your pipeline | -| Output | One room-level file | Composite, per-track, or per-turn audio | -| User audio | Before your input audio filter | After your input audio filter | -| Storage | Daily storage or your own S3 bucket | Wherever your code uploads it | -| Dashboard player | Yes | No | -| Code required | None | You write the upload and storage | - -If you already have a Daily cloud recording and you only need session audio for observability, the `AudioBufferProcessor` is duplicate work and duplicate storage. Use one or the other unless you specifically need both the pre-filter and post-filter audio. +If you need audio that reflects your filtering, [record it in the pipeline instead](/pipecat/fundamentals/recording-audio). ## Storage and retention From 81fe94ae58332b67c27b1d1f41123b80ea6f9af4 Mon Sep 17 00:00:00 2001 From: James Hush Date: Tue, 28 Jul 2026 11:53:36 +0800 Subject: [PATCH 3/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- pipecat-cloud/fundamentals/session-recordings.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pipecat-cloud/fundamentals/session-recordings.mdx b/pipecat-cloud/fundamentals/session-recordings.mdx index f2e62febf..0464c7b6e 100644 --- a/pipecat-cloud/fundamentals/session-recordings.mdx +++ b/pipecat-cloud/fundamentals/session-recordings.mdx @@ -18,7 +18,7 @@ Nothing else is required. You do not need to enable the dashboard player separat ## Turning recording on -The [`/start` endpoint](/api-reference/pipecat-cloud/rest-reference/endpoint/start) passes `dailyRoomProperties` and `dailyMeetingTokenProperties` through to Daily unchanged. Pipecat Cloud adds no recording defaults of its own, so if you do not ask for a recording, none is made. +The [`/start` endpoint](/api-reference/pipecat-cloud/rest-reference/endpoint/start) passes `dailyRoomProperties` and `dailyMeetingTokenProperties` through to Daily unchanged **when Pipecat Cloud is creating the room** (`createDailyRoom: true`). Pipecat Cloud adds no recording defaults of its own, so if you do not ask for a recording, none is made. ### Start automatically when the agent joins