Python Capture I/O API — Reader / Writer¶

Fraction (0..1) of I/Q components that saturated. Always 0.0 unless track_clipping() was enabled before writing -- the counter is the one extra per-sample compare, so it is opt-in. peak_dbfs is always tracked and is enough to tell you clipping happened; this tells you how much.

Largest per-axis magnitude written so far, in dBFS (full scale = 0 dBFS, so a value above 0 means an integer capture clipped). Always tracked. It is also the remedy: back off by ceil(peak_dbfs) dB of headroom and the capture fits. Float wire types never clip but still report a peak. -inf before anything is written.

True if an integer capture saturated -- peak_dbfs > 0 and the wire type is one of ci32/ci16/ci8. Always False for cf32/cf64, which cannot clip: a float sample above full scale is merely loud.

Which file type the capture turned out to be -- "raw", "csv", "blue" or "sigmf". Detected from the file's CONTENT, not its name, so a CSV called capture.dat reports "csv" and a BLUE file called capture.csv reports "blue". "raw" is also the fallback for a file nothing else recognised, so it means "headerless interleaved I/Q at the sample_type you passed" rather than a positive identification.

The wire sample type the samples are being decoded FROM -- "cf32", "cf64", "ci32", "ci16" or "ci8". For BLUE and SigMF this was read from the file's metadata and is authoritative; for raw and CSV it is simply the hint passed to the constructor, echoed back. read() returns complex64 at unit scale regardless.

Components per wire sample: "complex" for interleaved I/Q, "scalar" for a real capture. Only BLUE carries this (its format field's mode designator, C or S); every other file type is complex. A scalar capture still reads back as complex64 -- the imaginary part is exactly 0, so a real signal lands on the real axis.

Byte order of the samples on the wire, "le" or "be". Read from the metadata for BLUE (the HCB's head_rep) and SigMF (the _be/_le datatype suffix); for raw it is the constructor hint echoed back. CSV is text and ignores it.

Sample rate in Hz, or 0.0 when the file type does not carry one. BLUE derives it from the header's xdelta (fs = 1/xdelta); SigMF reads core:sample_rate. Raw and CSV have nowhere to record a rate, so they always report 0.0 -- whatever rate the capture was taken at has to travel with it by other means.

Centre frequency in Hz, or 0.0 when nothing in the capture declares one. 0.0 is ambiguous on its own -- a genuine baseband capture and a capture whose frequency could not be found report the same number -- so read fc_source alongside it: "none" there is what distinguishes them. SigMF takes it from captures[0]["core:frequency"]; BLUE from a FREQ keyword (see fc_source for the tags tried), in either the ASCII HCB keyword area or the typed extended header. Raw and CSV carry no metadata at all.

Which metadata fs was read from -- "xdelta" for BLUE (the type-1000 adjunct, as 1/xdelta), "core:sample_rate" for SigMF, or "none" when nothing carried a rate. Raw and CSV always report "none": they have nowhere to record one, so whatever rate the capture was taken at has to travel with it by other means.

Capture start time in seconds since the UNIX epoch, or 0.0 when the capture does not declare one. 0.0 does not mean 1970 -- read t0_source alongside it, exactly as with fc/fc_source. This is the t0 of t = t0 + n/fs: hand it to a SampleClock via track() and a replayed capture's timeline lands where the samples were taken, not where they are being replayed. BLUE carries it as a J1950 timecode in the header, converted here to the UNIX epoch.

Where t0 was read from -- "timecode" for a BLUE header that declares one, or "none". "none" is the common answer and the one that matters: a zero BLUE timecode means the field was never set, not 1950-01-01, and doppler's own writer leaves it zero -- so a caller that skips this check dates every doppler-written capture to 1950. SigMF's core:datetime is an ISO 8601 string this reader does not parse yet, so a SigMF capture also reports "none" rather than a guess.

Total samples in the capture, or 0 when the file type cannot say. BLUE takes it from the header's data_size; raw and SigMF divide the file length by the sample stride. A CSV has to be counted, so the first read of this property scans the file once (the scan is exact -- it parses rows the same way read does -- and leaves the read position alone); every later read is free.

Which piece of metadata fc was read from -- the keyword's own tag ("FREQ", "RF_FREQ", "CENTER_FREQ", "F_C"), "core:frequency" for SigMF, or "none" when nothing carried it. Check this before trusting fc == 0.0: "none" means not found, anything else means the capture really does say 0 Hz. BLUE type-1000 has no header field for centre frequency, so an RF capture conveys it as a keyword; FREQ in the HCB keyword area is the X-Midas convention and is tried first.

Payload bytes left over after the last whole sample; 0 for a capture whose declared sample type and mode match its content, and always 0 for CSV. Non-zero means either the sample_type/endian hint is wrong for a headerless file type or the capture is truncated -- the reader cannot tell which, and stops at the last complete sample either way. This is the only signal available for a raw file: a wrong hint does not fail, it returns plausible garbage at the wrong stride.

The BLUE extended header as a {tag: value} dict, in file order; empty when the capture carries no extended header. Values follow the keyword type: a str for A, an int/float for a single-element numeric keyword, a list for a multi-element one. For a detached capture these come from the HEADER file.

The BLUE header control block as a {field: value} dict, under the names the format itself uses -- version, head_rep, data_rep, detached, protected, pipe, ext_start, ext_size, data_start, data_size, type, format, flagmask, timecode, inlet, outlets, outmask, pipeloc, pipesize, in_byte, out_byte, outbytes, keylength, and the type-1000 adjunct xstart, xdelta, xunits. Empty for a non-BLUE file type. Nothing is renamed or omitted, so what you see is what the file holds; the decoded keywords are in keywords.