<div align="center">

# 🎙️ Alexander Smart Speaker

**Голосовой ассистент для Linux с wake word, STT/TTS и набором голосовых навыков**

[![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)

</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** | `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>