The MEF 3.0 on-disk format¶
A practical reference for the parts of MEF 3.0 that mef3io reads and writes
(time series + records; video is out of scope). Offsets below are what the
code actually uses (core/include/mef3io/types.hpp, core/src/headers.cpp)
and are cross-validated against meflib/pymef. All integers are
little-endian; type names follow meflib (si8 = int64, ui4 = uint32,
sf8 = float64, …). Strings live in fixed-size, null-padded UTF-8 fields.
Directory tree¶
A "file" in MEF is really a directory tree; the suffix of each directory says what it is:
session.mefd/ # session
├── session.rdat / session.ridx # optional session-level records
└── ch1.timd/ # one time-series channel
├── ch1.rdat / ch1.ridx # optional channel-level records
├── ch1-000000.segd/ # segment 0
│ ├── ch1-000000.tmet # metadata (fixed 16 384 B)
│ ├── ch1-000000.tidx # block index (1024 B UH + 56 B/block)
│ ├── ch1-000000.tdat # compressed data (1024 B UH + RED blocks)
│ └── ch1-000000.rdat/.ridx # optional segment-level records
└── ch1-000001.segd/ # segment 1, ...
A channel is split into segments (numbered directories); each segment is
a self-contained triple of metadata / index / data files. Appending more data
either extends the last segment's three files in place or starts a new
segment. Use Reader.segments(channel) to see which segment covers which
time and sample range, and Reader.toc(channel) for the per-block view.
Times¶
All times are uUTC: microseconds since the Unix epoch, si8. Two format
quirks matter:
- Times are stored negated. meflib marks "recording-time-offset applied"
by storing
rto - t(a negative number). Readers recover the true time ast >= 0 ? t : -t + rto, whererto(the recording time offset) lives in metadata section 3. This applies to universal-header start/end times, block start times, and record header times alike (record body times: see Records). The rule is implemented once, incore/include/mef3io/time.hpp. - What mef3io writes. Times are UTC, always; reading returns UTC.
- rto = 0 (every session mef3io creates): times are stored as
−t, the form shown above. The bytes are unchanged from earlier releases. - rto ≠ 0 (only in a foreign session that used meflib's deprecated
recording-time-offset "anonymization", which does not de-identify, and
which mef3io is extending): times are stored as
rto − t, meflib's own offset-applied form. This covers data blocks, index, universal headers and records alike. mef3io never writes a date there in plain, and every reader places the time correctly. (The date is still in the file: the offset itself sits in section 3, see below.) - New segments and channels added to a session whose segments all agree
on a non-zero
rtocarry that samertoin section 3, and their times follow the same rule. The session keeps agreeing, so its existing records stay readable. - Refused writes. These raise an error and leave the files untouched,
rather than store something that would misplace times or break the
session's
rto − tform:- A time at or before a non-zero
rto(WriteConflictError).rto − twould be non-negative, and every reader takes a non-negative time as the absolute date (meflib.c:7665). So the only correct encoding would be the absolute date, outside the session's ownrto − tform; mef3io refuses rather than mix the two. - A write to a level whose segments disagree on
rto(WriteConflictError, naming the segments). There is no single offset to store against. - A write that needs the offset while it is locked: section 3 of an
L2-encrypted session opened with only the level-1 password
(
PasswordError; open the writer with the level-2 password). A locked offset is unknown, never assumed to be 0.
- A time at or before a non-zero
- Unreadable metadata. Section 3 has no CRC of its own, so mef3io
trusts a segment's offset only after the same checks the full loader
makes: the header CRC, and the body CRC over the fixed 16 384-byte record
(never to EOF). Without them a damaged, e.g. zeroed, offset would read as
0, "no offset", and a write would store the real date. A
.tmetthat fails either check, or is truncated, is unreadable. That is always reported (Writer.unreadable_metadata, plus a warning). What happens next depends on the readable segments:- They agree on rto 0: the damaged file is skipped, so one damaged segment in an ordinary session does not block unrelated writes.
- They agree on a non-zero rto: the write is refused, because the agreement is unverified.
- None are readable: the write is refused, because the offset is unknown.
- A channel with no segment yet takes the session's offset for its records, under the same rules.
- A refused write changes nothing. Every check (record type, time, offset) runs before any directory or file is created. A segment directory without metadata left by an earlier crash is ignored (and reported) instead of being adopted. Segments are numbered by the highest real segment number, so such a directory never misplaces an append or a new segment.
- The empty value ("no entry") for a time is
INT64_MIN.
The recording-time offset as "anonymization" is deprecated by mef3io.
This is not a format change: MEF 3.0 still defines the field, and mef3io
reads and extends offset sessions exactly as described above. But the
offset only moves the date into recording_time_offset in section 3 of
every .tmet, which is plain text unless the session is encrypted, so
−stored + rto gives the real date back to anyone. mef3io therefore never
creates an offset session (a new session gets rto = 0), and
de-identification is a separate copy made by anonymize_session
(#70). See
De-identification and the recording-time offset.
Universal header — 1024 B, prefixes every file¶
Every .tmet/.tidx/.tdat/.rdat/.ridx file starts with the same 1024-byte
header:
| Offset | Type | Field |
|---|---|---|
| 0 | ui4 | header CRC (over bytes 4..1023) |
| 4 | ui4 | body CRC (over bytes 1024..end of file) |
| 8 | char[5] | file type string (tmet, tidx, tdat, rdat, ridx) |
| 13 / 14 | ui1 | MEF version major / minor (3 / 0) |
| 15 | ui1 | byte order (1 = little-endian) |
| 16 / 24 | si8 | start / end time (negated uUTC, see above) |
| 32 | si8 | number of entries (blocks / index entries / records) |
| 40 | si8 | maximum entry size (bytes) |
| 48 | si4 | segment number |
| 52 / 308 / 564 | char[256] | channel name / session name / anonymized name |
| 820 / 836 / 852 | ui1[16] | level UUID / file UUID / provenance UUID |
| 868 / 884 | ui1[16] | level-1 / level-2 password validation fields |
| 900 / 960 | ui1[60] / ui1[64] | protected / discretionary regions |
CRCs use CRC-32 with the Koopman polynomial (0x741B8CD7, reflected, start value 0xFFFFFFFF). The password validation fields hold the two-level key material (see encryption_model.md); all-zero fields mean the file is unencrypted.
Provenance region (mef3io ≥ 1.2) — frozen format¶
The universal header's 64-byte discretionary region (file offset 960) is set aside for the writing application. meflib never interprets it, and pymef only reports it as raw bytes. mef3io uses it, in every file it creates or modifies, to record which version created the file, which version last modified it, and what was done to it.
No times are recorded. The universal header is never encrypted, so a
write time would reveal when a recording was made. (recording_time_offset
was meant to hide that, but does not: see
De-identification.)
| Offset | Bytes | Type | Field |
|---|---|---|---|
| 0 | 4 | ASCII | magic M3IO |
| 4 | 1 | ui1 | layout version, currently 1 |
| 5 | 1 | ui1 | last operation (code, below) |
| 6 | 2 | — | reserved, zero |
| 8 | 20 | ASCII | created-by version, e.g. 1.2.0 |
| 28 | 20 | ASCII | last-modified-by version |
| 48 | 4 | ui4 LE | operations-ever mask: bit n set = code n was applied at some point |
| 52 | 4 | ui4 LE | modification count: operations after creation |
| 56 | 8 | — | reserved, zero |
Offsets are relative to the region; add 960 for the position in the file.
Operation codes
| Code | Name | Meaning |
|---|---|---|
| 0 | unset |
— |
| 1 | create |
file written fresh |
| 2 | append |
samples added to an existing segment |
| 3 | header-repair |
repair_session: declarations rewritten, samples untouched |
| 4 | recovery |
recover_session: index and data reconciled after an interrupted write |
| 5 | metadata-update |
reserved: descriptive metadata rewritten in place |
| 6 | anonymize |
the file belongs to a de-identified copy made by anonymize_session (#70); stamped on every file of the copy |
| 7 | rename |
rename_session or fix_name_drift (#72) changed the stored session name in place (and any description that was equal to it); stamped on every file whose header changed |
| 8 | transform |
the file belongs to a copy made by transform_session (#73): a choice of channels, new passwords, a new name or edited descriptive metadata, with every time and sample copied verbatim; stamped on every file of the copy (a region another program owns is left as it is) |
| 9 | segment-repaired |
stamped on a channel's last segment's .tmet when repair_session or recover_session modified another segment of that channel. The last segment itself was not repaired: that file only records that something earlier in its channel was. |
segment-repaired exists so that one file per channel, the last segment's
.tmet, shows that the channel changed, without anyone reading every segment.
mef3io's warm-start snapshot relies on it. The stamp is header-only: just this
region and the header CRC change. It is backed up like the repair's own writes.
It is skipped, and reported as a note rather than an error, in three cases:
the last segment's region belongs to another application, the last segment's
CRCs do not verify, or a writer's .mef3io-tmp temp file sits in the last
segment. The repair or recovery itself always proceeds.
Rules. These are the compatibility contract and do not change.
- The layout is frozen. Offsets, widths, byte order and encodings never change. A later layout version may only assign the reserved bytes (6–7, 56–63); it never redefines an existing field.
- Codes are append-only. A code is never renumbered, reused or redefined. Codes stay below 32 so that each has a bit in the mask. A reader that meets an unknown code reports it as unknown and does not fail.
- Version strings are ASCII, NUL-padded, at most 19 characters plus a
NUL terminator. A longer version is truncated, and any non-printable or
non-ASCII byte is written as
?. A string can never extend past its field. - The count saturates. It stops at
0xFFFFFFFFand never wraps back to zero, so even an acquisition appended to for months cannot overflow it or the fields next to it. - The mask only grows. A bit, once set, is never cleared, so a later append cannot hide that a file was repaired or recovered.
- Ownership. A region of all zeros, as written by meflib, pymef, mef_tools and mef3io ≤ 1.1, has never been stamped. The first mef3io modification initialises it but leaves created-by empty, so mef3io never claims a file it did not create. A region holding anything else without the magic belongs to another application and is never written.
- Unknown bytes are preserved. A writer updates only the fields above:
last operation, last-modified-by, mask and count. Every other byte is
copied through, and a newer layout-version byte is never downgraded.
The one exception is a de-identified copy (
anonymize_session): it clears another application's region, since it may hold identifying data, before stamping operation 6. archive_session/extract_sessionare byte-exact copies, not modifications, and never change the region.
The region lies under the universal header's CRC (bytes 4–1023), which every
mef3io write recomputes. Reader.segments(ch) reports the provenance of each
segment's .tmet (None when there is none). The C ABI provides
mef3io_reader_segment_provenance and mef3io_operation_name.
The layout is pinned by a golden-bytes test and the codes by a literal table
(core/tests/test_core.cpp, "provenance region"); behaviour on real files is
covered by tests/test_p21_writer_stamp.py.
Metadata file (.tmet) — exactly 16 384 B¶
[ 0..1023 ] universal header
[ 1024..2559 ] section 1 (1536 B) — never encrypted
[ 2560..13311] section 2 (10752 B) — encrypted with the LEVEL-1 key
[13312..16383] section 3 (3072 B) — encrypted with the LEVEL-2 key
Section 1 (offsets relative to the section):
| Offset | Type | Field |
|---|---|---|
| 0 | si1 | section-2 encryption level (+1 encrypted / −1 decrypted-on-disk) |
| 1 | si1 | section-3 encryption level (+2 / −2) |
A positive level means the section bytes are AES-128-ECB ciphertext; a
negative level means the same content is stored decrypted. Unencrypted files
carry −1/−2 (bytes 0xFF/0xFE — beware tools that read this byte as
unsigned).
Section 2 (time-series flavor; the technical metadata):
| Offset | Type | Field |
|---|---|---|
| 0 / 2048 | char[2048] | channel / session description |
| 4096 | si8 | recording duration (µs, spans gaps) |
| 4104 | char[2048] | reference description |
| 6152 | si8 | acquisition channel number |
| 6160 | sf8 | sampling frequency (Hz) |
| 6168–6192 | sf8 ×4 | LFF / HFF / notch filter, AC line frequency |
| 6200 | sf8 | units conversion factor (physical units per count) |
| 6208 | char[128] | units description (e.g. uV) |
| 6336 / 6344 | sf8 | maximum / minimum native sample value |
| 6352 | si8 | start sample (channel-wide index of this segment's first sample) |
| 6360 | si8 | number of samples (stored samples; gaps are not counted) |
| 6368 | si8 | number of blocks |
| 6376 | si8 | maximum block bytes |
| 6384 / 6388 | ui4 | maximum block samples / maximum difference bytes |
| 6392 | si8 | block interval (µs) |
| 6400 | si8 | number of discontinuities |
| 6408–6424 | si8 ×3 | maximum contiguous blocks / block bytes / samples |
Note the two easy-to-confuse quantities: number_of_samples counts samples
physically stored (NaN gaps are skipped at write time), while the
start/end times and recording_duration span the gaps. A gridded read
(Reader.read) therefore usually returns more samples than
number_of_samples, with NaN filling the gaps.
The buffer-sizing declarations¶
The maximum_* block of fields at 6376–6424 is not descriptive trivia — it is the
allocation contract. meflib does not allocate from them itself, but it exposes
helpers that take one as a buffer size and validate none of them, and
applications built on it pass them in before decoding
anything — so a writer that under-declares hands that reader a buffer too small
for the data about to go into it.
RED_allocate_processing_struct skips the allocation entirely for a
difference_buffer_size of 0, leaving difference_buffer NULL for
RED_decode to write through; meflib ships a guard for exactly this
(RED_check_RPS_allocation) but never calls it, so there is no error path at
all. Separately, find_discontinuity_indices (meflib.c:3548) mallocs
number_of_discontinuities entries and then writes one per flagged block — so
an under-declared discontinuity count is a heap overflow inside meflib itself.
0 is not the NO_ENTRY sentinel for any of them, so a reader cannot tell
an unset field from a genuine measurement:
| Field | NO_ENTRY | mef3io writes |
|---|---|---|
maximum_block_bytes |
-1 |
largest encoded block in the segment |
maximum_block_samples |
0xFFFFFFFF |
largest block sample count |
maximum_difference_bytes |
0xFFFFFFFF |
largest difference_bytes over the RED block headers |
maximum_contiguous_blocks |
-1 |
longest run of blocks between discontinuities |
maximum_contiguous_block_bytes |
-1 |
encoded bytes in the longest such run |
maximum_contiguous_samples |
-1 |
samples in the longest such run |
A contiguous run is delimited by the .tidx discontinuity flag — the same
flag a reader uses — so the declarations and the data agree by construction.
Each maximum is tracked independently: over-declaring only costs a reader some
allocation, whereas under-declaring truncates its buffer.
Two asymmetries worth knowing. maximum_difference_bytes is the one field not
derivable from the index, since it lives in the RED block headers inside
.tdat; meflib's own worst case is maximum_block_samples × 5
(RED_MAX_DIFFERENCE_BYTES), which is a tight bound in practice. And the
legacy pymef writer sets maximum_contiguous_block_bytes to the whole .tdat
body and leaves maximum_contiguous_samples at 0, both of which ignore
discontinuities; mef3io's values are per-run and exact.
mef3io's own reader never consults any of these fields — it sizes from each block's own header — so sessions that declare zeros, sentinels, or nonsense still read correctly.
Section 3 (the sensitive, level-2 part):
| Offset | Type | Field |
|---|---|---|
| 0 | si8 | recording time offset (rto, used to de-negate times; holds the recording date, see De-identification) |
| 8 / 16 | si8 | DST start / end time |
| 24 | si4 | GMT offset (seconds) |
| 28 / 156 | char[128] | subject name 1 / 2 |
| 284 | char[128] | subject ID |
| 412 | char[512] | recording location |
Block index (.tidx) — 1024 B UH + one 56 B entry per RED block¶
| Offset | Type | Field |
|---|---|---|
| 0 | si8 | file offset of the block in the .tdat — file-relative, so the first block is at 1024, not 0 |
| 8 | si8 | block start time (negated uUTC) |
| 16 | si8 | start sample (channel-wide index) |
| 24 | ui4 | number of samples in the block |
| 28 | ui4 | block bytes (header + payload, padded) |
| 32 / 36 | si4 | maximum / minimum sample value in the block |
| 44 | ui1 | RED flags (bit 0 = discontinuity) |
The index is what makes windowed reads cheap: a reader can binary-search the
time range and fetch only the needed byte range from the .tdat.
Data file (.tdat) — 1024 B UH + concatenated RED blocks¶
Samples are stored as int32 counts, compressed per block with RED (Range Encoded Differences): difference coding followed by an adaptive range coder. Each block starts with a 304-byte header:
| Offset | Type | Field |
|---|---|---|
| 0 | ui4 | block CRC |
| 4 | ui1 | flags (bit 0 = discontinuity; bits 1/2 = level-1/2 encrypted) |
| 16 / 20 | sf4 | detrend slope / intercept (unused when written lossless) |
| 24 | sf4 | scale factor (1.0 when lossless) |
| 28 | ui4 | difference bytes |
| 32 | ui4 | number of samples |
| 36 | ui4 | block bytes |
| 40 | si8 | block start time (negated uUTC) |
| 48 | ui1[256] | symbol statistics table for the range coder |
The compressed payload follows at offset 304; blocks are padded with 0x7e
to an 8-byte boundary. A set discontinuity flag means "this block does not
continue seamlessly from the previous one" — that is how gaps (NaN runs in
the original signal) are represented; nothing is stored for the gap itself.
RED blocks are written unencrypted even in encrypted sessions (meflib
default, RED_ENCRYPTION_LEVEL_DEFAULT, meflib.h:1082). That is not the design
of MEF 3.0 but an artifact of past implementations; the format defines
encrypted blocks (see Encrypted data blocks): the passwords
protect metadata sections 2/3 and record bodies, not the samples. A
block decodes without section 2, and its start time and sample count are in
plain text both here and in the .tidx, so the stored integer samples, their
timing and the sampling rate are all recoverable without a password; only the
conversion factor and units are missing. See
What encryption protects.
When a block IS encrypted, only bytes 0–15 of the statistics table are
ciphertext (header offsets 48–63). Bits 1/2 of the flags select the level-1
or level-2 key; meflib then runs AES-128 over one 16-byte block of the
256-byte table — RED_encode calls AES_encrypt(block_header->statistics, …)
(meflib.c:7027), RED_decode calls AES_decrypt (meflib.c:6676), and both
end in AES_cipher / AES_inv_cipher (meflib.c:292 / :423), which process a
single 4×4 state. Bytes 16–255 stay in the clear. The block CRC is computed
after encryption (meflib.c:7045), so it covers the ciphertext and can be
checked without a password. Nothing else in the block — header fields or the
compressed payload — is encrypted. Ciphering all 256 bytes is self-consistent
(it round-trips) but cannot read meflib's encrypted blocks and writes blocks
meflib cannot read; mef3io did exactly that until #80 (1.2.0 and earlier).
Few readers can actually open an encrypted block. pymef's time-series reader
(read_mef_ts_data, behind both read_ts_channels_sample and
read_ts_channels_uutc) never gives meflib's RED decoder its password data
(pymef3_file.c:2151 callocs the processing struct), so RED_decode
dereferences NULL at meflib.c:6675 on the first encrypted block. meflib itself
needs the LEVEL-2 password even for level-1 blocks: process_password_data
puts a level-1-only password's expanded key in level_2_encryption_key
(meflib.c:5080), leaving the level-1 key slot zero, so it would decrypt a
level-1 block with the wrong key. mef3io deliberately differs here — a level-1
password reads level-1 blocks — and its encoder reproduces meflib's encrypted
blocks byte for byte (tests/test_p24_red_block_encryption.py, on a
fixture whose blocks meflib itself encrypted).
To recover physical units: value = stored_int32 * units_conversion_factor,
with the factor of the segment the sample is stored in. The factor lives in
each segment's section 2, and the segments of one channel may store different
ones; meflib's channel-level aggregate then reads NO_ENTRY (0.0,
meflib.h:439; meflib.c:5494 and 6176). mef3io scales every block by its own
segment's factor; a factor of 0 ("not set") is read as 1 (the raw
counts, with a warning in Python), and NaN or infinity is refused.
Records (.rdat + .ridx) — annotations¶
.rdat holds the records; .ridx is a parallel index. Both start with the
universal header. Record header (24 B) in .rdat:
| Offset | Type | Field |
|---|---|---|
| 0 | ui4 | record CRC |
| 4 | char[4] | type (Note, EDFA, SyLg, Seiz, …) |
| 9 / 10 | ui1 | version major / minor |
| 11 | si1 | encryption level of the body |
| 12 | ui4 | body bytes |
| 16 | si8 | record time (negated uUTC) |
The body follows, padded with 0x7e to a 16-byte multiple (AES block size);
in encrypted sessions record bodies are level-2 encrypted. Each .ridx
entry (24 B): type[4] @ 0, version @ 5/6, encryption @ 7, file offset
(file-relative) @ 8, time @ 16.
Damaged record files fail. Rather than returning fewer records or
corrupted text, a record file is rejected for any of:
- a record cut off mid-way, or a header claiming more body_bytes than the
file holds;
- a per-record CRC mismatch (the coverage meflib checks, meflib.c:1839; a CRC
of 0, meflib's "no entry", is not checked);
- a universal header that declares more records than are present.
A file that declares fewer records than it holds is tolerated, as in meflib:
only the declared records are read (meflib.c:1869). A rejected file is
contained like any other: strict raises; lenient reads every record that is
intact (using the .ridx offsets to resynchronise past a damaged one) and
lists each damaged record in Reader.problems with kind "records", naming
the record and its byte offset. Nothing is repaired or removed.
Where record files live¶
Record files can exist at three levels (meflib.c:6343 / 5660 / 6030), each named after its directory:
| Level | Path |
|---|---|
| session | session.mefd/session.rdat (+ .ridx) |
| channel | session.mefd/ch1.timd/ch1.rdat |
| segment | session.mefd/ch1.timd/ch1-000000.segd/ch1-000000.rdat |
Reader.records() reads the session level; Reader.records("ch1") reads the
channel level AND every segment level of ch1; records("ch1", segment=0)
one segment; records(level="all") everything, including a channel that has
records but no segments yet. Every record carries level,
channel and segment so the source is never ambiguous. mef3io writes only
the session and channel levels.
The session-level file is <session name>.rdat, the only name meflib reads
(meflib.c:6335). The session name is the .mefd directory's name without
its suffix. For a .mefd.tar archive it is the session folder inside the
archive, so the archive file itself can be renamed freely. A differently named .rdat at the root is used only
when it is the only one there. With several and none matching the name, the
session-level records are ambiguous: strict raises, lenient reports it in
problems and returns none.
Record times and the recording-time offset¶
The header time is negated like every other MEF time and is resolved with the offset of what the file belongs to: a segment's own section 3; for a channel or the session, the offset all of their segments agree on.
If those segments disagree, there is no correct single value. Only times
stored negated depend on the offset, so a file holding none is read normally.
One that does is refused with FormatError (strict), or skipped and listed in
Reader.problems with an UnreadableSegmentWarning (lenient). Either way only
that one file is affected: the segment-level files carry their own segment's
offset and still read (records(ch, level="segment") in strict mode).
This is a deliberate divergence from meflib. In its default
RTO_REMOVE_ON_INPUT mode (meflib.h:278) meflib resolves record times with
the global offset left by whichever .tmet it read last (meflib.c:1806 →
1846); the "no entry" it records for a disagreeing channel or session
(meflib.c:5529, 6208) is only the metadata aggregate. Following the read order
would misplace the records by the difference without a word.
Writing. Record times follow the rule in Times:
- rto = 0 level: stored as −t, byte-identical to earlier releases.
- Non-zero rto: stored as rto − t. A record at or before the offset is
refused.
- A level whose segments disagree, or whose offset is locked: the write
is refused.
meflib applies the offset to the record header only (meflib.c:1846);
mefrec.c never rewrites a body. It does, however, display every body time
through remove_recording_time_offset (via local_date_time_string,
meflib.c:4649), i.e. with the same sign rule. mef3io does the same: body
times go through the same conversion as the header time. A non-negative body
time — the normal case, even in an offset session — is returned unchanged; a
negative one is resolved with the record's offset. So every time mef3io
returns, header or body, is absolute uUTC. The sentinels INT64_MIN and a
Seiz channel's -1 onset/offset are passed through as-is.
Body layouts (mefrec.h)¶
Offsets are relative to the start of the body. Every body type is
version-gated: meflib decodes each one only at version 1.0 (mefrec.c:201, 232,
540, …), so mef3io reads a body only when the header says 1.0 — which is what
mef3io, pymef and mef_tools write. Another version, or a body shorter than the
fixed part of its layout (e.g. an EDFA body without its 8-byte duration),
reads back with every body field None. The field names are the keys
Reader.records() returns (and the MATLAB struct fields); every record of a
type always carries all of its type's keys.
| Type | Body (offset: type name) |
|---|---|
Note, SyLg |
0: utf8 text (to the first NUL) |
EDFA |
0: si8 duration (µs); 8: utf8 text |
Seiz (1312 B + 272 B/channel) |
0: si8 earliest_onset (uUTC); 8: si8 latest_offset (uUTC); 16: si8 duration; 24: si4 number_of_channels; 28: si4 onset_code (−1 none, 0 unknown, 1 focal, 2 generalized, 3 propagated, 4 mixed); 32: utf8[128] marker_name_1; 160: utf8[128] marker_name_2; 288: utf8[1024] annotation; then channels: per channel 0: utf8[256] name, 256: si8 onset, 264: si8 offset (uUTC, −1 = none) |
Epoc (192 B) |
0: si8 id_number; 8: si8 timestamp (uUTC); 16: si8 end_timestamp (uUTC); 24: si8 duration; 32: utf8[32] epoch_type; 64: utf8[128] text |
Curs (160 B) |
0: si8 id_number; 8: si8 trace_timestamp (uUTC); 16: si8 latency; 24: sf8 value; 32: utf8[128] name |
CSti (200 B) |
0: utf8[64] task_type; 64: si8 stimulus_duration; 72: utf8[64] stimulus_type; 136: utf8[64] patient_response |
ESti (416 B) |
0: sf8 amplitude; 8: sf8 frequency; 16: si8 pulse_width; 24: si4 ampunit_code (−1 none, 0 unknown, 1 mA, 2 V); 28: si4 mode_code (−1 none, 0 unknown, 1 current, 2 voltage; mefrec.h:242-250); 32/160/288: utf8[128] waveform / anode / catode |
LNTP |
0: si8 length; 8: si4[length] template (pymef: si8, see below) |
UnRc |
no body fields |
Seiz returns at most number_of_channels channel entries, and fewer when
the body is shorter than it declares. For LNTP mef3io follows the
MEFREC_LNTP_1_0_TEMPLATE_OFFSET define (body offset 8); meflib's own display
code (mefrec.c:306) applies that offset with si4* pointer arithmetic and so
reads 4× too far.
LNTP incompatibility. pymef (and so the legacy mef_tools) writes the
template as si8 (pymef3_file.c:4159-4160; its reader notes the discrepancy
at :3729), not the si4 mefrec.h defines, and the header cannot say which.
mef3io reads si4 by default and takes the pymef layout only when the body
holds at least 8 × length bytes after the length AND every high 4 bytes are
the sign extension of the low 4 — which a si4 template followed by meflib's
0x7e padding never is. The values are returned as integers either way.
(A si4 file padded with zeros instead of 0x7e, whose template happens to
alternate value / sign-extension, would be misread; no known writer does that.)
Reading these bodies is supported; writing remains limited to Note, SyLg
and EDFA.
Sentinels and other conventions¶
| Meaning | Value |
|---|---|
| "no entry" time (si8) | INT64_MIN |
| "no entry" si8 / si4 / ui4 | −1 / −1 / 0xFFFFFFFF |
| RED NaN sample | INT32_MIN |
| GMT offset "no entry" | −86401 |
| pad byte (blocks, record bodies) | 0x7e |
How this maps to the mef3io API¶
| On-disk concept | API |
|---|---|
| Section 2 + universal header | Reader.info(ch) (fs, ufact, times, counts) |
| Section 3 (subject metadata) | Reader.info(ch) subject_* fields; None without L2 access |
| Segment triples | Reader.segments(ch) — time/sample range per segment |
.tidx entries |
Reader.toc(ch) — per-block start time, extrema, discontinuity |
| RED blocks | decoded transparently by read / read_raw |
| Records (session / channel / segment level) | Reader.records(ch, segment, level) / Writer.write_annotations(...) |
Related: encryption_model.md (how the two password levels derive keys and what they unlock), legacy_comparison.md (measured differences vs pymef/mef_tools), and design.md (mef3io internals).