smart-speaker/README.md

🎙️ Alexander Smart Speaker

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

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

Функция	Описание
🔊 Активация по ключевому слову	Активация по команде Alexandr
🧠 Диалог с AI	Взаимодействие с Perplexity с сохранением контекста
🌐 Перевод	Перевод RU ↔ EN с озвучиванием
🌤️ Погода	Информация о погоде по умолчанию и по названию города
⏰ Таймеры и будильники	Управление таймерами, будильниками и секундомерами
🔊 Управление громкостью	Регулировка системной громкости
🎵 Spotify интеграция	Управление воспроизведением (play/pause/next/current track)
🌍 Игра в города	Классическая игра в города

🏗️ Архитектура проекта

Диаграмма взаимодействия компонентов

graph TB
    subgraph "Основной цикл (main.py)"
        A[Бесконечный цикл] --> 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+
• Системные пакеты:

sudo apt-get update
sudo apt-get install -y portaudio19-dev libasound2-dev mpg123

💡 Для управления громкостью необходим pactl или amixer (обычно из pulseaudio-utils/alsa-utils).

🚀 Установка

1. Клонируйте репозиторий:

git clone https://github.com/your-username/alexander_smart-speaker.git
cd alexander_smart-speaker

2. Настройте виртуальное окружение:

python -m venv venv
source venv/bin/activate  # или venv\Scripts\activate на Windows
pip install -r requirements.txt

⚙️ Настройка

1. Создайте файл конфигурации:

cp .env.example .env

2. Обязательные переменные окружения:

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):

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

▶️ Запуск

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.

---

Если вам понравился проект, поставьте ⭐ звезду!