# SigMF stream

Replay a radio recording in real time

Stream a [SigMF](https://sigmf.org) recording to Nominal in real time, as if a software-defined
radio were capturing it now, at the recorded sample rate or a fraction of it. The recording is IQEngine’s `synthetic` example by
Marc ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)): 2 seconds at 480 kS/s. It comes from
[`nbdemo.data`](https://dev.nominal.io/demos/reference/data.md), which downloads it on first use.

**Requirements:** a `default` [profile](https://nominal-io.github.io/nominal-client/guides/api-keys-setup/)
for the Nominal Python Client, and the packages the notebook imports, including `nbdemo[rf]`.
[Running the notebooks](https://dev.nominal.io/demos/running.md) explains how to set them up.

Each execution of the notebook reuses the asset. It archives the dataset that earlier executions
streamed to, so the asset holds one dataset: this execution’s.

## Load the recording

A SigMF recording is a metadata file (`.sigmf-meta`) and the raw samples (`.sigmf-data`).
`nbdemo.data` reads both; the metadata holds the sample rate.

```ipython3
import numpy as np
from nbdemo.data.rf import sigmf_synthetic

recording = sigmf_synthetic.native  # a SigMFRecording, downloaded on first use
rate = recording.sample_rate  # samples per second
iq = recording.read_samples()  # complex samples
print(f"{len(iq):,} samples at {rate:,.0f} S/s = {len(iq) / rate:.1f} s")
```

```myst-ansi
1,000,000 samples at 480,000 S/s = 2.1 s
```

## Connect to Nominal

```ipython3
from nominal.core import NominalClient, set_display_options

# A Nominal object at the end of a cell displays as a card.
set_display_options(time_format="readable")

client = NominalClient.from_profile("default")
```

## Create the dataset

```ipython3
asset = client.get_or_create_asset_by_properties(
    {"example": "sigmf_stream"},
    name="VirtualSDR",
    description="A virtual software-defined radio, replaying a SigMF recording",
)
dataset = asset.get_or_create_dataset(
    "iq",
    name="iq",
    description="The recording's samples, streamed in real time",
)
dataset
```

```
Dataset(rid='ri.catalog.cerulean-staging.dataset.20ab35ec-9ccf-9d67-fded-0754971736ca', name='iq', description="The recording's samples, streamed in real time", properties=mappingproxy({}), labels=(), bounds=None, is_archived=False)
```

Dataset **iq** [Open in Nominal ↗](https://app.gov.nominal.io/w/ri.security.cerulean-staging.workspace.1870868e-c361-fd28-4bd5-e1b2325eb774/datasets/ri.catalog.cerulean-staging.dataset.20ab35ec-9ccf-9d67-fded-0754971736ca)

| RID | `ri.catalog.cerulean-staging.dataset.20ab35ec-9ccf-9d67-fded-0754971736ca`⧉ |
| --- | --- |
| Description | The recording's samples, streamed in real time |
| Data | none yet |

## Stream

A radio hands over samples a buffer at a time, so the loop sends 4,096 samples (8.5 ms) when that
buffer would have finished filling. Sample *n* is stamped with the start time plus *n* / `stream_rate`,
so the data has the same spacing as a radio sampling at that rate.

`RATE_FACTOR` scales the recording’s sample rate. At 1.0 the stream matches the recording’s
480 kS/s. At 0.01, the default, it plays at 4.8 kS/s: the same samples, a hundred times slower. The
docs build doesn’t run this cell, since it streams in real time.

Set `LOOP_FOREVER = True` to replay the recording until you interrupt the kernel, with timestamps
continuing across replays.

The status line below the cell updates every second. `lag` is how late the latest buffer was sent. It
stays near 0 ms while the loop keeps up with `stream_rate`, and the status changes to
FALLING BEHIND once it passes 100 ms.

```ipython3
import time

from IPython.display import display

LOOP_FOREVER = False  # True: replay until interrupted
BLOCK = 4096  # samples per buffer
RATE_FACTOR = 0.01  # 1.0: the recorded sample rate; 0.01: one hundredth of it
stream_rate = rate * RATE_FACTOR  # samples per second to stream
REPORT = 1.0  # seconds between status updates

start = time.time_ns()
sent = 0  # samples sent so far, across replays
worst_lag = 0.0  # the largest delay behind real time, in seconds
next_report = start
status = display("starting...", display_id=True)  # updated in place while streaming
with dataset.get_write_stream() as stream:
    while True:
        for i in range(0, len(iq), BLOCK):
            block = iq[i : i + BLOCK]
            index = sent + np.arange(len(block))
            times = start + np.round(index * 1e9 / stream_rate).astype("int64")
            sent += len(block)
            # wait until the buffer would have finished filling
            due = start + sent * 1e9 / stream_rate
            time.sleep(max(0.0, (due - time.time_ns()) / 1e9))
            stream.enqueue_batch("i", times, block.real)
            stream.enqueue_batch("q", times, block.imag)
            # lag: how late this buffer was sent, 0 when the loop keeps up
            lag = (time.time_ns() - due) / 1e9
            worst_lag = max(worst_lag, lag)
            if time.time_ns() >= next_report:
                next_report += int(REPORT * 1e9)
                elapsed = (time.time_ns() - start) / 1e9
                state = "OK" if lag < 0.1 else "FALLING BEHIND"
                status.update(
                    f"{state}: streamed {sent:,} samples in {elapsed:.0f} s "
                    f"({sent / elapsed:,.0f} S/s, streaming at {stream_rate:,.0f} S/s), "
                    f"lag {lag * 1e3:.1f} ms, worst {worst_lag * 1e3:.1f} ms"
                )
        if not LOOP_FOREVER:
            break
    elapsed = (time.time_ns() - start) / 1e9
status.update(
    f"done: streamed {sent:,} samples in {elapsed:.2f} s, worst lag {worst_lag * 1e3:.1f} ms"
)
```

[![The streamed I and Q samples plotted against time in a Nominal workbook, zoomed in to a few milliseconds](https://dev.nominal.io/demos/_images/sigmf-stream-thumbnail.png)](https://dev.nominal.io/demos/_images/sigmf-stream-thumbnail.png)
