Update README.md with architecture diagram
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
279
README.md
279
README.md
@@ -1,63 +1,193 @@
|
|||||||
# Alexander Smart Speaker
|
<div align="center">
|
||||||
|
|
||||||
Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков.
|
# 🎙️ Alexander Smart Speaker
|
||||||
|
|
||||||
## Что умеет
|
**Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков**
|
||||||
- Активация по ключевому слову `Alexandr`.
|
|
||||||
- Диалог с AI (Perplexity) с сохранением контекста.
|
|
||||||
- Перевод RU ↔ EN с озвучиванием.
|
|
||||||
- Погода по умолчанию и по названию города.
|
|
||||||
- Будильники, таймеры и секундомеры.
|
|
||||||
- Управление громкостью системы.
|
|
||||||
- Управление Spotify (play/pause/next/current track).
|
|
||||||
- Игра в города.
|
|
||||||
|
|
||||||
## Технологии
|
[](https://www.python.org/downloads/)
|
||||||
- Wake word: `pvporcupine`
|
[](https://www.linux.org/)
|
||||||
- STT: `deepgram-sdk`
|
[](LICENSE.txt)
|
||||||
- TTS: `Silero` (`torch`, `torchaudio`)
|
|
||||||
- AI: Perplexity API
|
|
||||||
- Погода: Open-Meteo
|
|
||||||
- Музыка: Spotify Web API (`spotipy`)
|
|
||||||
|
|
||||||
## Требования
|
</div>
|
||||||
- Linux
|
|
||||||
- Python 3.9+
|
## ✨ Возможности
|
||||||
- Системные пакеты:
|
|
||||||
|
| Функция | Описание |
|
||||||
|
|--------|----------|
|
||||||
|
| 🔊 **Активация по ключевому слову** | Активация по команде `Alexandr` |
|
||||||
|
| 🧠 **Диалог с AI** | Взаимодействие с Perplexity с сохранением контекста |
|
||||||
|
| 🌐 **Перевод** | Перевод RU ↔ EN с озвучиванием |
|
||||||
|
| 🌤️ **Погода** | Информация о погоде по умолчанию и по названию города |
|
||||||
|
| ⏰ **Таймеры и будильники** | Управление таймерами, будильниками и секундомерами |
|
||||||
|
| 🔊 **Управление громкостью** | Регулировка системной громкости |
|
||||||
|
| 🎵 **Spotify интеграция** | Управление воспроизведением (play/pause/next/current track) |
|
||||||
|
| 🌍 **Игра в города** | Классическая игра в города |
|
||||||
|
|
||||||
|
## 🏗️ Архитектура проекта
|
||||||
|
|
||||||
|
### Диаграмма взаимодействия компонентов
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TB
|
||||||
|
subgraph "Основной цикл (main.py)"
|
||||||
|
A[Бесконечный цикл] --> B{Режим активации}
|
||||||
|
B -->|Ожидание wake word| C[wait_for_wakeword]
|
||||||
|
B -->|Режим диалога| D[listen в режиме follow-up]
|
||||||
|
C --> E[Прослушивание команды]
|
||||||
|
D --> E
|
||||||
|
E --> F[Анализ команды]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph "Аудио подсистема (app/audio/)"
|
||||||
|
C1[wakeword.py<br/>- wait_for_wakeword<br/>- check_wakeword_once]
|
||||||
|
E1[stt.py<br/>- listen<br/>- get_recognizer]
|
||||||
|
G1[tts.py<br/>- speak<br/>- initialize]
|
||||||
|
H1[sound_level.py<br/>- parse_volume_text<br/>- set_volume]
|
||||||
|
|
||||||
|
C1 -.-> E1
|
||||||
|
E1 -.-> G1
|
||||||
|
H1 -.-> G1
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph "Ядро (app/core/)"
|
||||||
|
F1[commands.py<br/>- is_stop_command<br/>- _normalize_text]
|
||||||
|
F2[ai.py<br/>- ask_ai_stream<br/>- translate_text]
|
||||||
|
F3[cleaner.py<br/>- clean_response]
|
||||||
|
F4[config.py<br/>- Настройки проекта]
|
||||||
|
F5[smalltalk.py<br/>- get_smalltalk_response]
|
||||||
|
|
||||||
|
F --> F1
|
||||||
|
F --> F2
|
||||||
|
F --> F3
|
||||||
|
F --> F5
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph "Функции (app/features/)"
|
||||||
|
I1[weather.py<br/>- get_weather_report]
|
||||||
|
I2[timer.py<br/>- get_timer_manager]
|
||||||
|
I3[alarm.py<br/>- get_alarm_clock]
|
||||||
|
I4[stopwatch.py<br/>- get_stopwatch_manager]
|
||||||
|
I5[music.py<br/>- get_music_controller]
|
||||||
|
I6[cities_game.py<br/>- get_cities_game]
|
||||||
|
|
||||||
|
F --> I1
|
||||||
|
F --> I2
|
||||||
|
F --> I3
|
||||||
|
F --> I4
|
||||||
|
F --> I5
|
||||||
|
F --> I6
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph "Обработка команд"
|
||||||
|
F --> J{Тип команды}
|
||||||
|
J -->|Small talk| K[get_smalltalk_response]
|
||||||
|
J -->|Повтор| L[Повтор последнего ответа]
|
||||||
|
J -->|Стоп| M[is_stop_command]
|
||||||
|
J -->|Таймер| N[parse_command timer]
|
||||||
|
J -->|Будильник| O[parse_command alarm]
|
||||||
|
J -->|Секундомер| P[parse_command stopwatch]
|
||||||
|
J -->|Громкость| Q[parse_volume_text + set_volume]
|
||||||
|
J -->|Погода| R[get_weather_report]
|
||||||
|
J -->|Музыка| S[parse_command music]
|
||||||
|
J -->|Перевод| T[parse_translation_request]
|
||||||
|
J -->|Города| U[handle cities_game]
|
||||||
|
J -->|AI| V[ask_ai_stream]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph "Ответ пользователю"
|
||||||
|
K --> W[clean_response]
|
||||||
|
L --> W
|
||||||
|
M --> W
|
||||||
|
N --> W
|
||||||
|
O --> W
|
||||||
|
P --> W
|
||||||
|
Q --> W
|
||||||
|
R --> W
|
||||||
|
S --> W
|
||||||
|
T --> W
|
||||||
|
U --> W
|
||||||
|
V --> W
|
||||||
|
|
||||||
|
W --> X[speak]
|
||||||
|
X --> Y[Возврат в режим ожидания]
|
||||||
|
Y --> A
|
||||||
|
end
|
||||||
|
|
||||||
|
%% Connections
|
||||||
|
C1 -.-> A
|
||||||
|
E1 -.-> F
|
||||||
|
G1 -.-> X
|
||||||
|
F2 -.-> V
|
||||||
|
F3 -.-> W
|
||||||
|
I1 -.-> R
|
||||||
|
I2 -.-> N
|
||||||
|
I3 -.-> O
|
||||||
|
I4 -.-> P
|
||||||
|
I5 -.-> S
|
||||||
|
I6 -.-> U
|
||||||
|
|
||||||
|
style A fill:#e1f5fe
|
||||||
|
style F fill:#f3e5f5
|
||||||
|
style X fill:#e8f5e8
|
||||||
|
style Y fill:#fff3e0
|
||||||
|
</graph>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🛠️ Технологии
|
||||||
|
|
||||||
|
| Компонент | Технология |
|
||||||
|
|-----------|------------|
|
||||||
|
| **Wake word** | `pvporcupine` |
|
||||||
|
| **STT** | `deepgram-sdk` |
|
||||||
|
| **TTS** | `Silero` (`torch`, `torchaudio`) |
|
||||||
|
| **AI** | Perplexity API |
|
||||||
|
| **Погода** | Open-Meteo |
|
||||||
|
| **Музыка** | Spotify Web API (`spotipy`) |
|
||||||
|
|
||||||
|
## 📋 Требования
|
||||||
|
|
||||||
|
- **ОС**: Linux
|
||||||
|
- **Python**: 3.9+
|
||||||
|
- **Системные пакеты**:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sudo apt-get update
|
sudo apt-get update
|
||||||
sudo apt-get install -y portaudio19-dev libasound2-dev mpg123
|
sudo apt-get install -y portaudio19-dev libasound2-dev mpg123
|
||||||
```
|
```
|
||||||
|
|
||||||
Для управления громкостью нужен `pactl` или `amixer` (обычно из `pulseaudio-utils`/`alsa-utils`).
|
> 💡 Для управления громкостью необходим `pactl` или `amixer` (обычно из `pulseaudio-utils`/`alsa-utils`).
|
||||||
|
|
||||||
## Установка
|
## 🚀 Установка
|
||||||
|
|
||||||
|
1. **Клонируйте репозиторий**:
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/your-username/alexander_smart-speaker.git
|
git clone https://github.com/your-username/alexander_smart-speaker.git
|
||||||
cd alexander_smart-speaker
|
cd alexander_smart-speaker
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Настройте виртуальное окружение**:
|
||||||
|
```bash
|
||||||
python -m venv venv
|
python -m venv venv
|
||||||
source venv/bin/activate
|
source venv/bin/activate # или venv\Scripts\activate на Windows
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
## Настройка `.env`
|
## ⚙️ Настройка
|
||||||
|
|
||||||
|
1. **Создайте файл конфигурации**:
|
||||||
```bash
|
```bash
|
||||||
cp .env.example .env
|
cp .env.example .env
|
||||||
```
|
```
|
||||||
|
|
||||||
Минимально обязательные переменные:
|
2. **Обязательные переменные окружения**:
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
PERPLEXITY_API_KEY=...
|
PERPLEXITY_API_KEY=your_perplexity_api_key_here
|
||||||
DEEPGRAM_API_KEY=...
|
DEEPGRAM_API_KEY=your_deepgram_api_key_here
|
||||||
PORCUPINE_ACCESS_KEY=...
|
PORCUPINE_ACCESS_KEY=your_porcupine_access_key_here
|
||||||
```
|
```
|
||||||
|
|
||||||
Полный пример (как в `.env.example`):
|
3. **Полная конфигурация** (как в `.env.example`):
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
PERPLEXITY_API_KEY=your_perplexity_api_key_here
|
PERPLEXITY_API_KEY=your_perplexity_api_key_here
|
||||||
@@ -74,7 +204,7 @@ SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
|
|||||||
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback
|
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback
|
||||||
```
|
```
|
||||||
|
|
||||||
## Запуск
|
## ▶️ Запуск
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
make run
|
make run
|
||||||
@@ -82,41 +212,62 @@ make run
|
|||||||
python run.py
|
python run.py
|
||||||
```
|
```
|
||||||
|
|
||||||
## Примеры голосовых команд
|
## 🗣️ Примеры голосовых команд
|
||||||
- Активация: `Alexandr`
|
|
||||||
- Диалог: `Почему небо голубое?`
|
|
||||||
- Погода: `Какая сейчас погода?`, `Погода в Москве`
|
|
||||||
- Перевод: `Переведи на английский: как дела`
|
|
||||||
- Таймер: `Поставь таймер на 5 минут`
|
|
||||||
- Будильник: `Поставь будильник на 7:30`, `Будильник по будням в 8:00`
|
|
||||||
- Секундомер: `Запусти секундомер`, `Покажи активные секундомеры`
|
|
||||||
- Громкость: `Громкость 5`
|
|
||||||
- Spotify: `Включи музыку`, `Пауза`, `Что сейчас играет`
|
|
||||||
- Игра: `Давай сыграем в города`
|
|
||||||
- Остановка/прерывание: `Стоп`, `Хватит`, `Повтори`
|
|
||||||
|
|
||||||
## Полезные команды
|
| Категория | Команды |
|
||||||
|
|-----------|---------|
|
||||||
|
| **Активация** | `Alexandr` |
|
||||||
|
| **Диалог** | `Почему небо голубое?` |
|
||||||
|
| **Погода** | `Какая сейчас погода?`, `Погода в Москве` |
|
||||||
|
| **Перевод** | `Переведи на английский: как дела` |
|
||||||
|
| **Таймер** | `Поставь таймер на 5 минут` |
|
||||||
|
| **Будильник** | `Поставь будильник на 7:30`, `Будильник по будням в 8:00` |
|
||||||
|
| **Секундомер** | `Запусти секундомер`, `Покажи активные секундомеры` |
|
||||||
|
| **Громкость** | `Громкость 5` |
|
||||||
|
| **Spotify** | `Включи музыку`, `Пауза`, `Что сейчас играет` |
|
||||||
|
| **Игра** | `Давай сыграем в города` |
|
||||||
|
| **Остановка** | `Стоп`, `Хватит`, `Повтори` |
|
||||||
|
|
||||||
```bash
|
## 🛠️ Полезные команды
|
||||||
make run # запуск ассистента
|
|
||||||
make check # базовая проверка проекта
|
| Команда | Назначение |
|
||||||
make qwen-context # собрать контекст проекта
|
|---------|------------|
|
||||||
|
| `make run` | Запуск ассистента |
|
||||||
|
| `make check` | Базовая проверка проекта |
|
||||||
|
| `make qwen-context` | Собрать контекст проекта |
|
||||||
|
|
||||||
|
## 📁 Структура проекта
|
||||||
|
|
||||||
|
```
|
||||||
|
alexander_smart-speaker/
|
||||||
|
├── run.py # точка входа
|
||||||
|
├── app/
|
||||||
|
│ ├── main.py # главный цикл ассистента
|
||||||
|
│ ├── audio/ # wake word, STT, TTS, громкость
|
||||||
|
│ ├── core/ # конфиг, AI, роутинг команд, утилиты
|
||||||
|
│ └── features/ # погода, будильник, таймер, секундомер, музыка, города
|
||||||
|
├── assets/ # модели и звуки
|
||||||
|
├── data/ # сохраненные будильники/таймеры/секундомеры
|
||||||
|
└── scripts/ # скрипты для установки и обслуживания
|
||||||
```
|
```
|
||||||
|
|
||||||
## Структура проекта
|
## 🔧 Диагностика проблем
|
||||||
- `run.py` - точка входа.
|
|
||||||
- `app/main.py` - главный цикл ассистента.
|
|
||||||
- `app/audio/` - wake word, STT, TTS, громкость.
|
|
||||||
- `app/core/` - конфиг, AI, роутинг команд, утилиты.
|
|
||||||
- `app/features/` - погода, будильник, таймер, секундомер, музыка, города.
|
|
||||||
- `assets/` - модели и звуки.
|
|
||||||
- `data/` - сохраненные будильники/таймеры/секундомеры.
|
|
||||||
|
|
||||||
## Диагностика проблем
|
| Проблема | Решение |
|
||||||
- Ошибки STT/AI: проверьте ключи в `.env`.
|
|----------|---------|
|
||||||
- Нет звука: проверьте системное устройство вывода и утилиты `pactl`/`amixer`.
|
| Ошибки STT/AI | Проверьте ключи в `.env` |
|
||||||
- Не играет будильник/таймер: убедитесь, что установлен `mpg123`.
|
| Нет звука | Проверьте системное устройство вывода и утилиты `pactl`/`amixer` |
|
||||||
- Spotify не управляется: проверьте `SPOTIFY_*`, авторизацию и наличие активного устройства.
|
| Не играет будильник/таймер | Убедитесь, что установлен `mpg123` |
|
||||||
|
| Spotify не управляется | Проверьте `SPOTIFY_*`, авторизацию и наличие активного устройства |
|
||||||
|
|
||||||
## Лицензия
|
## 📄 Лицензия
|
||||||
MIT, см. `LICENSE.txt`.
|
|
||||||
|
MIT, см. [LICENSE.txt](LICENSE.txt).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
**Если вам понравился проект, поставьте ⭐ звезду!**
|
||||||
|
|
||||||
|
</div>
|
||||||
Reference in New Issue
Block a user