Skip to content

Configuration

Jump to bottom
magicint1337 edited this page Sep 5, 2025 · 3 revisions

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.

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]
Loading

Minimal valid example

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

[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:

[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:

[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()

[limits]

Connection caps per service type:

  • audio (int, default: 1000)
  • waterfall (int, default: 1000)
  • events (int, default: 1000)

Example:

[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()

Example:

[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()

Example:

[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()

Example:

[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:

Clone this wiki locally