Metadata-Version: 2.5
Name: laidline-pipecat
Version: 1.1.0
Summary: Pipecat `FrameProcessor` placed after TTS; marks TTS audio frames with streaming AudioSeal; one evidence entry per utterance.
Project-URL: Homepage, https://laidline.com
Project-URL: Documentation, https://laidline.com/docs/quickstart
Project-URL: Changelog, https://laidline.com/docs/changelog
Author: Laidline LLC
License-Expression: LicenseRef-Laidline-Source-Available
License-File: LICENSE
Keywords: ai-act,c2pa,pipecat,provenance,voice,watermark
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.12
Requires-Dist: laidline[audio]<2,>=1.0
Requires-Dist: pipecat-ai<2,>=1.12
Description-Content-Type: text/markdown

# laidline-pipecat

A Pipecat `FrameProcessor` that sits right after the TTS service. It marks the TTS audio frames (keyed from 8 kHz, unkeyed from 16 kHz) with streaming AudioSeal and writes one Laidline evidence entry per utterance.

```bash
pip install laidline-pipecat   # pulls laidline[audio] and pipecat-ai>=1.12,<2
```

```python
from laidline import MarkContext, Marker
from laidline_pipecat import LaidlineTTSProcessor

marker = Marker.from_config("laidline.yaml")  # in-process: keys, models and evidence stay on your host
pipeline = Pipeline(
    [
        transport.input(),
        stt,
        context_aggregator.user(),
        llm,
        tts,
        LaidlineTTSProcessor(marker, ctx=MarkContext(route="pipecat:support-bot", tenant="acme")),
        transport.output(),
        context_aggregator.assistant(),
    ]
)
```

## What it does

- Each downstream `TTSAudioRawFrame` is replaced by a copy carrying the marked PCM. The copy keeps the same length, rate, channels, `pts`, `transport_destination`, `context_id` and metadata. Every other frame passes through unchanged.
- `TTSStartedFrame` opens an utterance. `TTSStoppedFrame`, `InterruptionFrame`, `EndFrame`, `CancelFrame` and processor cleanup close it. Closing writes one `marked` evidence entry with `modality: audio`, `watermark.streaming: true`, the payload and issuer id, the duration, your `ctx`, and the TTS `context_id` under `extra.context_id`. An utterance that changes sample rate part-way gets one entry per format.
- It needs an in-process `Marker` with `watermark.audio.enabled: true`. A `MarkClient` raises `TypeError`, because the streaming path has no HTTP form. A Marker with audio watermarking disabled raises `ValueError`.
- A marking failure raises out of `process_frame`. Pipecat reports it as an error and does not push the unmarked frame.
- Unkeyed, the embedder is AudioSeal's streaming card (`watermark.audio.stream_kind: block`, the only value). A keyed deployment (`watermark.payload_keys`) marks through the keyed stream marker instead (see Survival).

## What it does not do

- Unkeyed, audio below 16 kHz (an 8 kHz phone bot) is not marked: it passes through unchanged and the entry says `watermark: null`, `watermark_skipped:rate_below_16k`. The unkeyed streaming mark does not survive below 16 kHz. A keyed deployment (`watermark.payload_keys`, what `laidline init` writes) marks from 8 kHz: measured 2026-11-07 at 8 kHz, 100 of 100 through simulated G.711 mu-law and A-law, G.726 and 5 percent packet loss (n = 100 per cell; ffmpeg codecs, not a carrier path). Rates between 8 and 16 kHz are admitted but unmeasured.
- A stream carries no C2PA manifest (`c2pa: null`, warning `manifest_skipped:streaming`). The watermark and the evidence entry are the provenance for live audio.
- For a recording you store, sign the file itself with `marker.mark_audio(..., fmt="wav" | "flac" | "mp3" | "m4a")`. This embeds a manifest and adds the batch mark. Laidline's `/v1/audio/speech` proxy in streaming mode stores a signed twin of a response only when `watermark.audio.store_signed_twin` is enabled and only for a stream that completed.

## Survival

Measured 2026-09-27 on LibriSpeech test-clean, 500 speech clips. The threshold for this table is 0.39, which flagged 0.75 % of 530 unmarked clips; the shipped default is 0.5, which flagged 0.38 % and detects less after heavy degradation. Figures are the share of clips on which the streaming-mode mark (the one this plugin embeds) is still detected:

| Transform | Streaming mode |
|---|---|
| Opus 24 kbps | 100 % |
| Opus 48 kbps | 100 % |
| MP3 64 kbps | 100 % |
| AAC 64 kbps | 100 % |
| G.711 mu-law | 0 % |
| 8 kHz resampling | 0 % |
| EnCodec 6 kbps | 100 % detected, 0 % exact issuer |
| Mimi | 0 % |

The streaming mark survives an offline Opus transcode at 24 and 48 kbps (100 percent on 500 LibriSpeech clips); no real WebRTC session or jitter was tested, keyed or unkeyed, and no real carrier leg with the unkeyed stream; the packet-loss figure above is a simulation (5 percent loss, repeat-last fill, keyed, 100 of 100 at 8 kHz). **The unkeyed streaming mark does not survive a simulated phone leg** (G.711 codec simulation). The unkeyed streaming mark was not run over a real call. The keyed stream at 8 kHz read 19 of 19 real SignalWire calls on 2026-11-08 (a pilot; Wilson 95 % lower bound 83.2 %; clips marked offline by `Marker.audio_stream`, not through this plugin; read on the recording aligned to the clip, the untrimmed recording 2 of 19; carrier routing unconfirmed, possibly on-net). Beside it, not pooled: over Amazon Connect and SignalWire, the keyed stream at 8 kHz read 576 of 577 real calls on 2026-11-08 (Wilson 95 % lower bound 99.0 %; clips marked the same way, played by Amazon Connect as an 8 kHz mu-law file and recorded by SignalWire at the callee; read on the recording aligned to the clip; 1 call failed and is not counted, its inbound leg never matched to the contact; carrier routing unconfirmed). For an unkeyed phone deployment, provenance comes from the evidence entry and from C2PA on stored recordings, not from the unkeyed watermark. The keyed stream (what `laidline init` writes, `watermark.payload_keys`) read 100 of 100 through simulated G.711 and through Opus at 24 kbit/s (ffmpeg codecs on 10 s of speech, 28 Oct 2026, not a carrier path; see [https://laidline.com/docs/integrations/pipecat](https://laidline.com/docs/integrations/pipecat)). For comparison, the batch (non-streaming) mark that `mark_audio` embeds survives simulated G.711 and 8 kHz at 100 %, and a real call with the batch mark: 96 % at the shipped 0.5 and 99 % at 0.39 (100 Twilio number-to-number calls recorded at the callee, G.711 8 kHz, carrier routing unconfirmed and possibly on-net, measured 2026-09-27); on SignalWire, the bench's current provider, 21 of 21 calls read the exact payload on the recording aligned to the clip (2026-10-21 and 22, carrier routing unconfirmed, possibly on-net; the untrimmed recording gave no exact read).

The unkeyed streaming mark's mean embed SNR is 17.4 dB (5th percentile 8.7 dB), which is audible on some voices. Listen to your own voices before you ship.

The full numbers and method are in [the benchmarks page](https://laidline.com/docs/benchmarks) ("Audio robustness"), and what was tested, and how, in [https://laidline.com/docs/integrations/pipecat](https://laidline.com/docs/integrations/pipecat). Streaming sessions, detection and the operating threshold are in [https://laidline.com/docs/integrations/audio](https://laidline.com/docs/integrations/audio).
