Update assistant features and docs

2026-02-12 14:12:37 +03:00
parent bb3133a1c0
commit ca8ebd6657
19 changed files with 814 additions and 180 deletions
--- a/README.md
+++ b/README.md
@@ -1,146 +1,122 @@
-# 🎙️ Alexander Smart Speaker
+# Alexander Smart Speaker

-<div align="center">
+Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков.

-![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white&style=for-the-badge)
-![Platform](https://img.shields.io/badge/Platform-Linux-FCC624?logo=linux&logoColor=black&style=for-the-badge)
-![License](https://img.shields.io/badge/License-MIT-45a163?style=for-the-badge)
+## Что умеет
+- Активация по ключевому слову `Alexandr`.
+- Диалог с AI (Perplexity) с сохранением контекста.
+- Перевод RU ↔ EN с озвучиванием.
+- Погода по умолчанию и по названию города.
+- Будильники, таймеры и секундомеры.
+- Управление громкостью системы.
+- Управление Spotify (play/pause/next/current track).
+- Игра в города.

-**Alexander** is a personal voice assistant for Linux that leverages modern AI technologies to create natural conversations. It listens, understands context, translates languages, checks the weather, and manages your time.
+## Технологии
+- Wake word: `pvporcupine`
+- STT: `deepgram-sdk`
+- TTS: `Silero` (`torch`, `torchaudio`)
+- AI: Perplexity API
+- Погода: Open-Meteo
+- Музыка: Spotify Web API (`spotipy`)

-[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Architecture](#-architecture)
+## Требования
+- 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`).
+
+## Установка

-</div>
-
---
-
-## ✨ Features
-
-### 🧠 Artificial Intelligence
-*   **Smart Dialogue**: Context-aware conversations powered by **Perplexity AI** (Llama 3.1).
-*   **Translator**: Instant bidirectional translation (RU ↔ EN) with native pronunciation.
-
-### 🗣️ Voice Interface
-*   **Wake Word**: Activates on the phrase **"Alexander"** (powered by Porcupine).
-*   **Speech Recognition**: Fast and accurate Speech-to-Text via **Deepgram**.
-*   **Text-to-Speech**: Natural sounding offline voice synthesis using **Silero TTS**.
-
-### 🛠️ Tools
-*   **⛅ Weather**: Detailed forecasts (current, daily range, hourly) via Open-Meteo.
-*   **⏰ Alarm & Timer**: Voice-controlled alarms and timers.
-*   **🔊 System Control**: Adjust system volume via voice commands.
-
---
-
-## ⚙️ Installation
-
-### 1. Prerequisites
-*   **OS**: Linux
-*   **Python**: 3.9+
-*   **System Libraries**:
-    ```bash
-    sudo apt-get install portaudio19-dev libasound2-dev mpg123
-    ```
-
-### 2. Setup
 ```bash
-# Clone the repository
 git clone https://github.com/your-username/alexander_smart-speaker.git
 cd alexander_smart-speaker

-# Create virtual environment
 python -m venv venv
 source venv/bin/activate
-
-# Install dependencies
 pip install -r requirements.txt
 ```

-### 3. Configuration
-Create a `.env` file based on the example:
+## Настройка `.env`
+
 ```bash
 cp .env.example .env
 ```

-Fill in your API keys in `.env`:
+Минимально обязательные переменные:
+
 ```ini
-# AI & Speech APIs
-PERPLEXITY_API_KEY=pplx-...
+PERPLEXITY_API_KEY=...
 DEEPGRAM_API_KEY=...
 PORCUPINE_ACCESS_KEY=...
-
-# TTS Settings
-TTS_EN_SPEAKER=en_0
-TTS_RU_SPEAKER=eugene
-
-# Weather Location (Your City Coordinates)
-WEATHER_LAT=63.56
-WEATHER_LON=53.69
-WEATHER_CITY=Ukhta
 ```

---
+Полный пример (как в `.env.example`):

-## 🚀 Usage
+```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
+```
+
+## Запуск

-Start the assistant:
 ```bash
+make run
+# или
 python run.py
 ```

-### Command Examples
+## Примеры голосовых команд
+- Активация: `Alexandr`
+- Диалог: `Почему небо голубое?`
+- Погода: `Какая сейчас погода?`, `Погода в Москве`
+- Перевод: `Переведи на английский: как дела`
+- Таймер: `Поставь таймер на 5 минут`
+- Будильник: `Поставь будильник на 7:30`, `Будильник по будням в 8:00`
+- Секундомер: `Запусти секундомер`, `Покажи активные секундомеры`
+- Громкость: `Громкость 5`
+- Spotify: `Включи музыку`, `Пауза`, `Что сейчас играет`
+- Игра: `Давай сыграем в города`
+- Остановка/прерывание: `Стоп`, `Хватит`, `Повтори`

-| Category | User Command (RU) | Action |
-|----------|-------------------|--------|
-| **Activation** | "Alexander" | Assistant starts listening |
-| **Dialogue** | "Почему небо голубое?" | Ask AI with context retention |
-| **Weather** | "Какая сейчас погода?", "Нужен ли зонт?" | Get weather forecast |
-| **Translation** | "Переведи на английский: привет, как дела?" | Translate and speak in EN |
-| **Alarm** | "Разбуди меня в 7:30", "Поставь таймер на 5 минут" | Set alarm or timer |
-| **Volume** | "Громкость 5", "Громкость 8" | Set system volume level |
-| **Control** | "Стоп", "Хватит", "Повтори" | Stop speech or repeat last phrase |
+## Полезные команды

---
-
-## 🏗️ Architecture
-
-```mermaid
-graph TD
-    Mic[🎤 Microphone] --> Wake[Wake Word<br/>Porcupine]
-    Wake -->|Activated| STT[STT<br/>Deepgram]
-    
-    STT --> Router{Command Router}
-    
-    Router -->|Forecast| Weather[⛅ Weather<br/>Open-Meteo]
-    Router -->|Time| Alarm[⏰ Alarm/Timer]
-    Router -->|Settings| Vol[🔊 Volume]
-    Router -->|Translate| Translator[A↔B Translator]
-    Router -->|Query| AI[🧠 Perplexity AI]
-
-    Weather --> TTS
-    Alarm --> TTS
-    Vol --> TTS
-    Translator --> TTS
-    AI --> Cleaner[Text Cleaner]
-    Cleaner --> TTS[🗣️ TTS<br/>Silero]
-
-    TTS --> Speaker[🔊 Speaker]
+```bash
+make run          # запуск ассистента
+make check        # базовая проверка проекта
+make qwen-context # собрать контекст проекта
 ```

-## 📂 Project Structure
-*   `app/main.py` — Entry point, main event loop.
-*   `app/audio/` — Audio processing modules (STT, TTS, Wake Word).
-*   `app/core/` — AI logic, configuration, text cleaning.
-*   `app/features/` — Skills (Weather, Alarm, Timer).
-*   `assets/` — Models (Porcupine) and sound effects.
-*   `data/` — Persistent state (alarms).
+## Структура проекта
+- `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_*`, авторизацию и наличие активного устройства.

-## 🛠️ Troubleshooting
-*   **Deepgram Error 400**: Check your API key balance and validity in `.env`.
-*   **No Sound**: Ensure `amixer` is installed and the default audio output is correctly configured in your OS.
-*   **Alarm not playing**: Verify that `mpg123` is installed (`sudo apt install mpg123`).
-
-## 📄 License
-MIT License. See `LICENSE.txt` for details.
+## Лицензия
+MIT, см. `LICENSE.txt`.