OnAir troubleshooting: drivers, USB, dropped samples, no sound, crashes

The radio is not found#

Check the cable and press Rescan for devices in the source list. The setup wizard says it plainly when it cannot see a radio: plug it in and press the button again.
Windows: a HackRF, RTL-SDR, Airspy, Airspy HF+, Fobos SDR and RX888 MkII need the WinUSB driver, installed once with Zadig (turn on List All Devices if the radio is not listed). The RX888 MkII needs it for both 04B4:00F3 and 04B4:00F1.
SDRplay: install the SDRplay API and make sure the SDRplay API Service is running. OnAir shows a help card when an RSP is plugged in but the API is missing.
LimeSDR: the Mini needs FTDI's FT60x driver; the LimeSDR-USB needs the Cypress CyUSB3 driver, not WinUSB, plus PothosSDR or LimeSuite. See BladeRF, LimeSDR and USRP.
Linux, Airspy: add yourself to plugdev, log out and in, and replug. Dragon OS and similar: see the build note below.
USB 3 radios (RX888, fast Fobos rates) must be on a USB 3 port, not a hub.
The log (onair.log, see Settings and files) says which library saw how many radios.

RTL-SDR Blog V4 does not tune HF#

The V4 up-converts HF inside the Blog library; OnAir never switches direct sampling on for it. On macOS OnAir bundles the Blog librtlsdr (0.2.6). Other dongles sample the Q input directly. See RTL-SDR.

The spectrum is there but the receiver does not lock#

Check the frequency and the standard (DVB, ATSC, DAB...). The setup wizard's country picks the right one.
Look at the ADC line in the status: ADC OVERLOAD means reduce the gain (or enable AGC); ADC level low or sees almost nothing means raise the gain or check the antenna. Auto-tune or Optimise gain do this for you.
A weak or echo-filled signal is the usual cause of a broken picture: use the quality score and the echo (multipath) detector while you move the antenna.
A TV channel needs a radio that samples fast enough (about 1 Msps per MHz of channel width).

Dropped samples and a stuttering picture#

Hover the dropped indicator in the status bar: it says what is happening.

Arriving from the radio below 97 % of the set rate / callback gaps: the radio or its driver hands over less than asked. This is not the receiver's CPU load. Try a USB port on the computer (no hub), a shorter cable or a lower sample rate.
Ring overflow: OnAir did not read the input fast enough and samples were thrown away. Close other programs, or pick a lower sample rate or a narrower channel.
Receiver load: near 100 % of real time the receiver is just keeping up. High load and lost samples are separate things.
Wide captures need a decent CPU: an Airspy at 10 Msps could not keep up with live ATSC on a 2-core laptop.
Network radios: the status bar counts the lost samples (underruns). rtl_tcp uses 8-bit samples up to about 2.5 Msps; a PlutoSDR over USB reaches about 4 Msps.
Files and the test signal never lose samples: they wait for the receiver.

No sound#

A mode that plays sound has a speaker or Listen control. HF decoders (FT8, RTTY, CW, PSK31, JS8Call, SSTV) have Listen; the command line is silent unless you add --listen.
With several receivers only one plays audio at a time (the speaker button of the tab).
Digital voice (DMR, P25, NXDN, dPMR, D-STAR) needs a codec library, and M17 / FreeDV need codec2: look at the ? next to the sound. See Voice codecs.
Some sound is not decoded at all: HD Radio (HDC, patented), CDR (DRA+, plays once you install the optional DRA+ add-on) and Inmarsat Aero voice. OnAir shows stations and data, and can save the raw DRA stream.
Linux: sound did not work when OnAir was started with sudo; fixed in 0.2.5 (issue 67).
Windows uses WASAPI through miniaudio, macOS CoreAudio.

GPU and compute options#

LDPC error correction and picture repair run on the GPU where available: Metal on macOS, Direct3D 11 on Windows. On Linux there is no GPU decoder yet, so error correction runs on the CPU.
DVB-S / DVB-S2 and DTMB have a CPU / GPU / Auto compute setting (the command line has --compute). Results are the same as the CPU.
On Windows a GPU adapter can be chosen (0.1.0 notes).
Reduce CPU when hidden (View menu) lowers the load when the window is not visible.

OnAir crashes or does not start#

Crash reports are written to a file next to the log (crash.txt on the platform's log folder); nothing is uploaded.
If a start keeps failing, OnAir tries the other interface after one unfinished start and, after two in a row, sets your saved settings aside and starts with the defaults. A note on screen says where the old settings are kept.
Release 0.2.5 fixed a crash at start on processors without AVX2 (issue 74).
Save bug report writes one zip with the diagnostics, the log and the last crash report. Attach it to a GitHub issue, with a short IQ recording of the problem if you can (Record IQ).

Building: the computer freezes#

Run cmake --build build -j "$(getconf _NPROCESSORS_ONLN)" (one job per core). A bare -j starts hundreds of compile jobs and can run out of memory (issue 43).

Still stuck?#

Ask on Discord or open an issue: say what you did, what you expected, what happened, your operating system, your radio and the standard of the channel.