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

# 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

# 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

# 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

# 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

# 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

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

Example: Send with Options

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-medium"
  }'

Configuration

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

# 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

# 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

# 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

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

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

Voice Model Not Found

# 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

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

Run in Development Mode

# 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

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