Metadata-Version: 2.5
Name: srtc
Version: 0.1.1
Summary: SRTC Python SDK - 面向服务端 AI 场景（ASR/LLM/TTS）的实时音视频 SDK
Project-URL: Homepage, https://www.stmlink.com
Project-URL: Documentation, https://docs.stmlink.com
Author-email: Seastart <dev@seastart.cn>
License-Expression: LicenseRef-Proprietary
Keywords: ai,asr,audio,realtime,rtc,tts,webrtc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Conferencing
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Requires-Dist: av>=12.0
Requires-Dist: cffi>=1.15
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: httpx>=0.25; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: pipecat
Requires-Dist: pipecat-ai>=1.0; extra == 'pipecat'
Description-Content-Type: text/markdown

# SRTC Python SDK

**English** | [中文](#srtc-python-sdk中文)

[SRTC](https://www.stmlink.com) is a real-time audio/video engine built for fully private deployment, with SDKs for every major platform, support for domestic (Xinchuang) OS and hardware, interoperability with legacy SIP/H.323 devices, and built-in AI Agent capabilities.

This SDK is for **server-side AI**: voice agents (ASR → LLM → TTS), recording, transcription and QA. Full documentation: [docs.stmlink.com](https://docs.stmlink.com/zh/rtc/python/integration).

- **PCM in, PCM out** — remote audio arrives decoded at the sample rate you choose; write TTS output as raw PCM. Codecs and resampling are handled inside the SDK.
- **Real-time pacing built in** — however fast your TTS is, audio goes out one 20 ms frame at a time; `clear()` stops playback instantly when the user barges in.
- **Continuous timeline** — silence the remote side suppresses (DTX) is filled back in by RTP timestamp, so VAD and recording durations stay correct.
- **asyncio native** — `async with` to leave automatically, `async for` to consume frames, sync or async event handlers.
- **Native core** — signaling, reconnection and media transport run in a bundled native library, behaving the same as every other SRTC SDK and staying off the GIL.
- **pipecat ready** — a built-in pipecat transport drops into existing voice-agent pipelines.

## Install

```sh
pip install srtc                # core
pip install "srtc[pipecat]"     # with pipecat integration
```

Python 3.10+. Linux x86_64 / aarch64, macOS Apple Silicon, Windows x64. Dependencies: `cffi`, `av` (bundles ffmpeg and libopus — no system ffmpeg needed), `numpy`.

> **Linux with glibc < 2.28 (e.g. CentOS 7):** the latest `av` only ships wheels for glibc 2.28+. Pin it: `pip install srtc "av>=12,<14"`.

## Quick start

```python
import asyncio
import srtc

async def main(token: str):   # token is issued by your backend via the SRTC server API
    async with await srtc.Channel.join(
        token,
        auto_subscribe_audio=True,                  # hear everyone, including later joiners
        audio_format=srtc.AudioFormat(16000, 1),    # PCM format you receive (default 16 kHz mono)
    ) as ch:
        tts = await ch.publish_audio(desc="tts", audio_format=srtc.AudioFormat(24000, 1))

        async for frame in ch.audio_frames():       # frame.uid tells you who is speaking
            text = asr.feed(frame.uid, frame.to_numpy())
            if text:
                await tts.write(await tts_engine.synthesize(await llm.chat(text)))

asyncio.run(main(token))
```

Each `Channel.join` needs a freshly issued token — a token is bound to one session.

**Sending audio**

```python
await tts.write(pcm)            # any length; paced out in real time, back-pressure when the buffer is full
tts.clear()                     # user barged in: drop everything not yet sent
await tts.wait_for_playout()    # wait until everything written has been sent
tts.buffered_seconds            # > 0 while the agent is still "speaking"
```

**Events** — subclass `srtc.ChannelHandler` and override what you need (`on_user_join`, `on_user_leave`, `on_track_added`, `on_audio_frame`, `on_active_speakers`, `on_custom_msg`, `on_disconnected`, …), then pass `handler=` to `Channel.join`.

**pipecat**

```python
from srtc.pipecat_transport import SRTCParams, SRTCTransport

transport = SRTCTransport(token, SRTCParams(audio_in_enabled=True, audio_out_enabled=True))
pipeline = Pipeline([transport.input(), stt, llm, tts, transport.output()])
```

**Errors** — failures raise `srtc.SdkError` with `code` and `msg`: `180xxx` are SDK errors, codes ≥ 1000 come from the server (e.g. `1033` concurrency limit reached).

**Deployment notes** — don't `fork` a process that has already created a `Channel` (use `spawn` with multiprocessing; importing before fork is fine). A single process handles about 20 concurrent channels at ~61% of one core; scale out with more processes.

See the [documentation](https://docs.stmlink.com/zh/rtc/python/integration) for the full API, the voice-agent guide and the pipecat guide.

## License

Proprietary. Copyright © Seastart. Use requires an SRTC service license; copying, modification or redistribution without permission is prohibited. A free edition with limited concurrency is available; higher concurrency and private deployments require a commercial license — see [stmlink.com](https://www.stmlink.com).

---

# SRTC Python SDK（中文）

[English](#srtc-python-sdk) | **中文**

[SRTC](https://www.stmlink.com) 是一款支持完全私有化部署的实时音视频通信引擎，覆盖全平台 SDK，支持信创国产化，兼容传统 SIP/H.323 设备，集成 AI Agent 能力。

本 SDK 面向**服务端 AI 场景**：语音 agent（ASR → LLM → TTS）、录音、转写、质检。完整文档见 [SRTC 文档中心](https://docs.stmlink.com/zh/rtc/python/integration)。

- **收发都是 PCM**：远端音频按你指定的采样率解码后交给你；TTS 输出的 PCM 直接写进去，编解码、重采样都在 SDK 内完成。
- **SDK 控发送节奏**：TTS 生成再快，也按实时节奏每 20ms 发一帧；用户插话时 `clear()` 立即停止播报。
- **时间轴连续**：对端 DTX 静音不发包时，SDK 按 RTP 时间戳补回静音帧，VAD 断句和录音时长都不会错位。
- **asyncio 原生**：`async with` 自动离开、`async for` 逐帧消费，事件回调可以是普通函数也可以是 async 函数。
- **原生内核**：信令、断线重连、音视频收发由内置原生库完成，与 SRTC 其它端行为一致，不占 Python GIL。
- **接入 pipecat**：内置 pipecat transport，直接接进现有的语音 agent 管线。

## 安装

```sh
pip install srtc                # 核心
pip install "srtc[pipecat]"     # 同时安装 pipecat 集成
```

Python 3.10+。平台：Linux x86_64 / aarch64、macOS Apple Silicon、Windows x64。依赖：`cffi`、`av`（自带 ffmpeg 与 libopus，无需系统安装 ffmpeg）、`numpy`。

> **glibc 低于 2.28 的 Linux（如 CentOS 7）**：`av` 的新版本只提供 glibc 2.28+ 的安装包，请固定版本安装：`pip install srtc "av>=12,<14"`。

## 快速开始

```python
import asyncio
import srtc

async def main(token: str):   # token 由你的业务服务端通过 SRTC 服务端 API 签发
    async with await srtc.Channel.join(
        token,
        auto_subscribe_audio=True,                  # 自动订阅所有人（含之后加入者）的音频
        audio_format=srtc.AudioFormat(16000, 1),    # 收到的 PCM 格式，默认 16k 单声道
    ) as ch:
        tts = await ch.publish_audio(desc="tts", audio_format=srtc.AudioFormat(24000, 1))

        async for frame in ch.audio_frames():       # 用 frame.uid 区分说话人
            text = asr.feed(frame.uid, frame.to_numpy())
            if text:
                await tts.write(await tts_engine.synthesize(await llm.chat(text)))

asyncio.run(main(token))
```

每次 `Channel.join` 都要用新签发的 Token，一个 Token 只绑定一次会话。

**发送音频**

```python
await tts.write(pcm)            # 任意长度，按实时节奏发送；缓冲满时 write 会等待（背压）
tts.clear()                     # 用户插话：丢弃所有未发出的音频
await tts.wait_for_playout()    # 等待已写入的全部发完
tts.buffered_seconds            # 大于 0 表示 agent 还在"说话"
```

**事件回调**：继承 `srtc.ChannelHandler`，覆写需要的方法（`on_user_join`、`on_user_leave`、`on_track_added`、`on_audio_frame`、`on_active_speakers`、`on_custom_msg`、`on_disconnected` 等），在 `Channel.join` 时通过 `handler=` 传入。

**pipecat**

```python
from srtc.pipecat_transport import SRTCParams, SRTCTransport

transport = SRTCTransport(token, SRTCParams(audio_in_enabled=True, audio_out_enabled=True))
pipeline = Pipeline([transport.input(), stt, llm, tts, transport.output()])
```

**错误**：失败时抛 `srtc.SdkError`，带 `code` 与 `msg`。`180xxx` 为 SDK 自身错误，≥1000 为服务端错误码（如 `1033` 并发已达上限）。

**部署注意**：已创建过 `Channel` 的进程不要再 fork（multiprocessing 请用 `spawn`；fork 前只 import 没问题）。单进程约 20 个频道同时在线时占约 61% 单核 CPU，会话更多请多进程横向扩展。

完整接口、语音 agent 实践与 pipecat 接入见 [文档中心](https://docs.stmlink.com/zh/rtc/python/integration)。

## 许可证

专有软件，版权归 Seastart 所有。使用需获得 SRTC 服务授权，未经许可不得复制、修改或再分发。SRTC 提供免费版（并发量受限），超出限额的并发与私有化部署需购买商业授权，详见 [官网](https://www.stmlink.com)。
