Field Guide · technology

Also known as: SigMF, Signal Metadata Format

SigMF (the Signal Metadata Format) is an open standard that stores a raw IQ recording alongside a small JSON file describing everything a decoder needs to interpret it — the sample format, sample rate, centre frequency, and time-stamped annotations.1 It solves the oldest problem in SDR file exchange: a bare IQ file is just a wall of numbers, and without out-of-band notes you cannot even tell whether it is 8-bit unsigned or 32-bit float, let alone what was on the air.

name.sigmf-dataraw interleaved IQ name.sigmf-meta (JSON) global: datatype, sample_rate, hw captures[]: sample_start, frequency annotations[]: span + label
A SigMF recording is a raw IQ dataset file plus a JSON sidecar with global, captures, and annotations objects.

How it works

A SigMF recording is a pair of files sharing a base name. The .sigmf-data file holds the raw interleaved samples — no header, no framing, just the bytes — exactly like a GNU Radio cfile. The .sigmf-meta file is JSON with three parts:

  • global — properties that hold for the whole file: core:datatype (e.g. cf32_le for complex little-endian float32, cu8 for 8-bit unsigned, ci16_le for 16-bit signed), core:sample_rate, hardware description, author, and SHA-512 hash of the data file.
  • captures — an array of segments, each marking a core:sample_start index and the RF core:frequency and wall-clock time in effect from that sample onward. Retuning mid-file produces a new capture entry rather than a new file.
  • annotations — an array of labelled regions, each spanning a sample range and optional frequency band, carrying a free-form core:label and application-specific keys. This is where a bursting signal, a detected emitter, or a training-set class is marked.

The datatype string is the crucial field: it names the element type, real-vs-complex, bit width, byte order and any offset, so the reader knows precisely how to parse the accompanying data file. Optional namespaced extensions (antenna:, signal:, capture_details:) add domain fields without polluting the core schema, and the whole thing can be bundled into a single .sigmf tarball archive for transport.

Relevance to SDR

SigMF has become the lingua franca for sharing IQ captures across tools that would otherwise disagree on format. GNU Radio, Inspectrum, IQEngine, and numerous machine-learning pipelines read and write it, and it grew out of a DARPA-sponsored effort to make RF datasets reproducible and self-describing. For automatic modulation classification and RF fingerprinting, the annotations array doubles as the label file: each burst carries its class inline, so a dataset is one directory rather than IQ plus a fragile external CSV.

GopherTrunk does not read SigMF natively — its offline replay path (gophertrunk replay) takes bare captures via a -format flag, understanding u8 (rtl_sdr 8-bit), f32 (GNU Radio cfile float32), and 16-bit PCM wav, with the sample rate and tune offset supplied on the command line rather than read from a sidecar. Because a SigMF .sigmf-data file is just one of those raw layouts, you can replay one by pointing GopherTrunk at the data file and transcribing core:datatype, core:sample_rate, and core:frequency from the meta JSON into the corresponding flags — the metadata SigMF standardises is exactly the set of parameters GopherTrunk otherwise expects you to know. Adopting the SigMF sidecar convention when you record captures for bug reports keeps them self-describing even though the replay tool reads the raw bytes directly. SigMF’s conceptual cousin inside a live flowgraph is the stream tag, which attaches the same kind of sample-indexed metadata to a running stream rather than a file on disk.

Sources

  1. SigMF specification — the official standard repository, defining the .sigmf-data / .sigmf-meta pair, the global/captures/annotations objects, and the datatype grammar. ↩

See also