edf2csv 0.1.0

package/dist/convert/timing.d.ts

@@ -0,0 +1,18 @@
+import type { Diagnostic } from '../edf/errors.js';
+import type { EdfFile } from '../edf/reader.js';
+export interface AnnotationTimingData {
+    recordStarts: (number | null)[];
+    malformed: number;
+}
+/**
+ * Resolve the true start time of every data record.
+ *
+ * Continuous recordings need no table because their record positions are
+ * arithmetic. EDF+D recordings carry their positions in the annotation channel;
+ * missing or malformed timekeeping entries are reported before falling back.
+ */
+export declare function deriveRecordStarts(file: EdfFile, annotationData: AnnotationTimingData): {
+    starts: Float64Array | null;
+    diagnostics: Diagnostic[];
+};
+//# sourceMappingURL=timing.d.ts.map

package/dist/convert/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../src/convert/timing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,OAAO,EACb,cAAc,EAAE,oBAAoB,GACnC;IAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAmE5D"}

package/dist/convert/timing.js

@@ -0,0 +1,69 @@
+/**
+ * Resolve the true start time of every data record.
+ *
+ * Continuous recordings need no table because their record positions are
+ * arithmetic. EDF+D recordings carry their positions in the annotation channel;
+ * missing or malformed timekeeping entries are reported before falling back.
+ */
+export function deriveRecordStarts(file, annotationData) {
+    const diagnostics = [];
+    if (annotationData.malformed > 0) {
+        diagnostics.push({
+            code: 'ANNOTATION_DECODE_FAILED',
+            severity: 'warning',
+            message: `${annotationData.malformed} annotation entr${annotationData.malformed === 1 ? 'y was' : 'ies were'} ` +
+                `unreadable and could not be exported.`,
+            hint: 'The rest were exported normally. The file may have been written by a non-conforming tool.',
+        });
+    }
+    if (file.header.continuity !== 'EDF+D')
+        return { starts: null, diagnostics };
+    if (file.annotationSignals.length === 0) {
+        diagnostics.push({
+            code: 'DISCONTINUOUS',
+            severity: 'warning',
+            message: 'This file is marked discontinuous but has no annotation channel, so where its ' +
+                'records sit in time is not recorded anywhere.',
+            hint: 'Times are written as if the records were contiguous. Any gaps are lost.',
+        });
+        return { starts: null, diagnostics };
+    }
+    const starts = new Float64Array(file.recordCount);
+    const missing = [];
+    for (let i = 0; i < file.recordCount; i++) {
+        const declared = annotationData.recordStarts[i];
+        if (declared === null || declared === undefined) {
+            missing.push(i);
+            starts[i] = i * file.header.recordDuration;
+        }
+        else {
+            starts[i] = declared;
+        }
+    }
+    if (missing.length > 0) {
+        const shown = missing.slice(0, 5).join(', ');
+        diagnostics.push({
+            code: 'ANNOTATION_DECODE_FAILED',
+            severity: 'warning',
+            message: `${missing.length} of ${file.recordCount} data records carry no readable timekeeping ` +
+                `annotation (record${missing.length === 1 ? '' : 's'} ${shown}` +
+                `${missing.length > 5 ? ', …' : ''}), so their true position in time is unknown.`,
+            hint: 'Those records are timed as if they were contiguous; treat their timestamps as unreliable.',
+        });
+    }
+    let outOfOrder = 0;
+    for (let i = 1; i < starts.length; i++) {
+        if (starts[i] < starts[i - 1])
+            outOfOrder++;
+    }
+    if (outOfOrder > 0) {
+        diagnostics.push({
+            code: 'DISCONTINUOUS',
+            severity: 'warning',
+            message: `${outOfOrder} data record${outOfOrder === 1 ? '' : 's'} start earlier than the record before it.`,
+            hint: 'Rows are written in file order, so the time column will not increase monotonically.',
+        });
+    }
+    return { starts, diagnostics };
+}
+//# sourceMappingURL=timing.js.map

package/dist/convert/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/convert/timing.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAa,EACb,cAAoC;IAEpC,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,IAAI,cAAc,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QACjC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,0BAA0B;YAChC,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,GAAG,cAAc,CAAC,SAAS,mBAAmB,cAAc,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,GAAG;gBACtG,uCAAuC;YACzC,IAAI,EAAE,2FAA2F;SAClG,CAAC,CAAC;IACL,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,KAAK,OAAO;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAE7E,IAAI,IAAI,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,eAAe;YACrB,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,gFAAgF;gBAChF,+CAA+C;YACjD,IAAI,EAAE,yEAAyE;SAChF,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;QACvB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,0BAA0B;YAChC,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,GAAG,OAAO,CAAC,MAAM,OAAO,IAAI,CAAC,WAAW,8CAA8C;gBACtF,qBAAqB,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,EAAE;gBAC/D,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,+CAA+C;YACnF,IAAI,EAAE,2FAA2F;SAClG,CAAC,CAAC;IACL,CAAC;IAED,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,IAAK,MAAM,CAAC,CAAC,CAAY,GAAI,MAAM,CAAC,CAAC,GAAG,CAAC,CAAY;YAAE,UAAU,EAAE,CAAC;IACtE,CAAC;IACD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,eAAe;YACrB,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,GAAG,UAAU,eAAe,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,2CAA2C;YAC3G,IAAI,EAAE,qFAAqF;SAC5F,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACjC,CAAC"}

package/dist/edf/annotations.d.ts

@@ -0,0 +1,43 @@
+/**
+ * EDF+ annotation (TAL) decoding.
+ *
+ * The annotations channel stores UTF-8 text in place of samples. Its bytes are a
+ * run of Time-stamped Annotation Lists, each terminated by a NUL, with the rest
+ * of the channel NUL-padded:
+ *
+ *   +<onset>[<0x15><duration>]<0x14><text><0x14>...<0x00>
+ *
+ * The first TAL of every data record must carry that record's start time and no
+ * text; that is how an EDF+D file states where each record actually sits in time.
+ *
+ *   +1.25<0x15>0.5<0x14>Seizure onset<0x14><0x00>
+ */
+declare const SEP_TEXT = 20;
+declare const SEP_DURATION = 21;
+declare const TAL_END = 0;
+export interface Annotation {
+    /** Seconds from the start of the recording. */
+    onset: number;
+    /** Seconds, or null when the TAL omitted a duration. */
+    duration: number | null;
+    text: string;
+    /** Index of the data record this annotation was stored in. */
+    recordIndex: number;
+}
+export interface DecodedRecordAnnotations {
+    /** Record start time in seconds, from the leading timekeeping TAL. */
+    recordStart: number | null;
+    annotations: Annotation[];
+    /** Non-empty chunks that were not valid TALs, so the caller can report them. */
+    malformed: number;
+}
+/**
+ * Decode one data record's annotation bytes.
+ *
+ * Malformed TALs are skipped rather than thrown, because a single bad annotation
+ * should not cost the user an entire conversion. The count of skipped chunks is
+ * returned so the caller can tell the user rather than losing them in silence.
+ */
+export declare function decodeRecordAnnotations(bytes: Buffer, recordIndex: number): DecodedRecordAnnotations;
+export { SEP_TEXT, SEP_DURATION, TAL_END };
+//# sourceMappingURL=annotations.d.ts.map

package/dist/edf/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,QAAA,MAAM,QAAQ,KAAO,CAAC;AACtB,QAAA,MAAM,YAAY,KAAO,CAAC;AAC1B,QAAA,MAAM,OAAO,IAAO,CAAC;AAKrB,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,sEAAsE;IACtE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,wBAAwB,CA2B1B;AA2CD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC"}

package/dist/edf/annotations.js

@@ -0,0 +1,88 @@
+/**
+ * EDF+ annotation (TAL) decoding.
+ *
+ * The annotations channel stores UTF-8 text in place of samples. Its bytes are a
+ * run of Time-stamped Annotation Lists, each terminated by a NUL, with the rest
+ * of the channel NUL-padded:
+ *
+ *   +<onset>[<0x15><duration>]<0x14><text><0x14>...<0x00>
+ *
+ * The first TAL of every data record must carry that record's start time and no
+ * text; that is how an EDF+D file states where each record actually sits in time.
+ *
+ *   +1.25<0x15>0.5<0x14>Seizure onset<0x14><0x00>
+ */
+const SEP_TEXT = 0x14; // separates onset/duration from text, and text from text
+const SEP_DURATION = 0x15; // separates onset from duration
+const TAL_END = 0x00;
+const TEXT_SEP_CHAR = String.fromCharCode(SEP_TEXT);
+const DURATION_SEP_CHAR = String.fromCharCode(SEP_DURATION);
+/**
+ * Decode one data record's annotation bytes.
+ *
+ * Malformed TALs are skipped rather than thrown, because a single bad annotation
+ * should not cost the user an entire conversion. The count of skipped chunks is
+ * returned so the caller can tell the user rather than losing them in silence.
+ */
+export function decodeRecordAnnotations(bytes, recordIndex) {
+    const annotations = [];
+    let recordStart = null;
+    let isFirstTal = true;
+    let malformed = 0;
+    let start = 0;
+    for (let i = 0; i <= bytes.length; i++) {
+        if (i !== bytes.length && bytes[i] !== TAL_END)
+            continue;
+        if (i > start) {
+            const chunk = bytes.subarray(start, i);
+            const parsed = parseTal(chunk, recordIndex);
+            if (parsed) {
+                if (isFirstTal) {
+                    recordStart = parsed.onset;
+                    isFirstTal = false;
+                }
+                for (const annotation of parsed.annotations)
+                    annotations.push(annotation);
+            }
+            else {
+                malformed++;
+            }
+        }
+        start = i + 1;
+    }
+    return { recordStart, annotations, malformed };
+}
+function parseTal(chunk, recordIndex) {
+    // The onset must be explicitly signed; anything else is not a TAL.
+    const first = chunk[0];
+    if (first !== 0x2b /* + */ && first !== 0x2d /* - */)
+        return null;
+    const text = chunk.toString('utf8');
+    const parts = text.split(TEXT_SEP_CHAR);
+    const head = parts[0] ?? '';
+    let onsetText = head;
+    let durationText = null;
+    const durationSep = head.indexOf(DURATION_SEP_CHAR);
+    if (durationSep >= 0) {
+        onsetText = head.slice(0, durationSep);
+        durationText = head.slice(durationSep + 1);
+    }
+    const onset = Number(onsetText);
+    if (!Number.isFinite(onset))
+        return null;
+    let duration = null;
+    if (durationText !== null && durationText !== '') {
+        const d = Number(durationText);
+        duration = Number.isFinite(d) ? d : null;
+    }
+    const annotations = [];
+    for (const raw of parts.slice(1)) {
+        // A trailing separator yields an empty segment; a timekeeping TAL is all empty.
+        if (raw === '')
+            continue;
+        annotations.push({ onset, duration, text: raw, recordIndex });
+    }
+    return { onset, annotations };
+}
+export { SEP_TEXT, SEP_DURATION, TAL_END };
+//# sourceMappingURL=annotations.js.map

package/dist/edf/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"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"}

package/dist/edf/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Error and diagnostic types.
+ *
+ * The distinction that matters here: an EdfError means we cannot produce
+ * trustworthy output and must stop. A Diagnostic with severity 'warning' means
+ * we can continue, but the user needs to know something about their data that
+ * they would not otherwise see.
+ */
+export type DiagnosticCode = 'MIXED_SAMPLING_RATES' | 'DISCONTINUOUS' | 'RECORD_COUNT_UNKNOWN' | 'RECORD_COUNT_MISMATCH' | 'TRAILING_BYTES' | 'DEGENERATE_DIGITAL_RANGE' | 'DEGENERATE_PHYSICAL_RANGE' | 'INVERTED_PHYSICAL_RANGE' | 'DUPLICATE_LABEL' | 'EMPTY_LABEL' | 'NONSTANDARD_UNIT' | 'NO_ANNOTATIONS' | 'ANNOTATION_DECODE_FAILED' | 'COMMA_DECIMAL' | 'LARGE_OUTPUT' | 'NO_SIGNAL_CHANNELS' | 'NO_SAMPLES' | 'STALE_OUTPUT' | 'HEADER_BYTES_MISMATCH' | 'NONPRINTABLE_LABEL';
+export interface Diagnostic {
+    code: DiagnosticCode;
+    severity: 'warning' | 'info';
+    message: string;
+    /** What the user can do about it. Omitted when there is nothing useful to say. */
+    hint?: string;
+}
+export type EdfErrorCode = 'FILE_TOO_SMALL' | 'BAD_HEADER_FIELD' | 'NO_DATA_RECORDS' | 'INVALID_SIGNAL_COUNT' | 'INVALID_RECORD_DURATION' | 'NO_SAMPLES' | 'UNREADABLE';
+/**
+ * A fatal problem with the recording itself. Carries a stable `code` so the CLI
+ * can map it to an exit status, and a `hint` so the user is not left guessing.
+ */
+export declare class EdfError extends Error {
+    readonly code: EdfErrorCode;
+    readonly hint: string | undefined;
+    constructor(code: EdfErrorCode, message: string, hint?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/edf/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/edf/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,cAAc,GACtB,sBAAsB,GACtB,eAAe,GACf,sBAAsB,GACtB,uBAAuB,GACvB,gBAAgB,GAChB,0BAA0B,GAC1B,2BAA2B,GAC3B,yBAAyB,GACzB,iBAAiB,GACjB,aAAa,GACb,kBAAkB,GAClB,gBAAgB,GAChB,0BAA0B,GAC1B,eAAe,GACf,cAAc,GACd,oBAAoB,GACpB,YAAY,GACZ,cAAc,GACd,uBAAuB,GACvB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,iBAAiB,GACjB,sBAAsB,GACtB,yBAAyB,GACzB,YAAY,GACZ,YAAY,CAAC;AAEjB;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAM/D"}

package/dist/edf/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Error and diagnostic types.
+ *
+ * The distinction that matters here: an EdfError means we cannot produce
+ * trustworthy output and must stop. A Diagnostic with severity 'warning' means
+ * we can continue, but the user needs to know something about their data that
+ * they would not otherwise see.
+ */
+/**
+ * A fatal problem with the recording itself. Carries a stable `code` so the CLI
+ * can map it to an exit status, and a `hint` so the user is not left guessing.
+ */
+export class EdfError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.name = 'EdfError';
+        this.code = code;
+        this.hint = hint;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/edf/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/edf/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyCH;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAe;IACnB,IAAI,CAAqB;IAElC,YAAY,IAAkB,EAAE,OAAe,EAAE,IAAa;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/edf/header.d.ts

@@ -0,0 +1,115 @@
+/**
+ * EDF / EDF+ header parsing.
+ *
+ * Layout (all fields are ASCII, left-justified, space-padded):
+ *
+ *   fixed header, 256 bytes
+ *     0    8   version ('0', or 255 + 'BIOSEMI' for BDF)
+ *     8   80   patient identification
+ *    88   80   recording identification
+ *   168    8   start date  dd.mm.yy
+ *   176    8   start time  hh.mm.ss
+ *   184    8   number of bytes in the header record
+ *   192   44   reserved  ('EDF+C' / 'EDF+D' live here)
+ *   236    8   number of data records (-1 if unknown)
+ *   244    8   duration of a data record, in seconds (may be fractional)
+ *   252    4   number of signals (ns)
+ *
+ *   signal header, ns * 256 bytes, stored FIELD-major rather than signal-major:
+ *   all ns labels, then all ns transducer types, and so on.
+ *     ns * 16   label
+ *     ns * 80   transducer type
+ *     ns *  8   physical dimension
+ *     ns *  8   physical minimum
+ *     ns *  8   physical maximum
+ *     ns *  8   digital minimum
+ *     ns *  8   digital maximum
+ *     ns * 80   prefiltering
+ *     ns *  8   number of samples in each data record
+ *     ns * 32   reserved
+ */
+import type { Diagnostic } from './errors.js';
+/** Label the EDF+ spec reserves for the annotations channel. */
+export declare const ANNOTATIONS_LABEL = "EDF Annotations";
+/** BDF+ uses its own spelling for the same channel. */
+export declare const BDF_ANNOTATIONS_LABEL = "BDF Annotations";
+export declare const FIXED_HEADER_BYTES = 256;
+export declare const SIGNAL_HEADER_BYTES = 256;
+export interface EdfSignal {
+    /** Position in the file, 0-based. Stable even when labels collide. */
+    index: number;
+    label: string;
+    transducer: string;
+    physicalDimension: string;
+    physicalMin: number;
+    physicalMax: number;
+    digitalMin: number;
+    digitalMax: number;
+    prefiltering: string;
+    samplesPerRecord: number;
+    reserved: string;
+    /** True for the EDF+ 'EDF Annotations' channel, which carries text, not signal. */
+    isAnnotations: boolean;
+    /** samplesPerRecord / recordDuration, in Hz. */
+    samplingRate: number;
+    /** Byte offset of this signal's samples within one data record. */
+    byteOffsetInRecord: number;
+}
+export interface EdfHeader {
+    version: string;
+    patientId: string;
+    recordingId: string;
+    /** Raw 'dd.mm.yy' as written in the file. */
+    startDateRaw: string;
+    /** Raw 'hh.mm.ss' as written in the file. */
+    startTimeRaw: string;
+    /** Resolved start instant, or null when the file's date/time fields are unusable. */
+    startDateTime: Date | null;
+    headerBytes: number;
+    reserved: string;
+    isEdfPlus: boolean;
+    /** True for BioSemi BDF/BDF+ files, whose samples are 3 bytes rather than 2. */
+    isBdf: boolean;
+    /** 'EDF+C' continuous, 'EDF+D' discontinuous, or null for plain EDF. */
+    continuity: 'EDF+C' | 'EDF+D' | null;
+    /** As declared in the header. -1 means "unknown", which the spec permits. */
+    declaredRecordCount: number;
+    recordDuration: number;
+    signalCount: number;
+    signals: EdfSignal[];
+    bytesPerSample: number;
+    recordBytes: number;
+}
+/** Everything derived by combining the header with the file's real size. */
+export interface EdfHeaderInfo {
+    header: EdfHeader;
+    /** Record count implied by the actual file size — the one we trust for reading. */
+    recordCount: number;
+    /** Bytes after the last complete data record. */
+    trailingBytes: number;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Parse the fixed 256-byte header plus the per-signal header block.
+ *
+ * @param buf   At least FIXED_HEADER_BYTES + ns * SIGNAL_HEADER_BYTES bytes.
+ * @param fileSize Total size of the file on disk, used to derive the real record count.
+ */
+export declare function parseHeader(buf: Buffer, fileSize: number): EdfHeaderInfo;
+/**
+ * The recording start as a zone-less wall clock, "YYYY-MM-DDTHH:MM:SS".
+ *
+ * EDF stores the start time as local wall-clock digits with no timezone anywhere in
+ * the format. `startDateTime` is built with Date.UTC purely so those digits survive a
+ * round trip unshifted, which makes it a carrier for the wall clock rather than a
+ * real instant. Serialising it with `toISOString()` would append a Z and assert UTC,
+ * and any reader converting to local time would then shift the recording by their own
+ * offset: 13:43:04 in the file becomes 08:43:04 in New York. The Z is omitted because
+ * the file genuinely does not say which zone it meant.
+ */
+export declare function formatWallClock(date: Date | null): string | null;
+/** "EDF", "EDF+ (EDF+D)", "BDF", "BDF+ (EDF+C)". */
+export declare function describeFormat(header: EdfHeader): string;
+/** Render a sampling rate without trailing noise: 256, 0.5, 12.5. */
+export declare function formatRate(hz: number): string;
+//# sourceMappingURL=header.d.ts.map

package/dist/edf/header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../src/edf/header.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AACnD,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AAEvD,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,aAAa,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,UAAU,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;IACrC,6EAA6E;IAC7E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,SAAS,CAAC;IAClB,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAgED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAgUxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAIxD;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7C"}