325 lines
11 KiB
Markdown
325 lines
11 KiB
Markdown
<div align="center">
|
||
|
||
# 🎙️ Alexander Smart Speaker
|
||
|
||
**Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков**
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](https://www.linux.org/)
|
||
[](LICENSE.txt)
|
||
|
||
</div>
|
||
|
||
## ✨ Возможности
|
||
|
||
| Функция | Описание |
|
||
|--------|----------|
|
||
| 🔊 **Активация по ключевому слову** | Активация по команде `Alexandr` |
|
||
| 🧠 **Диалог с AI** | Взаимодействие с Perplexity с сохранением контекста |
|
||
| 🌐 **Перевод** | Перевод RU ↔ EN с озвучиванием |
|
||
| 🌤️ **Погода** | Информация о погоде по умолчанию и по названию города |
|
||
| ⏰ **Таймеры и будильники** | Управление таймерами, будильниками и секундомерами |
|
||
| 🔊 **Управление громкостью** | Регулировка системной громкости |
|
||
| 🎵 **Spotify интеграция** | Управление воспроизведением (play/pause/next/current track) |
|
||
| 🌍 **Игра в города** | Классическая игра в города |
|
||
|
||
## 🏗️ Архитектура проекта
|
||
|
||
### Диаграмма взаимодействия компонентов
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "Основной цикл (app/main.py)"
|
||
A[main() - основной цикл] --> 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 до функций
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph "Активация и распознавание"
|
||
A[wakeword.py<br/>wait_for_wakeword()] --> B[stt.py<br/>listen()]
|
||
B --> C[Распознанный текст]
|
||
end
|
||
|
||
subgraph "Анализ команды"
|
||
C --> D{Тип команды}
|
||
end
|
||
|
||
subgraph "Обработка специфических команд"
|
||
D -->|Small talk| E[smalltalk.py<br/>get_smalltalk_response()]
|
||
D -->|Стоп команда| F[commands.py<br/>is_stop_command()]
|
||
D -->|Таймер| G[timer.py<br/>parse_command()]
|
||
D -->|Будильник| H[alarm.py<br/>parse_command()]
|
||
D -->|Секундомер| I[stopwatch.py<br/>parse_command()]
|
||
D -->|Громкость| J[sound_level.py<br/>parse_volume_text()<br/>set_volume()]
|
||
D -->|Погода| K[weather.py<br/>get_weather_report()]
|
||
D -->|Музыка| L[music.py<br/>parse_command()]
|
||
D -->|Перевод| M[ai.py<br/>parse_translation_request()<br/>translate_text()]
|
||
D -->|Города| N[cities_game.py<br/>handle()]
|
||
D -->|Обычный вопрос| O[ai.py<br/>ask_ai_stream()]
|
||
end
|
||
|
||
subgraph "Ответ пользователю"
|
||
E --> P[cleaner.py<br/>clean_response()]
|
||
F --> P
|
||
G --> P
|
||
H --> P
|
||
I --> P
|
||
J --> P
|
||
K --> P
|
||
L --> P
|
||
M --> P
|
||
N --> P
|
||
O --> P
|
||
P --> Q[tts.py<br/>speak()]
|
||
end
|
||
|
||
subgraph "Цикл управления"
|
||
Q --> R{Продолжить диалог?}
|
||
R -->|Да| S[Остаться в режиме ожидания]
|
||
R -->|Нет| T[Ждать wake word снова]
|
||
S --> B
|
||
T --> A
|
||
end
|
||
</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
|
||
sudo apt-get update
|
||
sudo apt-get install -y portaudio19-dev libasound2-dev mpg123
|
||
```
|
||
|
||
> 💡 Для управления громкостью необходим `pactl` или `amixer` (обычно из `pulseaudio-utils`/`alsa-utils`).
|
||
|
||
## 🚀 Установка
|
||
|
||
1. **Клонируйте репозиторий**:
|
||
```bash
|
||
git clone https://github.com/your-username/alexander_smart-speaker.git
|
||
cd alexander_smart-speaker
|
||
```
|
||
|
||
2. **Настройте виртуальное окружение**:
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate # или venv\Scripts\activate на Windows
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## ⚙️ Настройка
|
||
|
||
1. **Создайте файл конфигурации**:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. **Обязательные переменные окружения**:
|
||
|
||
```ini
|
||
PERPLEXITY_API_KEY=your_perplexity_api_key_here
|
||
DEEPGRAM_API_KEY=your_deepgram_api_key_here
|
||
PORCUPINE_ACCESS_KEY=your_porcupine_access_key_here
|
||
```
|
||
|
||
3. **Полная конфигурация** (как в `.env.example`):
|
||
|
||
```ini
|
||
PERPLEXITY_API_KEY=your_perplexity_api_key_here
|
||
PERPLEXITY_MODEL=llama-3.1-sonar-small-128k-chat
|
||
DEEPGRAM_API_KEY=your_deepgram_api_key_here
|
||
PORCUPINE_ACCESS_KEY=your_porcupine_access_key_here
|
||
PORCUPINE_SENSITIVITY=0.8
|
||
TTS_EN_SPEAKER=en_0
|
||
WEATHER_LAT=63.56
|
||
WEATHER_LON=53.69
|
||
WEATHER_CITY=Ухта
|
||
SPOTIFY_CLIENT_ID=your_spotify_client_id
|
||
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
|
||
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback
|
||
```
|
||
|
||
## ▶️ Запуск
|
||
|
||
```bash
|
||
make run
|
||
# или
|
||
python run.py
|
||
```
|
||
|
||
## 🗣️ Примеры голосовых команд
|
||
|
||
| Категория | Команды |
|
||
|-----------|---------|
|
||
| **Активация** | `Alexandr` |
|
||
| **Диалог** | `Почему небо голубое?` |
|
||
| **Погода** | `Какая сейчас погода?`, `Погода в Москве` |
|
||
| **Перевод** | `Переведи на английский: как дела` |
|
||
| **Таймер** | `Поставь таймер на 5 минут` |
|
||
| **Будильник** | `Поставь будильник на 7:30`, `Будильник по будням в 8:00` |
|
||
| **Секундомер** | `Запусти секундомер`, `Покажи активные секундомеры` |
|
||
| **Громкость** | `Громкость 5` |
|
||
| **Spotify** | `Включи музыку`, `Пауза`, `Что сейчас играет` |
|
||
| **Игра** | `Давай сыграем в города` |
|
||
| **Остановка** | `Стоп`, `Хватит`, `Повтори` |
|
||
|
||
## 🛠️ Полезные команды
|
||
|
||
| Команда | Назначение |
|
||
|---------|------------|
|
||
| `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/ # скрипты для установки и обслуживания
|
||
```
|
||
|
||
## 🔧 Диагностика проблем
|
||
|
||
| Проблема | Решение |
|
||
|----------|---------|
|
||
| Ошибки STT/AI | Проверьте ключи в `.env` |
|
||
| Нет звука | Проверьте системное устройство вывода и утилиты `pactl`/`amixer` |
|
||
| Не играет будильник/таймер | Убедитесь, что установлен `mpg123` |
|
||
| Spotify не управляется | Проверьте `SPOTIFY_*`, авторизацию и наличие активного устройства |
|
||
|
||
## 📄 Лицензия
|
||
|
||
MIT, см. [LICENSE.txt](LICENSE.txt).
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Если вам понравился проект, поставьте ⭐ звезду!**
|
||
|
||
</div> |