Metadata-Version: 2.5
Name: laidline-livekit
Version: 1.0.0
Summary: LiveKit Agents `tts_node` wrapper: marks audio frames with streaming AudioSeal; one evidence entry per call.
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,livekit,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: livekit-agents<2,>=1.8
Description-Content-Type: text/markdown

# laidline-livekit

A LiveKit Agents `tts_node` wrapper. It marks every synthesized `rtc.AudioFrame` with streaming AudioSeal and writes one Laidline evidence entry per call.

```bash
pip install laidline-livekit   # pulls laidline[audio] and livekit-agents>=1.8,<2
```

```python
from livekit.agents import Agent
from laidline import MarkContext, Marker
from laidline_livekit import mark_audio_frames

marker = Marker.from_config("laidline.yaml")  # in-process: keys, models and evidence stay on your host


class Assistant(Agent):
    async def tts_node(self, text, model_settings):
        return mark_audio_frames(
            marker,
            Agent.default.tts_node(self, text, model_settings),
            ctx=MarkContext(route="livekit:support-agent", tenant="acme"),
        )
```

## What it does

- `mark_audio_frames(marker, frames, *, ctx=None)` returns an async iterator of the same frames, marked. Rate, channels and timing stay the same, and each frame keeps its `userdata`, where LiveKit carries timed transcripts.
- Each call writes one `marked` evidence entry with `modality: audio`, `watermark.streaming: true`, the payload and issuer id, the duration, and your `ctx` (default route `livekit:tts_node`). An iterator that changes sample rate part-way gets one entry per format.
- The entry is written when the iterator ends. That includes a consumer that stops early (an interrupted turn) and a cancelled task. The wrapped iterator is closed as well.
- It checks its arguments when you call it: a `MarkClient` raises `TypeError`, because the streaming path has no HTTP form. A Marker with `watermark.audio.enabled: false` raises `ValueError`.
- The embedder is AudioSeal's streaming card (`watermark.audio.stream_kind: block`, the only kind).

## What it does not do

- 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 streaming mark does not survive below 16 kHz.
- 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 (for example egress to a file), 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 detection threshold is 0.39, which gave a 0.75 % false-positive rate. Figures are the share of clips on which the streaming-mode mark (the one this wrapper 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 WebRTC session, packet loss or jitter was tested. **It does not survive a simulated phone leg** (G.711 codec simulation, the codec of LiveKit SIP calls to the PSTN). The streaming mark was not run over a real call. For phone deployments, provenance comes from the evidence entry and from C2PA on stored recordings, not from the watermark. 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: 99 % (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).

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/livekit](https://laidline.com/docs/integrations/livekit). Streaming sessions, detection and the operating threshold are in [https://laidline.com/docs/integrations/audio](https://laidline.com/docs/integrations/audio).
