Struct Recording 

pub struct Recording { /* private fields */ }

An open plain SigMF recording: parsed metadata plus a handle to its dataset file.

See the module documentation for how sample indices are mapped to dataset bytes, and RecordingWriter for an example.

Implementations

impl Recording

pub fn open(path: impl AsRef<Path>) -> Result<Self, SigmfError>

Opens the recording described by the .sigmf-meta file at path and its dataset.

The dataset is the file named by core:dataset in the same directory as path or, when that is absent, path with its extension replaced by sigmf-data. For core:metadata_only recordings the dataset is opened only if core:dataset names an existing file; otherwise sample access returns SigmfError::NoDataset.

Errors

Returns an error if the metadata cannot be read or parsed, SigmfError::InvalidMetadata if core:dataset is not a plain filename, or SigmfError::Io if the dataset cannot be opened.

pub fn open_metadata_only(path: impl AsRef<Path>) -> Result<Self, SigmfError>

Opens only the metadata at path, without opening any dataset.

Methods that access samples return SigmfError::NoDataset.

Errors

Returns an error if the metadata cannot be read or parsed, or SigmfError::InvalidMetadata if core:dataset is not a plain filename.

pub fn metadata(&self) -> &Metadata

Returns the parsed metadata.

pub fn metadata_path(&self) -> &Path

Returns the path the metadata was opened from.

pub fn dataset_path(&self) -> Option<&Path>

Returns the path of the opened dataset, or None if no dataset was opened.

pub fn first_sample_index(&self) -> Integer

Returns the absolute sample index of the first frame in the dataset: core:offset, or zero when it is omitted.

pub fn frame_count(&self) -> Result<Integer, SigmfError>

Returns the number of frames stored in the dataset.

Capture header bytes and trailing bytes are excluded. Valid absolute sample indices are first_sample_index()..first_sample_index() + frame_count().

Errors

Returns SigmfError::NoDataset if no dataset is open, SigmfError::UnsupportedLayout if header or trailing bytes do not fit in the dataset, or SigmfError::InvalidMetadata if the remaining bytes are not a whole number of frames.

pub fn dataset_digest(&mut self) -> Result<String, SigmfError>

Computes the SHA-512 digest of the entire dataset file, including any header and trailing bytes, as a lowercase hexadecimal string.

Errors

Returns SigmfError::NoDataset if no dataset is open, or SigmfError::Io if reading fails.

pub fn verify_dataset_digest(&mut self) -> Result<(), SigmfError>

Checks the dataset against the core:sha512 digest in the metadata.

The comparison ignores ASCII case.

Errors

Returns SigmfError::InvalidMetadata if core:sha512 is absent, SigmfError::HashMismatch if the digests differ, or any error from dataset_digest.

pub fn read_frames( &mut self, start: Integer, count: Integer, ) -> Result<Vec<SampleValue>, SigmfError>

Reads count frames starting at absolute sample index start.

The stored dataset begins at first_sample_index (core:offset, or zero when omitted). Capture header bytes are skipped. The result holds count * core:num_channels samples in on-disk order and is read into memory at once; use frame_blocks for large ranges.

Errors

Returns SigmfError::InvalidRange if the range starts before the first sample or extends past the last frame, SigmfError::ResourceLimit if the block does not fit in memory, or any error from frame_count, decoding, or I/O.

pub fn frame_blocks( &mut self, start: Integer, count: Integer, block_frames: Integer, ) -> Result<FrameBlocks<'_>, SigmfError>

Returns an iterator that reads count frames starting at absolute sample index start, in blocks of at most block_frames frames.

The whole range is validated up front. Each item is the result of read_frames for one block; the iterator stops after the first error.

Errors

Returns SigmfError::InvalidRange if block_frames is zero or the range lies outside the dataset, or any error from frame_count.

pub fn crop_to( &mut self, metadata_path: impl AsRef<Path>, sample_start: Integer, sample_count: Integer, block_frames: Integer, extension_handler: Option<&mut dyn CropExtensionHandler>, ) -> Result<String, SigmfError>

Writes frames sample_start..sample_start + sample_count (absolute indices) to a new plain recording at metadata_path, returning the new dataset’s SHA-512 digest.

Absolute sample indices are preserved: the output’s core:offset is sample_start, and captures and annotations are clipped to the cropped range without being renumbered. core:dataset is cleared, so the output dataset is named after metadata_path, and core:sha512 is recomputed. Input NCD headers and trailing bytes are omitted from the output. Samples are copied in blocks of block_frames frames, and the output is published as described for RecordingWriter.

If extension fields are present, extension_handler must define their crop semantics; otherwise the operation fails rather than silently misaligning application-defined coordinates.

Errors

Returns SigmfError::InvalidRange if block_frames is zero or the range lies outside the dataset, SigmfError::InvalidMetadata if extension fields cannot be cropped, or any error from reading frames, RecordingWriter::new, or RecordingWriter::finish.