edfcore 0.2.60 → 0.2.61

package/CHANGELOG.md

@@ -6,6 +6,23 @@ alone does not tell you whether you were affected.
 edfcore is pre-1.0. Patch releases have carried behaviour changes where the old behaviour was a
 defect; those are called out below.
 
+## 0.2.60
+
+- **Added** `sampleAt`, `sampleStartTicksOf` and `sampleStartSecondsOf` — the recording-aware
+  counterpart to the sample-grid family, and the groundwork for 0.3.0.
+- 0.2.32 documented why the existing three cannot be fixed in place: they take
+  `(signal, value, recordDurationTicks)`, so a gap is not in their arguments and no arithmetic
+  inside them could find one. These take the RECORDING. On a contiguous file they agree with the
+  grid functions exactly — asserted sample by sample — and on a discontinuous one they differ by
+  the gaps.
+- `sampleAt` can return **`undefined`**, which is the answer the grid form structurally cannot
+  give: no sample exists at that instant, because it falls in a gap, before the recording, or after
+  it. `sampleIndexAt(signal, 5, d)` on a six-record file with a hole at 5 s names record 5; there
+  is no record 5 at that time.
+- Both refuse a probed index on a file with gaps rather than guessing, the same rule `segmentAt`
+  follows. A round-trip test pins the pair together across the gap: the sample at a sample's start
+  is that sample, for every sample in the file.
+
 ## 0.2.59
 
 - **Added** `calib.rec` from edfplus.info — the last corpus the README named. It was written by

package/dist/constants.d.ts

@@ -109,5 +109,5 @@ export declare const SIGNAL_FIELD_BLOCK_OFFSETS: {
     readonly reserved: 224;
 };
 /** Published package version. Kept in sync with package.json by a test. */
-export declare const VERSION = "0.2.60";
+export declare const VERSION = "0.2.61";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -79,5 +79,5 @@ export const SIGNAL_FIELD_BLOCK_OFFSETS = {
     reserved: 224,
 };
 /** Published package version. Kept in sync with package.json by a test. */
-export const VERSION = '0.2.60';
+export const VERSION = '0.2.61';
 //# sourceMappingURL=constants.js.map

package/dist/index.d.ts

@@ -51,5 +51,6 @@ export { formatHeader } from './format-header.js';
 export { inspectEdf } from './inspect.js';
 export { openEdf, readAnnotations, readRecords, readWindow } from './recording.js';
 export { sampleIndexAt, sampleStartSeconds, sampleStartTicks, } from './sample-grid.js';
+export { sampleAt, sampleStartSecondsOf, sampleStartTicksOf, } from './sample-locate.js';
 export { streamRecords } from './stream.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -63,5 +63,6 @@ export { formatHeader } from './format-header.js';
 export { inspectEdf } from './inspect.js';
 export { openEdf, readAnnotations, readRecords, readWindow } from './recording.js';
 export { sampleIndexAt, sampleStartSeconds, sampleStartTicks, } from './sample-grid.js';
+export { sampleAt, sampleStartSecondsOf, sampleStartTicksOf, } from './sample-locate.js';
 export { streamRecords } from './stream.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA2EH,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EACvB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,gCAAgC,EAChC,gBAAgB,EAChB,OAAO,GACR,MAAM,gBAAgB,CAAC;AAExB,8EAA8E;AAC9E,2EAA2E;AAC3E,2CAA2C;AAC3C,8EAA8E;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,8EAA8E;AAC9E,yEAAyE;AACzE,2EAA2E;AAC3E,6CAA6C;AAC7C,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,KAAK,EACL,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA2EH,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EACvB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,gCAAgC,EAChC,gBAAgB,EAChB,OAAO,GACR,MAAM,gBAAgB,CAAC;AAExB,8EAA8E;AAC9E,2EAA2E;AAC3E,2CAA2C;AAC3C,8EAA8E;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,8EAA8E;AAC9E,yEAAyE;AACzE,2EAA2E;AAC3E,6CAA6C;AAC7C,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,KAAK,EACL,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/sample-locate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Time and sample index, on the recording's own axis.
+ *
+ * Layer 7. The recording-aware counterpart to `sample-grid.ts`, and the reason it exists is stated
+ * plainly there: `sampleIndexAt`, `sampleStartTicks` and `sampleStartSeconds` take
+ * `(signal, value, recordDurationTicks)` — no index, no timeline — so a gap is not in their
+ * arguments and no arithmetic inside them could find one. They measure the signal's own SAMPLE
+ * GRID, which equals elapsed recording time only when the recording is contiguous.
+ *
+ * These two take the recording, so they can answer the question people actually mean. On a
+ * contiguous file they agree with the grid functions exactly. On an EDF+D file they differ by the
+ * gaps, and `sampleAt` can answer something the grid functions structurally cannot: that an
+ * instant has NO sample at all, because it falls in a hole.
+ *
+ * Both refuse a probed index on a file whose records do not cover its span, for the reason
+ * `segmentAt` does: `undefined` from `sampleAt` means "no sample exists here", and an index that
+ * has read record 0 and the last record cannot say that about anything in between. Merging "there
+ * is a gap here" with "nobody looked" is the confusion this whole area of the API avoids.
+ */
+import type { EdfRecording, EdfSampleLocation } from './types.js';
+/**
+ * The sample covering `seconds`, or `undefined` when no sample does.
+ *
+ * `undefined` is a real answer rather than a failure: on an EDF+D file an instant inside a gap has
+ * no sample, and so does any time before the recording starts or after it ends. That is the case
+ * `sampleIndexAt` cannot express — given only a signal and a record duration it always returns an
+ * index, even one past the end of the file.
+ *
+ * Floor, not round, and in exact integer arithmetic on ticks: a sample covers the half-open
+ * interval from its own start to the next one's, so the sample "at" a time is the one already
+ * running when that time arrives.
+ */
+export declare function sampleAt(recording: EdfRecording, signalIndex: number, seconds: number): EdfSampleLocation | undefined;
+/**
+ * When a sample starts, in exact ticks on the recording's axis.
+ *
+ * The inverse of `sampleAt`, and the recording-aware form of `sampleStartTicks`. On a contiguous
+ * file the two agree exactly; on an EDF+D file this one includes the gaps that precede the sample
+ * and `sampleStartTicks` does not.
+ *
+ * Rounds UP to a whole tick, as `sampleStartTicks` does: a sample boundary need not fall on one —
+ * 128 samples over 0.3 s puts sample 1 at 23,437.5 ticks — and truncating would return a tick
+ * lying inside the previous sample, which `sampleAt` would then map straight back to that
+ * previous sample.
+ */
+export declare function sampleStartTicksOf(recording: EdfRecording, signalIndex: number, sampleIndex: number): bigint;
+/** `sampleStartTicksOf` as float64 seconds. Compare with the ticks, never with this. */
+export declare function sampleStartSecondsOf(recording: EdfRecording, signalIndex: number, sampleIndex: number): number;
+//# sourceMappingURL=sample-locate.d.ts.map

package/dist/sample-locate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample-locate.d.ts","sourceRoot":"","sources":["../src/sample-locate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAyB,MAAM,YAAY,CAAC;AAkFzF;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,YAAY,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,iBAAiB,GAAG,SAAS,CAqC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,YAAY,EACvB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CA0BR;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,YAAY,EACvB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER"}

package/dist/sample-locate.js

@@ -0,0 +1,172 @@
+/**
+ * Time and sample index, on the recording's own axis.
+ *
+ * Layer 7. The recording-aware counterpart to `sample-grid.ts`, and the reason it exists is stated
+ * plainly there: `sampleIndexAt`, `sampleStartTicks` and `sampleStartSeconds` take
+ * `(signal, value, recordDurationTicks)` — no index, no timeline — so a gap is not in their
+ * arguments and no arithmetic inside them could find one. They measure the signal's own SAMPLE
+ * GRID, which equals elapsed recording time only when the recording is contiguous.
+ *
+ * These two take the recording, so they can answer the question people actually mean. On a
+ * contiguous file they agree with the grid functions exactly. On an EDF+D file they differ by the
+ * gaps, and `sampleAt` can answer something the grid functions structurally cannot: that an
+ * instant has NO sample at all, because it falls in a hole.
+ *
+ * Both refuse a probed index on a file whose records do not cover its span, for the reason
+ * `segmentAt` does: `undefined` from `sampleAt` means "no sample exists here", and an index that
+ * has read record 0 and the last record cannot say that about anything in between. Merging "there
+ * is a gap here" with "nobody looked" is the confusion this whole area of the API avoids.
+ */
+import { EdfChannelNotFoundError } from './errors.js';
+import { segmentAt } from './record-index.js';
+import { secondsToTicks, ticksToSeconds } from './tal/ticks.js';
+/** `b` must be positive. Bigint `/` truncates toward zero, so negatives need the correction. */
+function floorDiv(a, b) {
+    const quotient = a / b;
+    return a % b === 0n || a > 0n ? quotient : quotient - 1n;
+}
+function resolveSignal(recording, signalIndex, caller) {
+    const signal = recording.header.signals[signalIndex];
+    if (signal === undefined) {
+        throw new EdfChannelNotFoundError(`${caller}(): signalIndex ${signalIndex} is outside the ` +
+            `${recording.header.signals.length} signals this file declares. Next: pass an index from ` +
+            'header.dataSignalIndices, or resolve one with getSignal(header, label).', {
+            selector: signalIndex,
+            availableLabels: recording.header.signals.map((s) => s.label),
+        });
+    }
+    if (signal.kind === 'annotations') {
+        throw new RangeError(`${caller}(): signal ${signalIndex} (${JSON.stringify(signal.label)}) is an annotations ` +
+            'channel, whose region holds TAL text rather than samples, so it has no sample grid. ' +
+            'Next: use onsetTicksFromFirstRecord on the annotations themselves.');
+    }
+    if (signal.samplesPerRecord <= 0) {
+        throw new RangeError(`${caller}(): signal ${signalIndex} (${JSON.stringify(signal.label)}) declares ` +
+            `${signal.samplesPerRecord} samples per record, so it has no sample grid to index. ` +
+            'Next: check header.diagnostics for ZERO_SAMPLES_PER_RECORD.');
+    }
+    if (recording.header.recordDurationTicks <= 0n) {
+        throw new RangeError(`${caller}(): this file declares a record duration of zero, so records do not advance in ` +
+            'time and no elapsed time maps to a sample. This is legal EDF and a scoring file relies ' +
+            'on it. Next: index by record with readRecords().');
+    }
+    return signal;
+}
+/**
+ * The record a segment places at a given position, and that record's true start in ticks.
+ *
+ * `segment.startTicks` is already on the recording's axis, and records inside one segment are
+ * contiguous by construction, so this is exact.
+ */
+function recordStartTicks(recording, segment, recordIndex) {
+    const duration = recording.header.recordDurationTicks;
+    if (segment === undefined)
+        return BigInt(recordIndex) * duration;
+    return segment.startTicks + BigInt(recordIndex - segment.records.start) * duration;
+}
+/** The segment holding a record, on a scanned index; `undefined` when the file is contiguous. */
+function segmentOfRecord(recording, recordIndex) {
+    const segments = recording.index.segments;
+    if (segments === undefined)
+        return undefined;
+    for (const segment of segments) {
+        const first = segment.records.start;
+        if (recordIndex >= first && recordIndex < first + segment.records.count)
+            return segment;
+    }
+    return undefined;
+}
+/**
+ * Whether this recording needs a scanned index before a time can be located at all.
+ *
+ * A file whose records cover exactly its span is contiguous, and the nominal grid IS the true one
+ * — so a probed index is enough and no scan is demanded of the caller for nothing.
+ */
+function requiresScan(recording) {
+    return recording.timeline.spanSeconds !== recording.timeline.coveredSeconds;
+}
+/**
+ * The sample covering `seconds`, or `undefined` when no sample does.
+ *
+ * `undefined` is a real answer rather than a failure: on an EDF+D file an instant inside a gap has
+ * no sample, and so does any time before the recording starts or after it ends. That is the case
+ * `sampleIndexAt` cannot express — given only a signal and a record duration it always returns an
+ * index, even one past the end of the file.
+ *
+ * Floor, not round, and in exact integer arithmetic on ticks: a sample covers the half-open
+ * interval from its own start to the next one's, so the sample "at" a time is the one already
+ * running when that time arrives.
+ */
+export function sampleAt(recording, signalIndex, seconds) {
+    const signal = resolveSignal(recording, signalIndex, 'sampleAt');
+    if (!Number.isFinite(seconds)) {
+        throw new RangeError(`sampleAt(): seconds must be a finite number, received ${seconds}.`);
+    }
+    const duration = recording.header.recordDurationTicks;
+    const perRecord = BigInt(signal.samplesPerRecord);
+    const ticks = secondsToTicks(seconds);
+    if (!requiresScan(recording)) {
+        // Contiguous: the nominal grid is the true one, but the answer is still bounded by the file.
+        const recordIndex = Number(floorDiv(ticks, duration));
+        if (recordIndex < 0 || recordIndex >= recording.header.recordCount)
+            return undefined;
+        const withinTicks = ticks - BigInt(recordIndex) * duration;
+        const sampleWithinRecord = Number(floorDiv(withinTicks * perRecord, duration));
+        return {
+            sampleIndex: recordIndex * signal.samplesPerRecord + sampleWithinRecord,
+            recordIndex,
+            sampleWithinRecord,
+        };
+    }
+    // Discontinuous: `segmentAt` owns the "is there data here at all" question, and throws for a
+    // probed index rather than guessing.
+    const segment = segmentAt(recording.index, seconds);
+    if (segment === undefined)
+        return undefined;
+    const offsetTicks = ticks - segment.startTicks;
+    const recordIndex = segment.records.start + Number(floorDiv(offsetTicks, duration));
+    const withinTicks = offsetTicks - floorDiv(offsetTicks, duration) * duration;
+    const sampleWithinRecord = Number(floorDiv(withinTicks * perRecord, duration));
+    return {
+        sampleIndex: recordIndex * signal.samplesPerRecord + sampleWithinRecord,
+        recordIndex,
+        sampleWithinRecord,
+    };
+}
+/**
+ * When a sample starts, in exact ticks on the recording's axis.
+ *
+ * The inverse of `sampleAt`, and the recording-aware form of `sampleStartTicks`. On a contiguous
+ * file the two agree exactly; on an EDF+D file this one includes the gaps that precede the sample
+ * and `sampleStartTicks` does not.
+ *
+ * Rounds UP to a whole tick, as `sampleStartTicks` does: a sample boundary need not fall on one —
+ * 128 samples over 0.3 s puts sample 1 at 23,437.5 ticks — and truncating would return a tick
+ * lying inside the previous sample, which `sampleAt` would then map straight back to that
+ * previous sample.
+ */
+export function sampleStartTicksOf(recording, signalIndex, sampleIndex) {
+    const signal = resolveSignal(recording, signalIndex, 'sampleStartTicksOf');
+    if (!Number.isSafeInteger(sampleIndex)) {
+        throw new RangeError(`sampleStartTicksOf(): sampleIndex must be a whole number, received ${sampleIndex}.`);
+    }
+    const perRecord = signal.samplesPerRecord;
+    const duration = recording.header.recordDurationTicks;
+    const recordIndex = Math.floor(sampleIndex / perRecord);
+    const within = BigInt(sampleIndex - recordIndex * perRecord);
+    if (requiresScan(recording) && recording.index.segments === undefined) {
+        throw new RangeError('sampleStartTicksOf(): this file has gaps and its index has not been scanned, so the true ' +
+            'start of a record after a gap is not known. Next: await buildRecordIndex(recording) and ' +
+            'read the result into the recording.');
+    }
+    const start = recordStartTicks(recording, segmentOfRecord(recording, recordIndex), recordIndex);
+    const numerator = within * duration;
+    const offset = numerator / BigInt(perRecord);
+    // Ceil, matching `sampleStartTicks`.
+    return start + (numerator % BigInt(perRecord) === 0n ? offset : offset + 1n);
+}
+/** `sampleStartTicksOf` as float64 seconds. Compare with the ticks, never with this. */
+export function sampleStartSecondsOf(recording, signalIndex, sampleIndex) {
+    return ticksToSeconds(sampleStartTicksOf(recording, signalIndex, sampleIndex));
+}
+//# sourceMappingURL=sample-locate.js.map

package/dist/sample-locate.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edfcore",
-  "version": "0.2.60",
+  "version": "0.2.61",
   "description": "Modern, typed, zero-dependency reader for EDF, EDF+, BDF and BDF+ biosignal files. Works in browsers and Node with true random access.",
   "keywords": [
     "edf",

package/src/constants.ts

@@ -93,4 +93,4 @@ export const SIGNAL_FIELD_BLOCK_OFFSETS = {
 } as const;
 
 /** Published package version. Kept in sync with package.json by a test. */
-export const VERSION = '0.2.60';
+export const VERSION = '0.2.61';

package/src/index.ts

@@ -194,4 +194,9 @@ export {
   sampleStartSeconds,
   sampleStartTicks,
 } from './sample-grid.js';
+export {
+  sampleAt,
+  sampleStartSecondsOf,
+  sampleStartTicksOf,
+} from './sample-locate.js';
 export { streamRecords } from './stream.js';

package/src/sample-locate.ts

@@ -0,0 +1,212 @@
+/**
+ * Time and sample index, on the recording's own axis.
+ *
+ * Layer 7. The recording-aware counterpart to `sample-grid.ts`, and the reason it exists is stated
+ * plainly there: `sampleIndexAt`, `sampleStartTicks` and `sampleStartSeconds` take
+ * `(signal, value, recordDurationTicks)` — no index, no timeline — so a gap is not in their
+ * arguments and no arithmetic inside them could find one. They measure the signal's own SAMPLE
+ * GRID, which equals elapsed recording time only when the recording is contiguous.
+ *
+ * These two take the recording, so they can answer the question people actually mean. On a
+ * contiguous file they agree with the grid functions exactly. On an EDF+D file they differ by the
+ * gaps, and `sampleAt` can answer something the grid functions structurally cannot: that an
+ * instant has NO sample at all, because it falls in a hole.
+ *
+ * Both refuse a probed index on a file whose records do not cover its span, for the reason
+ * `segmentAt` does: `undefined` from `sampleAt` means "no sample exists here", and an index that
+ * has read record 0 and the last record cannot say that about anything in between. Merging "there
+ * is a gap here" with "nobody looked" is the confusion this whole area of the API avoids.
+ */
+
+import { EdfChannelNotFoundError } from './errors.js';
+import { segmentAt } from './record-index.js';
+import { secondsToTicks, ticksToSeconds } from './tal/ticks.js';
+import type { EdfRecording, EdfSampleLocation, EdfSegment, EdfSignal } from './types.js';
+
+/** `b` must be positive. Bigint `/` truncates toward zero, so negatives need the correction. */
+function floorDiv(a: bigint, b: bigint): bigint {
+  const quotient = a / b;
+  return a % b === 0n || a > 0n ? quotient : quotient - 1n;
+}
+
+function resolveSignal(recording: EdfRecording, signalIndex: number, caller: string): EdfSignal {
+  const signal = recording.header.signals[signalIndex];
+  if (signal === undefined) {
+    throw new EdfChannelNotFoundError(
+      `${caller}(): signalIndex ${signalIndex} is outside the ` +
+        `${recording.header.signals.length} signals this file declares. Next: pass an index from ` +
+        'header.dataSignalIndices, or resolve one with getSignal(header, label).',
+      {
+        selector: signalIndex,
+        availableLabels: recording.header.signals.map((s) => s.label),
+      },
+    );
+  }
+  if (signal.kind === 'annotations') {
+    throw new RangeError(
+      `${caller}(): signal ${signalIndex} (${JSON.stringify(signal.label)}) is an annotations ` +
+        'channel, whose region holds TAL text rather than samples, so it has no sample grid. ' +
+        'Next: use onsetTicksFromFirstRecord on the annotations themselves.',
+    );
+  }
+  if (signal.samplesPerRecord <= 0) {
+    throw new RangeError(
+      `${caller}(): signal ${signalIndex} (${JSON.stringify(signal.label)}) declares ` +
+        `${signal.samplesPerRecord} samples per record, so it has no sample grid to index. ` +
+        'Next: check header.diagnostics for ZERO_SAMPLES_PER_RECORD.',
+    );
+  }
+  if (recording.header.recordDurationTicks <= 0n) {
+    throw new RangeError(
+      `${caller}(): this file declares a record duration of zero, so records do not advance in ` +
+        'time and no elapsed time maps to a sample. This is legal EDF and a scoring file relies ' +
+        'on it. Next: index by record with readRecords().',
+    );
+  }
+  return signal;
+}
+
+/**
+ * The record a segment places at a given position, and that record's true start in ticks.
+ *
+ * `segment.startTicks` is already on the recording's axis, and records inside one segment are
+ * contiguous by construction, so this is exact.
+ */
+function recordStartTicks(
+  recording: EdfRecording,
+  segment: EdfSegment | undefined,
+  recordIndex: number,
+): bigint {
+  const duration = recording.header.recordDurationTicks;
+  if (segment === undefined) return BigInt(recordIndex) * duration;
+  return segment.startTicks + BigInt(recordIndex - segment.records.start) * duration;
+}
+
+/** The segment holding a record, on a scanned index; `undefined` when the file is contiguous. */
+function segmentOfRecord(recording: EdfRecording, recordIndex: number): EdfSegment | undefined {
+  const segments = recording.index.segments;
+  if (segments === undefined) return undefined;
+  for (const segment of segments) {
+    const first = segment.records.start;
+    if (recordIndex >= first && recordIndex < first + segment.records.count) return segment;
+  }
+  return undefined;
+}
+
+/**
+ * Whether this recording needs a scanned index before a time can be located at all.
+ *
+ * A file whose records cover exactly its span is contiguous, and the nominal grid IS the true one
+ * — so a probed index is enough and no scan is demanded of the caller for nothing.
+ */
+function requiresScan(recording: EdfRecording): boolean {
+  return recording.timeline.spanSeconds !== recording.timeline.coveredSeconds;
+}
+
+/**
+ * The sample covering `seconds`, or `undefined` when no sample does.
+ *
+ * `undefined` is a real answer rather than a failure: on an EDF+D file an instant inside a gap has
+ * no sample, and so does any time before the recording starts or after it ends. That is the case
+ * `sampleIndexAt` cannot express — given only a signal and a record duration it always returns an
+ * index, even one past the end of the file.
+ *
+ * Floor, not round, and in exact integer arithmetic on ticks: a sample covers the half-open
+ * interval from its own start to the next one's, so the sample "at" a time is the one already
+ * running when that time arrives.
+ */
+export function sampleAt(
+  recording: EdfRecording,
+  signalIndex: number,
+  seconds: number,
+): EdfSampleLocation | undefined {
+  const signal = resolveSignal(recording, signalIndex, 'sampleAt');
+  if (!Number.isFinite(seconds)) {
+    throw new RangeError(`sampleAt(): seconds must be a finite number, received ${seconds}.`);
+  }
+
+  const duration = recording.header.recordDurationTicks;
+  const perRecord = BigInt(signal.samplesPerRecord);
+  const ticks = secondsToTicks(seconds);
+
+  if (!requiresScan(recording)) {
+    // Contiguous: the nominal grid is the true one, but the answer is still bounded by the file.
+    const recordIndex = Number(floorDiv(ticks, duration));
+    if (recordIndex < 0 || recordIndex >= recording.header.recordCount) return undefined;
+    const withinTicks = ticks - BigInt(recordIndex) * duration;
+    const sampleWithinRecord = Number(floorDiv(withinTicks * perRecord, duration));
+    return {
+      sampleIndex: recordIndex * signal.samplesPerRecord + sampleWithinRecord,
+      recordIndex,
+      sampleWithinRecord,
+    };
+  }
+
+  // Discontinuous: `segmentAt` owns the "is there data here at all" question, and throws for a
+  // probed index rather than guessing.
+  const segment = segmentAt(recording.index, seconds);
+  if (segment === undefined) return undefined;
+
+  const offsetTicks = ticks - segment.startTicks;
+  const recordIndex = segment.records.start + Number(floorDiv(offsetTicks, duration));
+  const withinTicks = offsetTicks - floorDiv(offsetTicks, duration) * duration;
+  const sampleWithinRecord = Number(floorDiv(withinTicks * perRecord, duration));
+  return {
+    sampleIndex: recordIndex * signal.samplesPerRecord + sampleWithinRecord,
+    recordIndex,
+    sampleWithinRecord,
+  };
+}
+
+/**
+ * When a sample starts, in exact ticks on the recording's axis.
+ *
+ * The inverse of `sampleAt`, and the recording-aware form of `sampleStartTicks`. On a contiguous
+ * file the two agree exactly; on an EDF+D file this one includes the gaps that precede the sample
+ * and `sampleStartTicks` does not.
+ *
+ * Rounds UP to a whole tick, as `sampleStartTicks` does: a sample boundary need not fall on one —
+ * 128 samples over 0.3 s puts sample 1 at 23,437.5 ticks — and truncating would return a tick
+ * lying inside the previous sample, which `sampleAt` would then map straight back to that
+ * previous sample.
+ */
+export function sampleStartTicksOf(
+  recording: EdfRecording,
+  signalIndex: number,
+  sampleIndex: number,
+): bigint {
+  const signal = resolveSignal(recording, signalIndex, 'sampleStartTicksOf');
+  if (!Number.isSafeInteger(sampleIndex)) {
+    throw new RangeError(
+      `sampleStartTicksOf(): sampleIndex must be a whole number, received ${sampleIndex}.`,
+    );
+  }
+
+  const perRecord = signal.samplesPerRecord;
+  const duration = recording.header.recordDurationTicks;
+  const recordIndex = Math.floor(sampleIndex / perRecord);
+  const within = BigInt(sampleIndex - recordIndex * perRecord);
+
+  if (requiresScan(recording) && recording.index.segments === undefined) {
+    throw new RangeError(
+      'sampleStartTicksOf(): this file has gaps and its index has not been scanned, so the true ' +
+        'start of a record after a gap is not known. Next: await buildRecordIndex(recording) and ' +
+        'read the result into the recording.',
+    );
+  }
+
+  const start = recordStartTicks(recording, segmentOfRecord(recording, recordIndex), recordIndex);
+  const numerator = within * duration;
+  const offset = numerator / BigInt(perRecord);
+  // Ceil, matching `sampleStartTicks`.
+  return start + (numerator % BigInt(perRecord) === 0n ? offset : offset + 1n);
+}
+
+/** `sampleStartTicksOf` as float64 seconds. Compare with the ticks, never with this. */
+export function sampleStartSecondsOf(
+  recording: EdfRecording,
+  signalIndex: number,
+  sampleIndex: number,
+): number {
+  return ticksToSeconds(sampleStartTicksOf(recording, signalIndex, sampleIndex));
+}