147 lines
4.5 KiB
Markdown
147 lines
4.5 KiB
Markdown
# 🎙️ Alexander Smart Speaker
|
|
|
|
<div align="center">
|
|
|
|
|
|
|
|
|
|
|
|
**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.
|
|
|
|
[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Architecture](#-architecture)
|
|
|
|
</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:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Fill in your API keys in `.env`:
|
|
```ini
|
|
# AI & Speech APIs
|
|
PERPLEXITY_API_KEY=pplx-...
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Usage
|
|
|
|
Start the assistant:
|
|
```bash
|
|
python run.py
|
|
```
|
|
|
|
### Command Examples
|
|
|
|
| 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]
|
|
```
|
|
|
|
## 📂 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).
|
|
|
|
---
|
|
|
|
## 🛠️ 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.
|