# Alexander Smart Speaker

<div align="center">

Голосовой ассистент для Linux: wake word, STT/TTS, AI-диалог и полезные голосовые навыки.

[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Linux](https://img.shields.io/badge/Platform-Linux-FCC624?logo=linux&logoColor=111)](https://www.linux.org/)
[![MIT License](https://img.shields.io/badge/License-MIT-2ea44f)](LICENSE.txt)
[![Wake Word](https://img.shields.io/badge/Wake%20Word-Porcupine-0b7285)](https://picovoice.ai/platform/porcupine/)
[![STT](https://img.shields.io/badge/STT-Deepgram-4c6ef5)](https://deepgram.com/)
[![TTS](https://img.shields.io/badge/TTS-Silero-7950f2)](https://github.com/snakers4/silero-models)

</div>

## Что это

`Alexander Smart Speaker` слушает ключевое слово `Alexandr`, распознает речь, маршрутизирует команду в нужный модуль и озвучивает ответ.
Проект оптимизирован под русский язык, но поддерживает RU/EN сценарии (включая перевод и mixed-language TTS).

## Возможности

- Активация по wake word `Alexandr` (Porcupine).
- Follow-up окно 4 секунды после ответа: если пользователь молчит, ассистент возвращается к ожиданию wake word.
- Распознавание речи через Deepgram (WebSocket, VAD, fast stop).
- Озвучка через Silero TTS (RU + EN, с прерыванием по wake word).
- AI-диалог через Perplexity API со streaming-ответом и контекстом.
- Перевод RU -> EN и EN -> RU.
- Погода: текущий прогноз по городу по умолчанию или по названию города.
- Таймеры, будильники (включая будни/выходные), секундомеры.
- Управление громкостью системы (через `pactl`/`amixer`).
- Управление Spotify (play/pause/next/what's playing).
- Мини-игра "Города".

## Как это работает

```mermaid
flowchart TD
    A[Wake Word: Alexandr] --> B[STT: Deepgram]
    B --> C{Маршрутизация команды}
    C --> D[Feature modules]
    C --> E[AI/Translation]
    D --> F[TTS: Silero]
    E --> F
    F --> G[Follow-up режим или ожидание wake word]
```

## Быстрый старт

### 1) Системные зависимости (Ubuntu/Debian)

```bash
sudo apt-get update
sudo apt-get install -y portaudio19-dev libasound2-dev mpg123 pulseaudio-utils alsa-utils
```

### 2) Установка Python-зависимостей

```bash
git clone <URL_ВАШЕГО_РЕПОЗИТОРИЯ>
cd alexander_smart-speaker
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 3) Настройка `.env`

```bash
cp .env.example .env
```

Минимально обязательные переменные:

```ini
PERPLEXITY_API_KEY=...
DEEPGRAM_API_KEY=...
PORCUPINE_ACCESS_KEY=...
```

### 4) Запуск

```bash
make run
# или
python run.py
```

После запуска ассистент перейдет в режим ожидания фразы `Alexandr`.

## Конфигурация `.env`

| Переменная | Обязательно | По умолчанию | Назначение |
|---|---|---|---|
| `PERPLEXITY_API_KEY` | Да | - | Ключ Perplexity API |
| `PERPLEXITY_MODEL` | Нет | `llama-3.1-sonar-small-128k-chat` | Модель Perplexity |
| `DEEPGRAM_API_KEY` | Да | - | Ключ Deepgram STT |
| `PORCUPINE_ACCESS_KEY` | Да | - | Ключ PicoVoice Porcupine |
| `PORCUPINE_SENSITIVITY` | Нет | `0.8` | Чувствительность wake word |
| `TTS_EN_SPEAKER` | Нет | `en_0` | Английский голос TTS |
| `WEATHER_LAT` | Нет | - | Широта города по умолчанию |
| `WEATHER_LON` | Нет | - | Долгота города по умолчанию |
| `WEATHER_CITY` | Нет | `Ухта` | Город по умолчанию для погоды |
| `SPOTIFY_CLIENT_ID` | Нет | - | Spotify OAuth Client ID |
| `SPOTIFY_CLIENT_SECRET` | Нет | - | Spotify OAuth Client Secret |
| `SPOTIFY_REDIRECT_URI` | Нет | `http://localhost:8888/callback` | Redirect URI для Spotify |

## Примеры голосовых команд

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

## Полезные команды

| Команда | Что делает |
|---|---|
| `make run` | Запуск ассистента |
| `make check` | Локальная проверка проекта (`scripts/qwen-check.sh`) |
| `make qwen-context` | Сбор контекста проекта (`scripts/qwen-context.sh`) |

## Структура проекта

```text
alexander_smart-speaker/
├── run.py
├── app/
│   ├── main.py
│   ├── audio/      # wakeword, stt, tts, volume
│   ├── core/       # config, ai, command helpers, cleaner
│   └── features/   # weather, timer, alarm, stopwatch, music, cities game
├── assets/
│   ├── models/     # Porcupine keyword model (.ppn)
│   └── sounds/     # звуки уведомлений и будильника
├── data/           # persisted JSON: alarms, timers, stopwatches
└── scripts/
```

## Диагностика

| Проблема | Что проверить |
|---|---|
| Не реагирует на `Alexandr` | `PORCUPINE_ACCESS_KEY`, микрофон, чувствительность `PORCUPINE_SENSITIVITY` |
| STT не распознает речь | `DEEPGRAM_API_KEY`, сетевой доступ, выбранный микрофон |
| Нет звука | корректное аудиоустройство и доступность `pactl`/`amixer` |
| Будильник/таймер не звонит | наличие `mpg123` в системе |
| Spotify не управляется | заполнены `SPOTIFY_*`, есть активное устройство, Premium-аккаунт |

## Лицензия

Проект распространяется по лицензии MIT. См. `LICENSE.txt`.