Wiki › Recording and data

IQ recording

Recording saves the receiver's whole instantaneous bandwidth to disk in the device's own sample format, uncompressed, together with a SigMF sidecar. A recording is not "lossless" but free of silent losses: every lost sample is counted in the SigMF metadata, gaps with a known position are marked where they occurred, and the share of losses is added to the file name.

Making a recording

1. Tune the device to the required frequency and choose the sample rate: the whole captured band is recorded, not just the VFO band.
2. Press the ⏺ button in the side panel header (tooltip Start IQ recording (the stream resumes on its own)) or the Record button in the Record group on the Device tab.
3. While recording, the button in the group reads Recording… and the ⏺ icon is red.
4. To stop, press Stop in the group or ⏺ again. The ⏹ button in the header stops both the recording and the stream.

0.9.30 Starting a recording does not stop the processing thread: on a HackRF One this removed the loss of samples in transport at the very moment a recording starts.

What goes to disk

All recordings go to the C:\sdrsa-rec folder; if it does not exist, the app creates it. The folder cannot be changed. A recording consists of pairs of files — data and sidecar:

• 20261004-153012-000.sigmf-data — raw IQ samples;
• 20261004-153012-000.sigmf-meta — SigMF metadata in JSON.

The name is the date and time the recording started (YYYYMMDD-HHMMSS) and the segment number. A recording is cut into segments so that a single failure does not take everything: a new segment begins as soon as the previous one reaches 1 GiB or 60 seconds, and has its own sidecar. Segments are numbered -000, -001, -002…

Sample format

The one the device itself delivers: cs8 (signed 8 bit) for HackRF One and cu8 (unsigned 8 bit) for RTL-SDR 0.9.25. In the sidecar these are ci8 and cu8. Converting 8→16 bit would double the file and add not a single bit. The SDR SA PRO receivers PRO write their own formats: 12-bit samples in ci16_le 0.9.33 — written by Pluto and bladeRF; float32 with a scale of ±0.25 in cf32_le 0.9.43 — written by Fobos SDR. The full scale of such recordings is smaller than the scale of their type, and the sidecar names it in the sdrsa:full_scale field: without it the recording would read 24 or 12 dB lower than it looked while being recorded. The app's player and transmitter read this field.

Size

Two bytes per IQ sample, so the stream in MB/s is twice the sample rate in MS/s: 40 MB/s at 20 MS/s, 16 MB/s at 8 MS/s, 5.12 MB/s at 2.56 MS/s. Ten minutes at 20 MS/s is about 24 GB; measured: 24.26 GB with zero losses on a drive that keeps up. Recordings in ci16_le take four bytes per IQ sample, in cf32_le eight.

The sidecar during recording

While data is flowing it is updated about every two seconds, and each time it is replaced as a whole file rather than appended to. So even if the process is killed, a readable recording is left on disk. Its sdrsa:complete field becomes true only when the segment has been closed properly: it shows that a recording was cut off rather than merely short.

What the sidecar holds

The format and sample rate (core:datatype, core:sample_rate), the device (core:hw), the frequency of each stretch (captures with core:frequency), the start time of the recording, the loss counters (sdrsa:drops) and the gaps (annotations). When needed, also the full scale (sdrsa:full_scale) and the count of transport breaks (sdrsa:transport_breaks, see below).

The Record group

The group sits on the Device tab below the Source group.

Record and Stop

Start and end of the recording. While recording, the first button is inactive and reads Recording….

Format

The device's sample format and the word SigMF, for example "cs8 · SigMF". The hint next to it works out the stream in MB/s and the size per ten minutes for the current sample rate.

Duration

How many seconds of the air are already on disk in this recording.

On disk

The amount recorded in gigabytes and the number of the current segment.

Space left

Free disk space and how many minutes it will last at the current sample rate. It turns yellow when fewer than 10 minutes remain and red below 2. Shown only while recording.

Writer queue

The fill of the queue in front of the disk, in per cent, and the longest single write to disk, in milliseconds. The queue is sized for 20 seconds of the stream (800 MB of memory at 20 MS/s, but no more than one eighth of the free memory) and rides out short disk stalls. If it grows and turns yellow (above 70 %), the disk is not keeping up and losses will follow.

Losses in the recording

Four counters — see below. They appear as soon as something has been written to disk.

At the bottom of the group there is the path of the current file and, if something went wrong, a red line with the reason.

Losses: four counters

Losses are shown separately because they are different faults with different causes and different remedies. The first three numbers are in samples, the fourth is a count of gaps; all of them concern this recording only: what the device lost before the button was pressed is not charged to the file.

The same numbers are stored in the sidecar's sdrsa:drops field (source_ring, transport, paused, writer_ring). If anything was lost during a recording, the app adds it to the names of all its files after the stop: -drop0.12pct when 0.01 % of the samples or more were lost, or -drop12 — the exact number of samples — when the share is smaller. The result is, for example, 20261004-153012-000-drop0.12pct.sigmf-data. A sidecar can get lost, but the name travels with the data. Samples discarded while paused are not included in the name: that was your decision, not a fault.

Gaps with a known position

A gap whose position is known is written to the sidecar as an annotation labelled gap: the position in samples, how many samples are missing, and the cause in the sdrsa:gap_kind field. The data file simply joins the neighbouring samples at that point, so software reading the recording has to take the annotations into account. 0.9.35 The mark stands exactly where the gap is, and two different holes do not merge into one.

The number of samples lost in USB (Lost in transit) has no position: the app only knows from the clock how many samples are missing. It goes into the counter and the file name. The position of a break is marked by a transport annotation — only where the source itself knows it. The sdrsa:transport_breaks field says how many such breaks the recording had (total) and how many of them are marked with annotations (marked): there are at most 2000 annotations per recording, the rest are only counted.

A separate suspect label 0.9.25 marks samples that were recorded but cannot be trusted: it appears when the RTL-SDR synthesiser did not lock on the frequency. This is not a loss, so it is not counted as one.

Frequency, sample rate and sweep during a recording

• Frequency change. 0.9.25 Retuning does not stop the recording. From the first sample on the new frequency, a new captures entry with its own core:frequency is opened in the sidecar, so every stretch of the file is labelled with its own frequency. If the driver discarded samples on the retune, a retune gap stands at that point.
• Sample rate. 0.9.25 A recording has one sample rate for the whole file. An attempt to change it during a recording (including with the mouse wheel over the spectrum) is refused with the Sample rate not changed: recording in progress window. If the device ends up at another sample rate anyway, the recording stops by itself with the Recording stopped: the device sample rate changed window; everything recorded so far stays intact.
• Sweep. 0.9.25 A sweep during a recording runs at the recording's sample rate, but the recording receives no samples meanwhile. The break is marked with a sweep gap. If the recording has to be continuous, stop the sweep.
• Transmission. A recording cannot be started while transmitting (the Recording not started: transmission in progress window). A transmission in the middle of a recording leaves a transmit gap.

The drive

• For 20 MS/s, drive C: must sustain 40 MB/s — sustain, not just manage it for the first gigabytes: a ten-minute recording takes about 24 GB.
• A recording does not start if less than 2 GiB is free on the drive: the app says how much there is and how much is needed.
• Free space is also checked during the recording. When less than 2 GiB is left, the recording stops by itself and a red line appears in the group; everything recorded so far stays intact.
• If Disk fell behind is growing, the drive is slower than the stream. A lower sample rate will help.

Opening a recording again

A recording is opened in the app's start window with the Continue without a device button. The File → Open recording… menu item in the main window does not switch the source: after a file is chosen the app answers Not implemented, so to open a recording the app has to be restarted. In a recording with several frequencies every stretch is played back with its own: the Center field in the Source group shows the frequency of the current stretch. Details are on the Demo signal and IQ files page. The same file can be put back on the air through the HackRF One transmitter, provided its sample rate lies within 2–20 MS/s.

Limits

• The recording folder is C:\sdrsa-rec only; it cannot be changed.
• The whole instantaneous bandwidth is always recorded, in the device's format, uncompressed.
• With a tinySA or tinySA Ultra 0.9.25 there is no IQ recording: the instrument returns levels, not samples, so the tab has no Record group and the header has no ⏺ button.
• During a sweep and a transmission the recording receives no samples; these breaks are marked, not filled in.
• Losses in USB are an estimate from the clock; the position of a break in the file is marked only where the source itself knows it.
• The sample rate cannot be changed during a recording.

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.