Доработка документации

internal/audio/monitor.go

@@ -1,3 +1,7 @@
+// Package audio измеряет уровень звука с микрофона через arecord (ALSA):
+// USB-устройство находится автоматически, PCM-поток читается блоками по 100 мс,
+// уровень считается как RMS и публикуется по шкале 0–100 (поле sound_level
+// в /api/health). Падение arecord не фатально — захват перезапускается.
 package audio
 
 import (
@@ -15,6 +19,7 @@ import (
     "time"
 )
 
+// Monitor — фоновый измеритель уровня звука с микрофона.
 type Monitor struct {
     mu           sync.RWMutex
     currentLevel int
@@ -22,16 +27,21 @@ type Monitor struct {
     wg           sync.WaitGroup
 }
 
+// NewMonitor создаёт монитор; захват запускается отдельным вызовом Start.
 func NewMonitor() *Monitor {
     return &Monitor{}
 }
 
+// GetLevel возвращает текущий уровень звука по шкале 0–100
+// (RMS/32768 × 100 × 4 с отсечкой сверху); 0 — если захват не работает.
 func (m *Monitor) GetLevel() int {
     m.mu.RLock()
     defer m.mu.RUnlock()
     return m.currentLevel
 }
 
+// Start запускает захват звука в фоне. Ошибка (микрофон недоступен) не
+// критична для вызывающего кода — сервер продолжает работать без звука.
 func (m *Monitor) Start() error {
     ctx, cancel := context.WithCancel(context.Background())
     m.cancel = cancel
@@ -156,6 +166,8 @@ func (m *Monitor) handleCrash(ctx context.Context) {
     }
 }
 
+// findUSBDevice выбирает ALSA-устройство по выводу arecord -l: сначала USB-аудио,
+// затем любое устройство захвата, иначе "default".
 func (m *Monitor) findUSBDevice() string {
     cmd := exec.Command("arecord", "-l")
     output, err := cmd.Output()
@@ -201,6 +213,7 @@ func (m *Monitor) findUSBDevice() string {
     return "default"
 }
 
+// Stop останавливает захват и дожидается завершения горутины чтения.
 func (m *Monitor) Stop() {
     if m.cancel != nil {
         m.cancel()