Configuration

Environment Variables Reference

Sound Suite is configured through environment variables in a .env file at the project root. Here is the complete reference:

Core Settings

Variable	Default	Description
`PORT`	`3000`	Dashboard web server port
`MCP_PORT`	`3001`	MCP server port
`DATABASE_URL`	`file:./data/sound-suite.db`	SQLite database path (relative to prisma/)
`NODE_ENV`	`development`	Environment mode (`development` or `production`)

Embedding Configuration

Variable	Default	Description
`EMBEDDING_PROVIDER`	`transformers`	Provider: `transformers`, `ollama`, `openai`, or `anthropic`
`EMBEDDING_MODEL`	`Xenova/all-MiniLM-L6-v2`	Model name for the selected provider
`EMBEDDING_DIMENSIONS`	`384`	Vector dimensions (must match model output)
`OLLAMA_BASE_URL`	`http://localhost:11434`	Ollama API endpoint
`OPENAI_API_KEY`	—	OpenAI API key (required for openai provider)
`ANTHROPIC_API_KEY`	—	Anthropic API key (required for anthropic provider)

Processing Settings

Variable	Default	Description
`JOB_CONCURRENCY`	`2`	Number of documents processed simultaneously
`JOB_MAX_RETRIES`	`3`	Maximum retry attempts for failed documents
`OCR_ENABLED`	`true`	Enable OCR for scanned/low-density pages
`OCR_DENSITY_THRESHOLD`	`50`	Characters per page below which OCR is triggered
`CHUNK_SIZE`	`512`	Target tokens per text chunk
`CHUNK_OVERLAP`	`50`	Overlap tokens between consecutive chunks

MCP Server

Variable	Default	Description
`MCP_AUTH_MODE`	`none`	Authentication mode: `none`, `apikey`, or `oauth`
`MCP_API_KEY`	—	API key for `apikey` auth mode
`MCP_ALLOWED_ORIGINS`	`*`	CORS allowed origins

File Watching

Variable	Default	Description
`WATCH_PATHS`	—	Comma-separated list of directories to monitor
`WATCH_POLL_INTERVAL`	`1000`	Polling interval in ms (for network drives)
`WATCH_IGNORE_PATTERNS`	`.DS_Store,Thumbs.db`	File patterns to ignore

Watch Paths

Watch paths tell Sound Suite which directories to monitor for new PDF files. Each watched directory is typically associated with a case.

Setting Up Watch Paths

You can configure watch paths in two ways:

1. Through the Dashboard

Navigate to Case Management and click + to create a new case. Select the directory containing your case files. The watch path is automatically configured.

2. Through Environment Variables

# In .env file
WATCH_PATHS=/Users/you/Documents/cases/case-001,/Users/you/Documents/cases/case-002

How File Watching Works

Sound Suite uses chokidar for cross-platform file system monitoring
New PDF files are detected within seconds of being added
Modified files are re-processed (tracked by SHA-256 hash)
Subdirectories are watched recursively
Non-PDF files are ignored
The file watcher runs as a background service

Network Drives

For files on network drives (NAS, cloud storage mounts), enable polling mode:

WATCH_POLL_INTERVAL=2000  # Check every 2 seconds

Embedding Providers

Sound Suite supports multiple embedding providers. Choose based on your privacy requirements, performance needs, and available hardware.

Local: Transformers.js (Default)

Runs entirely on your machine using ONNX models. No API keys needed.

EMBEDDING_PROVIDER=transformers
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
EMBEDDING_DIMENSIONS=384

Pros: Completely private, no API costs, works offline
Cons: Slower on CPU-only machines, limited model selection

Local: Ollama

Uses Ollama for local embedding generation with larger models.

EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=qwen3-embedding:0.6b
EMBEDDING_DIMENSIONS=1024
OLLAMA_BASE_URL=http://localhost:11434

Pros: GPU-accelerated, high-quality embeddings, many model options
Cons: Requires Ollama installed separately, uses more memory

Cloud: OpenAI

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536
OPENAI_API_KEY=sk-...

Cloud: Anthropic

EMBEDDING_PROVIDER=anthropic
EMBEDDING_MODEL=claude-embed-1
EMBEDDING_DIMENSIONS=1024
ANTHROPIC_API_KEY=sk-ant-...

Changing Providers

You can change embedding providers at any time through the Admin panel. Navigate to Admin > Embedding to select a provider and model. Note that changing providers requires re-indexing existing documents since different models produce incompatible vectors.

MCP Server & Auth

The MCP server exposes Sound Suite's analysis tools to AI assistants. Configure authentication based on your security requirements.

No Authentication (Default)

Suitable for local-only use when the MCP server is not exposed to a network:

MCP_AUTH_MODE=none

API Key Authentication

Requires clients to include an API key in requests:

MCP_AUTH_MODE=apikey
MCP_API_KEY=your-secret-key-here

Clients include the key in the Authorization header:

curl -X POST http://localhost:3001/api/mcp/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key-here" \
  -d '{"tool": "list_tools", "params": {}}'

OAuth Authentication

For multi-user environments or when exposing the MCP server to a network:

MCP_AUTH_MODE=oauth

Connecting AI Clients

To connect Claude Desktop or other MCP clients, add Sound Suite to your MCP configuration:

{
  "mcpServers": {
    "sound-suite": {
      "url": "http://localhost:3000/api/mcp/execute",
      "transport": "http"
    }
  }
}

The MCP endpoint URL is displayed on the Admin > General page in the dashboard.