Wiki Spectrum analyzer

Scale, auto scale and waterfall

The level scale and the waterfall palette are the same two numbers: the top (Ref) and the range. By default the app drives them itself: the top follows the highest peak of all visible traces, the bottom follows the noise floor. This page covers manual control of the scale, the auto-scale rules, the dBFS and dBm units, and the waterfall: row rate, palettes, history and the heat map.

The Amplitude group

The Spectrum analyzer tab, the Amplitude group. The default scale after the first launch runs from −10 to −100 dBFS 0.9.25, that is Ref −10 and a range of 90 dB; from there the auto scale adjusts both ends.

Scale 0.9.25: auto (default) or manual. In "auto" the app drives the scale and the Ref and Range sliders are disabled. In "manual" the sliders and the wheel over the level axis apply.
Ref: The top of the level scale: from −140 to +20, in the units of the axis (dBFS or dBm).
Range: How many decibels the screen and the waterfall palette hold: from 20 to 140 dB. Smaller: the signal "grows", but peaks are clipped at the top.
Spectrum extent: From ×1.0 (default) to ×3.0 in steps of 0.1. It stretches the vertical axis of the spectrum itself without touching the waterfall palette: the axis must hold the peaks, the palette must separate noise levels. The extent is added symmetrically — half above the peaks, half below the floor. When it is above ×1.0, a line stands under the slider: Axis … dB versus … for the palette — the waterfall is unchanged.
Pedestal and Peak: Two numbers to read: the 5th percentile of the live spectrum (the noise floor level) and the 99.9th percentile (the highest content in the frame, excluding isolated outliers).
The Auto button: Fits the scale to the visible region once: Ref goes 6 dB above the highest point, the bottom 3 dB below the floor. In a zoomed picture only what is on screen counts: a strong signal beyond the edge of the window does not push the scale up. The Instrument → Autoscale menu item and the A key do the same.
The Whole band button: Returns the frequency zoom of the picture to the whole band; it is enabled when the picture is zoomed. The menu item Instrument → Whole band, the Home key, a double-click on the spectrum or a middle-button click without dragging does the same.

Gamma and Palette in the same group belong to the waterfall — see below.

The scale with the mouse wheel

The wheel over the level axis (the strip with labels to the left of the spectrum) changes the range by about 10 % per notch.
Shift+wheel over the level axis shifts Ref by 5 dB.
Shift+wheel over the spectrum itself also changes the range.

Any of these actions switches Scale to manual 0.9.25: a hand on the scale is a choice. Otherwise the auto scale would take some of the steps back. The other mouse gestures are on the main window and controls page.

Auto scale 0.9.25

The auto scale moves both ends so that the spectrum together with its traces fits completely — clipped neither at the top nor at the bottom — and does not jump on random spikes. The target is always the same: the highest peak 6 dB below Ref, the noise floor 3 dB above the bottom of the palette.

The rules

What counts. The live spectrum and all visible traces in the visible region — Max hold, frozen traces and the reference included. The peak is the highest point. The floor is the 5th percentile; a Min hold trace does not count towards the floor, because it would drag the bottom after the lowest noise.
The fit. After start-up, after a pause is lifted, or after auto is chosen, the scale goes to the target with both ends as soon as a steady window of 0.8 s has been collected (in a sweep, two passes). It is computed from the lowest values of the window, so a burst in the first frame does not push the scale up.
Widening is fast. The top goes up when the peak stays closer than 3 dB to Ref (or above it) for the whole 0.8 s. The bottom goes down when the floor is just as steadily closer than 3 dB to the bottom. Clipping is the worst outcome, so the wait here is short.
A single spike does not move the axis. To raise the top, the peak has to be in every snapshot of the window. The exception is logical: if the spike has stayed in a Max hold trace, it is on screen, and the scale makes room for it.
Narrowing is slow. The top comes down only when the highest peak has stayed more than 12 dB below Ref for over 20 s; the bottom goes up only when the floor has stayed more than 15 dB above the bottom for over 20 s. A radio with pauses shorter than 20 s does not rock the scale.
Steps are whole decibels; the scale does not move by less than a decibel. The limits are those of the sliders: Ref from −140 to +20, range from 20 to 140 dB.
Moving the top does not drag the bottom. When Ref rises, the range grows with it, and the floor stays where it was.
A change of band (a retune, entering or leaving a sweep) makes the collected windows and waits be forgotten: the floor of the old band must not set the bottom for the new one.
While paused the scale does not move — the picture stands still.
In a sweep levels are taken once per completed pass, so "steady" means at least two passes in a row.

The auto scale does not touch Spectrum extent: that is your extra margin beyond those 6 and 3 dB.

What else repositions the scale

A gain change. A fraction of a second after the change the scale repositions itself once — from measured levels, not from arithmetic: the noise floor does not follow gain one-to-one, because at low gain the ADC noise dominates rather than that of the RF chain.
The device type 0.9.25. The scale is remembered separately for every device type — HackRF One, RTL-SDR, tinySA, and in SDR SA PRO PRO also Pluto, Fobos SDR and bladeRF: their levels lie in different places on the axis. If no scale has been saved for a device yet, the app fits it once from measured levels.

dBFS, dBm and the UNCAL badge

The unit of the axis is chosen not by the user but by the source. It stands in the top left corner of the level axis, at the Ref slider and in the Pedestal and Peak fields.

dBFS: Decibels relative to the full scale of the ADC: a full-scale tone at the centre of a bin reads 0 dBFS. This is how levels from HackRF One, RTL-SDR, IQ recordings and the demo signal are shown, and in SDR SA PRO PRO also from the Pluto, Fobos SDR and bladeRF receivers. It is not the power at the input: that depends on the gains, and there is no amplitude calibration of these receivers in either the free edition or SDR SA PRO. This is why the trust bar permanently carries the amber dBFS — UNCAL badge.
dBm 0.9.25: Calibrated levels come only from a tinySA: the instrument measures by itself and returns dBm. The axis is then labelled dBm and the badge turns green: dBm — instrument. The warning does not disappear — it becomes a statement.

Compare dBFS levels with one another only at the same gains and on the same device. They cannot be compared with the dBm of another instrument.

The waterfall

The waterfall is the history of the spectrum: every row is the spectrum over a short interval of time, the newest at the top. The colour of a point is its level on the palette, from the bottom of the scale (Ref minus the range) up to Ref. The waterfall is drawn by the graphics card, so a change of Ref, range, gamma or palette recolours the whole visible history at once.

Rows, fold and frames

One row is several spectra folded by the main detector. How many is shown by the Fold field.
The rate is set by the Rows/s slider at the bottom of the Resolution bandwidth group: from 30 to 1200, 400 by default. More rows mean a faster waterfall, a smaller fold and a shorter memory.
There are never more rows than spectra. If there are fewer spectra per second than rows requested (a large N at a low sample rate), every row is one spectrum. The actual figures are the rows/s and spectra/s fields in the Host group on the Device tab.
Nor are there fewer rows than portions of samples: every portion from the device gives at least one row. So at 20 MS/s the actual rate does not drop below about 150 rows/s, whatever the slider says.
Vertically one row takes one pixel, so the screen shows as many of the latest rows as there are pixels in the height of the waterfall.
Spectrum frames (60, 30 or 15) is the redraw rate, not the row rate: rows are not lost and land in a frame as a batch. More in Spectrum frames and Spectrum from blocks.
In a sweep the waterfall gets one row per completed pass; with a tinySA, one row per instrument sweep.
When there are more bins than pixels across the width, they are reduced by Detector ↔px: with peak a narrow spur between pixels is not lost.

Palettes and gamma

Palette: Five palettes, listed from the most uniform in lightness: cividis, viridis, inferno (default), gqrx, turbo. In the first three lightness rises together with level. gqrx and turbo are not monotonic: they have stretches where lightness falls as level rises, so the eye sees an edge where the signal has none. gqrx is the classic one, for eyes used to it; turbo is bright and high-contrast, but detail in it may appear sharper than it is. The "?" hint next to the list warns about this: in non-monotonic palettes level cannot be read by eye. The same palette colours the heat map.
Gamma: From 0.3 to 3.0, 1.0 by default. It bends only the waterfall palette: below one it pulls weak signals out of the noise, above one it suppresses the small and keeps the strong. It does not affect measured levels or the spectrum trace — it is paint only.

History

The app keeps the last 16384 rows. The depth in seconds is inverse to the rate: at an actual 400 rows/s that is about 41 s, at 30 more than 9 minutes, at 1200 about 14 s.
Alt+wheel over the spectrum or the waterfall scrolls the history by 500 rows: down goes into the past, up towards live. The History field in the Host group shows live or the distance back in rows.
To return at once: the Back to live button in the Source group on the Device tab, the same item in the Instrument menu, or the L key.
A scrolled waterfall does not freeze: it shows what was there that many rows earlier and keeps moving. To study a still picture, pause the stream (Space).
Every row remembers its own band. After a retune or a change of sample rate the old rows stay at their own frequencies, and where a row did not see a frequency, it is blank.
The history holds up to 4096 points per row. A wider row (N 8192 or 16384, a sweep grid) is reduced by peak over groups of neighbouring bins — a narrow spur stays visible, and the trust bar says History peak ×2 or more. The traces stay at full width.

Splitting the screen

The frequency-axis strip between the spectrum and the waterfall is a handle: drag it with the mouse to change the share of height given to the spectrum, between 12 and 88 %. By default the spectrum takes 42 %. The position is saved together with the workspace.

The heat map

The heat map is another view of the same spectrum: the curve leaves a trail whose colour shows what share of time the curve spent at that level. A carrier is hot, noise and isolated bursts are cold; a pulsed signal stays on screen for a few time constants after the live curve has gone back to the noise. It is switched on with a right-click on the spectrum, the Heat map item; it is off by default. Two sliders then appear in the Amplitude group:

Persistence: The time constant of the trail: from 0.2 to 10 s, 1.5 s by default. Longer gives a steadier picture, but old content fades more slowly.
Contrast: Colour compression: from 0.10 to 1.0, 0.50 by default. A lower value: noise and bursts get warmer and the difference from the carrier melts away; a higher value: the carrier separates from the noise.

Under the sliders the app says in words what exactly is drawn: the map is fed with the row of trace T1 (in a sweep, with the stitched pass), the level is divided into 256 steps of 0.67 dB, and bins per pixel are reduced by peak.

Limits

Levels from HackRF One, RTL-SDR, recordings and the demo signal (and in SDR SA PRO from its receivers too) are in dBFS, not in calibrated dBm; only a tinySA gives dBm. More in Limits and roadmap.
A strong carrier in view stretches the palette: the auto scale makes room for the highest peak, and weak signals fall lower in its colours. Gamma or a manual scale brings back the contrast of the weak ones.
In a sweep the auto scale needs two passes to accept a level as steady, so it reacts no faster than twice the pass time.
The waterfall has no time scale: the depth of the history is set by the row rate.
The waterfall history lives in video memory: it is not saved to a file and is gone when the app closes. To keep what was on the air, use IQ recording.
The history holds at most 16384 rows of 4096 points; wider rows are reduced by peak.
The spectrum and the waterfall need OpenGL 3.3 — without it they are not drawn (see Troubleshooting).

The wiki describes version 0.9.49. Your app's version is shown in the Help menu, under About. Found a mistake? Write to us.