# TimeVoice

**Repository Path**: ue5/time-voice

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PiVoice — Raspberry Pi 定时语音播报系统

PiVoice 是一个基于 Web 面板管理的树莓派定时语音播报系统。支持倒计时、日程提醒、多语言 TTS，通过局域网浏览器即可配置。支持蓝牙音响无线播放。

## 技术栈

| 层 | 技术 |
|---|---|
| 前端 | Vite + React + TypeScript + Tailwind CSS |
| 后端 API | Flask（Python 3） |
| 守护进程 | Python 3 + APScheduler |
| TTS 引擎 | edge-tts (Microsoft Neural) |
| 音频播放 | mpg123 + PulseAudio（支持 HDMI + 蓝牙音响）；BGM fallback 用 ffplay |
| 配置存储 | YAML 文件 |
| 进程管理 | systemd |

## 架构

```
浏览器 → http://192.168.31.98:5000 → Flask（API + 静态文件）
                                         ↓
                                   rpi-scheduler.service（APScheduler）
                                         ↓
                                   edge-tts → mpg123 → PulseAudio → HDMI / 蓝牙音响
```

- Flask 同时提供 React SPA 静态文件和 REST API，单端口 5000
- 守护进程通过 systemd 管理，不暴露 HTTP 端口
- Windows 上 `npm run build` 构建前端，scp `dist/` 到 Pi
- PulseAudio 以用户 session 模式运行，支持动态切换音频输出（HDMI ↔ 蓝牙）

## 快速开始

### 环境要求
- 树莓派（推荐 Zero 2W / 3B+ / 4B）
- 系统: Debian 11 (Bullseye) 或更新
- 音频: HDMI 或蓝牙音响

### 部署

```bash
# Windows 上一键部署（需安装 Python + PyYAML）
python deploy.py
```

流程: 构建前端 → 上传文件到 Pi → 重启服务。

首次部署会在 Pi 上安装系统依赖（ffmpeg, pulseaudio, pulseaudio-module-bluetooth 等）。

### 配置

修改 Pi 连接信息统一在 `config/deploy.yaml`：

```yaml
pi:
  host: 192.168.31.98
  user: aby
  deploy_dir: /home/aby/pivoice
```

### 访问

浏览器打开 `http://192.168.31.98:5000`

## Web 面板功能

| 页面 | 路径 | 功能 |
|------|------|------|
| 控制台 | `/` | 守护进程状态、今日任务、最近日志（调度日志 + 播报日志） |
| 学习计时 | `/study-timer` | 单键开始/暂停学习计时、日目标设置、达标自动停止 + 音效、蓝牙遥控支持(PICO)、手动编辑累计时长 |
| 定时任务 | `/schedules` | 新增/编辑/删除/启停定时任务 |
| 智能播报 | `/poll-tasks` | 新增/编辑/删除/启停智能播报任务（轮询 + LLM 条件播报） |
| 语音测试 | `/test` | 在线试听 TTS 效果 |
| 音频库 | `/audio-library` | 上传/管理音频文件，分类管理 |
| 蓝牙音响 | `/bluetooth` | 扫描/配对/连接蓝牙音响，设置自动连接 |
| 设置 | `/settings` | LLM API配置、电源指示灯、开机自启

## 蓝牙音响配置

通过 Web 面板「蓝牙音响」页面即可完成配置，无需命令行操作：

1. 点击「扫描」按钮，等待扫描完成
2. 在设备列表中找到你的蓝牙音响（如 `BT-SPEAKER`）
3. 点击「连接」按钮，首次配对可能需要在音响上确认
4. 连接成功后，音频自动切换到蓝牙音响输出
5. 开启「自动连接」开关，树莓派重启后自动重连

详细配置说明见 [docs/bluetooth-setup.md](docs/bluetooth-setup.md)。

## 配置说明

配置通过 Web 面板操作，自动保存到 `config/schedules.yaml`。

### Schedule 配置

所有任务统一模型，无 fixed/countdown 区分。每条任务均有 `targetDate`（默认 `2026-10-15`），message 中可以使用 `{days}` 自动计算剩余天数。

| 字段 | 说明 | 示例 |
|------|------|------|
| `id` | 任务标识 | `morning_study` |
| `cron` | 执行时间 | `0 8 * * *` |
| `message` | 播报内容，支持关键词 | `距离10月15日还有{days}天` |
| `targetDate` | 倒计时目标日期 | `2026-10-15` |
| `language` | 语言 | `zh-CN` |
| `voice` | TTS 语音名 | `zh-CN-XiaoxiaoNeural` |

### Cron 表达式示例

| 表达式 | 含义 |
|--------|------|
| `0 8 * * *` | 每天 08:00 |
| `30 7 * * *` | 每天 07:30 |
| `0 9 * * 1-5` | 工作日 09:00 |

## 日常管理命令（SSH 到 Pi 执行）

```bash
# 查看服务状态
sudo systemctl status rpi-scheduler pivoice-web

# 重启服务（修改配置后）
sudo systemctl restart rpi-scheduler pivoice-web

# 查看调度器日志
tail -f /home/aby/pivoice/logs/scheduler.log

# 查看 Flask 日志
sudo journalctl -u pivoice-web.service -f

# 查看蓝牙连接状态
bluetoothctl info

# 查看当前音频输出
PULSE_SERVER=/run/user/1000/pulse/native pactl list sinks short
```

## 项目结构

```
PiVoice/
├── frontend/            # Vite + React SPA
│   ├── src/
│   │   ├── pages/       # Dashboard, Schedules, ScheduleEdit, PollTasks, VoiceTest, Bluetooth, AudioLibrary, StudyTimer, Settings, VoiceLibraries
│   │   ├── components/  # ui/, layout/, KeywordSelector
│   │   └── lib/         # types.ts, api.ts, constants.ts
│   └── dist/            # Windows 构建产物（scp 到 Pi）
├── backend/             # Flask API + Python 守护进程
│   ├── app.py           # Flask 应用（端口 5000）
│   ├── audio_core.py     # PulseAudio 统一入口（pactl、sink 管理、A2DP 恢复、音频播放）
│   ├── helpers.py       # 共享工具函数
│   ├── scheduler_daemon.py
│   ├── tts_engine.py      # TTS 引擎 + 关键词解析 + BGM 管理
│   ├── message_builder.py
│   ├── config_loader.py
│   ├── voice_library.py   # 语音库 CRUD
│   ├── poll_manager.py   # 智能播报后台线程（多轮 LLM + Bing 搜索 + 播报）
│   ├── llm_config.py     # LLM API 配置 + Bing 联网搜索
│   ├── study_timer.py    # 学习计时器核心（累加器+状态机+声音回调+持久化）
│   ├── bt_remote.py      # 蓝牙HID遥控（evdev监听+学习+自动重连）
│   ├── bluetooth_manager.py  # 蓝牙扫描/配对/连接 + PulseAudio 路由
│   └── preview_player.py
├── config/
│   ├── schedules.yaml    # 定时任务配置（部署时不碰）
│   ├── poll_tasks.yaml   # 智能播报任务配置（部署时不碰）
│   ├── llm.yaml          # LLM API 配置
│   ├── deploy.yaml       # 部署配置（Pi IP / 用户 / 路径）
│   └── audio-library.json  # 音频元数据（部署时不碰）
├── scripts/
│   ├── connect_speaker.py  # 蓝牙音箱连接
│   ├── setup.sh         # Pi 端依赖安装
│   ├── start.sh         # 手动启动/重启服务
│   ├── setup_pulseaudio.py
│   ├── pulseaudio.service  # PulseAudio systemd 服务
│   ├── pivoice-web.service
│   └── rpi-scheduler.service
├── deploy.py            # 一键部署脚本
└── logs/                # 运行日志（Pi 端）
```

## 故障排查

| 问题 | 解决 |
|------|------|
| 没有声音 | 检查 PulseAudio：`PULSE_SERVER=/run/user/1000/pulse/native pactl list sinks short`；测试音频：`PULSE_SERVER=/run/user/1000/pulse/native mpg123 -o pulse /usr/share/sounds/alsa/Front_Center.wav`；完整诊断见 [docs/bluetooth-setup.md](docs/bluetooth-setup.md) |
| 蓝牙音响无法连接 | 确保音响处于配对模式（指示灯快闪）；Web 面板删除后重新配对 |
| TTS 失败 | 检查网络，edge-tts 需要联网 |
| 守护进程未运行 | `sudo systemctl status rpi-scheduler` |
| Web 面板无法访问 | 确认端口 5000，`ss -tlnp \| grep 5000` |
| 页面白屏 | 浏览器 Ctrl+Shift+R 强制刷新清除缓存 |
| 配置修改无效 | Dashboard 点"重启守护进程"或 `sudo systemctl restart rpi-scheduler` |
| apt update 报错 | bullseye-backports 已失效，setup.sh 已注释 |
| 蓝牙音响连接后没声音 | 确认 system PA 已禁用（`systemctl is-active pulseaudio.service` 必须 inactive）；全项目 PA socket 必须统一指向 `/run/user/1000/pulse/native` |