From df61febe289a78dbdf03ccca414186caf903fe04 Mon Sep 17 00:00:00 2001 From: future Date: Sun, 15 Feb 2026 12:48:33 +0300 Subject: [PATCH] Update README.md with architecture diagram Co-authored-by: Qwen-Coder --- README.md | 279 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 215 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 4ebee0a..d08fee4 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,193 @@ -# Alexander Smart Speaker +
-Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков. +# 🎙️ Alexander Smart Speaker -## Что умеет -- Активация по ключевому слову `Alexandr`. -- Диалог с AI (Perplexity) с сохранением контекста. -- Перевод RU ↔ EN с озвучиванием. -- Погода по умолчанию и по названию города. -- Будильники, таймеры и секундомеры. -- Управление громкостью системы. -- Управление Spotify (play/pause/next/current track). -- Игра в города. +**Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков** -## Технологии -- Wake word: `pvporcupine` -- STT: `deepgram-sdk` -- TTS: `Silero` (`torch`, `torchaudio`) -- AI: Perplexity API -- Погода: Open-Meteo -- Музыка: Spotify Web API (`spotipy`) +[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) +[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](https://www.linux.org/) +[![License](https://img.shields.io/github/license/your-username/alexander_smart-speaker)](LICENSE.txt) -## Требования -- 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
- wait_for_wakeword
- check_wakeword_once] + E1[stt.py
- listen
- get_recognizer] + G1[tts.py
- speak
- initialize] + H1[sound_level.py
- parse_volume_text
- set_volume] + + C1 -.-> E1 + E1 -.-> G1 + H1 -.-> G1 + end + + subgraph "Ядро (app/core/)" + F1[commands.py
- is_stop_command
- _normalize_text] + F2[ai.py
- ask_ai_stream
- translate_text] + F3[cleaner.py
- clean_response] + F4[config.py
- Настройки проекта] + F5[smalltalk.py
- get_smalltalk_response] + + F --> F1 + F --> F2 + F --> F3 + F --> F5 + end + + subgraph "Функции (app/features/)" + I1[weather.py
- get_weather_report] + I2[timer.py
- get_timer_manager] + I3[alarm.py
- get_alarm_clock] + I4[stopwatch.py
- get_stopwatch_manager] + I5[music.py
- get_music_controller] + I6[cities_game.py
- 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 + +``` + +## 🛠️ Технологии + +| Компонент | Технология | +|-----------|------------| +| **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`). +> 💡 Для управления громкостью необходим `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 +source venv/bin/activate # или venv\Scripts\activate на Windows pip install -r requirements.txt ``` -## Настройка `.env` +## ⚙️ Настройка +1. **Создайте файл конфигурации**: ```bash cp .env.example .env ``` -Минимально обязательные переменные: +2. **Обязательные переменные окружения**: ```ini -PERPLEXITY_API_KEY=... -DEEPGRAM_API_KEY=... -PORCUPINE_ACCESS_KEY=... +PERPLEXITY_API_KEY=your_perplexity_api_key_here +DEEPGRAM_API_KEY=your_deepgram_api_key_here +PORCUPINE_ACCESS_KEY=your_porcupine_access_key_here ``` -Полный пример (как в `.env.example`): +3. **Полная конфигурация** (как в `.env.example`): ```ini 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 ``` -## Запуск +## ▶️ Запуск ```bash make run @@ -82,41 +212,62 @@ make run 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`. -- Не играет будильник/таймер: убедитесь, что установлен `mpg123`. -- Spotify не управляется: проверьте `SPOTIFY_*`, авторизацию и наличие активного устройства. +| Проблема | Решение | +|----------|---------| +| Ошибки STT/AI | Проверьте ключи в `.env` | +| Нет звука | Проверьте системное устройство вывода и утилиты `pactl`/`amixer` | +| Не играет будильник/таймер | Убедитесь, что установлен `mpg123` | +| Spotify не управляется | Проверьте `SPOTIFY_*`, авторизацию и наличие активного устройства | -## Лицензия -MIT, см. `LICENSE.txt`. +## 📄 Лицензия + +MIT, см. [LICENSE.txt](LICENSE.txt). + +--- + +
+ +**Если вам понравился проект, поставьте ⭐ звезду!** + +
\ No newline at end of file