Signal Generator

The SigMFGenerator class provides a builder-pattern API for creating synthetic RF signals as SigMF files. It is intended for generating test signals and example files during development and testing.

Signals are complex baseband (cf32_le) and support tones, linear frequency sweeps, additive white Gaussian noise, and frequency/phase offsets. All parameters can be left unspecified and randomized with a seed for reproducibility.

Basic Usage

from sigmf.siggen import SigMFGenerator

# generate a 1 kHz tone at 48 kHz sample rate for 1 second
signal = SigMFGenerator().tone(1000).sample_rate(48000).duration(1.0).generate()
signal.read_samples()  # complex64 numpy array

The returned object is a standard SigMFFile backed by an in-memory buffer, so all the usual metadata and data access methods work.

Combining Components

Chain multiple .tone() and .sweep() calls to build multi-component signals. Each component gets its own annotation with frequency bounds and a label.

signal = (
    SigMFGenerator()
    .tone(1000)
    .tone(-2500)
    .sweep(500, 4000)
    .sample_rate(48000)
    .duration(0.5)
    .snr(20)
    .generate()
)

# each component is annotated individually
for annotation in signal.get_annotations():
    print(annotation)

Random Test Signals

Calling .generate() with no components produces a fully random signal. A seed ensures reproducibility across runs.

# deterministic random signal
signal = SigMFGenerator(seed=0xDEADBEEF).generate()

# the number and type of components are randomly chosen
print(signal.description)  # e.g. "synthetic signal with 3 tones and 2 sweeps"
print(signal.get_annotations())  # one annotation per component

Without a seed, each call produces a different signal.

Metadata & Annotations

Annotations are automatically created for each signal component, noise floor, and any applied frequency or phase offsets. Metadata fields like description, author, and comment can be set via the builder.

signal = (
    SigMFGenerator()
    .tone(440)
    .sample_rate(44100)
    .duration(1.0)
    .snr(25)
    .frequency_offset(1000)
    .author("test@example.com")
    .description("test tone with noise")
    .comment("for unit testing")
    .generate()
)

print(signal.get_global_info())
print(signal.get_annotations())

API

class sigmf.siggen.SigMFGenerator(seed: int | None = None)

Builder pattern class for generating synthetic RF signals as SigMF files.

Supports deterministic generation (with specified parameters) and random generation (parameterless methods with seed-controlled randomness).

Parameters:: seed (int, optional) – Random seed for reproducible signal generation.

Examples

>>> # deterministic 1khz tone
>>> gen = SigMFGenerator(seed=42)
>>> signal = gen.tone(1000).sample_rate(48000).duration(1.0).generate()

>>> # multiple tones combined
>>> signal = gen.tone(1000).tone(1500).tone(2000).generate()

>>> # tone plus sweep
>>> signal = SigMFGenerator().sample_rate(100e3).tone(440).sweep(1000, 5000).duration(0.5).generate()

amplitude(amplitude: float)

Set signal amplitude.

Parameters:: amplitude (float) – Signal amplitude (linear scale).
Returns:: Self for method chaining.
Return type:: SigMFGenerator

author(author: str)

Set author metadata.

Parameters:: author (str) – Author name/email.
Returns:: Self for method chaining.
Return type:: SigMFGenerator

comment(comment: str)

Set comment metadata.

Parameters:: comment (str) – Comment text.
Returns:: Self for method chaining.
Return type:: SigMFGenerator

description(description: str)

Set description metadata.

Parameters:: description (str) – Signal description.
Returns:: Self for method chaining.
Return type:: SigMFGenerator

duration(duration_s: float)

Set signal duration.

Parameters:: duration_s (float) – Duration in seconds.
Returns:: Self for method chaining.
Return type:: SigMFGenerator

frequency_offset(offset_hz: float)

Add frequency offset to signal.

Parameters:: offset_hz (float) – Frequency offset in Hz.
Returns:: Self for method chaining.
Return type:: SigMFGenerator

generate() → SigMFFile

Generate the synthetic signal and return as sigmf file.

Returns:: Generated signal file with metadata.
Return type:: SigMFFile
Raises:: SigMFGeneratorError – If required parameters are missing or invalid.

phase_offset(offset_rad: float)

Add phase offset to signal.

Parameters:: offset_rad (float) – Phase offset in radians.
Returns:: Self for method chaining.
Return type:: SigMFGenerator

sample_rate(rate_hz: float)

Set sample rate.

Parameters:: rate_hz (float) – Sample rate in Hz.
Returns:: Self for method chaining.
Return type:: SigMFGenerator

snr(snr_db: float)

Add white gaussian noise at specified snr.

Parameters:: snr_db (float) – Signal-to-noise ratio in dB.
Returns:: Self for method chaining.
Return type:: SigMFGenerator

sweep(start_frequency_hz: float | None = None, end_frequency_hz: float | None = None, amplitude: float | None = None)

Add a linear frequency sweep to the signal.

Parameters:

start_frequency_hz (float, optional) – Starting frequency in Hz. If None, will be randomly generated.
end_frequency_hz (float, optional) – Ending frequency in Hz. If None, will be randomly generated.
amplitude (float, optional) – Sweep amplitude (linear scale). If None, uses default amplitude.

Returns:

Self for method chaining.

Return type:

SigMFGenerator

tone(frequency_hz: float | None = None, amplitude: float | None = None)

Add a sinusoidal tone to the signal.

Parameters:

frequency_hz (float, optional) – Tone frequency in Hz. If None, will be randomly generated.
amplitude (float, optional) – Tone amplitude (linear scale). If None, uses default amplitude.

Returns:

Self for method chaining.

Return type:

SigMFGenerator