Skip to content

converters.rst

Latest commit

 

History

History
214 lines (139 loc) · 7.14 KB

converters.rst

File metadata and controls

214 lines (139 loc) · 7.14 KB

Converters

The SigMF Python library includes converters to import data from various RF recording formats into SigMF. Converters can create standard SigMF file pairs or Non-Conforming Datasets (NCDs) that reference the original files.

Overview

Conversion is available for:

  • BLUE files - MIDAS Blue and Platinum BLUE RF recordings (usually .cdif)
  • WAV files - Audio recordings (.wav)
  • Signal Hound Spike files - Signal Hound zero-span recordings (.xml + .iq)

All converters return a :class:`~sigmf.SigMFFile` object with converted metadata.

Fromfile Auto-Detection

The :func:`~sigmf.sigmffile.fromfile` function automatically detects input file formats and reads without writing any output files:

import sigmf

# auto-detect and create NCD for any supported format
meta = sigmf.fromfile("recording.cdif")  # BLUE file
meta = sigmf.fromfile("recording.wav")   # WAV file
meta = sigmf.fromfile("recording.xml")   # Signal Hound Spike file
meta = sigmf.fromfile("recording.sigmf")  # SigMF archive

all_samples = meta.read_samples()
sample_rate = meta.sample_rate

Python API

For programmatic access, use the individual converter functions directly:

from sigmf.convert.wav import wav_to_sigmf
from sigmf.convert.blue import blue_to_sigmf
from sigmf.convert.signalhound import signalhound_to_sigmf

# convert WAV to SigMF archive
_ = wav_to_sigmf(wav_path="recording.wav", out_path="recording", create_archive=True)

# convert BLUE to SigMF pair and return metadata for new files
meta = blue_to_sigmf(blue_path="recording.cdif", out_path="recording")

# convert Signal Hound Spike to SigMF pair
meta = signalhound_to_sigmf(signalhound_path="recording.xml", out_path="recording")

Command Line Usage

Converters are accessed through a unified command-line interface that automatically detects file formats:

# unified converter
sigmf_convert input_file output_file

# examples
sigmf_convert recording.cdif recording.sigmf
sigmf_convert recording.wav recording.sigmf
sigmf_convert recording.xml recording.sigmf

The converter uses magic byte detection to automatically identify BLUE, WAV, and Signal Hound Spike file formats. No need to remember format-specific commands!

Output Options

The unified converter supports multiple output modes:

# standard conversion (creates out.sigmf-data and out.sigmf-meta files)
sigmf_convert in.wav out

# archive mode (creates single out.sigmf archive)
sigmf_convert in.wav out --archive

# non-conforming dataset (creates out.sigmf-meta only, references original file)
sigmf_convert in.wav out --ncd

# extra verbose output
sigmf_convert in.wav out -vv

Important: When using --ncd, the input and output files must be in the same directory. This ensures proper relative path references in the metadata.

BLUE Converter

The BLUE converter handles CDIF (.cdif) recordings while placing BLUE header information into the following global fields:

  • blue:fixed - Fixed header information (at start of file).
  • blue:adjunct - Adjunct header information (after fixed header).
  • blue:extended - Extended header information (at end of file). Note any duplicate fields will have a suffix like _1, _2, etc appended.
.. autofunction:: sigmf.convert.blue.blue_to_sigmf

Examples

from sigmf.convert.blue import blue_to_sigmf

# standard conversion
meta = blue_to_sigmf(blue_path="recording.cdif", out_path="recording")

# create NCD automatically (metadata-only, references original file) but don't save any output file
meta = blue_to_sigmf(blue_path="recording.cdif")

# access standard SigMF data & metadata
all_samples = meta.read_samples()
sample_rate = meta.sample_rate

# access BLUE-specific metadata
blue_type = meta.get_global_field("blue:fixed")["type"]  # e.g., 1000
blue_version = meta.get_global_field("blue:fixed")["keywords"]["IO"]  # e.g., "X-Midas"

Tested Formats

BLUE files use a 2-digit format code where the first is the sample type (row) and the second is the sample size (column). For example SB contains real values with 8 bits per sample and CF contains complex values with 32 bits per component (64 bits per sample).

The following table summarizes tested BLUE formats and their compatibility with the converter:

Code :abbr:`P (packed)` :abbr:`N (int4)` :abbr:`B (int8)` :abbr:`U (uint16)` :abbr:`I (int16)` :abbr:`V (uint32)` :abbr:`L (int32)` :abbr:`F (float32)` :abbr:`X (int64)` :abbr:`D (float64)` :abbr:`O (excess-128)`
:abbr:`S (scalar)` ❌ ❌ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌
:abbr:`C (complex)` ❌ ❌ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌
Legend:
  • ✅ = Tested and known working
  • ❌ = Unsupported

WAV Converter

Converts WAV audio recordings to SigMF format.

.. autofunction:: sigmf.convert.wav.wav_to_sigmf

Examples

from sigmf.convert.wav import wav_to_sigmf

# standard conversion
meta = wav_to_sigmf(wav_path="recording.wav", out_path="recording")

# create NCD automatically (metadata-only, references original file)
meta = wav_to_sigmf(wav_path="recording.wav")

# access standard SigMF data & metadata
all_samples = meta.read_samples()
sample_rate_hz = meta.sample_rate

Signal Hound Spike Converter

The Signal Hound Spike converter handles recordings from Signal Hound devices. These recordings consist of two files: an XML metadata file (.xml) and a binary IQ data file (.iq). The converter extracts metadata from the XML file and references the IQ data file, storing Signal Hound-specific fields in the spike: namespace extension.

.. autofunction:: sigmf.convert.signalhound.signalhound_to_sigmf

Examples

from sigmf.convert.signalhound import signalhound_to_sigmf

# standard conversion (provide path to XML file)
meta = signalhound_to_sigmf(signalhound_path="recording.xml", out_path="recording")

# create NCD automatically (metadata-only, references original .iq file)
meta = signalhound_to_sigmf(signalhound_path="recording.xml")

# access standard SigMF data & metadata
all_samples = meta.read_samples()
sample_rate = meta.sample_rate
center_freq = meta.get_captures()[0]["core:frequency"]

# access Signal Hound-specific metadata in spike: namespace
reference_level_dbm = meta.get_global_field("spike:reference_level_dbm")
scale_factor_mw = meta.get_global_field("spike:scale_factor_mw")
if_bandwidth_hz = meta.get_global_field("spike:if_bandwidth_hz")
iq_filename = meta.get_global_field("spike:iq_filename")  # original IQ file name
preview_trace = meta.get_global_field("spike:preview_trace")  # max-hold trace