smart-speaker/README.md

Alexander Smart Speaker

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

Что это

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

Возможности

• Активация по wake word Alexandr (Porcupine).
• Непрерывный follow-up режим после активации (без повторного 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).
• Мини-игра "Города".

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

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)

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

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

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

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

cp .env.example .env

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

PERPLEXITY_API_KEY=...
DEEPGRAM_API_KEY=...
PORCUPINE_ACCESS_KEY=...

4) Запуск

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)

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

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.