New readme

2026-01-24 23:49:02 +03:00
parent d6181cccb7
commit e5047a1297
1 changed files with 111 additions and 74 deletions
--- a/README.md
+++ b/README.md
@@ -1,99 +1,136 @@
-# Умная колонка «Alexandr»
+# 🎙️ Умная колонка «Alexandr»
-Небольшой голосовой ассистент для Linux: реагирует на wake word, распознает речь, обращается к AI, озвучивает ответы, умеет переводить и работать с будильником.
+![Python](https://img.shields.io/badge/Python-3.9%2B-blue?logo=python&logoColor=white)
 ![Platform](https://img.shields.io/badge/Platform-Linux-linux?logo=linux&logoColor=white)
 ![License](https://img.shields.io/badge/License-MIT-green)
-## Возможности
+**Alexandr** — это персональный голосовой ассистент для Linux, объединяющий современные нейросетевые технологии для создания естественного диалога. Он слушает, понимает, переводит, рассказывает о погоде и следит за временем.
 - Wake word: «Alexandr» (Porcupine).
 - Распознавание речи (Deepgram, RU/EN).
 - Озвучка (Silero TTS, RU/EN).
 - Перевод RU↔EN (Perplexity).
 - Будильник с голосовым отключением.
 - Таймер с голосовым отключением.
 - Управление громкостью (ALSA amixer).
-## Требования
+---
 - Linux
 - Python 3.9+
 - Системные утилиты: `mpg123`, `amixer` (ALSA)
 - Драйверы/библиотеки для микрофона (PortAudio)
-## Установка
+## ✨ Возможности
 ### 🧠 Искусственный интеллект
 *   **Умный диалог**: Поддержка контекста беседы на базе **Perplexity AI** (Llama 3.1).
 *   **Переводчик**: Мгновенный двусторонний перевод (RU ↔ EN) с озвучкой на целевом языке.
 ### 🗣️ Голосовой интерфейс
 *   **Wake Word**: Активация по фразе **«Alexandr»** (технология Porcupine).
 *   **Распознавание речи**: Быстрое и точное STT от **Deepgram**.
 *   **Синтез речи**: Естественная офлайн-озвучка с помощью **Silero TTS**.
 ### 🛠️ Инструменты
 *   **⛅ Погода**: Точный прогноз погоды (текущая, на день, на ближайшие часы) через Open-Meteo.
 *   **⏰ Будильник**: Голосовая установка будильников и таймеров.
 *   **🔊 Управление**: Регулировка громкости системы.
 ---
 ## ⚙️ Установка
 ### 1. Системные требования
 *   OS: Linux
 *   Python 3.9+
 *   Библиотеки: `portaudio19-dev` (для микрофона), `libasound2-dev` (ALSA), `mpg123` (для будильника).
 ### 2. Сборка проекта
 ```bash
 # Клонирование репозитория
 git clone https://github.com/your-username/alexander_smart-speaker.git
 cd alexander_smart-speaker
 # Создание виртуального окружения
 python -m venv venv
 source venv/bin/activate
 # Установка зависимостей
 pip install -r requirements.txt
 ```
-## Настройка окружения
+### 3. Конфигурация
-Создайте `.env` в корне проекта:
+Создайте файл `.env` на основе примера:
 ```bash
 cp .env.example .env
 ```
-PERPLEXITY_API_KEY=...
+
-PERPLEXITY_MODEL=llama-3.1-sonar-small-128k-chat
+Заполните ключи в `.env`:
 ```ini
 # AI & Speech
 PERPLEXITY_API_KEY=pplx-...
 DEEPGRAM_API_KEY=...
 PORCUPINE_ACCESS_KEY=...
 # TTS Settings
 TTS_EN_SPEAKER=en_0
 TTS_RU_SPEAKER=eugene
 # Weather (Координаты вашего города)
 WEATHER_LAT=63.56
 WEATHER_LON=53.69
 WEATHER_CITY=Ухта
 ```
-## Запуск
+---
 ## 🚀 Запуск и Использование
 ```bash
-python main.py
+python run.py
 ```
-## Примеры команд
+### Примеры команд
 - Активировать: «Alexandr»
 - Перевод: «переведи на английский как пройти в библиотеку»
 - Перевод: «переведи с английского» → сказать фразу на английском
 - Громкость: «громкость 5»
 - Будильник: «будильник на 7:30», «разбуди на 8 15»
 - Таймер: «таймер на 6 минут», «поставь будильник через 6 минут»
 - Отмена будильников: «отмени будильник»
 - Отмена таймеров: «отмени таймер»
 - Стоп/сброс: «стоп», «хватит»
-## Объяснение работы
+| Категория | Команда пользователя | Действие |
-1) Система ждет wake word («Alexandr») через Porcupine.
+|-----------|---------------------|----------|
-2) После активации включается распознавание речи (Deepgram).
+| **Активация** | «Alexandr» | Ассистент начинает слушать |
-3) Команда распознается и проверяется на спец‑действия: будильник, громкость, перевод.
+| **Диалог** | «Почему небо голубое?» | Запрос в AI с сохранением контекста |
-4) Если это перевод — отправляется отдельный запрос в Perplexity и результат озвучивается.
+| **Погода** | «Какая сейчас погода?», «Нужен ли зонт?» | Прогноз погоды |
-5) Если это обычный запрос — идет в AI, ответ очищается от разметки и озвучивается.
+| **Перевод** | «Переведи на английский: привет, как дела?» | Перевод и озвучка (EN) |
-6) После ответа включается режим продолжения диалога без повторного wake word.
+| **Будильник** | «Разбуди меня в 7:30», «Поставь таймер на 5 минут» | Установка сигнала |
 | **Громкость** | «Громкость 5», «Громкость 8» | Изменение системной громкости |
 | **Управление** | «Стоп», «Хватит», «Повтори» | Остановка речи или повтор фразы |
-## Архитектурная схема
+---
-```
+
-Микрофон
+## 🏗️ Архитектура
-  │
+
-  ▼
+```mermaid
-Wake word (Porcupine) ──► STT (Deepgram) ──► Логика команд
+graph TD
-                                           │
+    Mic[🎤 Микрофон] --> Wake[Wake Word<br>(Porcupine)]
-                                           ├─► Будильник (alarm.py)
+    Wake -->|Activated| STT[STT<br>(Deepgram)]
-                                           ├─► Громкость (sound_level.py)
+    
-                                           ├─► Перевод (ai.py)
+    STT --> Router{Анализ команды}
-                                           └─► Диалог (ai.py)
+    
-                                           │
+    Router -->|Прогноз| Weather[⛅ Погода<br>(Open-Meteo)]
-                                           ▼
+    Router -->|Время| Alarm[⏰ Будильник/Таймер]
-                                   Очистка текста (cleaner.py)
+    Router -->|Настройки| Vol[🔊 Громкость]
-                                           │
+    Router -->|Перевод| Translator[A↔B Переводчик]
-                                           ▼
+    Router -->|Вопрос| AI[🧠 Perplexity AI]
-                                      TTS (tts.py)
+    
-                                           │
+    Weather --> TTS
-                                           ▼
+    Alarm --> TTS
-                                       Динамик
+    Vol --> TTS
    Translator --> TTS
    AI --> Cleaner[Очистка текста]
    Cleaner --> TTS[🗣️ TTS<br>(Silero)]
    TTS --> Speaker[🔊 Динамик]
 ```
-## Структура проекта
+## 📂 Структура проекта
- `main.py` — основной цикл работы ассистента.
+*   `app/main.py` — Точка входа, основной цикл событий.
- `wakeword.py` — детектор wake word (Porcupine).
+*   `app/audio/` — Модули работы со звуком (STT, TTS, Wake Word).
- `stt.py` — потоковое распознавание речи (Deepgram).
+*   `app/core/` — Логика AI, конфиги, очистка текста.
- `tts.py` — озвучивание (Silero TTS).
+*   `app/features/` — Навыки (Погода, Будильник, Таймер).
- `ai.py` — запросы к Perplexity (чат и перевод).
+*   `assets/` — Модели (Porcupine) и звуки.
- `cleaner.py` — очистка ответа и преобразование чисел (RU).
+*   `data/` — Сохранение состояния (будильники).
 - `alarm.py` — будильник и логика расписания.
 - `sound_level.py` — управление громкостью.
-## Частые проблемы
+---
 - Ошибка Deepgram 400: проверьте `DEEPGRAM_API_KEY` и доступность модели.
 - Нет звука: проверьте `amixer` и настройки ALSA.
 - Будильник не играет: установите `mpg123`.
-## Лицензия
+## 🛠️ Решение проблем
-См. `LICENSE.txt`.
+- **Ошибка Deepgram 400**: Проверьте баланс и правильность `DEEPGRAM_API_KEY`.
 - **Нет звука**: Убедитесь, что `amixer` установлен и устройство вывода настроено по умолчанию.
 - **Будильник не играет**: Убедитесь, что установлен `mpg123`.
 ## 📄 Лицензия
 MIT License. См. `LICENSE.txt`.