Open-source PRAYCG pipeline: OpenBCI/LSL media protocol, timing QC, and exploratory EEG/autonomic
hbanks87
kansas city
Good evening,
I am preparing to release an open-source experimental pipeline built around OpenBCI, Lab Streaming Layer, media-based cognitive tasks, and post-processing analysis. I would like to share the GitHub/OSF materials here for technical critique from the OpenBCI community.
This project started out as an intense curiosity and has been a tremendous amount of fun. This is not a professional project. I did this for fun. I have no real idea as to whether it is valuable to anyone. The project is called PRAYCG. It is an exploratory psychophysiology protocol and software stack for testing whether naturalistic narrative stimuli produce measurable EEG/autonomic state trajectories beyond low-level sensory entrainment and beyond analytic task demand.
This is not a clinical tool, not a diagnostic system, and not a claim that OpenBCI can prove consciousness, memory biology, or any metaphysical theory. It is best understood as an open-source methods workbench for stimulus preparation, acquisition logistics, timing/QC, and exploratory analysis.
What the protocol does
The core design is a three-arm naturalistic viewing protocol:
Phase-scrambled sensory control
The source video is scrambled so recognizable story/faces/narrative meaning are damaged while low-level audiovisual structure is partially preserved. This is meant to ask: “Is the response just light, sound, motion, cuts, rhythm, cue timing, or audiovisual energy?”
Target narrative
The intact narrative is watched naturally. This asks: “What happens when the story is allowed to land?”
Contextual Override
The same intact narrative is watched again, but with an analytic task, usually an upper-right number-cue running-sum task. Target and Override use the same cue-embedded video; only the instructions differ. This asks: “What changes when the participant is measuring/extracting rather than receiving?”
Current hardware stack
My current setup uses:
OpenBCI Cyton + Daisy
OpenBCI gelfree/gelless cap workflow
BrainFlow/LSL EEG stream
LabRecorder XDF recording
ALS-PT19 or similar light sensor for physical screen timing
Polar H10 R-R intervals
Vernier respiration belt
optional Faraday/shielded enclosure setup(see the box section on github)
PRAYCG2.0 protocol runner with structured event logs and self-report/confound reports
What the software release includes
The repository contains or will contain:
MediaPrep + StimulusFingerprint
prepares Target, Override, and phase-scrambled Control videos
embeds cue schedules
generates stimulus-side QC and exogenous regressors
supports predeclared anchor files for event-locked analysis
PRAYCG2.0 Protocol Runner
loads Control, Target, Override, cue schedule, and anchor file
logs structured events
includes pre-run display/audio calibration
includes branch-level self-report and confound reports
includes final reflection baseline
supports override task reporting
BrainFlow / ALS / LSL tools
OpenBCI streaming helpers
ALS/PT19 timing-sensor support
LabRecorder workflow documentation
stream checklist and timing-QC workflow
Master Comprehensive Analysis Suite
time-resolved feature extraction
artifact scoring
stimulus-regressor residualization
MRED/A-MRED endpoint-compression modules
MRED-Peak vs MRED-Resolution
DGA / Decoder Gate Availability
NUPI / Narrative Update Polarity Index
visualization tools
offline plain-English report generator
Documentation
full end-to-end SOP from media procurement to analysis
hardware- how to build a faraday cage for eeg studies
formula/module explanation report
Main analysis idea
The current primary analysis direction is called MRED: Meaning Recognition / Encoding Dissociation.
In plain language, MRED asks whether the system can distinguish:
immediate recognition of meaningful material, versus
delayed integration, after-state, or regulatory carryover.
The compressed endpoint layer currently separates:
MRED-Peak: acute anchor-locked recognition + delayed integration
MRED-Resolution: slower reflective/regulatory recovery after the stimulus
A-MRED: anchor-locked MRED candidate that must pass condition, artifact, and QC gates
I am not treating gamma as a “meaning biomarker.” Lower-gamma/high-frequency features are treated as artifact-sensitive candidate work-signal proxies. The pipeline tries to penalize or flag muscle activity, eye/forehead artifact, cue burden, sensory drive, respiration, confounds, and exogenous stimulus timing.
Why I am posting here
I am looking for critique from people who know OpenBCI, EEG acquisition, artifact handling, and LSL better than I do.
The areas where I most want feedback are:
OpenBCI Cyton + Daisy acquisition reliability
gelfree/gelless cap best practices
BrainFlow configuration
LSL stream naming and synchronization
LabRecorder setup and XDF recording workflow
ALS/PT19 photodiode/light-sensor timing validation
whether my start-pulse design should be longer or barcode-like
artifact control for gamma-band claims
EOG/EMG channel additions
jaw/forehead/eye artifact separation
respiration and HRV integration
whether the analysis suite is overbuilt and how it should be simplified
how to make the public GitHub repository easier for other OpenBCI users to run
Current limitations
The project is exploratory and self-run so far. Several pilot runs revealed exactly the kinds of issues that need better engineering:
timing-pulse detection needing a better physical ALS holder
BrainFlow/OpenBCI effective sample-rate variability
cue visibility/legibility issues in some stimuli
gamma-band artifact vulnerability
the need for EOG/EMG
the need for cleaner locked-anchor and timing workflows
I am not presenting pilot outputs as confirmatory. The point of the current release is to expose the machinery and invite technical critique before treating anything as strong evidence.
Links
GitHub repository:
https://github.com/hbanks87/praycg-open
Here is a list of the fun ideas/theories that I have come up with as a result of running this protocol. The following are not proven claims. They are the current working hypotheses made visible by the protocol,
software, and pilot failures/successes:
- Meaning recognition and meaning integration can dissociate. A subject can recognize meaningful geometry without showing clean delayed integration under current proxies.
- Peak-like meaning and resolution-like meaning appear to have different physiological shapes. Some events strike sharply; others settle slowly into afterglow.
- Analytic extraction does not simply erase meaning. It can reroute, delay, tax, or alter the route by which
meaning is accessed. - Sensory clarity and emotional impact are separable. Clearer semantic access can occur in one branch while stronger emotional absorption occurs in another.
- Meaning requires access conditions. Sensory access, prior state-space, personal relevance, autonomic
availability, low task burden, and low confound load all matter. - Baseline2 may be one of the most important windows for integration, but it is cumulative and cannot be attributed to Target alone without stronger design.
- The phase-scrambled Control remains essential because sensory entrainment and meaning integration are not the same construct.
- The suite is increasingly a theory of availability: whether a living system is available to decode, receive, and be changed by meaning.
Again, this is not a claim of proof. It is an open-source exploratory pipeline, and I am sharing it because I want the engineering and analysis assumptions challenged.
Thank you for taking the time to read this and have a wonderful day,
Hoyt
Comments
Hoyt, thanks for posting your open source project.
I did find this document in your Github which provides a bit more background:
https://github.com/hbanks87/praycg-open/blob/main/docs/PRAYCG_Working_Theory_PUBLIC_v0_6.pdf
Can you elaborate on your project title, acronym, PRAYCG, which according to the Github breaks down to: PR-AYC-G. One of your summary statements above says:
So, some kind of 'story' is told, via various forms of narration (video, audio?), along with certain control stimuli which are expected to produce more predictable responses. If the narration is being received / interpreted correctly, isn't it natural to assume it 'lands' in the consciousness of the subject and is understood? Unless the person is sedated, isn't it normal to assume this reception goes beyond sensory entrainment? Does the story have emotional content, and you expect to measure emotional valence; EEG has been used for this in the past. It also sounds like some of your runs will impose moderate task loads on the subject, I assume to track whether this interferes with the story landing?
What kind of applications do you foresee with your project?
Regards, William
Hey William,
Thank you so much for taking the time to read my post and go through the github! Sincerely. Thank you for your time. My edited response:
You are right that, in ordinary language, if an awake person watches a story and understands it, we usually say the story “lands.” I am not trying to prove that people understand stories.
The narrower question is whether we can separate several things that usually arrive tangled together:
low-level audiovisual entrainment,
semantic or emotional reception of the story,
analytic task load, and
delayed after-state or carryover.
That is why PRAYCG uses a three-arm structure.
The current protocol is approximately:
Baseline 1
Eyes-open stillness baseline.
Phase-scrambled Control
The same source video is scrambled so recognizable story/faces/narrative content are damaged while some low-level audiovisual structure is preserved. This branch is not assumed to be physiologically dead. It is meant to ask whether a response can be explained by light, sound, motion, cuts, rhythm, cue timing, or audiovisual energy. This is achieved by a fourier transform to both audio/visual files.
Washout 1 + brief self-report / confound report
Target Narrative
The intact narrative is watched naturally. This is the receptive condition.
Washout 2 + self-report / confound report
Contextual Override
The same intact cued video is watched again, but the participant performs an analytic task. In my current version, this is usually a running-sum task using number cues displayed in the upper-right corner. Target and Override use the same cue-embedded video; only the instructions differ.
Washout 3 + Override task report
Final reflection baseline
A second 2-minute baseline after all three branches, intended to capture possible after-state / reflective carryover.
Final comparative self-report
The key engineering detail is that Target and Override are intended to be the same rendered stimulus file or bit-identical cue-embedded versions. The participant’s stance changes; the audiovisual input should not. The phase-scrambled Control is generated from the cue-embedded Target so that cue timing and low-level cue energy are represented in the control branch as well.
So yes, the story has emotional content. But I am trying to avoid treating this as a generic “happy/sad” valence-classification project. EEG has certainly been used for emotion/valence work before, and I am not trying to reinvent that. PRAYCG is more interested in the time course of a cognitive-emotional event: initial recognition, possible integration, task interference, and post-stimulus carryover.
The internal term I am using for this is MRED, Meaning Recognition / Encoding Dissociation. In plain language, MRED asks whether recognizing a meaningful moment and integrating or carrying it forward afterward are separable. A participant might understand a scene but not show much after-state carryover. Another scene might not produce a sharp peak but may produce a slower reflective afterglow. Another condition might preserve semantic understanding but change the physiological trajectory because the person is doing an analytic task.
The Contextual Override arm is meant to test that last issue. If the same intact stimulus produces a different EEG/autonomic pattern when the participant is forced into a running-sum task, that supports the idea that task stance matters and that the Target response is not reducible to the video stream alone. It does not prove meaning by itself; it adds one contrast.
The current data streams I am working with include OpenBCI EEG, LSL markers, optional ALS/PT19 light-sensor timing validation, respiration, Polar H10 R-R intervals, self-report, and confound reports. The analysis suite includes artifact scoring, stimulus fingerprinting, timing checks, lower-gamma/theta features, autonomic summaries, and an offline report generator. I am treating gamma as an artifact-sensitive candidate feature, not as a meaning biomarker.
As for the acronym, PRAYCG began as an internal codename from a broader theoretical project. For the public OpenBCI release, I am treating PRAYCG mostly as the project label. The empirical content is the three-arm protocol and the open-source pipeline, not the acronym.
Applications are still speculative. I do not see this as a clinical, diagnostic, or commercial tool right now. The immediate value is more basic and methodological:
an OpenBCI/LSL naturalistic-stimulus protocol,
a reproducible media-prep and phase-scrambling workflow,
a timing/QC workflow using LSL and light-sensor validation,
a way to compare natural viewing against analytic task stance,
a testbed for gamma/artifact criticism in naturalistic EEG,
and an educational/open-source workbench for people learning multimodal EEG acquisition.
Longer term, if replicated with more participants and better hardware controls, it might be useful for studying media cognition, attention, cognitive load, affective neuroscience, BCI stimulus design, and how narrative material interacts with autonomic regulation. But the current repository should be read as exploratory methods development, not as a finished neuroscience claim. I believe there may be some hypotheses here for temporal smearing as well.
The main critique I am looking for from this community is practical:
Is the OpenBCI acquisition/timing strategy sane?
How should I improve ALS/PT19 timing validation?
What EOG/EMG additions would most improve artifact control?
How would you simplify the analysis stack?
What would make the GitHub repository easier to audit and run?
Where am I making unsupported assumptions about the hardware?
So I agree with your framing: stories normally land when people understand them. PRAYCG is trying to ask a more technical question: can we measure differences between sensory entrainment, story reception, analytic extraction, and after-state carryover in a way that survives artifact and timing criticism?
Regards,
Hoyt
Good afternoon everyone,
I made several updates to the PRAYCG GitHub repository and wanted to share them here for anyone interested in reviewing the workflow or testing the software locally.
1. Master theory and protocol document
I added a public-facing master theory/protocol document here:
https://github.com/hbanks87/praycg-open/blob/main/PRAYCG_Master_Theory_and_Protocol_PUBLIC_v1_0.md
This document gives the broader structure of the project.
2. PRAYCG Control Center
I also uploaded an early work-in-progress PRAYCG Control Center release:
https://github.com/hbanks87/praycg-open/releases/tag/PRAYCG_CC
The Control Center is meant to be a single desktop hub for the PRAYCG workflow. The goal is to reduce the number of separate scripts a user has to remember.
3. Installation and workflow instructions
I added two beginner-facing documents for the Control Center and PRAYCG workflow:
Control Center installation guide:
https://github.com/hbanks87/praycg-open/blob/main/software/PRAYCG_OPS_v1_3/13_PRAYCG Control Center_v0.5/PRAYCG_ControlCenter_v0_5_Installation_Guide.pdf
Stimulus-to-analysis workflow:
https://github.com/hbanks87/praycg-open/blob/main/software/PRAYCG_OPS_v1_3/13_PRAYCG Control Center_v0.5/PRAYCG_Stimulus_to_Analysis_Workflow_v1_0.pdf
These are written for users who are only mildly familiar with Python and Windows software installation. They cover Python 3.11 installation, dependencies, Control Center launch, stimulus selection, MediaPrep, acquisition streams, LabRecorder, PRAYCG2.0, and running analysis afterward.
4. “The Box” hardware documentation
I also added documentation for what I have been calling “the box”:
https://github.com/hbanks87/praycg-open/tree/main/hardware/the_box
This is my nickname for a DIY Faraday-style enclosure I built for my own EEG experiments. I uploaded a PDF with 30+ pictures and construction notes.
To be clear: the box is not required to run PRAYCG. It is just my current local acquisition environment. I am sharing it because some people have found it interesting or useful.
Thank you again for the feedback so far, William.
Regards,
Hoyt