Crown Debrief reads a recorded session from a Neurosity Crown and tells you what happened: when you peaked, when you crashed, how long your best stretch lasted. Then it answers questions about that data for someone who has never seen EEG. This page covers what it does, how it decides, the calls I made along the way, and exactly where it stops.
What it is
A debrief that reports on your session, and a guide that answers questions about it.
It sits on top of an earlier project, crown-focus-logger, which records focus, calm, and the five frequency bands to CSV. That project solved recording; this one solves making sense of what was recorded. The logger is included unchanged, and both features read the same CSV files it writes.
The debrief loads a session and reports on it: how much of the recording had a usable signal, what your personal focus range was, your longest focused stretches and clearest dips with clock times, how the session split across states, and how the frequency bands moved. Then it writes all of that up in plain English and offers one behavioural suggestion.
The guide answers questions about the headset, about the numbers, about how to run things, and about the session you have open. Every answer says where it came from. When it does not know, it says so rather than guessing.
The shape of it: Crown or mock, to CSV on disk, to a set of plain analysis modules, to the debrief and the guide. The same modules run in Node and in a browser, which is what allows a future static site with no server behind it.
The debrief is computed, then written. There is no AI model in it.
Two reasons, and the second matters more. A public site cannot ship an API key, because anyone can read it. And a research tool that stops working when an external service is down is fragile in a lab.
So a plain analysis engine works out the facts, and a set of sentence templates turns those facts into readable English. No model is involved, no key exists, and nothing needs the network to run.
The useful side effect is auditability. Every claim in the debrief traces back to a number in the CSV, and an engineer can check any of them. That is a stronger position for research than “the model said so.” A suite of 120 automated checks holds the analysis to it: 75 in the analysis engine, and 45 that run against a real Crown recording and check the pipeline reproduces the console’s own figures.
Where a model genuinely helps, rewriting the report in more natural prose, the integration is optional, local only, and receives the computed summary rather than raw EEG. There is also a copy-summary button that puts a compact, labelled version of the session on your clipboard, ready to paste into whichever assistant you prefer. The app owns the numbers; any model you like can own the words.
Your sessions are files on your own machine. Nothing is uploaded, because there is nowhere to upload to.
Recorded sessions, and any notes written against them, stay on your own machine. The .gitignore excludes both, so neither can be committed by accident. Session notes never go near the public version at all.
The handoff version is designed as a set of static files with no server behind it. When someone drops a CSV into it, the file is read inside their own browser and goes nowhere. No upload, no database, nothing to breach.
When the optional local model integration is switched on, it receives the computed summary, medians, ranges, peak times, band averages, and never raw EEG readings. One function builds that summary, and it is the only path from recorded data to any external service.
If this ever grows: If sessions from more than one person are ever collected, contributing has to be an explicit opt-in, separate from using the tool. Brain data is about as sensitive as personal data gets, and consent for that cannot be a side effect of clicking something else.
How it decides
There is no “good” focus score, so the app learns yours instead.
Focus and calm vary enormously between people, and anything above 0.3 already counts as significant, so a fixed threshold would mislead almost everyone. The app builds its comparisons from your own history instead: ten sessions, with norms kept per metric and per hour of day.
The per-hour part matters. Comparing a 3pm reading against an all-day average would label almost everybody’s afternoon a slump, so each hour is compared with the same hour on other days.
Until ten sessions exist, the app says so, with a visible “learning what’s normal for you” state, rather than inventing a comparison it cannot support.
Words, not numbers, because naming a state changes it
If you are building anything that reports a brain state back to a person, this is the decision I would make again, and the reason an interpreter was the thing worth building rather than another chart. Lieberman et al. (2007) put people in an fMRI scanner and showed them emotional faces. When participants labelled what they saw in words, amygdala response to the image dropped and activity in a right prefrontal region rose, compared with matching one face to another. Naming a state, on its own, dampened the brain’s reaction to it. The effect is known as affect labeling.
A number arrives without a scale, so the reader supplies one, and the one they supply is usually a grade. A sentence carries its own scale. That is why the debrief describes a session in English and why the baseline speaks in five fixed words rather than a score, and the research suggests the choice may do a little more than aid comprehension.
The honest limit. Lieberman’s study is about labeling emotions in pictures, measured by fMRI, in a lab. Stretching it to “reading a written EEG debrief helps you regulate” is my extrapolation and I have not seen it tested. I use the finding as a reason to prefer words over raw numbers, not as a promised effect of the product. The debrief describes what the data did and stops.
Five words describe every metric, and none of them is a judgement.
One fixed scale describes everything: well above usual, above usual, typical, below usual, well below usual. Never good, never bad.
Fixing the vocabulary removes a whole class of misreading. A number cannot be graded into a judgement about a person if the only available words are comparative.
The guide cites every answer, and refuses rather than guesses.
The guide is keyword search (BM25) over the project’s own notes: no dependencies, no network, no model. Each note is split into one chunk per heading, so an answer can cite a section rather than a whole document, and words in headings count four times more heavily than words in the body, because a heading says what a section is about.
Three rules it follows. Every answer names its source, which note and which section, and nothing goes unattributed. Questions about your own data, like “what is my focus doing,” are answered from the loaded session, not from generic text. And when retrieval finds nothing, the answer says so instead of guessing; there is a test asserting that refusal.
Known limit: Retrieval is keyword-based. It handles questions that share vocabulary with the notes and misses paraphrases that do not. That is why headings in the knowledge base carry alternative phrasings, so those get indexed too.
The judgment calls
Three screens, and the live view is deliberately hard to reach.
Today answers “how did that go” with one figure: deep work, the time spent meaningfully above your own normal. It is expressed in minutes rather than as a score on purpose. Minutes are a unit people already understand, they cannot be misread as a percentage, and counting them does not grade anyone’s brain.
Session shows the recording as a state ribbon: named states over time rather than two noisy traces. Four states carry colour, and two conditions deliberately do not: poor signal is drawn as a hatch and a break in recording as a faint gap. Absence must never look like a state, which is the one rule that palette exists to enforce. Scrub for a readout, drag to select a window, and everything recomputes for it.
Detail holds the live stream, band power, electrode contact, and the internals, reached by a quiet link, because none of it helps you read a session.
The live dashboard was demoted on purpose, and anyone building a Crown app has to make the same call about where the live number goes. The reasoning: Wegner, Broome and Blumberg asked people to relax while under mental load, and the instruction backfired. Those told to relax showed higher physiological arousal, measured as skin conductance, than those relaxing without the instruction or under less load. Their explanation is that trying to hold a mental state starts a monitoring process that keeps checking for failure, and under load the monitoring wins. A live calm score is a machine running that monitoring for you, four times a second, on a screen you are watching. So the primary experience here is the debrief you read afterwards, when watching the number can no longer disturb what the number measures. Record live, interpret later. The same instinct is why Muse gives feedback through sound rather than a chart, and the live stream still exists for debugging on the Detail screen, out of the way.
What is cited and what is not. Wegner’s finding is about instructed relaxation under load, not about EEG feedback. I have not found a study showing that watching a live EEG score degrades the measured state, so the step from his result to this screen layout is design reasoning and I label it that way. It is also a clean experiment for whoever has the hardware: one session with the dashboard visible, one with it hidden, compare the calm traces.
Six rules the code follows, meant to survive future changes.
A poor signal never produces a confident state. The state engine reports “unreadable” rather than guessing. A loose electrode must never be laundered into a plausible-looking reading.
Adaptation changes shape, never substance. The guide may shorten or scaffold an answer when your readings suggest you are scattered. It must never soften, hedge, or withhold something true because it decided you could not handle it. A visible state badge shows what it thinks you are in and what it is doing about it, so you can see the adaptation, debug it, and disagree with it.
It stays behavioural. “Your longest good stretch was 10:20 to 11:05, protect that window” is your own data read back to you. “Your theta suggests you need more magnesium” is pseudo-neuroscience and would embarrass the project in front of a lab.
No clinical claims. This is a consumer headset, not a medical device. The app describes what the data did and stops.
The guide cites everything, and refuses rather than guesses.
No credentials in browsers. There is no bring-your-own-key input and there should never be one. A key pasted into a web page is readable by anything on that page, and worse, asking people to paste credentials into websites trains the exact habit phishing depends on.
The honest limits
Five things this system cannot tell you, no matter how well it runs.
It will not tell you why anything happened. EEG records when something changed and is permanently silent on the cause. That is the gap session notes fill: a one-line note against a peak or a slump is the only thing that can supply the why.
It is not diagnostic. Eight dry electrodes on a consumer device report state, not condition. Nothing here is a health assessment.
Focus and calm are relative, not absolute. They are model outputs measured against a personal baseline that drifts with headset fit, hydration, caffeine, and time of day. Comparing your score to someone else’s is meaningless without a normalisation layer that nobody has built.
Retrieval is keyword-based. It will miss a paraphrase that shares no vocabulary with the notes.
Coverage gaps are physical. Eight channels at CP3, C3, F5, PO3, PO4, F6, C4, and CP4 give good frontal, central, and parieto-occipital coverage, with no midline, temporal, or true prefrontal sites, which limits emotion and drowsiness work. The eight names are colour coded to match the console everywhere on this site; the key sits with the primer.
What is still open, plainly listed.
The live view runs on a mock source; wiring a real Crown into that stream is not done, though the collector does talk to real hardware. Hour-of-day analysis is reported from a single session, which is not enough to be a pattern, and the interface says so. The static handoff site is built: it runs from a plain file server with no backend, and the shipped code makes no network calls at all. The baseline uses the ten most recent sessions with no seasonal or day-of-week weighting. Activity tags are applied per event, not by dragging a range on the ribbon.
The extension I would build next: a button for distractions, a report on how it felt
The most useful thing missing from this system is also the smallest, and it is what would make a session usable as research rather than as a curiosity. Two parts. A button that marks a distraction the moment it happens, writing a timestamp into the session file. And a short report afterwards, filled in by the person who wore the headset, on how the session felt. Both attach to the debrief and both stay on the machine that recorded them.
The case for the button is the limit stated above: EEG records that something changed and is permanently silent on why. A dip at minute seven is unexplained data, and unexplained data cannot be filtered, excluded, or learned from. One press costs a second and converts it into an annotated event, which means a later analysis can drop marked windows, compare marked against unmarked stretches, or look for whatever the signal does around a known interruption. That is the labelled record the console does not give you and will not export.
The case for the felt report is that it is separate information rather than a check on the number. Mauss et al. measured emotional experience, expressive behaviour and physiology at the same time while people watched emotional films: experience and behaviour tracked each other closely, while physiology was only modestly associated with either. What a person reports and what their body is doing are two records, not one record and its verification. The nearest test in this domain says the same thing more bluntly. Li et al. ran intensive motor-imagery practice across 400 trials and found that general fatigue, mental fatigue and distress all rose significantly while decoding performance did not change. If you want to know whether a session was hard, the signal will not tell you and the person will.
So the design rule stays what it is elsewhere in this system: the tool never tells you what you felt. It reports what the signal did relative to your own baseline, you report the rest, and the two sit side by side in the same file. Kept over enough sessions that is a dataset with both halves in it, which is the thing worth having and the reason I would build this before anything else on the open list.
The honest limit. Mauss measured heart rate and skin conductance, not EEG, and the emotions were film-induced. Carrying the coherence gap over to a consumer headset’s calm score is my inference, and if anything the gap should be wider here, since the score is a model’s guess layered on the physiology. That does not change the specification. It is the reason for it.
Live mode has never been run against a physical Crown.
The interpreter has read real recordings, and its reading of them was checked against the console’s own channel readouts, agreeing to within 0.1%. What it has never done is take a live stream off a headset: every figure came from a file exported after the fact. The live screens were developed against mock data, labelled as synthetic everywhere it appears so it cannot be mistaken for a real reading.
That is the state of it. The analysis is tested against real files, the design decisions are made, and the live path is the part still waiting on a headset.
Sources
README.md and HANDOFF.md in the crown-debrief repository, the Crown Debrief build specification, and knowledge/reading-your-data.md and knowledge/safety-and-privacy.md.
- Lieberman, M. D. et al. (2007). Putting Feelings Into Words. Psychological Science 18(5):421-428.
- Wegner, D. M., Broome, A., and Blumberg, S. J. (1997). Ironic effects of trying to relax under stress. Behaviour Research and Therapy 35(1):11-21.
- Mauss, I. B. et al. (2005). The tie that binds? Coherence among emotion experience, behavior, and physiology. Emotion 5(2):175-190.
- Li, S. et al. (2021). Exploring Fatigue Effects on Performance Variation of Intensive Brain-Computer Interface Practice. Frontiers in Neuroscience 15:773790.
