Troubleshooting

Troubleshooting

Real issues hit getting the Frequency Recorder GUI running against actual hardware, in the order you're likely to hit them.

"unknown modulation" and the process immediately exits (code 1)

Cause: rtl_airband was built without -DNFM=ON. The NFM modulation keyword only exists in the binary when compiled with that flag (src/config.cpp, guarded by #ifdef NFM); without it, a channel set to modulation = "nfm" fails validation and the engine exits before ever touching the SDR.

Fix: rebuild with the flag:

cd RTLSDR-Airband
rm -rf build
mkdir build && cd build
cmake -DNFM=ON ../
make
sudo make install

Config fails to parse / engine rejects a "Record to file" channel, no clear reason why

Cause: a bug in the third-party libconf Python library this GUI uses to read/write config files. It formats boolean values (dated_subdirectories, split_on_transmission, and any other true/false field) using Python's own capitalization - True/False - which real libconfig++ (what rtl_airband actually links against) does not recognize; only the lowercase true/false keywords are valid boolean literals to it. libconf's own reader is case-insensitive on the way in, so a config written and re-read through this GUI round-trips fine and never reveals the bug - it only ever showed up against the real engine. This affected every "Record to file" output, since those always set dated_subdirectories/split_on_transmission.

Fix: update to a current checkout (git pull, restart gui/app.py) - patched narrowly in gui/config_io.py rather than touching the third-party package. If you have an old config file lying around that was saved by a pre-fix version, opening and re-saving it through the GUI (or just checking Raw Config for = True;/= False; instead of = true;/= false;) will correct it.

The process shows "stopped" right after Start, but exit code is 0 (not a crash)

Cause: rtl_airband daemonizes by default — without -f/-F it double-forks into the background and the parent process (the one the GUI was watching) exits(0) immediately, on purpose. The GUI passes -F (foreground, no waterfall TUI) for exactly this reason, so if you're seeing this on a current checkout, you're likely on an older commit — git pull and restart gui/app.py.

If you have stray processes from before this fix: old daemonized copies may still be running, invisible to the GUI, and holding the SDR open:

pgrep -a rtl_airband
pkill rtl_airband   # if the above lists anything

The checkbox / feature I expect isn't showing up

Usually a stale checkout or a cached page, not a bug:

cd RTLSDR-Airband
git pull

Restart python3 gui/app.py, then hard-refresh the browser (Ctrl+Shift+R).

Squelch confusion

Older versions of this GUI exposed a raw dB number, and it was actually wired to the wrong config key (squelch_threshold, an absolute dBFS value, instead of squelch_snr_threshold, the actual "dB above noise" setting the label described). Current versions use a single 0–9 level like a handheld radio's SQL knob instead — see Frequency Recorder GUI.

Live audio sounds sped up, slowed down, or pitched wrong

The sample rate setting (Process Control tab) doesn't match how the binary was actually built: 16000 for -DNFM=ON, 8000 for AM-only builds. Fix the setting to match your build.

Where did Start/Stop/Restart go?

Earlier versions put Start/Stop/Restart inside the Process Control tab — easy to lose track of after editing something on Frequencies. They now live in a bar directly under the header, visible on every tab. If you're still seeing them only inside Process Control, git pull and restart gui/app.py.

Device index

Not actually a fault — it's just which physical RTL-SDR dongle to use if more than one is plugged in. 0 means "the first one found." If you only have one dongle, leave it at 0.