edfcore - Parsing EDF EEG files in TypeScript

sarthak — Wed, 12 Aug 2026 08:26:59 +0000

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.

DEV Community: sarthak

edfcore - Parsing EDF EEG files in TypeScript