# Doubao Speech-to-Text for Home Assistant

豆包语音识别 Home Assistant 集成插件，基于 [doubaoime-asr](https://github.com/starccy/doubaoime-asr) 开发。

## 问题反馈

[HomeAssistant 豆包输入法 STT 语音识别插件
反馈](https://bbs.nextrt.com/d/3-homeassistant-dou-bao-shu-ru-fa-stt-yu-yin-shi-bie-cha-jian)

## 功能特性

- ✅ 完全兼容 Home Assistant STT 组件规范
- ✅ UI 配置界面，无需手动编辑配置文件
- ✅ 自动设备注册和凭据管理
- ✅ 支持中文语音识别（zh-CN, zh）
- ✅ 实时流式识别
- ✅ 自动标点符号添加
- ✅ 保留原有设备伪装功能

## 系统要求

- Home Assistant 2024.1+
- Python 3.11+


## 安装方法

### 方法 1: 手动安装

1. 将整个 `custom_components/hass_stt_doubao` 目录复制到 Home Assistant 配置目录的 `custom_components` 文件夹下：

2. 重启 Home Assistant

### 方法 2: HACS 安装（推荐）

1. 确保你已经在 Home Assistant 中安装并配置了 HACS（Home Assistant Community Store）。
2. 点击 HACS 界面左上角的菜单，选择 自定义仓库（Custom repositories），在弹出的窗口中输入仓库地址`https://github.com/xyzmos/hass_stt_doubao`，类别选择`集成`，然后点击 `添加`。之后再搜索 "Doubao STT" 并安装。
3. 重启 Home Assistant

## 配置

### 通过 UI 配置（推荐）

1. 进入 Home Assistant 设置 → 设备与服务
2. 点击右下角 "添加集成"
3. 搜索 "Doubao Speech to Text"
4. 按照向导完成配置：
   - **凭据文件路径**：默认 `doubao_credentials.json`（相对于 HA 配置目录）
   - **启用标点符号**：默认启用

### 配置说明

- **凭据文件路径**：首次运行时会自动注册虚拟设备并保存凭据到此文件，避免重复注册
- **启用标点符号**：是否在识别结果中自动添加标点符号

## 使用示例

### 在 Assist 中使用

配置完成后，Doubao STT 会自动出现在 Assist 管道配置中：

1. 进入设置 → Assist → 管道
2. 选择或创建一个管道
3. 在 "语音转文字" 选项中选择 "Doubao STT"
4. 保存配置

### 在自动化中使用

```yaml
automation:
  - alias: "语音控制示例"
    trigger:
      - platform: event
        event_type: voice_command
    action:
      - service: stt.process
        data:
          entity_id: stt.doubao_stt
          language: zh-CN
```

## 技术架构

```
Home Assistant Audio Stream (PCM 16kHz Mono)
           ↓
    DoubaoSTTEntity
           ↓
    Audio Encoder (PCM → Opus)
           ↓
    DoubaoASR WebSocket Client
           ↓
    Doubao ASR Service
           ↓
    Recognition Result (Text)
```

## 目录结构

```
custom_components/hass_stt_doubao/
├── __init__.py              # 集成初始化
├── manifest.json            # 集成元数据
├── const.py                 # 常量定义
├── config_flow.py           # 配置流
├── stt.py                   # STT 实体实现
├── strings.json             # UI 字符串
├── translations/
│   └── zh.json             # 中文翻译
└── doubaoime_asr/          # doubaoime-asr 核心模块
    ├── __init__.py
    ├── asr.py
    ├── audio.py
    ├── config.py
    ├── constants.py
    ├── device.py
    └── asr_pb2.py
```

## 故障排除

### 无法连接到 Doubao 服务

1. 检查网络连接
2. 确认系统已安装 libopus0
3. 查看 Home Assistant 日志：`设置 → 系统 → 日志`

### 识别结果为空

1. 确保音频格式正确（PCM 16kHz Mono）
2. 检查麦克风是否正常工作
3. 尝试重新配置集成

### 凭据失效

1. 删除凭据文件（默认在配置目录下的 `doubao_credentials.json`）
2. 重新配置集成，会自动重新注册设备

## 免责声明

本项目基于 [doubaoime-asr](https://github.com/starccy/doubaoime-asr) - 核心 ASR 的实现，**非官方提供的 API**。

- 本项目仅供学习和研究目的
- 不保证未来的可用性和稳定性
- 服务端协议可能随时变更导致功能失效

## 许可证

MIT License

## 致谢

- [doubaoime-asr](https://github.com/starccy/doubaoime-asr) - 核心 ASR 实现
- [Home Assistant](https://www.home-assistant.io/) - 智能家居平台

## 更新日志

### v1.0.0 (2026-02-05)
- 初始版本
- 完整的 STT 组件实现
- UI 配置支持
- 自动设备注册
- 中文语音识别