Get started
Troubleshooting
Find a symptom, its cause and its fix below. The concept and how-to pages link here from their “Common mistakes” sections.
Streams and acquisition
“buffer empty” or no data on the first read
Stream.get_window() returns an empty array because the acquisition thread hasn’t received any chunks yet. Either the source isn’t connected (stream.info is None), or the upstream LSL outlet hasn’t started publishing.
Acquisition thread freezes
A blocking call inside the source’s read() pauses acquisition and ring-buffer updates, delaying prediction. Custom sources should poll without blocking, for example with pylsl.pull_chunk(timeout=0.0).
Wrong shape from a custom source
If a Source adapter accidentally returns (n_channels, n_samples) instead of sample-major (n_samples, n_channels), the recording layer writes a Zarr array with the wrong shape and replay won’t match.
See Streams concept page, Add a custom source.
Recording
One-click sessions yield bad models
iter_labeled_windows uses every nonnegative labeled segment long enough for a window, including the first. One short trial per class may supply too few representative windows for a useful model.
sess.class_names = [...] doesn’t persist
Setting class_names as an attribute on the session object after the fact doesn’t write it to meta.json. Pass the class names to sess.save_meta(name, class_names=[...]) to persist them.
Waiting for a .mg.zip save
app.stop_recording() normally finalizes and packs the session on a daemon thread. Returning from it does not mean the archive is ready. App.run() cleanup saves an open take inline and waits up to 30 seconds for saves already in progress.
See Recording concept page, Record and replay, Run headless.
Pipeline (training and prediction)
Predict thread won’t fire
Several causes:
pipeline.start_predicting()was never called. Click Predict in the GUI or call it in headless mode.pipeline.model is None. Train first or load a saved model withpipeline.load_model = load_pickleplus the Load Model button / explicit call.- Your
@pipeline.predictreturned a non-dictvalue. Non-dict returns are silently dropped and the previous prediction stays inpipeline.predictions. - The app is still in
idle,recordingortraining, so prediction has not started.start_predicting()accepts eitheridleorrecording; also check that input windows are nonempty and both decorators are wired.
“Save Model button is disabled”
pipeline.save_model is unset, so the button has no callable to invoke.
“GPU contention” / training and predict don’t run together
The state machine refuses entry to training while predicting, and vice versa, to avoid
PyTorch CUDA memory contention. This exclusion is intentional and is not a bug.
extract() shape mismatch after retraining
Your extract() returns a different feature dimensionality from what the trained model expects. Check whether WINDOW_MS or HOP_MS changed between training and predicting.
See Pipeline concept page, Add a custom model.
Widgets and the UI
Widget appears in the wrong place / overlaps another
Grid cells use Python slicing conventions. grid[0:6, 1:3] is rows 0-5 inclusive, cols 1-2 inclusive. Two widgets occupying overlapping cells will draw on top of each other.
Widget state shared accidentally between instances
Two SignalViewer("emg") instances share state because their default identity is the stream name. Give them distinct widget_id values to view the same stream independently.
Widget calls work in @app.ui but not elsewhere
Dear ImGui is not thread-safe. Call widgets inside @app.ui on the render thread. Calling them from the predict thread or a custom thread will crash or silently do nothing.
See Widgets concept page, Add a custom widget.
Outputs
An outlet sends old values forever
Outlet.push(data) writes to a latest-value slot. The output thread sends whatever’s in the slot every 1/hz. If you stop pushing but the slot still holds the last value, the same value gets re-sent forever.
The output thread falls behind
Your _send takes longer than 1/hz per call. The daemon thread can’t keep up.
Virtual Hand Interface
“VHI launcher button errors” / FileNotFoundError
Install VHI where virtual_hand() looks by default, at <repo>/tools/MyoGestic-VHI in a git checkout or <user_data>/myogestic/vhi elsewhere. Before calling Popen, the launcher raises a FileNotFoundError with the exact install command.
VHI hand looks twitchy
You’re pushing raw model output. VHI moving at 32-50 Hz amplifies any per-tick jitter.
VHI hand drifts after retraining
The OneEuroFilter keeps smoothing history across training boundaries; the first few frames after a retrain blend the new model’s first prediction with the old model’s tail.
See Integrate the Virtual Hand, Post-process predictions.
Threading and performance
time.sleep in @pipeline.predict delays predictions
It blocks the predict thread. The framework already paces ticks at predict_hz.
Stale-tick warnings
Predict thread is firing faster than acquisition is producing new data. Stateful models check last_ts and short-circuit when the timestamp hasn’t advanced.