# xiaozhi-pet

**Repository Path**: fa0/xiaozhi-pet

## Basic Information

- **Project Name**: xiaozhi-pet
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-17
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小智桌面宠物 (XiaoZhi Desktop Pet)

一个基于 Live2D 和 PyQt5 的智能桌面宠物应用，集成了小智语音助手 SDK，支持语音交互、实时对话和丰富的 Live2D 角色动画。

## ✨ 功能特性

- 🎭 **Live2D 角色展示**：使用 Live2D Cubism 4.0 技术，展示流畅的 2D 角色动画
- 🎤 **语音交互**：集成小智语音助手，支持语音唤醒和实时对话
- 🔊 **音量可视化**：实时显示语音音量，角色会根据音量大小做出相应动作
- 💬 **对话气泡**：显示 AI 助手的回复内容，支持自动隐藏
- 🎨 **无边框窗口**：透明背景，可拖动，支持置顶显示
- 👀 **视线跟随**：角色会跟随鼠标移动，实现自然的视线交互
- 🖱️ **交互控制**：
  - 单击：打断当前对话（触发动作）
  - 双击：结束对话（发送告别语并隐藏窗口）
  - 拖动：移动窗口位置

## 📋 环境要求

- Python 3.7+
- macOS / Linux / Windows
- PyQt5 >= 5.15.0
- PyQtWebEngine >= 5.15.0
- 小智 SDK (xiaozhi_sdk)
- 其他依赖见 `requirements.txt`

## 🚀 安装步骤

### 1. 克隆项目

```bash
git clone <repository-url>
cd xiaozhi-pet
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置小智设备

设备 MAC 地址默认通过 `xiaozhi_sdk` 的 `get_mac_address()` 自动获取（见 `src/main.py`），无需手动配置。可在「设置 → 设备信息」中查看当前 MAC 地址。

### 4. 运行应用

```bash
python main.py
```

## 📁 项目结构

```
xiaozhi-pet/
├── README.md                 # 项目说明文档
├── requirements.txt          # Python 依赖列表
├── main.py                   # 程序入口
├── src/
│   ├── __init__.py
│   ├── main.py              # 主窗口应用（PyQt5）
│   ├── bridge.py            # JS ↔ Python 通信桥梁
│   ├── audio_wakeup.py      # 离线语音唤醒
│   ├── global_shortcut.py   # 全局快捷键唤醒
│   ├── settings_window.py   # 设置窗口
│   ├── desktop_manager.py   # 多桌面空间显示管理
│   ├── utils.py             # 工具函数（视觉模型等）
│   ├── xiaozhi/             # 小智客户端、音频处理与 MCP 工具
│   ├── templates/
│   │   └── index.html     # Live2D 渲染页面
│   └── static/             # 静态资源
│       ├── cubism4.min.js  # Live2D Cubism 4.0 SDK
│       ├── live2dcubismcore.min.js
│       ├── pixi.js         # PIXI.js 渲染引擎
│       └── hiyori_pro_zh/  # Live2D 模型文件
│           └── runtime/
│               └── ...
```

## 🎮 使用说明

### 启动应用

运行 `python main.py` 后，应用会：

1. 在屏幕右下角创建一个无边框窗口
2. 加载 Live2D 角色模型
3. 启动小智语音助手客户端
4. 开始监听麦克风输入

### 交互方式

- **快捷键唤醒**：按 `Cmd/Ctrl + Shift + R` 唤醒（窗口隐藏时也可响应）
- **离线语音唤醒**：在「设置 → 唤醒配置」中下载模型并配置唤醒词后，可通过说出唤醒词激活
- **拖动窗口**：按住鼠标左键拖动窗口到任意位置
- **单击角色**：打断当前对话
- **双击角色**：结束对话并隐藏窗口
- **视线跟随**：移动鼠标，角色会跟随视线

### 音量可视化

当语音助手播放音频时，角色的嘴巴会根据音量大小自动开合，实现自然的说话效果。

## ⚙️ 配置说明

### 修改唤醒后的开场白

在 `src/main.py` 中修改唤醒时发送的文本：

```python
self.start_async_thread("你好啊")
```

### 修改快捷键唤醒组合

在 `src/main.py` 中修改（macOS 用 `cmd`，其他平台用 `ctrl`）：

```python
shortcut_config = ["cmd", "shift", "r"]
```

### 修改窗口大小

在 `src/main.py` 中修改：

```python
self.resize(500, 400)  # 宽度, 高度
```

### 修改模型路径

在 `src/templates/index.html` 中修改：

```javascript
model = await PIXI.live2d.Live2DModel.from('../static/hiyori_pro_zh/runtime/hiyori_pro_t11.model3.json');
```

## 🔧 技术栈

- **前端渲染**：PIXI.js + Live2D Cubism 4.0
- **桌面应用**：PyQt5 + QWebEngine
- **语音处理**：sounddevice + numpy
- **语音助手**：小智 SDK (xiaozhi_sdk)
- **通信协议**：QWebChannel (Python ↔ JavaScript)

## ⚠️ 注意事项

1. **macOS 兼容性**：应用已配置 macOS 特定的环境变量以解决 WebEngine 崩溃问题
2. **音频权限**：首次运行需要授予麦克风权限
3. **设备连接**：确保小智设备已正确连接并配置 MAC 地址
4. **模型文件**：确保 Live2D 模型文件完整，路径正确

## 🐛 故障排除

### 窗口无法显示

- 检查 PyQt5 和 PyQtWebEngine 是否正确安装
- 在 macOS 上，确保环境变量 `QT_MAC_WANTS_LAYER=1` 已设置

### 音频无法播放

- 检查系统音频权限
- 确认 sounddevice 库已正确安装
- 检查音频设备是否可用

### Live2D 模型加载失败

- 检查模型文件路径是否正确
- 确认所有模型文件（.model3.json, .moc3, .texture 等）完整
- 查看浏览器控制台错误信息

### 小智连接失败

- 确认设备 MAC 地址正确
- 检查网络连接
- 确认小智 SDK 已正确安装和配置

## 📝 开发说明

### 添加新动作

在 `src/templates/index.html` 中的 `motion_list` 数组中添加动作名称：

```javascript
const motion_list = [
    ...Array(1).fill("Flick"),
    ...Array(1).fill("你的新动作"),  // 添加新动作
];
```

### 自定义样式

修改 `src/templates/index.html` 中的 CSS 样式来自定义气泡框、窗口等外观。

## 📄 许可证

[在此添加许可证信息]

## 🙏 致谢

- [Live2D Cubism](https://www.live2d.com/) - Live2D 技术
- [PIXI.js](https://pixijs.com/) - 2D WebGL 渲染引擎
- [PyQt5](https://www.riverbankcomputing.com/software/pyqt/) - Python GUI 框架
- 小智语音助手 SDK

## 📧 联系方式

如有问题或建议，请提交 Issue 或联系项目维护者。