Guides
Record and replay
Capture sessions in the GUI and select them in SessionManager for training. Replay a session offline to debug prediction without repeating the experiment.
Live capture
Drop two widgets in @app.ui:
from myogestic.widgets import RecordingControls, SessionManager
CLASSES = ["Rest", "Fist", "Open"]
recording = RecordingControls( CLASSES, on_record=app.start_recording, on_stop=app.stop_recording, on_gesture=lambda i: ctrl_outlet.push_sample([float(i)]),)sessions = SessionManager(base_path="data", class_names=CLASSES)
@app.uidef ui(ctx): with grid[0, 0]: recording.ui(ctx) with grid[1, 0]: pipeline.training_data = sessions.ui()RecordingControls renders:
- Record / Stop buttons that call
app.start_recording()/app.stop_recording()("data"is the default root). - One button per class. Clicking a button writes a
LabelEvent(class_index, timestamp=local_clock())to the active session’s label track and fires youron_gesturecallback. Use the callback to drive an external pattern (synthetic generator, robot, prompt screen).
The on_gesture callback is yours; while recording, the label is added by RecordingControls itself before calling it. The selected gesture is also labelled when capture starts. You don’t need to call ctx.session.add_label() manually.
Timed takes
Offer fixed-length takes alongside the usual Start / stop mode:
recording = RecordingControls( CLASSES, on_record=app.start_recording, on_stop=app.stop_recording, take_lengths=(3.0, 5.0, 10.0), warmups=(0.0, 1.0, 2.0, 3.0), timed=True, take_length=5.0, warmup=2.0,)By default, the widget starts in Start / stop mode. Pass timed=True to open in
Timed, which shows the take-length and warm-up choices. The keyword-only
take_length and warmup arguments select the initial entries; each defaults to
None, selecting the first value in take_lengths or warmups. An explicit value
outside its sequence raises ValueError naming the allowed values. The example
above opens in Timed at 5 s with a 2 s warm-up, as Myocontrol does.
Empty take_lengths keeps start/stop only; timed=True without any take lengths
raises ValueError. Take lengths must be finite and positive; warm-ups must be
finite and nonnegative, with at least one choice. Zero is Off and starts capture
on the Record press.
Choose a gesture before starting a labelled timed take. Warm-up records nothing.
Cancel returns to idle without creating a session.
When capture begins, the chosen gesture is labelled once and the other tiles are
disabled until the take ends. The action row shows elapsed / target time and a
progress line. The first UI frame at or after the deadline calls on_stop, saving
the take through the existing app callback. Timing resolution follows the frame
rate; a delayed frame stops immediately when it resumes. Stop early also saves
the captured data and marks the confirmation (stopped early). The confirmation
lasts two seconds. Start/stop mode shows elapsed time and permits gesture changes.
recording.take is an immutable snapshot with phase (idle, warmup, recording,
or saved), timed, gesture, elapsed_s, length_s, warmup_left_s, and
saved_text. Read it after ui() to draw a signal overlay, as Myocontrol does.
Call recording.ui(ctx, visible=False) on frames where another workflow step is
open: this advances the timer without drawing controls. Call ui() once per frame.
Participant changes or a recorded stream disconnecting cancel a countdown; during
capture they stop and retain the data already collected, then return the widget
to idle. An outside stop or a replacement session clears the widget’s pending
action without stopping another capture. Calling app.stop_recording() during
warm-up cancels that countdown even though the app is still idle.
Saved sessions
SessionManager lists folders and archives under base_path when you press its rescan icon.
Passing ui(participant="P-014") scans that participant’s subfolder automatically. Each take
occupies one line, grouped by its recorded day (Today, Yesterday, or a date); only the newest
group starts open. A take’s gesture names, time, and duration stay on that line, with its file
name, optional take name, and streams in the tooltip. The list alone scrolls, leaving the
header, selected count, and gesture chips visible.
Use All / None to select or clear every take, including collapsed days. Gesture chips show totals across all listed takes; toggling one excludes that class from training and mutes its chips in the take rows. Exclusions survive None followed by All, and reset when you change participants or clear the list. The load icon adds files from elsewhere under Loaded; the broom clears the list while leaving files on disk.
ui() returns a TrainingData instance ready for @pipeline.train.
selection() reads the same selection without rendering or scanning: n_selected, n_total,
and class_seconds (selected takes and included gestures only). Older recordings without
per-gesture duration metadata contribute zero seconds for their labels. Myocontrol’s Train
card uses this summary for its gesture bars and total, explains missing gestures before a fit,
and shows the saved model’s filename after training.
Recording cycles
For models that need many short trials per session, record cycle-style:
[Record] [Rest] 3 s "rest" [Fist] 3 s "first activation" [Rest] 3 s [Fist] 3 s "second activation" ...[Stop]One Record→Stop cycle yields one session, with one labelled segment per gesture selection. iter_labeled_windows includes the first segment and slices each segment into as many full windows as fit. Repeated activations provide separate trials. Extra overlapping windows from
one sustained hold do not add activations.
Reading sessions programmatically
Use open_session_store for either layout (folder or .mg.zip). Older takes, named .session.zip, open the same way:
from myogestic.session import open_session_store
sess = open_session_store("data/recordings/20260506-1846_R+F.mg.zip")
# Continuous data - sample-major as recordeddata, ts = sess.get_continuous("emg")print(data.shape, ts.shape) # (N, n_ch), (N,)
# Stream metadatainfo = sess.stream_info("emg")print(info.n_channels, info.fs, info.channel_names)
# Per-trial slicesfor r in sess.get_trials("emg", pre_s=0, post_s=0, class_names=sess.class_names): print(r.class_name, r.data.shape, r.timestamps.shape)r.data is (n_samples, n_channels) - sample-major (as stored on disk).
Iterating windows for training
Classification - iter_labeled_windows
from myogestic.session import iter_labeled_windows
X, y = [], []for window, ts, cls in iter_labeled_windows( data.paths, stream_name="emg", window_ms=200, hop_ms=100, classes={0, 1, 2},): X.append(rms(window)) # window: (n_channels, n_samples) y.append(cls)window_ms/hop_ms: window duration / step in milliseconds.classes: optional set of class indices to include (handy when you want to skip “rest”).- Drops windows that straddle a label boundary so each window has exactly one class.
- Each iteration yields
(window, ts, class_index)-tsis the matching 1-D timestamp array. windowis channels-first - match your feature extractor.
Regression - iter_aligned_windows
from myogestic.session import iter_aligned_windows
X, Y = [], []for window, targets, ts in iter_aligned_windows( paths=data.paths, primary_stream_name="emg", aligned_stream_names=["vhi_guide"], window_ms=200, hop_ms=50, n_alignment_samples=1,): X.append(rms(window)) Y.append(targets["vhi_guide"]) # 1-D vector aligned to the window midpointprimary_stream_nameis the stream you slice into windows.aligned_stream_nameslists the target streams sampled nearest the EMG window’s midpoint.n_alignment_samplesis the number of nearby target samples to average, clipped at the stream’s ends.
Replay as a Source
ReplaySource reads from a .mg.zip (or folder) and re-emits the data at the original sample rate, like a live device:
from myogestic import App, Streamfrom myogestic.sources import ReplaySource
app = App("Offline replay")app.streams( Stream( "emg", source=ReplaySource( session_path="data/recordings/20260506-1846_R+F.mg.zip", stream_name="emg", speed=1.0, # 0.5 = half-speed, 2.0 = double-speed ), window_ms=1000, ))if not app.ctx.streams["emg"].reconnect(): raise RuntimeError(app.ctx.streams["emg"].last_error)app.run()Your @pipeline.predict receives replayed data with the recorded shape, channel count and timestamps. Use replay for:
- Debugging the predict path without re-running the experiment.
- Comparing models on a fixed input.
- Demos without hardware.
The replay loops back to the start when it reaches the end. speed scales the pacing against
wall-clock time. speed=0 halts after the first chunk; replay has no manual-advance call.
Record a prediction run
Load or train a model, press Predict, then press Record. The pill row reads PREDICTING REC. In Myocontrol’s Drive step, use Record this run while predicting. Press it again to save; predicting continues. Stop predicting saves an open run first, then returns to idle. Drive runs appear in Takes with a Drive tag and stay unticked for training until selected.
Stop when done; the archive holds the raw streams and what the model saw and did:
from myogestic.session import open_session_storeimport numpy as np
with open_session_store("data/P-014/predictions/P-014_20260913-1012_free.mg.zip") as s: print(s.event_streams) # ('features.vec', 'prediction.pose', 'pipeline.tick', 'controls') pose = np.array(s.stores["prediction.pose"]) # (n_ticks, 5) t = np.array(s.ts_stores["prediction.pose"]) # data time of each tick tick = np.array(s.stores["pipeline.tick"])[:, 0] # decision clock print("median latency", np.median(tick - t), "s") print(s.extras["pipeline"]["model"]) # 'model.joblib', beside the arraysThe model is pickled into the session when pipeline.save_model is set (the ML widgets’ Save button uses the same callable). Unrecordable values returned by extract or predict, such as text or 2-D arrays, are named in s.extras["pipeline"]["skipped"] with the reason. When the model running was trained in this app, s.extras["pipeline"]["trained_on"] lists the takes it learnt from, and ["model_file"] names its file in models/ if it was autosaved; a model loaded from disk or set by hand records neither.
Check a replay against the live run
Run the same app on the recording with ReplaySource(path, "emg") in place of the device, press Predict, press Record, and stop before the replay loops back to the start. ReplaySource returns the recorded timestamps, so both sessions are in the same clock. Ticks can fall on different samples because wall time paces prediction. Feature frames anchored to ring position can also shift phase. Compare one monotonic pass by nearest timestamp within half a tick:
live = open_session_store("live.mg.zip")replay = open_session_store("replay.mg.zip")tl, pl = np.array(live.ts_stores["prediction.pose"]), np.array(live.stores["prediction.pose"])tr, pr = np.array(replay.ts_stores["prediction.pose"]), np.array(replay.stores["prediction.pose"])j = np.searchsorted(tr, tl).clip(1, len(tr) - 1)j = np.where(np.abs(tr[j - 1] - tl) < np.abs(tr[j] - tl), j - 1, j)close = np.abs(tr[j] - tl) < 0.5 / live.extras["pipeline"]["predict_hz"]print("matched", close.mean(), "max |Δpose|", np.abs(pr[j][close] - pl[close]).max())For exact matches, anchor the extract frame grid to data timestamps.
The app chooses that anchoring; a grid based on ring position does not provide it.
Common mistakes
See Troubleshooting for errors by symptom.
- Recording too short. A labelled segment shorter than
window_msyields no training windows. Record repeated holds long enough for full windows, and check counts before training. sess.class_names = [...]aftersave_meta. Class names persist only when passed as a kwarg tosave_meta(name, class_names=...). (RecordingControlshandles this when it triggersapp.start_recording.)- Sample-major in user code.
sess.get_continuous("emg")returns sample-major (matches storage).iter_labeled_windowsanditer_aligned_windowsflip to channels-first (matches predict). Don’t transpose twice by accident. - Replay-then-predict-on-live.
ReplaySourceand a realLSLSourcecan’t share the stream name. Pick one per app.