Guides
Enable on-disk recording
Capture every connected Stream’s samples to a Zarr-backed .mg.zip archive through GUI controls or the headless API. Both flows produce the same artefact. The API gives full programmatic control over configuration, lifecycle, storage and read-back.
Enable recording in four lines
from myogestic import App, Streamfrom myogestic.sources import LSLSourcefrom myogestic.widgets import RecordingControls
app = App("My recording") # 1. construct Appapp.streams(Stream("emg", source=LSLSource("EMG"), window_ms=1000)) # 2. register stream(s)if not app.ctx.streams["emg"].reconnect(): raise RuntimeError(app.ctx.streams["emg"].last_error)
recording = RecordingControls( ["Rest", "Fist"], on_record=app.start_recording, # 3. wire Record button on_stop=app.stop_recording,) # 4. wire Stop button
@app.uidef ui(ctx): recording.ui(ctx)
app.run()Click Record → data flows into data/<ID>/recordings/<ID>_<YYYYMMDD-HHMM>/ (or data/recordings/<YYYYMMDD-HHMM>/ with no participant set). Click Stop → that folder packs into <ID>_<YYYYMMDD-HHMM>_<codes>.mg.zip beside it, named for the gestures it recorded (P-014_20260517-1423_R+F.mg.zip). See File names for the naming standard.
Capture and name a take
RecordingControls provides one button per gesture class; each click writes a label event. Use RecordButton to capture a signal and name the take after stopping:
from myogestic.widgets import RecordButton
recorder = RecordButton( on_record=app.start_recording, on_stop=app.stop_recording, on_discard=app.discard_recording, # optional; omit and the dialog offers no Discard)Stop detaches the streams before the naming dialog opens. Time spent naming the take is excluded from the recording.
The full-width red Record button becomes a tinted Recording row with a mono elapsed clock and Stop. After stopping, a surface row shows the captured duration; the naming dialog offers Name (optional), a preview of the resulting file stem, Save, and an outlined Discard labelled with the captured duration when a discard handler is supplied. If the app requires a participant, Record stays disabled with a visible reminder to set their ID first.
The name is written to meta.json and appended to the archive filename, so a saved take is <ID>_<YYYYMMDD-HHMM>[_<codes>][_<name>].mg.zip beside its original recording folder and appears in SessionManager with gesture chips, time, and duration; its tooltip preserves the take name and archive filename. The optional codes segment holds a short code for each class with recorded time, in class-index order, joined with + (Fist and Open hand give F+Oh); past 40 characters it becomes the first three codes and a count (R+F+P+6-more). The typed name is slugged down to ASCII letters, digits, - and _. Naming is optional; a take with neither codes nor a name is <ID>_<YYYYMMDD-HHMM>.mg.zip. A second take with the same name in the same minute gets -2. See File names for how codes are chosen and pinned.
Discard calls app.discard_recording() to remove the take folder without writing an archive.
It is a separate counterpart to stop_recording(). It does not save a take and then clean it up.
Lifecycle in detail
┌──────────────────────────────────────────────────────┐ │ │ │ App.run() │ │ ├─ stream.start() ── acquisition threads spin │ │ └─ enter GUI loop │ │ │ │ ┌─ user clicks Record ────────────────────────┐ │ │ │ app.start_recording(base_path="data") │ │ │ │ ├─ ctx.recording = True │ │ │ │ ├─ idle → recording; predicting stays │ │ │ │ ├─ ctx.session = Session(base_path, ...) │ │ │ │ ├─ Session.init_stream(name, info) │ │ │ │ │ creates <stream>.zarr and │ │ │ │ │ <stream>_timestamps.zarr │ │ │ │ └─ acquisition threads now append to Zarr │ │ │ │ │ │ │ │ user clicks gesture buttons │ │ │ │ recording_controls adds │ │ │ │ ctx.session.add_label(class_idx, │ │ │ │ timestamp=local_clock()) │ │ │ │ │ │ │ │ user clicks Stop │ │ │ │ app.stop_recording() │ │ │ │ ├─ detach streams; freeze session │ │ │ │ ├─ finalize hooks; Session.save_meta(...) │ │ │ │ ├─ writes meta.json + labels.json │ │ │ │ ├─ Session.pack_to_zip() (daemon thread) │ │ │ │ │ -> <stamp>_<what>.mg.zip │ │ │ │ │ folder removed once pack succeeds │ │ │ │ └─ recording → idle; predicting stays │ │ │ └────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────┘The artefact
data/P-014/recordings/└── P-014_20260517-1423_R+F.mg.zip # final packaged artifact # (after Stop completes)A take started while a model is predicting goes to data/P-014/predictions/ instead, and
Pipeline.autosave_dir writes trained models to data/P-014/models/. See
On-disk layout.
Inside the zip:
P-014_20260517-1423_R+F.mg.zip├── emg.zarr/ # shape (n_samples, n_channels), dtype = stream dtype│ └── chunks: (fs, n_channels) # 1 second per chunk├── emg_timestamps.zarr/ # shape (n_samples,) float64 LSL clock seconds│ └── chunks: (fs,)├── vhi_control.zarr/ # one pair of arrays per registered Stream├── vhi_control_timestamps.zarr/├── meta.json # app_name, created (start time), streams (n_channels, fs, dtype), class_names└── labels.json # list of {timestamp, class_index}While recording is in progress and before stop_recording() completes, the same content lives as an unpacked folder data/P-014/recordings/P-014_20260517-1423/. The folder is deleted only after the zip is verified.
Zarr defaults
Recording uses Zarr v3 with these defaults, applied per registered Stream:
| Setting | Value | Why |
|---|---|---|
| Sample array shape | (n_samples, n_channels) |
sample-major, append-only |
| Sample array chunk | (int(fs), n_channels) |
one second of data per chunk |
| Sample array dtype | the Stream’s StreamInfo.dtype (typically float32) |
matches what the source produced |
| Timestamp array shape | (n_samples,) |
parallel to sample array |
| Timestamp array chunk | (int(fs),) |
one second per chunk |
| Timestamp array dtype | float64 |
LSL clock seconds |
| Outer zip compression | ZIP_STORED (none) |
Zarr chunks already compress internally |
Defaults are computed from each Stream’s StreamInfo; they are not configured per recording. Set the storage location with base_path. Install the [zarrs] extra to use a Rust-accelerated codec pipeline:
uv sync --extra zarrs # transparent speedup; no code change neededWith zarrs installed, MyoGestic registers zarrs.ZarrsCodecPipeline at import time to speed up large-session reads and writes. Otherwise it uses Python Zarr.
Headless flow (no GUI)
For unattended capture, drive the same API from a plain script. Use mode="headless" so app.run() doesn’t try to open a window:
import osimport signalimport threadingimport timefrom myogestic import App, Streamfrom myogestic.sources import LSLSource
app = App("Headless capture")app.streams(Stream("emg", source=LSLSource("EMG"), window_ms=1000))if not app.ctx.streams["emg"].reconnect(): raise RuntimeError(app.ctx.streams["emg"].last_error)app.ctx.class_names = ["Rest", "Fist"]
def _capture(app): # Run on a background thread so app.run()'s main loop can spin # the acquisition threads while we sleep here. def _run(): time.sleep(2) # let buffers warm up app.start_recording("data") app.ctx.session.add_label(0) # initial class index for class_idx in (1, 0, 1, 0): # cycle Fist <-> Rest time.sleep(5) app.ctx.session.add_label(class_idx) time.sleep(5) app.stop_recording(wait=True) os.kill(os.getpid(), signal.SIGINT) # return through App.run cleanup
threading.Thread(target=_run, daemon=True).start()
app.before_run_hooks.append(_capture)app.run(mode="headless")The artefact lands in data/recordings/ (or data/<ID>/recordings/ with a participant set) as in the GUI flow.
Custom GUI integration
Call the API directly for custom Record buttons, conditional triggers or multi-step protocols:
from imgui_bundle import imguifrom mne_lsl.lsl import local_clock
@app.uidef ui(ctx): if ctx.state == "idle": if imgui.button("Start trial"): app.start_recording(base_path="experiments/trial5") # Optional: stamp an initial label so first samples are # labeled before any user input. app.ctx.session.add_label(class_index=0, timestamp=local_clock()) elif ctx.state == "recording": imgui.text(f"Recording: {app.ctx.session.path}") if imgui.button("Stop trial"): app.stop_recording()The Session API surface
When ctx.state == "recording", app.ctx.session is a live Session instance you can access directly:
| Method | Purpose |
|---|---|
Session(base_path="data") |
Constructor (called by start_recording; you rarely need it directly). |
session.path |
Path to the session folder being written. |
session.stores[name] |
The live zarr.Array for stream name (sample data, append-only). |
session.ts_stores[name] |
Parallel timestamp zarr.Array for stream name. |
session.label_track |
list[LabelEvent] of all labels added so far. |
session.add_label(class_index, timestamp=None) |
Append one label. timestamp defaults to local_clock(). |
session.init_stream(name, info) |
Pre-allocate Zarr arrays for one stream (auto-called by start_recording). |
session.append(name, data, timestamps) |
Append a chunk (auto-called by the acquisition thread). |
session.save_meta(app_name, class_names=None) |
Write meta.json and labels.json (auto-called by stop_recording). |
session.pack_to_zip() |
Pack folder into .mg.zip (auto-called on a daemon thread after stop). |
You typically only call add_label directly; everything else is wired by start_recording / stop_recording. The class is documented at myogestic.session.Session.
Reading sessions back
from myogestic.session import open_session_store
# Works for both packed zips AND unpacked folders.sess = open_session_store("data/P-014/recordings/P-014_20260517-1423_R+F.mg.zip")
emg = sess.stores["emg"] # zarr.Array, shape (n_samples, n_channels)emg_ts = sess.ts_stores["emg"] # zarr.Array, shape (n_samples,) float64labels = sess.label_track # list[LabelEvent]info = sess.stream_info("emg") # StreamInfo(fs, n_channels, dtype)For windowed training iteration, use the helpers in myogestic.session:
from myogestic.session import iter_labeled_windows, iter_aligned_windows
# Classification: one (window, ts, class_index) per hop step.for window, ts, cls in iter_labeled_windows( [sess.path], stream_name="emg", window_ms=200, hop_ms=100, classes={0, 1},): ...
# Regression: align a primary stream with one or more aligned streams.for window, aligned, ts in iter_aligned_windows( [sess.path], primary_stream_name="emg", aligned_stream_names=["vhi_control"], window_ms=200, hop_ms=50,): target = aligned["vhi_control"] ...iter_labeled_windows keeps each window inside one labelled segment.
iter_aligned_windows ignores labels and samples each target near the primary
window’s midpoint. Both handle the window/hop math. See Record and replay and the Recording concept page.
Common pitfalls
-
Calling
start_recordingbefore streams connect. AStreamwhoseinfo is Noneis skipped (no Zarr schema yet). Callstream.reconnect()and check its result first.App.run()starts acquisition threads but does not connect their sources. -
Recording with the synthetic generator paused. The generator only produces data while it’s running. Click Launch in the
ProcessLauncherpanel before Record, or in headless flow start the generator subprocess beforeapp.run(). -
Killing the process mid-recording. The
.mg.zipis packed only atstop_recording(). Starting a take writesmeta.jsonwithfinished: false; each stream declaration checkpoints its schema, and a normal stop updates the metadata withfinished: true. A crash leaves the rawdata/<ID>/recordings/<ID>_<timestamp>/folder (orpredictions/for a prediction take), readable withopen_session_store(...)and listed bySessionManager. With the recording process stopped, pack that folder through the normal verified pack path:Python from myogestic.session import recover_sessionarchive = recover_session("data/P-001/recordings/P-001_20261107-0930")Recovery removes the folder after packing succeeds and keeps
finished: falsein the archive. It recovers samples and event batches already written to disk; buffered event rows, labels and extras changed since the last checkpoint, and outputs from finalize hooks may be missing. It does not resume recording or run those hooks. Metadata is written at start, stream declaration and stop, with no extra writes per acquisition chunk or event-buffer flush. Older crashed folders withoutmeta.jsoncannot be recovered this way. -
Forgetting class names.
RecordingControlssets them automatically. For custom labels, setapp.ctx.class_names = ["Rest", "Fist"]before stopping;stop_recordingpasses that list tosave_meta.
See also
- Recording concept page - the runtime model + label-track design.
- Record and replay - feeding a recorded session back into a
ReplaySourcefor offline debugging. myogestic.App.start_recording/stop_recording- full API reference for the lifecycle methods.myogestic.session.Session- fullSessionclass reference.myogestic.session.open_session_store- load packed or unpacked sessions.myogestic.session.iter_labeled_windows,iter_aligned_windows- training-window iterators.