sound-analyze/services/api

services/api

Назначение

FastAPI‑сервис поверх TimescaleDB, который предоставляет REST‑доступ к аудио‑метрикам и агрегированным статистикам.

Основные endpoint’ы

• GET /api/v1/audio/latest?limit=100

  • Возвращает последние N точек audio_data.

• GET /api/v1/audio/range?from=<ts>&to=<ts>

  • Данные за заданный интервал, проверка from < to.

• GET /api/v1/stats/summary?period=1h

  • Агрегированная статистика (avg/max/min по dB, доминантная частота, процент тишины) по окну (10s|1m|1h|6h|24h|7d|30d).

• GET /api/v1/events/loud?threshold=-35&from=<ts>&to=<ts>

  • “Громкие” события, где rms_db выше порога, опционально с интервалом времени.

• GET /api/v1/export/csv?from=<ts>&to=<ts>

  • Экспорт диапазона в CSV: time,rms_db,frequency_hz,is_silence.

• GET /api/v1/health/live / ready

  • Примитивный healthcheck и проверка доступности БД.

Модель данных

Таблица audio_data в TimescaleDB:

CREATE TABLE audio_data (
    time TIMESTAMPTZ NOT NULL,
    rms_db REAL CHECK (rms_db >= -50.0 AND rms_db <= 0.0),
    frequency_hz INTEGER CHECK (frequency_hz >= 100 AND frequency_hz <= 8000),
    is_silence BOOLEAN NOT NULL DEFAULT FALSE
);

Плюс continuous aggregate audio_data_1min и политики retention/refresh.