my_speaker_RPi3/docs/API_DOCUMENTATION.md

Документация API My Speaker

Общая информация

API My Speaker предоставляет интерфейс для взаимодействия с системой распознавания речи, управления настройками и получения данных о работе системы. API построено на FastAPI и использует REST-подход.

Базовый URL: /api

Аутентификация

Все запросы к API (кроме авторизации) требуют аутентификации. Аутентификация осуществляется с помощью токена доступа, который можно получить через эндпоинт /api/auth/login.

Токен можно передавать одним из следующих способов:

1. В заголовке Authorization: Bearer <token>
2. В параметре запроса ?token=<token>

Эндпоинты аутентификации

Авторизация

POST /api/auth/login

Запрос:

{
  "username": "admin",
  "password": "your_password"
}

Ответ:

{
  "access_token": "unique_session_token",
  "token_type": "bearer"
}

Получение информации о текущем пользователе

GET /api/auth/me

Ответ:

{
  "username": "admin",
  "is_authenticated": true
}

Выход из системы

POST /api/auth/logout

Ответ:

{
  "status": "success",
  "message": "Выход выполнен успешно"
}

Панель управления (Dashboard)

Все запросы к эндпоинтам панели управления выполняются с использованием токена полученного при авторизации.

Получение данных о речи

GET /api/dashboard/speech-data
curl -X 'GET' \
  'http://192.168.200.111:8000/api/dashboard/sys-monitor' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer dc1460d1-6e67-4730-afb2-c94de7d243b4'

**Ответ:**
```json
{
  "state": "listening",
  "speech_prob": 0.85,
  "speech_threshold": 0.5,
  "energy": 1200,
  "energy_threshold": 1000,
  "speech_detected": true,
  "continuous_frames": 5,
  "gain": 1.2,
  "noise_floor": 300
}

Получение данных о нагрузке системы

GET /api/dashboard/sys-monitor

Ответ:

{
  "cpu_percent": 25.5,
  "memory_percent": 40.2,
  "temperature": 45.3
}

Получение последних распознанных фраз

GET /api/dashboard/recent-phrases?limit=10

Ответ:

[
  {
    "text": "включи свет",
    "timestamp": "2023-06-15T14:30:45",
    "is_command": true
  },
  {
    "text": "какая погода сегодня",
    "timestamp": "2023-06-15T14:29:30",
    "is_command": false
  }
]

Получение статистики работы системы

GET /api/dashboard/stats

Ответ:

{
  "uptime": "2:30:15",
  "recognized_commands": 15,
  "total_phrases": 45
}

Настройки (Settings)

Все запросы к эндпоинтам настроек выполняются с использованием токена полученного при авторизации.

Получение всех настроек

GET /api/settings

Ответ:

{
  "vad": {
    "mode": 3,
    "sample_rate": 16000,
    "frame_duration_ms": 30,
    "ring_buffer_size": 20,
    "speech_threshold": 0.5,
    "energy_threshold": 1000,
    "min_speech_duration_ms": 300,
    "record_stop_delay_sec": 1.0,
    "prebuffer_duration_sec": 1.0,
    "max_record_duration_sec": 5.0,
    "target_rms": 2000.0,
    "max_gain": 5.0,
    "noise_reduction_factor": 1.5,
    "noise_update_alpha": 0.05,
    "min_rms_threshold_factor": 2.0,
    "gain_smoothing_alpha": 0.1,
    "adaptive_energy_std_factor": 2.5,
    "adaptive_energy": true,
    "noise_reduction_enabled": true,
    "auto_gain_enabled": true,
    "record_on_speech": true
  },
  "system": {
    "history_maxlen": 100,
    "polling_interval_ms": 500,
    "logging_level": "INFO",
    "log_file": "logs/app.log",
    "log_save_file": true
  },
  "stt": {
    "model_path": "/path/to/vosk/model"
  },
  "commands": {
    "commands_file": "commands/commands.yaml"
  },
  "auth": {
    "username": "admin",
    "password": "admin"
  }
}

Обновление настроек VAD

PUT /api/settings/vad

Запрос:

{
  "mode": 3,
  "speech_threshold": 0.7,
  "energy_threshold": 1200
}

Ответ:

{
  "mode": 3,
  "sample_rate": 16000,
  "frame_duration_ms": 30,
  "ring_buffer_size": 20,
  "speech_threshold": 0.7,
  "energy_threshold": 1200,
  "min_speech_duration_ms": 300,
  "record_stop_delay_sec": 1.0,
  "prebuffer_duration_sec": 1.0,
  "max_record_duration_sec": 5.0,
  "target_rms": 2000.0,
  "max_gain": 5.0,
  "noise_reduction_factor": 1.5,
  "noise_update_alpha": 0.05,
  "min_rms_threshold_factor": 2.0,
  "gain_smoothing_alpha": 0.1,
  "adaptive_energy_std_factor": 2.5,
  "adaptive_energy": true,
  "noise_reduction_enabled": true,
  "auto_gain_enabled": true,
  "record_on_speech": true
}

Обновление системных настроек

PUT /api/settings/system

Запрос:

{
  "history_maxlen": 200,
  "polling_interval_ms": 1000
}

Ответ:

{
  "history_maxlen": 200,
  "polling_interval_ms": 1000,
  "logging_level": "INFO",
  "log_file": "logs/app.log",
  "log_save_file": true
}

Обновление настроек STT

PUT /api/settings/stt

Запрос:

{
  "model_path": "/new/path/to/vosk/model"
}

Ответ:

{
  "model_path": "/new/path/to/vosk/model"
}

Обновление настроек команд

PUT /api/settings/commands

Запрос:

{
  "commands_file": "commands/new_commands.yaml"
}

Ответ:

{
  "commands_file": "commands/new_commands.yaml"
}

Обновление настроек авторизации

PUT /api/settings/auth

Запрос:

{
  "username": "new_admin",
  "password": "new_password"
}

Ответ:

{
  "username": "new_admin",
  "password": "new_password"
}

Перезапуск VAD и STT

POST /api/settings/restart

Ответ:

{
  "status": "success",
  "message": "VAD и STT перезапущены"
}

Коды ошибок

• 401 Unauthorized - Ошибка авторизации
• 500 Internal Server Error - Внутренняя ошибка сервера

Примечания

• Все запросы и ответы используют формат JSON
• Для всех запросов, требующих авторизации, необходимо передавать токен доступа
• Параметры в запросах на обновление настроек являются опциональными, можно передавать только те параметры, которые нужно изменить