Skip to content

FAQ

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

FAQ

Answers to common questions about installing, configuring, and running NovaSDR. These answers reflect the actual runtime behavior of the backend and UI.

Note

NovaSDR was previously named "PhantomSDR-Plus". You may still see legacy identifiers (for example, "PhantomSDR+ v2.0.0") in logs; they will be harmonized over time.

General

What is NovaSDR?

NovaSDR is a web-enabled SDR server written in C++. It ingests raw samples (IQ or real) from stdin and exposes spectrum/waterfall and audio over WebSockets. It serves a Svelte-based UI as static files from server.html_root.

Do I need Apache or Nginx?

No. NovaSDR serves the built frontend itself. Just point [server].html_root to your built frontend/dist/, start the server, and open the printed address (default http://localhost:9002).

Setup & Build

Which platforms are supported?

Primarily Linux x86_64 with Meson/Ninja. Other platforms may work if dependencies are available, but are not first-class targets.

Which dependencies are required?

Core libraries include FFTW3f, zstd, FLAC++, zlib, Boost (system, iostreams), and libcurl. See Installation for distro-specific commands.

How do I enable GPU acceleration?

Install and configure your GPU runtime, then set:

  • accelerator = "opencl" for OpenCL, or
  • accelerator = "cuda" for NVIDIA GPUs, or
  • accelerator = "mkl" for MKL (if compiled with MKL)

If an accelerator is requested but not compiled in, the server will log a critical error and exit. Selection takes place in broadcast_server::broadcast_server().

Configuration

Where is the configuration file?

NovaSDR reads a TOML file (default config.toml). Pass a different file with --config path.

Which keys are required?

Under [input], you must provide:

  • sps (input sample rate, integer)
  • frequency (center/baseband frequency in Hz)
  • signal ("iq" or "real")

If any of these are missing, NovaSDR fails fast with a clear error. See Configuration for a full reference and a minimal known-good example.

What does signal = "iq" vs signal = "real" change?

  • For iq, the effective spectrum base is frequency - sps/2.
  • For real, the effective spectrum base is frequency.

This is used to map FFT bins to absolute frequency and derive default passbands for initial demodulation. Details are in broadcast_server::broadcast_server().

What values should I use for fft_size?

Start at 131072. Larger sizes increase memory and CPU usage but improve resolution. If you see “Out of memory” or high CPU:

  • Reduce fft_size (for example, 65536)
  • Reduce sps (sample rate)

Memory sizing and FFT level preparation occur around broadcast_server::broadcast_server().

Which compression settings are safe?

Default to:

  • waterfall_compression = "zstd"
  • audio_compression = "flac"

Opus/AV1 require building the server with those codecs. NovaSDR will otherwise fail fast with an explicit message. Implementation in broadcast_server::broadcast_server().

Devices & Capture

How do I connect my SDR?

NovaSDR reads from stdin. Pipe samples from your SDR capture tool:

  • RTL-SDR
    • Tool: rtl_sdr
    • Format: u8
    • Signal: "iq"
  • HackRF One
    • Tool: hackrf_transfer
    • Format: s8
    • Signal: "iq"
  • Airspy HF+
    • Tool: airspy_rx
    • Format: s16
    • Signal: "iq"
  • SDRplay RSP1A
    • Tool: rx_sdr -d driver=sdrplay
    • Format: s16
    • Signal: "iq"
  • RX888 MK2
    • Tool: rx888_stream
    • Format: s16
    • Signal: "real" (typical for direct sampling)

Driver and format selection are handled in main().

Are there curated example configs?

Yes. See the repository example configs and Devices for usage guidance and safe defaults.

UI & Usage

How does the UI find the server?

The UI derives the WebSocket base URL from the current browser origin:

The waterfall is too dark/bright. How do I fix it?

Adjust input.brightness_offset in small steps (for example, -6 to +6) and restart the server.

I hear no audio. What should I check?

  • Confirm the tuned frequency is inside captured bandwidth for your sps and signal.
  • Ensure a suitable default mode: 
    [input.defaults]
frequency = 100900000
modulation = "WBFM"   # AM | SAM | FM | WBFM | USB | LSB

Default passband selection per mode is derived in broadcast_server::broadcast_server().

Multi-user & Online Listing

How do I show other listeners on the UI?

Set:

[server]
otherusers = 1

How do I list my station on sdr-list.xyz?

Set:

[websdr]
register_online = true
name = "Your Station"
grid_locator = "JO62"

NovaSDR will periodically update sdr-list.xyz in a background thread:

Performance & Resources

How do I reduce CPU usage?

  • Lower input.sps
  • Lower input.fft_size
  • Keep audio_compression = "flac" and waterfall_compression = "zstd"
  • Use fft_threads = 1 unless you have headroom

How do I prevent out-of-memory (OOM)?

Start conservative:

  • sps = 2_048_000 (for RTL-SDR)
  • fft_size = 131072 (reduce further if needed)

Should I enable fft_threads > 1?

Only if your CPU has spare cores and you measure a real benefit. Threaded FFTs are initialized around main().

Security & Networking

How do I expose NovaSDR to the internet?

NovaSDR provides a built-in static server and WebSockets. If exposing it:

  • Use host firewalls to allow only required ports
  • Track resource usage and connection limits under [limits]
  • Consider running as a service user with restricted permissions

Does NovaSDR support TLS directly?

Not currently documented as a built-in feature. A typical approach is to place NovaSDR behind a TLS-terminating gateway. If you prefer not to introduce external infrastructure, keep NovaSDR on non-public networks.

Logging

How do I enable debug logging or write to a file?

  • --debug increases verbosity
  • --log path/to/file.log writes logs to a file

CLI argument parsing is implemented in main().

Still have questions?

Clone this wiki locally