Crate sigmf 

Read, write, and validate SigMF (Signal Metadata Format) recordings.

SigMF describes a recording of digital samples with a JSON metadata file (.sigmf-meta) stored next to a binary dataset (.sigmf-data). Recordings may be grouped by a .sigmf-collection file and bundled into a single .sigmf tar archive. This crate implements the SigMF 1.2 specification:

• Metadata — strongly typed global, capture, and annotation objects that round-trip unknown and extension fields losslessly (meta::Metadata).
• Datasets — every SigMF datatype (cf32_le, ri16_be, ru8, …) with multi-channel, non-conforming (NCD), and streaming access (recording_file::Recording, recording_file::RecordingWriter, utils::data).
• Archives — create and read .sigmf tar archives (ArchiveWriter, Archive) with SHA-512 integrity checks.
• Collections — .sigmf-collection files (collection::Collection).
• Validation — structural and semantic checks with machine-readable issues (validation).
• Extensions — typed, namespaced metadata extensions (extensions::SigmfExtension, with an optional derive macro).

Quick start

Write a recording to disk and stream it back:

use sigmf::datatype::Datatype;
use sigmf::global::Global;
use sigmf::meta::Metadata;
use sigmf::num_complex::Complex;
use sigmf::recording_file::{Recording, RecordingWriter};
use sigmf::utils::data::SampleValue;
use std::str::FromStr;

let mut metadata = Metadata::new(
    Global::new("1.2.6", Datatype::from_str("cf32_le")?),
    Vec::new(),
    Vec::new(),
);
metadata.set_sample_rate(1e6);
metadata.set_description("A short tone".to_string());

// Writes `tone.sigmf-data`, then `tone.sigmf-meta` with `core:sha512` filled in.
let mut writer = RecordingWriter::new(dir.join("tone.sigmf-meta"), metadata)?;
let samples: Vec<SampleValue> = (0..1024)
    .map(|n| {
        let phase = n as f32 * 0.1;
        SampleValue::ComplexF32(Complex::new(phase.cos(), phase.sin()))
    })
    .collect();
writer.write_frames(&samples)?;
writer.finish()?;

let mut recording = Recording::open(dir.join("tone.sigmf-meta"))?;
recording.verify_dataset_digest()?;
assert_eq!(recording.frame_count()?, 1024);
let start = recording.first_sample_index();
for block in recording.frame_blocks(start, 1024, 256)? {
    let block = block?;
    assert_eq!(block.len(), 256);
}

Bundle recordings into a .sigmf archive and read them back:

use sigmf::datatype::Datatype;
use sigmf::global::Global;
use sigmf::meta::Metadata;
use sigmf::{Archive, ArchiveWriter};
use std::str::FromStr;

let path = dir.join("capture.sigmf").to_string_lossy().into_owned();
let metadata = Metadata::new(
    Global::new("1.2.6", Datatype::from_str("ri8")?),
    Vec::new(),
    Vec::new(),
);

let mut writer = ArchiveWriter::new(path.clone())?;
writer.add("burst", metadata, &[1u8, 2, 3, 4])?;
writer.build()?;

let archive = Archive::load(&path)?;
assert_eq!(archive.get_names(), ["burst"]);
let samples = archive.get_samples_from_name("burst")?;
assert_eq!(samples.len(), 4); // `ri8` is real 8-bit: one byte per sample

Cargo features

Feature	Description
derive	Re-exports SigmfExtension, a derive macro for extensions::SigmfExtension.
schema	JSON Schema generation and validation for extensions (extensions::extension_schema, extensions::validate_json_schema).

No features are enabled by default.

Re-exports

pub use num_complex;

Modules

annotation

SigMF annotation segments.

capture

Capture segments: entries of the SigMF captures array.

collection

The SigMF collection object (.sigmf-collection files).

datatype

SigMF sample datatypes (core:datatype).

extensions

Typed access to SigMF extension namespaces.

global

The SigMF global object.

meta

SigMF recording metadata: the contents of a .sigmf-meta file.

recording

References from a SigMF collection to its member recordings.

recording_file

Plain on-disk SigMF recordings: a .sigmf-meta file and its .sigmf-data dataset side by side in one directory.

utils

Lower-level helpers used by the rest of the crate.

validation

Semantic validation of SigMF metadata and collections.

Structs

Archive

An opened .sigmf archive: a tar file of recordings and an optional collection.

ArchiveWriter

Builds a new .sigmf archive.

Enums

SigmfError

Errors returned by this crate.

Type Aliases

Integer

JSON integer type used for unsigned SigMF fields such as core:sample_start and core:sample_count.

Number

JSON number type used for floating-point SigMF fields such as core:sample_rate and core:frequency.

Derive Macros

SigmfExtensionderive

Derives extensions::SigmfExtension for a struct of namespaced fields.