I built edfcore, a zero-dependency TypeScript library for reading EDF-family biosignal recordings — and what looked like a pretty straightforward binary format turned out to have a lot more personality than I expected.
I wanted a clean way to work with EEG, ECG, and sleep-study recordings directly from JavaScript and TypeScript without having to route everything through Python first.
So:
npm install edfcore
The goal is to make EDF data usable inside things like:
- browser-based EEG viewers
- Node.js processing pipelines
- Electron applications
- research platforms
- biosignal visualization tools
The part I didn't expect was how many assumptions you can make about EDF that are completely wrong.
There isn't one sampling rate
An EDF file does not have one global sample rate.
Every signal declares its own number of samples per data record, so the same recording can contain 256 Hz EEG beside a sensor updating once per second.
That means any abstraction that treats the entire file as one uniform timeline has to repeat, interpolate, or otherwise change something.
Annotations are signals
EDF+ annotations aren't just sitting somewhere nicely separated as metadata.
They're stored through a special signal channel.
That means the same record structure can contain normal physiological samples for one signal and encoded event/timing information for another.
BDF uses 24-bit samples
BioSemi BDF makes things even more interesting because it stores signed 24-bit values.
JavaScript gives you convenient integer readers for 16-bit and 32-bit values, but there is no getInt24().
So those samples have to be reconstructed manually from three bytes and sign-extended correctly.
The worst bugs look valid
This ended up being the biggest lesson from building the parser.
The annoying failure isn't:
Error: cannot read file
It's:
Here are hundreds of thousands of perfectly normal-looking numbers.
A parser can be slightly wrong and still generate a waveform that looks completely believable.
That's why I spent a lot of time testing edge cases and comparing decoded results against existing EDF tooling.
The result became edfcore.
GitHub:
https://github.com/tayal-sarthak/edfcore
Docs:
https://edfcore.vercel.app/
NPM:
https://www.npmjs.com/package/edfcore
I also built a companion CLI called edf2csv for people who just want an EDF/BDF recording converted into CSV:
https://github.com/tayal-sarthak/edf2csv
Both projects are MIT licensed.
If you're building browser EEG tooling, Node-based research software, or anything else involving EDF files, I'd love to hear what you're working on.
Top comments (0)