# Plaud Live Agent SDK
Plaud实时AI助手客户端SDK，基于LiveKit WebRTC技术构建，提供高性能的实时音频通信和AI助手交互功能。
## 特性
- 🎤 **实时音频通信**: 基于WebRTC的低延迟音频传输
- 🤖 **AI助手集成**: 支持与各种AI助手服务集成
- 🔧 **易于使用**: 简洁的API设计，快速上手
- 📱 **跨平台**: 支持Windows、macOS、Linux
- 🚀 **高性能**: 优化的音频处理管道
## 包结构
```
pkg/
├── live_agent_sdk/ # 核心SDK包
│ ├── __init__.py # 包初始化文件
│ ├── agent_client.py # 主要客户端类
│ ├── agent_config.py # 配置类
│ ├── audio_pcm_data.py # 音频数据类
├── examples/ # 使用示例
│ └── basic_usage.py
├── setup.py # 安装配置
├── pyproject.toml # 现代Python包配置
├── README.md # 详细文档
├── requirements.txt # 依赖列表
├── MANIFEST.in # 包文件清单
├── build_and_install.sh # 构建脚本
```
## 安装
### 从PyPI安装（推荐）
```bash
pip install plaud-live-agent-sdk
```
### 开发环境安装
```bash
pip install plaud-live-agent-sdk[dev,audio]
```
## 快速开始
### 基本使用
```python
import asyncio
from live_agent_sdk import (
LiveAgentClient,
AgentConfig,
AudioPlayInConfig,
AudioPlayOutConfig,
AudioPCMData
)
async def main():
# 1. 创建客户端配置
config = AgentConfig(
agent_name="my-assistant",
audio_play_in_config=AudioPlayInConfig(sample_rate=48000, channels=1),
audio_play_out_config=AudioPlayOutConfig(sample_rate=48000, channels=1)
)
# 2. 创建客户端
client = LiveAgentClient(config=config)
# 3. 注册音频输出回调
def handle_audio_output(audio_data):
# 处理接收到的音频数据
print(f"收到音频: {len(audio_data.data)} 字节")
client.register_play_out_audio_stream(callback=handle_audio_output)
# 4. 连接到房间
await client.connect(participant_id="user-123", room_id="room-456")
# 5. 发送音频数据
audio_data = AudioPCMData(data=your_audio_data)
await client.push_audio_frame(audio_data)
# 6. 保持连接
await asyncio.sleep(10)
# 7. 断开连接
await client.disconnect()
if __name__ == "__main__":
asyncio.run(main())
```
### 完整示例
参考 `examples/basic_usage.py` 查看基本使用示例。
## API 参考
### LiveAgentClient
主要的客户端类，处理与LiveKit服务器的连接和音频流。
#### 构造函数
```python
LiveAgentClient(config: AgentConfig)
```
#### 方法
- `register_play_out_audio_stream(callback)`: 注册音频输出处理回调
- `connect(participant_id, room_id)`: 连接到LiveKit房间
- `disconnect()`: 断开连接
- `push_audio_frame(audio_data)`: 发送音频帧
#### 属性
- `is_connected`: 连接状态
- `agent_name`: 代理名称
### AgentConfig
客户端配置类。
```python
AgentConfig(
agent_name: str,
audio_play_in_config: AudioPlayInConfig = AudioPlayInConfig(sample_rate=16000, channels=1),
audio_play_out_config: AudioPlayOutConfig = AudioPlayOutConfig(sample_rate=16000, channels=1)
)
```
### AudioPlayInConfig / AudioPlayOutConfig
音频配置类。
```python
AudioPlayInConfig(sample_rate: int, channels: int)
AudioPlayOutConfig(sample_rate: int, channels: int)
```
### AudioPCMData
音频数据包装类。
```python
AudioPCMData(data: numpy.ndarray)
```
## 配置说明
### LiveKit服务器配置
SDK默认使用演示服务器配置，生产环境请使用自己的LiveKit服务器：
```python
# 默认配置
url = "wss://live-agent-demo-zeah44xr.livekit.cloud"
api_key = "API64Nz8xJApJHa"
api_secret = "QfbOfwD6TuD12MWTQU0bTAWTOfJu3y2C3JJA9etwwN5B"
```
### 音频格式
SDK使用PCM音频格式，支持以下参数：
- **采样率**: 16000Hz, 48000Hz (推荐)
- **声道数**: 1 (单声道), 2 (立体声)
- **数据类型**: int16
## 错误处理
SDK包含完善的错误处理机制：
```python
try:
await client.connect(participant_id="user", room_id="room")
except Exception as e:
print(f"连接失败: {e}")
```
## 开发
### 本地开发安装
```bash
git clone https://github.com/plaud-ai/live-agent-sdk.git
cd live-agent-sdk
pip install -e .
```
### 安装开发版本
```bash
pip install -e .[dev]
```
### 运行测试
```bash
# 安装测试依赖
pip install -e .[dev]
# 运行测试
pytest tests/
```
### 构建包
```bash
# 使用构建脚本
./build_and_install.sh
# 或手动构建
python3 setup.py sdist bdist_wheel
```
## 故障排除
### 常见问题
1. **导入错误**: 确保已正确安装 SDK
2. **连接失败**: 检查网络连接和服务器配置
3. **音频问题**: 检查音频格式和采样率设置
### 调试
启用详细日志：
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
## 许可证
MIT License
## 支持
- 文档: README.md
- 问题反馈: [GitHub Issues](https://github.com/plaud-ai/live-agent-sdk/issues)
- 邮箱: dev-support@plaud.ai
Raw data
{
"_id": null,
"home_page": "https://github.com/plaud-ai/plaud-live-agent-dev",
"name": "plaud-live-agent-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Plaud AI <dev-support@plaud.ai>",
"keywords": "Plaud, livekit, webrtc, audio, real-time, ai, assistant",
"author": "Plaud AI",
"author_email": "Plaud AI <dev-support@plaud.ai>",
"download_url": "https://files.pythonhosted.org/packages/a5/7a/cd0e4711e9a23f76fb0575d2c93328860e7acf75b8a3081b0ef5f42efa51/plaud_live_agent_sdk-1.0.1.tar.gz",
"platform": null,
"description": "# Plaud Live Agent SDK\n\nPlaud\u5b9e\u65f6AI\u52a9\u624b\u5ba2\u6237\u7aefSDK\uff0c\u57fa\u4e8eLiveKit WebRTC\u6280\u672f\u6784\u5efa\uff0c\u63d0\u4f9b\u9ad8\u6027\u80fd\u7684\u5b9e\u65f6\u97f3\u9891\u901a\u4fe1\u548cAI\u52a9\u624b\u4ea4\u4e92\u529f\u80fd\u3002\n\n## \u7279\u6027\n\n- \ud83c\udfa4 **\u5b9e\u65f6\u97f3\u9891\u901a\u4fe1**: \u57fa\u4e8eWebRTC\u7684\u4f4e\u5ef6\u8fdf\u97f3\u9891\u4f20\u8f93\n- \ud83e\udd16 **AI\u52a9\u624b\u96c6\u6210**: \u652f\u6301\u4e0e\u5404\u79cdAI\u52a9\u624b\u670d\u52a1\u96c6\u6210\n- \ud83d\udd27 **\u6613\u4e8e\u4f7f\u7528**: \u7b80\u6d01\u7684API\u8bbe\u8ba1\uff0c\u5feb\u901f\u4e0a\u624b\n- \ud83d\udcf1 **\u8de8\u5e73\u53f0**: \u652f\u6301Windows\u3001macOS\u3001Linux\n- \ud83d\ude80 **\u9ad8\u6027\u80fd**: \u4f18\u5316\u7684\u97f3\u9891\u5904\u7406\u7ba1\u9053\n\n## \u5305\u7ed3\u6784\n\n```\npkg/\n\u251c\u2500\u2500 live_agent_sdk/ # \u6838\u5fc3SDK\u5305\n\u2502 \u251c\u2500\u2500 __init__.py # \u5305\u521d\u59cb\u5316\u6587\u4ef6\n\u2502 \u251c\u2500\u2500 agent_client.py # \u4e3b\u8981\u5ba2\u6237\u7aef\u7c7b\n\u2502 \u251c\u2500\u2500 agent_config.py # \u914d\u7f6e\u7c7b\n\u2502 \u251c\u2500\u2500 audio_pcm_data.py # \u97f3\u9891\u6570\u636e\u7c7b\n\u251c\u2500\u2500 examples/ # \u4f7f\u7528\u793a\u4f8b\n\u2502 \u2514\u2500\u2500 basic_usage.py\n\u251c\u2500\u2500 setup.py # \u5b89\u88c5\u914d\u7f6e\n\u251c\u2500\u2500 pyproject.toml # \u73b0\u4ee3Python\u5305\u914d\u7f6e\n\u251c\u2500\u2500 README.md # \u8be6\u7ec6\u6587\u6863\n\u251c\u2500\u2500 requirements.txt # \u4f9d\u8d56\u5217\u8868\n\u251c\u2500\u2500 MANIFEST.in # \u5305\u6587\u4ef6\u6e05\u5355\n\u251c\u2500\u2500 build_and_install.sh # \u6784\u5efa\u811a\u672c\n```\n\n## \u5b89\u88c5\n\n### \u4ecePyPI\u5b89\u88c5\uff08\u63a8\u8350\uff09\n\n```bash\npip install plaud-live-agent-sdk\n```\n\n### \u5f00\u53d1\u73af\u5883\u5b89\u88c5\n\n```bash\npip install plaud-live-agent-sdk[dev,audio]\n```\n\n## \u5feb\u901f\u5f00\u59cb\n\n### \u57fa\u672c\u4f7f\u7528\n\n```python\nimport asyncio\nfrom live_agent_sdk import (\n LiveAgentClient,\n AgentConfig,\n AudioPlayInConfig,\n AudioPlayOutConfig,\n AudioPCMData\n)\n\nasync def main():\n # 1. \u521b\u5efa\u5ba2\u6237\u7aef\u914d\u7f6e\n config = AgentConfig(\n agent_name=\"my-assistant\",\n audio_play_in_config=AudioPlayInConfig(sample_rate=48000, channels=1),\n audio_play_out_config=AudioPlayOutConfig(sample_rate=48000, channels=1)\n )\n \n # 2. \u521b\u5efa\u5ba2\u6237\u7aef\n client = LiveAgentClient(config=config)\n \n # 3. \u6ce8\u518c\u97f3\u9891\u8f93\u51fa\u56de\u8c03\n def handle_audio_output(audio_data):\n # \u5904\u7406\u63a5\u6536\u5230\u7684\u97f3\u9891\u6570\u636e\n print(f\"\u6536\u5230\u97f3\u9891: {len(audio_data.data)} \u5b57\u8282\")\n \n client.register_play_out_audio_stream(callback=handle_audio_output)\n \n # 4. \u8fde\u63a5\u5230\u623f\u95f4\n await client.connect(participant_id=\"user-123\", room_id=\"room-456\")\n \n # 5. \u53d1\u9001\u97f3\u9891\u6570\u636e\n audio_data = AudioPCMData(data=your_audio_data)\n await client.push_audio_frame(audio_data)\n \n # 6. \u4fdd\u6301\u8fde\u63a5\n await asyncio.sleep(10)\n \n # 7. \u65ad\u5f00\u8fde\u63a5\n await client.disconnect()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### \u5b8c\u6574\u793a\u4f8b\n\n\u53c2\u8003 `examples/basic_usage.py` \u67e5\u770b\u57fa\u672c\u4f7f\u7528\u793a\u4f8b\u3002\n\n## API \u53c2\u8003\n\n### LiveAgentClient\n\n\u4e3b\u8981\u7684\u5ba2\u6237\u7aef\u7c7b\uff0c\u5904\u7406\u4e0eLiveKit\u670d\u52a1\u5668\u7684\u8fde\u63a5\u548c\u97f3\u9891\u6d41\u3002\n\n#### \u6784\u9020\u51fd\u6570\n\n```python\nLiveAgentClient(config: AgentConfig)\n```\n\n#### \u65b9\u6cd5\n\n- `register_play_out_audio_stream(callback)`: \u6ce8\u518c\u97f3\u9891\u8f93\u51fa\u5904\u7406\u56de\u8c03\n- `connect(participant_id, room_id)`: \u8fde\u63a5\u5230LiveKit\u623f\u95f4\n- `disconnect()`: \u65ad\u5f00\u8fde\u63a5\n- `push_audio_frame(audio_data)`: \u53d1\u9001\u97f3\u9891\u5e27\n\n#### \u5c5e\u6027\n\n- `is_connected`: \u8fde\u63a5\u72b6\u6001\n- `agent_name`: \u4ee3\u7406\u540d\u79f0\n\n### AgentConfig\n\n\u5ba2\u6237\u7aef\u914d\u7f6e\u7c7b\u3002\n\n```python\nAgentConfig(\n agent_name: str,\n audio_play_in_config: AudioPlayInConfig = AudioPlayInConfig(sample_rate=16000, channels=1),\n audio_play_out_config: AudioPlayOutConfig = AudioPlayOutConfig(sample_rate=16000, channels=1)\n)\n```\n\n### AudioPlayInConfig / AudioPlayOutConfig\n\n\u97f3\u9891\u914d\u7f6e\u7c7b\u3002\n\n```python\nAudioPlayInConfig(sample_rate: int, channels: int)\nAudioPlayOutConfig(sample_rate: int, channels: int)\n```\n\n### AudioPCMData\n\n\u97f3\u9891\u6570\u636e\u5305\u88c5\u7c7b\u3002\n\n```python\nAudioPCMData(data: numpy.ndarray)\n```\n\n## \u914d\u7f6e\u8bf4\u660e\n\n### LiveKit\u670d\u52a1\u5668\u914d\u7f6e\n\nSDK\u9ed8\u8ba4\u4f7f\u7528\u6f14\u793a\u670d\u52a1\u5668\u914d\u7f6e\uff0c\u751f\u4ea7\u73af\u5883\u8bf7\u4f7f\u7528\u81ea\u5df1\u7684LiveKit\u670d\u52a1\u5668\uff1a\n\n```python\n# \u9ed8\u8ba4\u914d\u7f6e\nurl = \"wss://live-agent-demo-zeah44xr.livekit.cloud\"\napi_key = \"API64Nz8xJApJHa\"\napi_secret = \"QfbOfwD6TuD12MWTQU0bTAWTOfJu3y2C3JJA9etwwN5B\"\n```\n\n### \u97f3\u9891\u683c\u5f0f\n\nSDK\u4f7f\u7528PCM\u97f3\u9891\u683c\u5f0f\uff0c\u652f\u6301\u4ee5\u4e0b\u53c2\u6570\uff1a\n\n- **\u91c7\u6837\u7387**: 16000Hz, 48000Hz (\u63a8\u8350)\n- **\u58f0\u9053\u6570**: 1 (\u5355\u58f0\u9053), 2 (\u7acb\u4f53\u58f0)\n- **\u6570\u636e\u7c7b\u578b**: int16\n\n## \u9519\u8bef\u5904\u7406\n\nSDK\u5305\u542b\u5b8c\u5584\u7684\u9519\u8bef\u5904\u7406\u673a\u5236\uff1a\n\n```python\ntry:\n await client.connect(participant_id=\"user\", room_id=\"room\")\nexcept Exception as e:\n print(f\"\u8fde\u63a5\u5931\u8d25: {e}\")\n```\n\n## \u5f00\u53d1\n\n### \u672c\u5730\u5f00\u53d1\u5b89\u88c5\n\n```bash\ngit clone https://github.com/plaud-ai/live-agent-sdk.git\ncd live-agent-sdk\npip install -e .\n```\n\n### \u5b89\u88c5\u5f00\u53d1\u7248\u672c\n\n```bash\npip install -e .[dev]\n```\n\n### \u8fd0\u884c\u6d4b\u8bd5\n\n```bash\n# \u5b89\u88c5\u6d4b\u8bd5\u4f9d\u8d56\npip install -e .[dev]\n\n# \u8fd0\u884c\u6d4b\u8bd5\npytest tests/\n```\n\n### \u6784\u5efa\u5305\n\n```bash\n# \u4f7f\u7528\u6784\u5efa\u811a\u672c\n./build_and_install.sh\n\n# \u6216\u624b\u52a8\u6784\u5efa\npython3 setup.py sdist bdist_wheel\n```\n\n## \u6545\u969c\u6392\u9664\n\n### \u5e38\u89c1\u95ee\u9898\n\n1. **\u5bfc\u5165\u9519\u8bef**: \u786e\u4fdd\u5df2\u6b63\u786e\u5b89\u88c5 SDK\n2. **\u8fde\u63a5\u5931\u8d25**: \u68c0\u67e5\u7f51\u7edc\u8fde\u63a5\u548c\u670d\u52a1\u5668\u914d\u7f6e\n3. **\u97f3\u9891\u95ee\u9898**: \u68c0\u67e5\u97f3\u9891\u683c\u5f0f\u548c\u91c7\u6837\u7387\u8bbe\u7f6e\n\n### \u8c03\u8bd5\n\n\u542f\u7528\u8be6\u7ec6\u65e5\u5fd7\uff1a\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## \u8bb8\u53ef\u8bc1\n\nMIT License\n\n## \u652f\u6301\n\n- \u6587\u6863: README.md\n- \u95ee\u9898\u53cd\u9988: [GitHub Issues](https://github.com/plaud-ai/live-agent-sdk/issues)\n- \u90ae\u7bb1: dev-support@plaud.ai \n",
"bugtrack_url": null,
"license": null,
"summary": "Plaud Live Agent SDK - \u5b9e\u65f6AI\u52a9\u624b\u5ba2\u6237\u7aefSDK",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/Plaud-AI/plaud-live-agent-dev/issues",
"Documentation": "https://github.com/Plaud-AI/plaud-live-agent-dev/blob/main/README.md",
"Homepage": "https://github.com/Plaud-AI/plaud-live-agent-dev",
"Repository": "https://github.com/Plaud-AI/plaud-live-agent-dev"
},
"split_keywords": [
"plaud",
" livekit",
" webrtc",
" audio",
" real-time",
" ai",
" assistant"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d2423b5dd23c55663b28cdf745ef37960d1a6cbbdb3ecdd55e953c0356704d44",
"md5": "53eb0886e779bbacc0daf14be7a45e67",
"sha256": "50464e0d3bb180114e2545f28a351395f8f1c16f1c2d39dc5d8938e01fbb3d88"
},
"downloads": -1,
"filename": "plaud_live_agent_sdk-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53eb0886e779bbacc0daf14be7a45e67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8042,
"upload_time": "2025-08-15T09:12:17",
"upload_time_iso_8601": "2025-08-15T09:12:17.316907Z",
"url": "https://files.pythonhosted.org/packages/d2/42/3b5dd23c55663b28cdf745ef37960d1a6cbbdb3ecdd55e953c0356704d44/plaud_live_agent_sdk-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a57acd0e4711e9a23f76fb0575d2c93328860e7acf75b8a3081b0ef5f42efa51",
"md5": "90d50bf6c3a171f5725f14f0bcaa07bd",
"sha256": "0530f4dc0c80e750f9fcee333da161605d026adf111efbc2834b1f0b0116ede9"
},
"downloads": -1,
"filename": "plaud_live_agent_sdk-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "90d50bf6c3a171f5725f14f0bcaa07bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11248,
"upload_time": "2025-08-15T09:12:18",
"upload_time_iso_8601": "2025-08-15T09:12:18.497796Z",
"url": "https://files.pythonhosted.org/packages/a5/7a/cd0e4711e9a23f76fb0575d2c93328860e7acf75b8a3081b0ef5f42efa51/plaud_live_agent_sdk-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 09:12:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plaud-ai",
"github_project": "plaud-live-agent-dev",
"github_not_found": true,
"lcname": "plaud-live-agent-sdk"
}
JSON
