voice-server/OPERATIONS.md

# Voice Server Operations Guide

## Service Management

The voice server runs as a user systemd service and auto-starts on boot.

### Status

```bash
# Check if service is running
systemctl --user status voice-server

# Check if service is enabled (auto-start)
systemctl --user is-enabled voice-server
```

### Start / Stop / Restart

```bash
# Start the service
systemctl --user start voice-server

# Stop the service
systemctl --user stop voice-server

# Restart the service
systemctl --user restart voice-server

# Reload after config changes (without full restart)
systemctl --user reload voice-server
```

### Enable / Disable Auto-Start

```bash
# Enable auto-start on boot
systemctl --user enable voice-server

# Disable auto-start
systemctl --user disable voice-server

# Enable and start immediately
systemctl --user enable --now voice-server
```

## Logs

```bash
# View recent logs
journalctl --user -u voice-server

# Follow logs in real-time
journalctl --user -u voice-server -f

# View logs since last boot
journalctl --user -u voice-server -b

# View last 50 lines
journalctl --user -u voice-server -n 50
```

## Health Check

```bash
# Quick health check
curl -s http://localhost:8888/health | python3 -m json.tool

# Check specific fields
curl -s http://localhost:8888/health | jq '.status'
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/notify` | POST | Submit text for TTS playback |
| `/health` | GET | Health check with system status |
| `/voices` | GET | List available voice models |
| `/docs` | GET | Swagger UI documentation |

### Example: Send TTS Request

```bash
curl -X POST http://localhost:8888/notify \
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello, this is a test"}'
```

### Example: Send with Options

```bash
curl -X POST http://localhost:8888/notify \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Speaking at a different rate",
    "rate": 200,
    "voice": "en_US-lessac-high"
  }'
```

### Example: Urgent Message (Higher Volume)

```bash
curl -X POST http://localhost:8888/notify \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Critical alert! Immediate attention required.",
    "urgent": true
  }'
```

The `urgent` flag plays audio at 1.5x volume for critical messages.

## Configuration

Configuration is via environment variables. Edit the service file or create a `.env` file:

```bash
# Copy example config
cp .env.example .env

# Edit configuration
nano .env
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `HOST` | `0.0.0.0` | Bind address |
| `PORT` | `8888` | Listen port |
| `MODEL_DIR` | `./models` | Voice model directory |
| `DEFAULT_VOICE` | `en_US-lessac-medium` | Default voice model |
| `DEFAULT_RATE` | `170` | Default speech rate (WPM) |
| `QUEUE_MAX_SIZE` | `50` | Maximum queue size |
| `LOG_LEVEL` | `INFO` | Logging level |

## Troubleshooting

### Service Won't Start

```bash
# Check for errors
journalctl --user -u voice-server -n 100 --no-pager

# Verify paths exist
ls -la /mnt/NV2/Development/voice-server/.venv/bin/uvicorn

# Test manually
cd /mnt/NV2/Development/voice-server
.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8888
```

### No Audio Output

```bash
# Check audio devices
python3 -c "import sounddevice; print(sounddevice.query_devices())"

# Check PulseAudio/PipeWire is running
pactl info

# Verify PortAudio is installed
rpm -q portaudio  # Fedora/RHEL
dpkg -l portaudio19-dev  # Debian/Ubuntu
```

### Port Already in Use

```bash
# Find what's using port 8888
lsof -i :8888

# Kill the process if needed
kill $(lsof -t -i :8888)
```

### Voice Model Not Found

```bash
# List installed models
ls -la /mnt/NV2/Development/voice-server/models/

# Download a model
cd /mnt/NV2/Development/voice-server/models/
curl -LO "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx"
curl -LO "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json"
```

## Development

### Run Tests

```bash
cd /mnt/NV2/Development/voice-server
.venv/bin/pytest tests/ -v
```

### Run in Development Mode

```bash
# Stop the service first
systemctl --user stop voice-server

# Run with auto-reload
.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --port 8888
```

### Update Dependencies

```bash
cd /mnt/NV2/Development/voice-server
source .venv/bin/activate
uv pip install -e ".[dev]"
```