# Configuration

This page is the authoritative map of all NovaSDR configuration keys. Values and behavior mirror the backend implementation.

> [!NOTE]
> NovaSDR was previously called "PhantomSDR-Plus". Some legacy identifiers may appear in logs. Functionality is unchanged.

---

## Contents

- How the config is structured
- Minimal valid example
- Sections and keys
  - [server]
  - [websdr]
  - [limits]
  - [input]
  - [input.driver]
  - [input.defaults]
- Choosing safe values
- Known compile-time options

---

## How the config is structured

A single TOML file (default: `config.toml`) contains all settings. The backend loads it on startup and fails fast on invalid or missing required keys.

- File loading and validation happen in [`main()`](../../src/spectrumserver.cpp:489).
- Runtime defaults and constraints are enforced in [`broadcast_server::broadcast_server()`](../../src/spectrumserver.cpp:51).

```mermaid
graph TD
  A[config.toml] --> B[Load and validate]
  B --> C[Apply defaults]
  C --> D[Initialize FFT and streams]
  D --> E[Start WebSockets and serve UI]
```

---

## Minimal valid example

This is the smallest known-good configuration that will start the server. Adjust values to fit your setup.

```toml
[server]
port = 9002
html_root = "frontend/dist/"
otherusers = 1
threads = 1

[websdr]
register_online = false
name = "NovaSDR"
antenna = "Discone"
grid_locator = "JO62"
hostname = ""
operator = "ChangeThis"
email = "example@test.com"
callsign_lookup_url = "https://www.qrz.com/db/"
chat_enabled = true

[limits]
audio = 100
waterfall = 200
events = 200

[input]
sps = 2048000
frequency = 100900000
signal = "iq"
fft_size = 131072
fft_threads = 1
brightness_offset = 0
audio_sps = 12000
waterfall_size = 1024
waterfall_compression = "zstd"
audio_compression = "flac"
accelerator = "none"
smeter_offset = 0

[input.driver]
name = "stdin"
format = "u8"

[input.defaults]
frequency = 100900000
modulation = "WBFM"
```

---

## Sections and keys

### [server]

- `port` (int, default: `9002`)  
  TCP listen port.

- `host` (string, default: `"0.0.0.0"`)  
  Bind address.

- `html_root` (string, default: `"html/"`)  
  Directory for static UI files. Use the built frontend path: `frontend/dist/`.

- `otherusers` (int, default: `1`)  
  Show other listeners on the UI (1) or hide them (0).

- `threads` (int, default: `1`)  
  Backend network worker threads.

Example:
```toml
[server]
port = 9002
host = "0.0.0.0"
html_root = "frontend/dist/"
otherusers = 1
threads = 1
```

---

### [websdr]

- `register_online` (bool, default: `false`)  
  Publish station information to https://sdr-list.xyz at intervals.

- `name`, `antenna`, `grid_locator`, `hostname`, `operator`, `email` (strings)  
  Metadata displayed in the UI and used for listing.

- `callsign_lookup_url` (string, default: `"https://www.qrz.com/db/"`)  
  Base URL for callsign lookups from the UI.

- `chat_enabled` (bool, default: `true`)  
  Toggle chat overlay.

Example:
```toml
[websdr]
register_online = false
name = "NovaSDR Station"
antenna = "Discone"
grid_locator = "JO62"
hostname = ""
operator = "DL1ABC"
email = "you@example.com"
callsign_lookup_url = "https://www.qrz.com/db/"
chat_enabled = true
```

Publishing thread implementation: [`broadcast_server::update_websdr_list()`](../../src/spectrumserver.cpp:309)

---

### [limits]

Connection caps per service type:

- `audio` (int, default: `1000`)
- `waterfall` (int, default: `1000`)
- `events` (int, default: `1000`)

Example:
```toml
[limits]
audio = 100
waterfall = 200
events = 200
```

---

### [input] (required)

Core stream parameters:

- `sps` (int, required)  
  Input sample rate in samples per second.

- `frequency` (int, required)  
  Center or baseband frequency in Hz.

- `signal` (string, required)  
  `"iq"` for complex samples or `"real"` for single-channel direct sampling.

- `fft_size` (int, default: `131072`, power of two)  
  Primary FFT size for spectrum and waterfall.

- `fft_threads` (int, default: `1`)  
  FFT worker threads.

- `brightness_offset` (int, default: `0`)  
  Adjust waterfall brightness (negative darkens, positive brightens).

- `audio_sps` (int, default: `12000`)  
  Maximum demod output sample rate.

- `waterfall_size` (int, default: `1024`)  
  Minimum downsampled FFT size for waterfall levels.

- `waterfall_compression` (string, default: `"zstd"`)  
  `"zstd"` or `"av1"` (requires AV1 compiled in).

- `audio_compression` (string, default: `"flac"`)  
  `"flac"` or `"opus"` (requires Opus compiled in).

- `accelerator` (string, default: `"none"`)  
  `"none"`, `"opencl"`, `"cuda"`, `"mkl"`. Startup fails if a requested accelerator is not compiled in.

- `smeter_offset` (int, default: `0`)  
  S-meter calibration offset in dB.

Frequency mapping behavior:
- For `signal = "iq"`, the effective spectrum base equals `frequency - sps / 2`.
- For `signal = "real"`, the spectrum base equals `frequency`.

Used throughout initialization: [`broadcast_server::broadcast_server()`](../../src/spectrumserver.cpp:92)

Example:
```toml
[input]
sps = 2048000
frequency = 100900000
signal = "iq"
fft_size = 131072
fft_threads = 1
brightness_offset = 0
audio_sps = 12000
waterfall_size = 1024
waterfall_compression = "zstd"
audio_compression = "flac"
accelerator = "none"
smeter_offset = 0
```

---

### [input.driver] (required)

- `name` (string, required)  
  `"stdin"` (current supported method).

- `format` (string, required)  
  One of: `u8`, `s8`, `u16`, `s16`, `cs16`, `f32`, `cf32`, `f64`. Must match your capture tool’s output.

Typical mappings:
- rtl_sdr → `u8` (IQ)
- hackrf_transfer → `s8` (IQ)
- airspy_rx → `s16` (IQ)
- rx_sdr driver=sdrplay → `s16` (IQ)
- rx888_stream → `s16` (REAL)

Driver selection is handled in [`main()`](../../src/spectrumserver.cpp:597)

Example:
```toml
[input.driver]
name = "stdin"
format = "u8"
```

---

### [input.defaults]

Initial UI state for new clients:

- `frequency` (int, Hz)
- `modulation` (string) — One of: `AM`, `SAM`, `FM`, `WBFM`, `USB`, `LSB`

Default demod passbands are derived from this mode and the bin mapping:
[`broadcast_server::broadcast_server()`](../../src/spectrumserver.cpp:140)

Example:
```toml
[input.defaults]
frequency = 100900000
modulation = "WBFM"
```

---

## Choosing safe values

> [!TIP]
> If startup fails due to memory or CPU pressure, first reduce `fft_size`, then `sps`.

- Start with `sps = 2048000` and `fft_size = 131072`.  
- Keep `waterfall_compression = "zstd"` and `audio_compression = "flac"` unless you compiled additional codecs.  
- Leave `accelerator = "none"` until you confirm your OpenCL or CUDA runtime is installed and NovaSDR was compiled with that support.  
- Keep `fft_threads = 1` unless you have headroom and measure a benefit.

---

## Known compile-time options

If you request these but the backend was not compiled with them, NovaSDR exits early with a clear log message:

- `audio_compression = "opus"` requires Opus at build time.  
  Check: [`broadcast_server::broadcast_server()`](../../src/spectrumserver.cpp:183)

- `waterfall_compression = "av1"` requires AV1 at build time.  
  Check: [`broadcast_server::broadcast_server()`](../../src/spectrumserver.cpp:172)

- `accelerator = "opencl"` or `"cuda"` or `"mkl"` require those backends at build time.  
  Selection: [`broadcast_server::broadcast_server()`](../../src/spectrumserver.cpp:194)