xiaozhi-sdk 0.0.2__tar.gz

xiaozhi_sdk-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dairoot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xiaozhi_sdk-0.0.2/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+recursive-include file *
+recursive-exclude file *.pyc
+recursive-exclude file __pycache__

xiaozhi_sdk-0.0.2/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: xiaozhi-sdk
+Version: 0.0.2
+Summary: 一个用于连接和控制小智智能设备的Python SDK，支持实时音频通信、MCP工具集成和设备管理功能。
+Home-page: https://github.com/dairoot/xiaozhi-sdk
+Author: dairoot
+Author-email: 623815825@qq.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: websockets
+Requires-Dist: aiohttp
+Requires-Dist: av
+Requires-Dist: opuslib
+Requires-Dist: requests
+Requires-Dist: sounddevice
+Requires-Dist: python-socks
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 小智SDK (XiaoZhi SDK)
+
+[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/badge/pypi-xiaozhi--sdk-blue.svg)](https://pypi.org/project/xiaozhi-sdk/)
+
+基于虾哥的 [小智esp32 websocket 通讯协议](https://github.com/78/xiaozhi-esp32/blob/main/docs/websocket.md) 实现的 Python SDK。
+
+一个用于连接和控制小智设备的 Python SDK。支持以下功能：
+- 实时音频通信
+- MCP 工具集成
+- 设备管理与控制
+
+---
+
+## 📦 安装
+
+```bash
+pip install xiaozhi-sdk
+```
+
+---
+
+## 🚀 快速开始
+
+### 1. 终端使用
+
+最简单的方式是通过终端直接连接设备：
+
+#### 查看帮助信息
+
+```bash
+python -m xiaozhi_sdk -h
+```
+
+输出示例：
+```text
+positional arguments:
+  device             你的小智设备的MAC地址 (格式: XX:XX:XX:XX:XX:XX)
+
+options:
+  -h, --help         显示帮助信息并退出
+  --url URL          小智服务 websocket 地址
+  --ota_url OTA_URL  小智 OTA 地址
+```
+
+#### 连接设备（需要提供 MAC 地址）
+
+```bash
+python -m xiaozhi_sdk 00:22:44:66:88:00
+```
+
+### 2. 编程使用
+参考 [examples](examples/) 文件中的示例代码，可以快速开始使用 SDK。
+
+
+### 运行测试
+
+```bash
+pytest tests/
+```
+
+
+---
+
+## 🫡 致敬
+
+- 🫡 虾哥的 [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) 项目

xiaozhi_sdk-0.0.2/README.md

@@ -0,0 +1,68 @@
+# 小智SDK (XiaoZhi SDK)
+
+[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/badge/pypi-xiaozhi--sdk-blue.svg)](https://pypi.org/project/xiaozhi-sdk/)
+
+基于虾哥的 [小智esp32 websocket 通讯协议](https://github.com/78/xiaozhi-esp32/blob/main/docs/websocket.md) 实现的 Python SDK。
+
+一个用于连接和控制小智设备的 Python SDK。支持以下功能：
+- 实时音频通信
+- MCP 工具集成
+- 设备管理与控制
+
+---
+
+## 📦 安装
+
+```bash
+pip install xiaozhi-sdk
+```
+
+---
+
+## 🚀 快速开始
+
+### 1. 终端使用
+
+最简单的方式是通过终端直接连接设备：
+
+#### 查看帮助信息
+
+```bash
+python -m xiaozhi_sdk -h
+```
+
+输出示例：
+```text
+positional arguments:
+  device             你的小智设备的MAC地址 (格式: XX:XX:XX:XX:XX:XX)
+
+options:
+  -h, --help         显示帮助信息并退出
+  --url URL          小智服务 websocket 地址
+  --ota_url OTA_URL  小智 OTA 地址
+```
+
+#### 连接设备（需要提供 MAC 地址）
+
+```bash
+python -m xiaozhi_sdk 00:22:44:66:88:00
+```
+
+### 2. 编程使用
+参考 [examples](examples/) 文件中的示例代码，可以快速开始使用 SDK。
+
+
+### 运行测试
+
+```bash
+pytest tests/
+```
+
+
+---
+
+## 🫡 致敬
+
+- 🫡 虾哥的 [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) 项目

xiaozhi_sdk-0.0.2/setup.cfg

@@ -0,0 +1,17 @@
+[flake8]
+ignore = E203, E266, E501, W503, F403, F401, E731, E711, C901, F841, D103, B008, D400, E402, E712
+max-line-length = 120
+max-complexity = 20
+exclude = 
+	tests/*
+
+[coverage:run]
+omit = 
+	xiaozhi_sdk/__main__.py
+	tests/*
+	setup.py
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

xiaozhi_sdk-0.0.2/setup.py

@@ -0,0 +1,49 @@
+import os
+
+from setuptools import find_packages, setup
+
+
+# 收集指定目录下的所有文件
+def get_data_files(*directories):
+    data_files = []
+    for directory in directories:
+        if os.path.exists(directory):
+            for root, _, files in os.walk(directory):
+                for file in files:
+                    # 将相对于项目根目录的路径转换为相对于包的路径
+                    rel_path = os.path.relpath(os.path.join(root, file), ".")
+                    data_files.append(rel_path)
+    return data_files
+
+
+setup(
+    name="xiaozhi-sdk",  # 包名
+    version="0.0.2",  # 版本号
+    packages=find_packages(),  # 自动发现包
+    package_data={
+        "xiaozhi_sdk": ["../" + f for f in get_data_files("file")],  # 包含file目录下的所有文件
+    },
+    include_package_data=True,  # 使用MANIFEST.in文件包含额外文件
+    install_requires=[  # 依赖
+        "numpy",
+        "websockets",
+        "aiohttp",
+        "av",
+        "opuslib",
+        "requests",
+        "sounddevice",
+        "python-socks",
+    ],
+    author="dairoot",
+    author_email="623815825@qq.com",  # 作者邮箱
+    description="一个用于连接和控制小智智能设备的Python SDK，支持实时音频通信、MCP工具集成和设备管理功能。",  # 简短描述
+    long_description=open("README.md").read(),  # 详细描述（通常从 README 读取）
+    long_description_content_type="text/markdown",  # README 文件格式
+    url="https://github.com/dairoot/xiaozhi-sdk",  # 项目主页
+    classifiers=[  # 分类元数据
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.8",  # 支持的 Python 版本
+)

xiaozhi_sdk-0.0.2/tests/test_iot.py

@@ -0,0 +1,19 @@
+import os
+import sys
+import uuid
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from xiaozhi_sdk.iot import OtaDevice
+
+
+@pytest.mark.asyncio
+async def test_main():
+    serial_number = ""
+    license_key = ""
+    mac_address = "00:22:44:66:88:00"
+    ota = OtaDevice(mac_addr=mac_address, client_id=str(uuid.uuid4()), serial_number=serial_number)
+    res = await ota.activate_device()
+    await ota.check_activate(res["activation"]["challenge"], license_key)

xiaozhi_sdk-0.0.2/tests/test_opus.py

@@ -0,0 +1,9 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from xiaozhi_sdk.utils import setup_opus
+
+setup_opus()
+import opuslib

xiaozhi_sdk-0.0.2/tests/test_pic.py

@@ -0,0 +1,47 @@
+import asyncio
+
+import aiohttp
+
+
+async def explain_image():
+    url = "http://api.xiaozhi.me/vision/explain"
+    question = "这个图片里有什么？"
+    image_path = "./file/image/leijun.jpg"
+
+    boundary = "----ESP32_CAMERA_BOUNDARY"
+    headers = {
+        "Content-Type": f"multipart/form-data; boundary={boundary}",
+        # 不设置Transfer-Encoding，aiohttp自动处理
+    }
+
+    with open(image_path, "rb") as f:
+        img_data = f.read()
+
+    # 手动构造multipart body
+    body = bytearray()
+
+    # question字段
+    body.extend(f"--{boundary}\r\n".encode())
+    body.extend(b'Content-Disposition: form-data; name="question"\r\n\r\n')
+    body.extend(question.encode("utf-8"))
+    body.extend(b"\r\n")
+
+    # 文件字段头
+    body.extend(f"--{boundary}\r\n".encode())
+    body.extend(b'Content-Disposition: form-data; name="file"; filename="camera.jpg"\r\n')
+    body.extend(b"Content-Type: image/jpeg\r\n\r\n")
+    body.extend(img_data)
+    body.extend(b"\r\n")
+
+    # multipart结束
+    body.extend(f"--{boundary}--\r\n".encode())
+
+    async with aiohttp.ClientSession() as session:
+        async with session.post(url, data=body, headers=headers) as resp:
+            print(f"Status: {resp.status}")
+            text = await resp.text()
+            print("Response:", text)
+
+
+if __name__ == "__main__":
+    asyncio.run(explain_image())

xiaozhi_sdk-0.0.2/tests/test_xiaozhi.py

@@ -0,0 +1,87 @@
+import asyncio
+import os
+import sys
+import time
+
+import numpy as np
+import pytest
+import sounddevice as sd
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from xiaozhi_sdk import XiaoZhiWebsocket
+from xiaozhi_sdk.utils import read_audio_file
+
+
+async def assistant_audio_play(audio_queue, wait_time=1):
+    # 创建一个持续播放的流
+    stream = sd.OutputStream(samplerate=16000, channels=1, dtype=np.int16)
+    stream.start()
+    last_time = None
+    while True:
+        if not audio_queue:
+            await asyncio.sleep(0.01)
+            if last_time and time.time() - last_time > wait_time:
+                break
+
+            continue
+
+        pcm_data = audio_queue.popleft()
+        stream.write(pcm_data)
+        last_time = time.time()
+
+    stream.stop()
+    stream.close()
+
+
+def mcp_tool_func():
+    def mcp_take_photo(data) -> tuple[bytes, bool]:
+        with open("./file/image/leijun.jpg", "rb") as f:
+            return f.read(), False
+
+    def mcp_get_device_status(data) -> tuple[dict, bool]:
+        data = {
+            "audio_speaker": {"volume": 80},
+            "screen": {"brightness": 75, "theme": "light"},
+            "network": {"type": "wifi", "ssid": "wifi名称", "signal": "strong"},
+        }
+        return data, False
+
+    def mcp_set_volume(data) -> tuple[dict, bool]:
+        return {}, False
+
+    return {
+        "set_volume": mcp_set_volume,
+        "get_device_status": mcp_get_device_status,
+        "take_photo": mcp_take_photo,
+    }
+
+
+async def message_handler_callback(message):
+    print("message received:", message)
+    pass
+
+
+MAC_ADDR = "00:22:44:66:88:00"
+URL = None
+
+
+@pytest.mark.asyncio
+async def test_main():
+    xiaozhi = XiaoZhiWebsocket(message_handler_callback, url=URL)
+    await xiaozhi.set_mcp_tool_callback(mcp_tool_func())
+    await xiaozhi.init_connection(MAC_ADDR)
+
+    # say hellow
+    for pcm in read_audio_file("./file/audio/say_hello.wav"):
+        await xiaozhi.send_audio(pcm)
+    await xiaozhi.send_silence_audio()
+    await assistant_audio_play(xiaozhi.output_audio_queue)
+
+    # say take photo
+    for pcm in read_audio_file("./file/audio/take_photo.wav"):
+        await xiaozhi.send_audio(pcm)
+    await xiaozhi.send_silence_audio()
+    await assistant_audio_play(xiaozhi.output_audio_queue, 5)
+
+    await xiaozhi.close()

xiaozhi_sdk-0.0.2/xiaozhi_sdk/__init__.py

@@ -0,0 +1,200 @@
+import asyncio
+import json
+import os
+import re
+import uuid
+from collections import deque
+from typing import Any, Callable, Dict, Optional
+
+import websockets
+
+from xiaozhi_sdk.config import INPUT_SERVER_AUDIO_SAMPLE_RATE
+from xiaozhi_sdk.iot import OtaDevice
+from xiaozhi_sdk.mcp import McpTool
+from xiaozhi_sdk.utils import get_wav_info, read_audio_file, setup_opus
+
+setup_opus()
+from xiaozhi_sdk.opus import AudioOpus
+
+
+class XiaoZhiWebsocket(McpTool):
+
+    def __init__(
+        self,
+        message_handler_callback: Optional[Callable] = None,
+        url: Optional[str] = None,
+        ota_url: Optional[str] = None,
+        audio_sample_rate: int = 16000,
+        audio_channels: int = 1,
+    ):
+        super().__init__()
+        self.url = url
+        self.ota_url = ota_url
+        self.audio_channels = audio_channels
+        self.audio_opus = AudioOpus(audio_sample_rate, audio_channels)
+
+        # 客户端标识
+        self.client_id = str(uuid.uuid4())
+        self.mac_addr: Optional[str] = None
+
+        # 回调函数
+        self.message_handler_callback = message_handler_callback
+
+        # 连接状态
+        self.hello_received = asyncio.Event()
+        self.session_id = ""
+        self.websocket = None
+        self.message_handler_task: Optional[asyncio.Task] = None
+
+        # 输出音频
+        self.output_audio_queue: deque[bytes] = deque()
+
+        # OTA设备
+        self.ota: Optional[OtaDevice] = None
+
+    async def _send_hello(self, aec: bool) -> None:
+        """发送hello消息"""
+        hello_message = {
+            "type": "hello",
+            "version": 1,
+            "features": {"aec": aec, "mcp": True},
+            "transport": "websocket",
+            "audio_params": {
+                "format": "opus",
+                "sample_rate": INPUT_SERVER_AUDIO_SAMPLE_RATE,
+                "channels": 1,
+                "frame_duration": 60,
+            },
+        }
+        await self.websocket.send(json.dumps(hello_message))
+        await asyncio.wait_for(self.hello_received.wait(), timeout=10.0)
+
+    async def _start_listen(self) -> None:
+        """开始监听"""
+
+        listen_message = {"session_id": self.session_id, "type": "listen", "state": "start", "mode": "realtime"}
+        await self.websocket.send(json.dumps(listen_message))
+
+    async def _activate_iot_device(self, ota_info: Dict[str, Any]) -> None:
+        """激活IoT设备"""
+        if not ota_info.get("activation"):
+            return
+
+        if not self.ota:
+            return
+
+        await self._send_demo_audio()
+        challenge = ota_info["activation"]["challenge"]
+        await asyncio.sleep(3)
+
+        for _ in range(10):
+            if await self.ota.check_activate(challenge):
+                break
+            await asyncio.sleep(3)
+
+    async def _send_demo_audio(self) -> None:
+        """发送演示音频"""
+        current_dir = os.path.dirname(os.path.abspath(__file__))
+        wav_path = os.path.join(current_dir, "../file/audio/greet.wav")
+        framerate, channels = get_wav_info(wav_path)
+        audio_opus = AudioOpus(framerate, channels)
+
+        for pcm_data in read_audio_file(wav_path):
+            opus_data = await audio_opus.pcm_to_opus(pcm_data)
+            await self.websocket.send(opus_data)
+        await self.send_silence_audio()
+
+    async def send_silence_audio(self, duration_seconds: float = 1.2) -> None:
+        """发送静音音频"""
+        frames_count = int(duration_seconds * 1000 / 60)
+        pcm_frame = b"\x00\x00" * int(INPUT_SERVER_AUDIO_SAMPLE_RATE / 1000 * 60)
+
+        for _ in range(frames_count):
+            await self.send_audio(pcm_frame)
+
+    async def _handle_websocket_message(self, message: Any) -> None:
+        """处理接受到的WebSocket消息"""
+        if isinstance(message, bytes):
+            pcm_array = await self.audio_opus.opus_to_pcm(message)
+            self.output_audio_queue.extend(pcm_array)
+        else:
+            data = json.loads(message)
+            message_type = data["type"]
+
+            if message_type == "hello":
+                self.hello_received.set()
+                self.session_id = data["session_id"]
+            elif message_type == "mcp":
+                await self.mcp(data)
+            elif self.message_handler_callback:
+                await self.message_handler_callback(data)
+
+    async def _message_handler(self) -> None:
+        """消息处理器"""
+        try:
+            async for message in self.websocket:
+                await self._handle_websocket_message(message)
+        except websockets.ConnectionClosed:
+            if self.message_handler_callback:
+                await self.message_handler_callback(
+                    {"type": "websocket", "state": "close", "source": "sdk.message_handler"}
+                )
+
+    async def set_mcp_tool_callback(self, tool_func: Dict[str, Callable[..., Any]]) -> None:
+        """设置MCP工具回调函数"""
+        self.tool_func = tool_func
+
+    async def init_connection(self, mac_addr: str, aec: bool = False) -> None:
+        """初始化连接"""
+        # 校验MAC地址格式 XX:XX:XX:XX:XX:XX
+        mac_pattern = r"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$"
+        if not re.match(mac_pattern, mac_addr):
+            raise ValueError(f"无效的MAC地址格式: {mac_addr}。正确格式应为 XX:XX:XX:XX:XX:XX")
+
+        self.mac_addr = mac_addr.lower()
+        self.ota = OtaDevice(self.mac_addr, self.client_id, self.ota_url)
+        ota_info = await self.ota.activate_device()
+
+        headers = {
+            "Authorization": "Bearer {}".format(ota_info["websocket"]["token"]),
+            "Protocol-Version": "1",
+            "Device-Id": self.mac_addr,
+            "Client-Id": self.client_id,
+        }
+        self.url = self.url or ota_info["websocket"]["url"]
+        self.websocket = await websockets.connect(uri=self.url, additional_headers=headers)
+        self.message_handler_task = asyncio.create_task(self._message_handler())
+
+        await self._send_hello(aec)
+        await self._start_listen()
+        asyncio.create_task(self._activate_iot_device(ota_info))
+        await asyncio.sleep(0.5)
+
+    async def send_audio(self, pcm: bytes) -> None:
+        """发送音频数据"""
+        if not self.websocket:
+            return
+
+        state = self.websocket.state
+        if state == websockets.protocol.State.OPEN:
+            opus_data = await self.audio_opus.pcm_to_opus(pcm)
+            await self.websocket.send(opus_data)
+        elif state in [websockets.protocol.State.CLOSED, websockets.protocol.State.CLOSING]:
+            if self.message_handler_callback:
+                await self.message_handler_callback({"type": "websocket", "state": "close", "source": "sdk.send_audio"})
+                self.websocket = None
+            await asyncio.sleep(0.5)
+        else:
+            await asyncio.sleep(0.1)
+
+    async def close(self) -> None:
+        """关闭连接"""
+        if self.message_handler_task and not self.message_handler_task.done():
+            self.message_handler_task.cancel()
+            try:
+                await self.message_handler_task
+            except asyncio.CancelledError:
+                pass
+
+        if self.websocket:
+            await self.websocket.close()

xiaozhi_sdk-0.0.2/xiaozhi_sdk/__main__.py

@@ -0,0 +1,101 @@
+import argparse
+import asyncio
+import logging
+import time
+from collections import deque
+from typing import Optional
+
+import numpy as np
+import sounddevice as sd
+
+from xiaozhi_sdk import XiaoZhiWebsocket
+from xiaozhi_sdk.config import INPUT_SERVER_AUDIO_SAMPLE_RATE
+
+# 配置logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+)
+logger = logging.getLogger("xiaozhi_sdk")
+
+# 全局状态
+input_audio_buffer: deque[bytes] = deque()
+is_playing_audio = False
+
+
+async def handle_message(message):
+    """处理接收到的消息"""
+    logger.info("message received: %s", message)
+
+
+async def play_assistant_audio(audio_queue: deque[bytes]):
+    """播放音频流"""
+    global is_playing_audio
+
+    stream = sd.OutputStream(samplerate=INPUT_SERVER_AUDIO_SAMPLE_RATE, channels=1, dtype=np.int16)
+    stream.start()
+    last_audio_time = None
+
+    while True:
+        if not audio_queue:
+            await asyncio.sleep(0.01)
+            if last_audio_time and time.time() - last_audio_time > 1:
+                is_playing_audio = False
+            continue
+
+        is_playing_audio = True
+        pcm_data = audio_queue.popleft()
+        stream.write(pcm_data)
+        last_audio_time = time.time()
+
+
+class XiaoZhiClient:
+    """小智客户端类"""
+
+    def __init__(self, mac_address: str, url: Optional[str] = None, ota_url: Optional[str] = None):
+        self.mac_address = mac_address
+        self.xiaozhi: Optional[XiaoZhiWebsocket] = None
+        self.url = url
+        self.ota_url = ota_url
+
+    async def start(self):
+        """启动客户端连接"""
+        self.xiaozhi = XiaoZhiWebsocket(handle_message, url=self.url, ota_url=self.ota_url)
+        await self.xiaozhi.init_connection(self.mac_address, aec=False)
+        asyncio.create_task(play_assistant_audio(self.xiaozhi.output_audio_queue))
+
+    def audio_callback(self, indata, frames, time, status):
+        """音频输入回调函数"""
+        pcm_data = (indata.flatten() * 32767).astype(np.int16).tobytes()
+        input_audio_buffer.append(pcm_data)
+
+    async def process_audio_input(self):
+        """处理音频输入"""
+        while True:
+            if not input_audio_buffer:
+                await asyncio.sleep(0.02)
+                continue
+
+            pcm_data = input_audio_buffer.popleft()
+            if not is_playing_audio:
+                await self.xiaozhi.send_audio(pcm_data)
+
+
+async def main():
+    """主函数"""
+    parser = argparse.ArgumentParser(description="小智SDK客户端")
+    parser.add_argument("device", help="小智设备的MAC地址 (格式: XX:XX:XX:XX:XX:XX)")
+    parser.add_argument("--url", help="小智服务websocket地址")
+    parser.add_argument("--ota_url", help="小智OTA地址")
+
+    args = parser.parse_args()
+    logger.info("Recording... Press Ctrl+C to stop.")
+
+    client = XiaoZhiClient(args.device, args.url, args.ota_url)
+    await client.start()
+
+    with sd.InputStream(callback=client.audio_callback, channels=1, samplerate=16000, blocksize=960):
+        await client.process_audio_input()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

xiaozhi_sdk-0.0.2/xiaozhi_sdk/config.py

@@ -0,0 +1,3 @@
+INPUT_SERVER_AUDIO_SAMPLE_RATE = 16000
+
+OTA_URL = "https://api.tenclass.net/xiaozhi/ota/"

xiaozhi_sdk-0.0.2/xiaozhi_sdk/data.py

@@ -0,0 +1,60 @@
+from typing import Any, Dict, List
+
+mcp_initialize_payload: Dict[str, Any] = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "result": {
+        "protocolVersion": "2024-11-05",
+        "capabilities": {"tools": {}},
+        "serverInfo": {"name": "", "version": "0.0.1"},
+    },
+}
+
+mcp_tool_conf: Dict[str, Dict[str, Any]] = {
+    "get_device_status": {
+        "description": "Provides the real-time information of the device, including the current status of the audio speaker, screen, battery, network, etc.\nUse this tool for: \n1. Answering questions about current condition (e.g. what is the current volume of the audio speaker?)\n2. As the first step to control the device (e.g. turn up / down the volume of the audio speaker, etc.)",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    "set_volume": {
+        "description": "Set the volume of the audio speaker. If the current volume is unknown, you must call `self.get_device_status` tool first and then call this tool.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"volume": {"type": "integer", "minimum": 0, "maximum": 100}},
+            "required": ["volume"],
+        },
+    },
+    "set_brightness": {
+        "description": "Set the brightness of the screen.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"brightness": {"type": "integer", "minimum": 0, "maximum": 100}},
+            "required": ["brightness"],
+        },
+    },
+    "set_theme": {
+        "description": "Set the theme of the screen. The theme can be `light` or `dark`.",
+        "inputSchema": {"type": "object", "properties": {"theme": {"type": "string"}}, "required": ["theme"]},
+    },
+    "take_photo": {
+        "description": "Take a photo and explain it. Use this tool after the user asks you to see something.\nArgs:\n  `question`: The question that you want to ask about the photo.\nReturn:\n  A JSON object that provides the photo information.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"question": {"type": "string"}},
+            "required": ["question"],
+        },
+    },
+    "open_tab": {
+        "description": "Open a web page in the browser. 小智后台：https://xiaozhi.me",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"url": {"type": "string"}},
+            "required": ["url"],
+        },
+    },
+}
+
+mcp_tools_payload: Dict[str, Any] = {
+    "jsonrpc": "2.0",
+    "id": 2,
+    "result": {"tools": []},
+}

xiaozhi_sdk-0.0.2/xiaozhi_sdk/iot.py

@@ -0,0 +1,76 @@
+import hashlib
+import hmac
+import json
+from typing import Any, Dict, Optional
+
+import aiohttp
+
+from xiaozhi_sdk.config import OTA_URL
+
+# 常量定义
+DEFAULT_APPLICATION_VERSION = "1.0.0"
+BOARD_TYPE = "xiaozhi-sdk-box"
+USER_AGENT = "xiaozhi-sdk/{}".format(DEFAULT_APPLICATION_VERSION)
+BOARD_NAME = "xiaozhi-sdk-{}".format(DEFAULT_APPLICATION_VERSION)
+
+
+class OtaDevice:
+    """
+    OTA设备管理类
+
+    用于处理设备的激活和挑战验证操作。
+
+    Attributes:
+        ota_url (str): OTA服务器URL
+        mac_addr (str): 设备MAC地址
+        client_id (str): 客户端ID
+        serial_number (str): 设备序列号
+    """
+
+    def __init__(self, mac_addr: str, client_id: str, ota_url: Optional[str] = None, serial_number: str = "") -> None:
+        self.ota_url = ota_url or OTA_URL
+        self.mac_addr = mac_addr
+        self.client_id = client_id
+        self.serial_number = serial_number
+
+    def _get_base_headers(self) -> Dict[str, str]:
+        return {
+            "user-agent": USER_AGENT,
+            "Device-Id": self.mac_addr,
+            "Client-Id": self.client_id,
+            "Content-Type": "application/json",
+        }
+
+    async def activate_device(self) -> Dict[str, Any]:
+        headers = self._get_base_headers()
+        headers["serial-number"] = self.serial_number
+
+        payload = {
+            "application": {"version": DEFAULT_APPLICATION_VERSION},
+            "board": {
+                "type": BOARD_TYPE,
+                "name": BOARD_NAME,
+            },
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(self.ota_url, headers=headers, data=json.dumps(payload)) as response:
+                response.raise_for_status()
+                return await response.json()
+
+    async def check_activate(self, challenge: str, license_key: str = "") -> bool:
+        url = f"{self.ota_url}/activate"
+        headers = self._get_base_headers()
+
+        hmac_instance = hmac.new(license_key.encode(), challenge.encode(), hashlib.sha256)
+        hmac_result = hmac_instance.hexdigest()
+
+        payload = {
+            "serial_number": self.serial_number,
+            "challenge": challenge,
+            "hmac": hmac_result
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(url, headers=headers, data=json.dumps(payload)) as response:
+                return response.status == 200

xiaozhi_sdk-0.0.2/xiaozhi_sdk/mcp.py

@@ -0,0 +1,100 @@
+import json
+import logging
+
+import requests
+
+from xiaozhi_sdk.data import mcp_initialize_payload, mcp_tool_conf, mcp_tools_payload
+
+logger = logging.getLogger("xiaozhi_sdk")
+
+
+class McpTool(object):
+
+    def __init__(self):
+        self.session_id = ""
+        self.explain_url = ""
+        self.explain_token = ""
+        self.websocket = None
+        self.tool_func = {}
+
+    def get_mcp_json(self, payload: dict):
+        return json.dumps({"session_id": self.session_id, "type": "mcp", "payload": payload})
+
+    def _build_response(self, request_id: str, content: str, is_error: bool = False):
+        return self.get_mcp_json(
+            {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "result": {
+                    "content": [{"type": "text", "text": content}],
+                    "isError": is_error,
+                },
+            }
+        )
+
+    async def analyze_image(self, img_byte: bytes, question: str = "这张图片里有什么？"):
+        headers = {"Authorization": f"Bearer {self.explain_token}"}
+        files = {"file": ("camera.jpg", img_byte, "image/jpeg")}
+        payload = {"question": question}
+        try:
+            response = requests.post(self.explain_url, files=files, data=payload, headers=headers, timeout=5)
+            res_json = response.json()
+        except Exception as e:
+            return "网络异常", True
+        if res_json.get("error"):
+            return res_json, True
+        return res_json, False
+
+    async def mcp_tool_call(self, mcp_json: dict):
+        tool_name = mcp_json["params"]["name"]
+        tool_func = self.tool_func[tool_name]
+        try:
+            tool_res, is_error = tool_func(mcp_json["params"]["arguments"])
+        except Exception as e:
+            logger.error("tool_func error: %s", e)
+            return
+
+        if tool_name == "take_photo":
+            tool_res, is_error = await self.analyze_image(tool_res, mcp_json["params"]["arguments"]["question"])
+
+        content = json.dumps(tool_res, ensure_ascii=False)
+        return self._build_response(mcp_json["id"], content, is_error)
+
+    async def mcp(self, data: dict):
+        payload = data["payload"]
+        method = payload["method"]
+
+        if method == "initialize":
+            self.explain_url = payload["params"]["capabilities"]["vision"]["url"]
+            self.explain_token = payload["params"]["capabilities"]["vision"]["token"]
+
+            mcp_initialize_payload["id"] = payload["id"]
+            await self.websocket.send(self.get_mcp_json(mcp_initialize_payload))
+
+        elif method == "notifications/initialized":
+            # print("\nMCP 工具初始化")
+            pass
+
+        elif method == "notifications/cancelled":
+            logger.error("MCP 工具加载失败")
+
+        elif method == "tools/list":
+            mcp_tools_payload["id"] = payload["id"]
+            tool_list = []
+            for name, func in self.tool_func.items():
+                if func:
+                    tool_list.append(name)
+                    mcp_tool_conf[name]["name"] = name
+                    mcp_tools_payload["result"]["tools"].append(mcp_tool_conf[name])
+            await self.websocket.send(self.get_mcp_json(mcp_tools_payload))
+            if tool_list:
+                logger.info("MCP 加载成功，当前可用工具列表为：%s", tool_list)
+
+        elif method == "tools/call":
+            tool_name = payload["params"]["name"]
+            if not self.tool_func.get(tool_name):
+                raise Exception("Tool not found")
+            mcp_res = await self.mcp_tool_call(payload)
+            await self.websocket.send(mcp_res)
+        else:
+            logger.warning("unknown method %s: %s", method, payload)

xiaozhi_sdk-0.0.2/xiaozhi_sdk/opus.py

@@ -0,0 +1,55 @@
+import av
+import numpy as np
+import opuslib
+
+from xiaozhi_sdk import INPUT_SERVER_AUDIO_SAMPLE_RATE
+
+
+class AudioOpus:
+
+    def __init__(self, sample_rate, channels):
+        self.sample_rate = sample_rate
+        self.channels = channels
+
+        # 创建 Opus 编码器
+        self.opus_encoder = opuslib.Encoder(
+            fs=sample_rate, channels=channels, application=opuslib.APPLICATION_VOIP  # 采样率  # 单声道  # 语音应用
+        )
+
+        # 创建 Opus 解码器
+        self.opus_decoder = opuslib.Decoder(
+            fs=INPUT_SERVER_AUDIO_SAMPLE_RATE,  # 采样率
+            channels=1,  # 单声道
+        )
+
+        self.resampler = av.AudioResampler(format="s16", layout="mono", rate=sample_rate)
+
+    async def pcm_to_opus(self, pcm):
+        pcm_array = np.frombuffer(pcm, dtype=np.int16)
+        pcm_bytes = pcm_array.tobytes()
+        return self.opus_encoder.encode(pcm_bytes, 960)
+
+    async def change_sample_rate(self, pcm_array):
+        if self.sample_rate == INPUT_SERVER_AUDIO_SAMPLE_RATE:
+            return pcm_array.reshape(1, 960)
+
+        c = int(self.sample_rate / INPUT_SERVER_AUDIO_SAMPLE_RATE)
+        frame = av.AudioFrame.from_ndarray(np.array(pcm_array).reshape(1, -1), format="s16", layout="mono")
+        frame.sample_rate = INPUT_SERVER_AUDIO_SAMPLE_RATE  # Assuming input is 16kHz
+        resampled_frames = self.resampler.resample(frame)
+        samples = resampled_frames[0].to_ndarray().flatten()
+        new_frame = av.AudioFrame.from_ndarray(
+            samples.reshape(1, -1),
+            format="s16",
+            layout="mono",
+        )
+        new_frame.sample_rate = self.sample_rate
+        new_samples = new_frame.to_ndarray().flatten()
+        arr_padded = np.pad(new_samples, (0, 960 * c - new_samples.shape[0]), mode="constant", constant_values=0)
+        return arr_padded.reshape(c, 960)
+
+    async def opus_to_pcm(self, opus):
+        pcm_data = self.opus_decoder.decode(opus, 960)
+        pcm_array = np.frombuffer(pcm_data, dtype=np.int16)
+        samples = await self.change_sample_rate(pcm_array)
+        return samples

xiaozhi_sdk-0.0.2/xiaozhi_sdk/utils.py

@@ -0,0 +1,57 @@
+import ctypes.util
+import os
+import platform
+import wave
+
+
+def get_wav_info(file_path):
+    with wave.open(file_path, "rb") as wav_file:
+        return wav_file.getframerate(), wav_file.getnchannels()
+
+
+def read_audio_file(file_path):
+    """
+    读取音频文件并通过yield返回PCM流
+
+    Args:
+        file_path (str): 音频文件路径
+
+    Yields:
+        bytes: PCM音频数据块
+    """
+    with wave.open(file_path, "rb") as wav_file:
+        while True:
+            pcm = wav_file.readframes(960)  # 每次读取960帧（60ms的音频数据）
+            if not pcm:
+                break
+            yield pcm
+
+
+def setup_opus():
+
+    def fake_find_library(name):
+        current_dir = os.path.dirname(os.path.abspath(__file__))
+        if name == "opus":
+            system = platform.system().lower()
+            machine = platform.machine().lower()
+
+            # 检测架构
+            if machine in ["x86_64", "amd64", "x64"]:
+                arch = "x64"
+            elif machine in ["arm64", "aarch64"]:
+                arch = "arm64"
+            else:
+                # 默认使用x64作为回退
+                arch = "x64"
+
+            if system == "darwin":  # macOS
+                return f"{current_dir}/../file/opus/macos-{arch}-libopus.dylib"
+            elif system == "windows":  # Windows
+                return f"{current_dir}/../file/opus/windows-{arch}-opus.dll"
+            elif system == "linux":  # Linux
+                return f"{current_dir}/../file/opus/linux-{arch}-libopus.so"
+            else:
+                # 默认情况，尝试系统查找
+                return ctypes.util.find_library(name)
+
+    ctypes.util.find_library = fake_find_library

xiaozhi_sdk-0.0.2/xiaozhi_sdk.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: xiaozhi-sdk
+Version: 0.0.2
+Summary: 一个用于连接和控制小智智能设备的Python SDK，支持实时音频通信、MCP工具集成和设备管理功能。
+Home-page: https://github.com/dairoot/xiaozhi-sdk
+Author: dairoot
+Author-email: 623815825@qq.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: websockets
+Requires-Dist: aiohttp
+Requires-Dist: av
+Requires-Dist: opuslib
+Requires-Dist: requests
+Requires-Dist: sounddevice
+Requires-Dist: python-socks
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 小智SDK (XiaoZhi SDK)
+
+[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/badge/pypi-xiaozhi--sdk-blue.svg)](https://pypi.org/project/xiaozhi-sdk/)
+
+基于虾哥的 [小智esp32 websocket 通讯协议](https://github.com/78/xiaozhi-esp32/blob/main/docs/websocket.md) 实现的 Python SDK。
+
+一个用于连接和控制小智设备的 Python SDK。支持以下功能：
+- 实时音频通信
+- MCP 工具集成
+- 设备管理与控制
+
+---
+
+## 📦 安装
+
+```bash
+pip install xiaozhi-sdk
+```
+
+---
+
+## 🚀 快速开始
+
+### 1. 终端使用
+
+最简单的方式是通过终端直接连接设备：
+
+#### 查看帮助信息
+
+```bash
+python -m xiaozhi_sdk -h
+```
+
+输出示例：
+```text
+positional arguments:
+  device             你的小智设备的MAC地址 (格式: XX:XX:XX:XX:XX:XX)
+
+options:
+  -h, --help         显示帮助信息并退出
+  --url URL          小智服务 websocket 地址
+  --ota_url OTA_URL  小智 OTA 地址
+```
+
+#### 连接设备（需要提供 MAC 地址）
+
+```bash
+python -m xiaozhi_sdk 00:22:44:66:88:00
+```
+
+### 2. 编程使用
+参考 [examples](examples/) 文件中的示例代码，可以快速开始使用 SDK。
+
+
+### 运行测试
+
+```bash
+pytest tests/
+```
+
+
+---
+
+## 🫡 致敬
+
+- 🫡 虾哥的 [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) 项目

xiaozhi_sdk-0.0.2/xiaozhi_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,40 @@
+LICENSE
+MANIFEST.in
+README.md
+setup.cfg
+setup.py
+file/audio/greet.wav
+file/audio/say_hello.wav
+file/audio/take_photo.wav
+file/image/leijun.jpg
+file/opus/linux-arm64-libopus.so
+file/opus/linux-x64-libopus.so
+file/opus/macos-arm64-libopus.dylib
+file/opus/macos-x64-libopus.dylib
+file/opus/windows-x86_64-opus.dll
+tests/test_iot.py
+tests/test_opus.py
+tests/test_pic.py
+tests/test_xiaozhi.py
+xiaozhi_sdk/__init__.py
+xiaozhi_sdk/__main__.py
+xiaozhi_sdk/config.py
+xiaozhi_sdk/data.py
+xiaozhi_sdk/iot.py
+xiaozhi_sdk/mcp.py
+xiaozhi_sdk/opus.py
+xiaozhi_sdk/utils.py
+xiaozhi_sdk.egg-info/PKG-INFO
+xiaozhi_sdk.egg-info/SOURCES.txt
+xiaozhi_sdk.egg-info/dependency_links.txt
+xiaozhi_sdk.egg-info/requires.txt
+xiaozhi_sdk.egg-info/top_level.txt
+xiaozhi_sdk/../file/audio/greet.wav
+xiaozhi_sdk/../file/audio/say_hello.wav
+xiaozhi_sdk/../file/audio/take_photo.wav
+xiaozhi_sdk/../file/image/leijun.jpg
+xiaozhi_sdk/../file/opus/linux-arm64-libopus.so
+xiaozhi_sdk/../file/opus/linux-x64-libopus.so
+xiaozhi_sdk/../file/opus/macos-arm64-libopus.dylib
+xiaozhi_sdk/../file/opus/macos-x64-libopus.dylib
+xiaozhi_sdk/../file/opus/windows-x86_64-opus.dll

xiaozhi_sdk-0.0.2/xiaozhi_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xiaozhi_sdk-0.0.2/xiaozhi_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy
+websockets
+aiohttp
+av
+opuslib
+requests
+sounddevice
+python-socks

xiaozhi_sdk-0.0.2/xiaozhi_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+xiaozhi_sdk