gpx-from-gopro 0.1.0 → 0.3.0

package/README.md

@@ -16,13 +16,20 @@ npm install gpx-from-gopro
 
 ## CLI
 
+No install needed:
+
 ```sh
-gpx-from-gopro <dir|file.mp4> [...] [--out DIR] [--tz HOURS] [--rate HZ] [--cache-dir DIR | --no-cache]
+npx gpx-from-gopro <dir|file.mp4> [...] [--out DIR] [--tz HOURS] [--rate HZ] [--cache-dir DIR | --no-cache]
 ```
 
-Recurses directories for video files, groups by camera family + local date, and writes one merged
-`<YYYYMMDD>-<family>.gpx` per group. A per-file extraction cache (keyed by size+mtime+rate) lets a
-killed run resume without re-extracting. `--rate HZ` downsamples from the native ~18 Hz; `--tz HOURS`
+Once installed (`npm install [-g] gpx-from-gopro`), drop the `npx` prefix and just run
+`gpx-from-gopro ...`.
+
+Recurses directories for video files, groups by camera body (serial, falling back to filename
+family) + local date, and writes one merged `<YYYYMMDD>-<family>.gpx` per group — within it, points
+split into one `<trkseg>` per recording session (keyed on the filename file-number, with a time-gap
+split for restarts/dropouts). A per-file extraction cache (keyed by size+mtime+rate) lets a killed
+run resume without re-extracting. `--rate HZ` downsamples from the native ~18 Hz; `--tz HOURS`
 overrides the longitude-guessed local date.
 
 ## Library — telemetry export

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gpx-from-gopro",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Extract a GoPro video's GPS telemetry as GPX or render-agnostic TrackPoints (points + meta + timezone + UTC anchor).",
   "keywords": [
     "gopro",
@@ -32,7 +32,8 @@
     "directory": "packages/gopro"
   },
   "dependencies": {
-    "gpx-stabilizer": "^0.1.0",
+    "gpx-stabilizer": "^0.3.0",
+    "egm96-universal": "^1.1.1",
     "gopro-telemetry": "^1.2.11",
     "gpmf-extract": "^0.3.3",
     "mp4box": "^0.5.4",

package/src/gopro-cache.js

@@ -6,6 +6,18 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
+// Cache schema version: bump whenever the cached record's shape or the
+// extraction output changes, so stale records read as a miss and re-extract.
+// 3: points carry `cts` (media offset); the record is { meta, points, streams },
+// where `streams` holds every non-GPS GPMF channel (IMU/scene/exposure/…) as raw
+// cts samples and `meta` also carries camera fields (`model`/`firmware`/`serial`/
+// `mediaId`/`highlights`, from the moov udta). These additions are
+// ADDITIVE — an older v3 record without them reads back as `streams: {}` / absent
+// fields (graceful), so while the multi-sensor format is still iterated we clear
+// stale records by hand instead of bumping the version; bump before shipping.
+// (v2 was { hasGps, meta, points }, pre-cts.)
+export const CACHE_V = 3;
+
 /**
  * Cache-record path for a source file: sidecar `<file>.gpxcache.json` by
  * default, or a hashed name inside `cacheDir` (keeps the media tree clean).
@@ -21,6 +33,21 @@ export function cachePath(file, cacheDir = null) {
   return `${file}.gpxcache.json`;
 }
 
+/**
+ * Resolve the opt-in `cache` option to a record path, or null when caching is
+ * off. Caching is ON by default: `undefined`/`true` → sidecar next to the
+ * source; `{ dir }` → a hashed name under `dir` (keeps the media tree clean);
+ * `false`/`null` → disabled.
+ * @param {string} file
+ * @param {boolean | { dir?: string | null } | null} [cache]
+ * @returns {string | null}
+ */
+export function resolveCachePath(file, cache = true) {
+  if (cache === false || cache == null) return null;
+  const dir = typeof cache === "object" ? (cache.dir ?? null) : null;
+  return cachePath(file, dir);
+}
+
 /**
  * Read a cache record, returning it only when it matches `ident`
  * (v + size + mtime + rate); missing/unreadable/stale all return null.

package/src/gopro-cli.js

@@ -1,23 +1,28 @@
 #!/usr/bin/env node
-// gpx-from-gopro — extract GoPro GPS into merged GPX, grouped by camera family + local date.
+// gpx-from-gopro — extract GoPro GPS into merged GPX, one file per camera per local date.
 //   gpx-from-gopro <dir|file.mp4> [...] [--out DIR] [--tz HOURS] [--rate HZ] [--cache-dir DIR | --no-cache]
 //
 // - Recurses directories for video files (mp4/mov/m4v/360); skips .LRV/.THM and ._ AppleDouble.
-// - Groups by (filename family, local date): GOPR/GP = old camera, GX/GH = new camera; a session's
-//   first file (GOPR) and its continuation chapters (GP..) merge into one family.
+// - Groups by (camera, local date): camera = the body serial (udta CAME) when known, so two
+//   same-model bodies shot on the same day stay separate; falls back to the filename family
+//   (GOPR/GP = old, GX/GH = new) for files without a serial. Crash-fragmented files still merge
+//   (same serial+date), so a session GoPro split across a crash is rejoined into the day's file.
+// - Within a day's file, points split into one <trkseg> per recording session, keyed on the
+//   filename file-number (a recording's chapters share it), with a within-session time-gap
+//   split for restarts/dropouts: an uncrashed activity is one segment; a crash (new file-number)
+//   shows as a segment break, same file. (GUMI is per-chapter on some bodies, so unused here.)
 // - Local date: timezone from the median longitude of the first valid fixes (round(lon/15)),
 //   snapped to the machine's local timezone when within 1 hour; override with --tz.
-// - One merged <YYYYMMDD>-<family>.gpx per group, written to --out (default ".").
+// - One merged <YYYYMMDD>-<family>.gpx per group (a short serial suffix is added only when two
+//   cameras collide on the same family+date), written to --out (default ".").
 // - Tolerant: a file that fails to extract is logged and skipped, the run continues.
 // - Caches each file's extracted points (sidecar <file>.gpxcache.json by default, or --cache-dir),
 //   keyed by size+mtime+rate+version, so a killed run resumes without re-extracting done files.
 import { mkdirSync, readdirSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import { saveGpx } from "gpx-stabilizer";
-import { extractGoproPoints, probeGoproMeta } from "./gopro.js";
-import { cachePath, readCache, writeCache } from "./gopro-cache.js";
-
-const CACHE_V = 2; // bump when extraction output shape/logic changes (invalidates old caches)
+import { buildGroups, family, fileNumber } from "./group.js";
+import { readGoproSamples } from "./telemetry.js";
 
 const VIDEO_RE = /\.(mp4|mov|m4v|360)$/i;
 const MEDIAN_N = 30;
@@ -48,22 +53,11 @@ if (manualTZ != null && Number.isNaN(manualTZ)) {
   console.error(`invalid --tz: ${opts.tz}`);
   process.exit(1);
 }
-// --rate HZ -> group samples to that rate; omit for native (~18 Hz)
-const groupTimes = opts.rate ? Math.round(1000 / Number(opts.rate)) : undefined;
-// per-file extraction cache: sidecar next to source by default, or --cache-dir; --no-cache disables
-const cacheEnabled = !opts["no-cache"];
-const cacheDir = opts["cache-dir"] ?? null;
-
-// ---- camera family from filename ----
-function family(file) {
-  const b = basename(file).toUpperCase();
-  if (/^GOPR\d+\./.test(b)) return "GOPR";
-  if (/^GP\d\d\d+\./.test(b)) return "GOPR";
-  if (/^GX\d\d\d+\./.test(b)) return "GX";
-  if (/^GH\d\d\d+\./.test(b)) return "GH";
-  const m = b.match(/^([A-Z]+)/);
-  return m ? m[1] : "MISC";
-}
+// --rate HZ -> downsample to that rate; omit for native (~18 Hz)
+const rate = opts.rate ? Number(opts.rate) : undefined;
+// per-file extraction cache (on by default): sidecar next to source; --cache-dir
+// redirects to a managed dir; --no-cache disables
+const cache = opts["no-cache"] ? false : opts["cache-dir"] ? { dir: opts["cache-dir"] } : true;
 
 // ---- timezone from median longitude of the first valid fixes ----
 function medianLon(points) {
@@ -127,70 +121,43 @@ if (videos.length === 0) {
 }
 console.log(`found ${videos.length} video file(s)`);
 
-const groups = new Map(); // key "YYYYMMDD-FAMILY" -> { points, family, date }
+const entries = []; // one per extracted file -> buildGroups
 let ok = 0;
 let skipped = 0;
 let failed = 0;
 for (const file of videos) {
-  const ident = { v: CACHE_V, size: 0, mtime: 0, rate: groupTimes ?? null };
+  let meta;
+  let points;
+  let fromCache;
   try {
-    const st = statSync(file);
-    ident.size = st.size;
-    ident.mtime = Math.round(st.mtimeMs);
+    ({ meta, points, fromCache } = await readGoproSamples(file, { rate, cache }));
   } catch (e) {
-    console.error(`  FAILED stat ${basename(file)}: ${e.message}`);
+    console.error(`  FAILED ${basename(file)}: ${(e?.message ?? String(e)).split("\n")[0]}`);
     failed++;
     continue;
   }
-  const cp = cacheEnabled ? cachePath(file, cacheDir) : null;
-  const cached = cp ? readCache(cp, ident) : null;
-
-  let points;
-  if (cached) {
-    if (!cached.hasGps) {
-      console.error(`  no GPS track, skip (cached): ${basename(file)}`);
-      skipped++;
-      continue;
-    }
-    points = cached.points;
-  } else {
-    // Cheap moov probe first: skip files with no GPMF GPS track without the
-    // (slow) full extraction. Catches stitched products and non-GoPro videos.
-    let meta;
-    try {
-      meta = await probeGoproMeta(file);
-    } catch (e) {
-      console.error(
-        `  FAILED probe ${basename(file)}: ${(e?.message ?? String(e)).split("\n")[0]}`,
-      );
-      failed++;
-      continue;
-    }
-    if (!meta.hasGps) {
-      if (cp) writeCache(cp, { ...ident, hasGps: false, meta }, cacheDir);
-      const dim = meta.width && meta.height ? `${meta.width}x${meta.height}` : "?";
-      console.error(`  no GPS track, skip: ${basename(file)} (${dim} ${meta.codec ?? "?"})`);
-      skipped++;
-      continue;
-    }
-    try {
-      points = await extractGoproPoints(file, groupTimes ? { groupTimes } : {});
-    } catch (e) {
-      console.error(`  FAILED ${basename(file)}: ${(e?.message ?? String(e)).split("\n")[0]}`);
-      failed++;
-      continue;
-    }
-    if (points.length === 0) {
-      if (cp) writeCache(cp, { ...ident, hasGps: false, meta }, cacheDir);
-      console.error(`  no GPS, skip: ${basename(file)}`);
-      skipped++;
-      continue;
-    }
-    if (cp) writeCache(cp, { ...ident, hasGps: true, meta, points }, cacheDir);
+  // No GPMF GPS track (caught cheaply by the moov probe) or an extraction that
+  // yielded nothing — skip either way.
+  if (!meta.hasGps || points.length === 0) {
+    const dim = meta.width && meta.height ? `${meta.width}x${meta.height}` : "?";
+    console.error(
+      `  no GPS track, skip${fromCache ? " (cached)" : ""}: ${basename(file)} (${dim} ${meta.codec ?? "?"})`,
+    );
+    skipped++;
+    continue;
   }
 
   const fam = family(file);
-  const fix = points.find((p) => !(p.lat === 0 && p.lon === 0)) ?? points[0];
+  const fix = points.find((p) => !(p.lat === 0 && p.lon === 0));
+  if (!fix) {
+    // Every sample is a (0,0) pre-lock placeholder — the GPS never got a position fix (indoor /
+    // no sky view). buildGroups would drop them all and skip the resulting empty group anyway;
+    // catch it here so the log is honest. A fallback date off points[0] would be the GoPro's
+    // pre-satellite clock default (e.g. 2021), which reads deceptively like a real misdated file.
+    console.error(`  no real fix, skip: ${basename(file)} (0/${points.length} fixed)`);
+    skipped++;
+    continue;
+  }
   const tz = decideTZ(medianLon(points));
   const date = fix.time != null ? localDate(fix.time, tz) : null;
   if (date == null) {
@@ -198,33 +165,31 @@ for (const file of videos) {
     skipped++;
     continue;
   }
-  const key = `${date}-${fam}`;
-  if (!groups.has(key)) groups.set(key, { points: [], family: fam, date });
-  groups.get(key).points.push(...points);
-  console.log(`  ${basename(file)}: ${points.length} pts -> ${key}${cached ? " (cached)" : ""}`);
+  // Hand the grouping inputs to buildGroups: serial (CAME) splits cameras, the filename
+  // file-number splits recording sessions into <trkseg>s (+ a time-gap split). See ./group.js.
+  entries.push({ family: fam, date, serial: meta.serial, session: fileNumber(file), points });
+  const tag = meta.serial ? `${date}-${fam}#${meta.serial.slice(0, 4)}` : `${date}-${fam}`;
+  console.log(`  ${basename(file)}: ${points.length} pts -> ${tag}${fromCache ? " (cached)" : ""}`);
   ok++;
 }
 
 mkdirSync(outDir, { recursive: true });
+const { groups, skipped: emptyGroups } = buildGroups(entries);
+for (const name of emptyGroups) console.error(`  no real fix, skip group: ${name}`);
 const written = [];
-for (const [key, g] of groups) {
-  g.points.sort((a, b) => (a.time ?? 0) - (b.time ?? 0));
-  // metadata start time = earliest real (non 0,0) fix, avoiding pre-lock placeholder times
-  const realTimes = g.points
-    .filter((p) => !(p.lat === 0 && p.lon === 0) && p.time != null)
-    .map((p) => p.time);
-  const startMs = realTimes.length ? Math.min(...realTimes) : null;
+for (const g of groups) {
   const track = {
-    segments: [g.points],
+    segments: g.segments,
     meta: {
-      name: key,
-      time: startMs != null ? new Date(startMs).toISOString() : null,
+      name: g.name,
+      time: g.startMs != null ? new Date(g.startMs).toISOString() : null,
       type: null,
     },
   };
-  const path = join(outDir, `${key}.gpx`);
+  const path = join(outDir, `${g.name}.gpx`);
   saveGpx(track, path, { creator: "gpx-from-gopro" });
-  written.push(`${key}.gpx (${g.points.length} pts)`);
+  const npts = g.segments.reduce((s, seg) => s + seg.length, 0);
+  written.push(`${g.name}.gpx (${npts} pts, ${g.segments.length} seg)`);
 }
 
 console.log(`\ndone. processed=${ok} skipped=${skipped} failed=${failed}`);

package/src/gopro.js

@@ -1,8 +1,11 @@
 // Extract a GoPro video's GPS track as package TrackPoints
-// ({ lat, lon, ele, time, speed }). Uses gpmf-extract to pull the GPMF 'gpmd'
-// track and gopro-telemetry to interpret it. The MP4 is streamed to mp4box in
-// blocks so multi-GB files never load whole into RAM. No filtering: every GPS
-// sample is kept (including pre-lock 0,0 points), matching the exiftool path.
+// ({ lat, lon, ele, time, speed, fix, hdop, cts }). Uses gpmf-extract to pull the
+// GPMF 'gpmd' track and gopro-telemetry to interpret it. The MP4 is streamed to
+// mp4box in blocks so multi-GB files never load whole into RAM. No filtering:
+// every GPS sample is kept (including pre-lock 0,0 points), matching the exiftool
+// path. `cts` is the sample's media offset (ms from stream start) — the x-axis a
+// consumer regresses UTC against to recover the true recording start (see
+// telemetry.js regressStartUtc).
 import { open } from "node:fs/promises";
 import goproTelemetry from "gopro-telemetry";
 import gpmfExtract from "gpmf-extract";
@@ -39,6 +42,67 @@ function fileFeeder(path) {
   };
 }
 
+// GoPro firmware prefix → camera model. HD5 / H21 verified against real files; the rest follow
+// GoPro's documented firmware scheme (HD6–HD9 = HERO6–9, H22–H24 = HERO11–13).
+const GOPRO_MODEL = {
+  HD5: "HERO5",
+  HD6: "HERO6",
+  HD7: "HERO7",
+  HD8: "HERO8",
+  HD9: "HERO9",
+  H21: "HERO10",
+  H22: "HERO11",
+  H23: "HERO12",
+  H24: "HERO13",
+};
+
+/**
+ * Camera model from a GoPro `FIRM` firmware string (e.g. "HD5.02.02.60.00" → "HERO5").
+ * @param {string | null} firmware
+ * @returns {string | null}  null for missing/unknown firmware
+ */
+export function goproModel(firmware) {
+  return firmware ? (GOPRO_MODEL[firmware.slice(0, 3)] ?? null) : null;
+}
+
+/**
+ * Read a GoPro `udta` atom's string from a moov-region buffer. GoPro stores camera info as
+ * custom atoms `[4-byte BE size][4CC][ASCII data]` inside `udta` (FIRM=firmware, CAME=serial,
+ * LENS, …) — non-standard boxes mp4box doesn't decode, so read them straight from the bytes.
+ * @param {Buffer} buf     bytes covering the moov (including udta)
+ * @param {string} fourcc  e.g. "FIRM"
+ * @returns {string | null}
+ */
+export function readUdtaRaw(buf, fourcc) {
+  const i = buf.indexOf(fourcc, 0, "latin1");
+  if (i < 4) return null;
+  const size = buf.readUInt32BE(i - 4); // the 4 bytes before the 4CC are the atom's byte size
+  if (size < 8 || i - 4 + size > buf.length) return null;
+  return buf.subarray(i + 4, i - 4 + size);
+}
+
+/**
+ * A GoPro `udta` atom read as a trimmed ASCII string (`FIRM`, `LENS`, …), or null.
+ * @param {Buffer} buf
+ * @param {string} fourcc
+ * @returns {string | null}
+ */
+export function readUdtaAtom(buf, fourcc) {
+  const d = readUdtaRaw(buf, fourcc);
+  return d ? d.toString("latin1").replace(/\0+$/, "").trim() || null : null;
+}
+
+// Parse the `HMMT` atom (GoPro highlight tags = the times the user pressed the tag button): a u32
+// count, then that many u32 millisecond offsets. [TBC] format inferred from a count=0 sample; not
+// verified against a clip with real highlights.
+function parseHighlights(buf) {
+  if (!buf || buf.length < 4) return [];
+  const n = buf.readUInt32BE(0);
+  const out = [];
+  for (let k = 0; k < n && 8 + k * 4 <= buf.length; k++) out.push(buf.readUInt32BE(4 + k * 4));
+  return out;
+}
+
 /**
  * @typedef {object} GoproMeta
  * @property {boolean} hasGps      whether a GPMF 'gpmd' track with samples is present
@@ -48,6 +112,11 @@ function fileFeeder(path) {
  * @property {string | null} codec  video codec (e.g. "avc1.64002a")
  * @property {number | null} fps    video frame rate
  * @property {number | null} durationS video duration in seconds
+ * @property {string | null} firmware  GoPro firmware string (e.g. "HD5.02.02.60.00"), or null
+ * @property {string | null} model     camera model from the firmware (e.g. "HERO5"), or null
+ * @property {string | null} serial    camera serial (udta `CAME`, hex) — tells two same-model bodies apart
+ * @property {string | null} mediaId   global media id (udta `GUMI`, hex) — links a recording's chapter files
+ * @property {number[]} highlights     user highlight-tag offsets in ms (udta `HMMT`); [] if none
  */
 
 /**
@@ -73,10 +142,12 @@ export async function probeGoproMeta(path) {
       error = e;
     };
     const buf = Buffer.allocUnsafe(PROBE_CHUNK);
+    const moovChunks = []; // keep the moov-region bytes mp4box reads, to find GoPro's udta/FIRM
     let pos = 0;
     while (pos < size && info === null && error === null) {
       const { bytesRead } = await fh.read(buf, 0, PROBE_CHUNK, pos);
       if (bytesRead === 0) break;
+      moovChunks.push(Buffer.from(buf.subarray(0, bytesRead))); // copy: buf is reused next loop
       const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + bytesRead);
       ab.fileStart = pos; // absolute offset; mp4box uses it to place the block
       const next = file.appendBuffer(ab);
@@ -88,6 +159,12 @@ export async function probeGoproMeta(path) {
     const gpmd = tracks.find((t) => t.codec === "gpmd");
     const video = tracks.find((t) => t.type === "video") ?? tracks.find((t) => t.video);
     const durationS = info?.duration && info?.timescale ? info.duration / info.timescale : null;
+    // GoPro stows camera meta in moov's udta as custom atoms — read them from the moov bytes above
+    // (already in hand, ~0 extra IO): FIRM=firmware, CAME=serial, GUMI=media id, HMMT=highlight tags.
+    const moov = Buffer.concat(moovChunks);
+    const firmware = readUdtaAtom(moov, "FIRM");
+    const came = readUdtaRaw(moov, "CAME");
+    const gumi = readUdtaRaw(moov, "GUMI");
     return {
       hasGps: gpmd != null && gpmd.nb_samples > 0,
       gpmdSamples: gpmd?.nb_samples ?? 0,
@@ -96,6 +173,11 @@ export async function probeGoproMeta(path) {
       codec: video?.codec ?? null,
       fps: video && durationS ? video.nb_samples / durationS : null,
       durationS,
+      firmware,
+      model: goproModel(firmware),
+      serial: came ? came.toString("hex") : null,
+      mediaId: gumi ? gumi.toString("hex") : null,
+      highlights: parseHighlights(readUdtaRaw(moov, "HMMT")),
     };
   } finally {
     await fh.close();
@@ -112,14 +194,78 @@ export async function probeGoproMeta(path) {
  */
 export async function extractGoproPoints(path, opts = {}) {
   const groupTimes = opts.rate ? Math.round(1000 / opts.rate) : opts.groupTimes;
+  const cfg = { stream: ["GPS"], ...(groupTimes ? { groupTimes } : {}) }; // auto GPS5/GPS9
+  const extracted = await gpmfExtract(fileFeeder(path));
+  // Two interpretations of the SAME extraction. timeOut:'date' yields the GPS UTC
+  // per sample but strips cts; timeIn:'MP4'/timeOut:'cts' yields the media offset
+  // (ms within the video, cts 0 = first frame) but no date. We need both — UTC for
+  // `time`, media cts as the x-axis the start regression extrapolates to 0.
+  const telemetry = await goproTelemetry(extracted, { ...cfg, timeIn: "GPS", timeOut: "date" });
+  const mediaTel = await goproTelemetry(extracted, { ...cfg, timeIn: "MP4", timeOut: "cts" });
+  return buildGpsPoints(telemetry, mediaTel);
+}
+
+/**
+ * @typedef {object} GoproStream
+ * @property {string | null} name   stream description (e.g. "Accelerometer")
+ * @property {any} units            stream units, as gopro-telemetry reports them
+ * @property {{ cts: number | null, value: any }[]} samples  media-cts-timed samples
+ */
+
+/**
+ * Extract a GoPro MP4's FULL telemetry: GPS `points` plus every NON-GPS stream
+ * (IMU `ACCL`/`GYRO`, `GRAV`/`CORI`, `SCEN`, exposure `SHUT`/ISO, …) as raw
+ * cts-timed samples, for multi-sensor analysis. One `gpmf-extract` (the IO, done
+ * once) then three cheap parse passes — reading more streams costs ~0 extra IO
+ * (all streams share the one gpmd track; the filter is post-parse). `rate` /
+ * `groupTimes` downsamples only the GPS `points`; **aux streams stay native**
+ * (the IMU's ~200 Hz is the whole point).
+ * @param {string} path
+ * @param {{ rate?: number, groupTimes?: number }} [opts]
+ * @returns {Promise<{ points: import("gpx-stabilizer").TrackPoint[], streams: Record<string, GoproStream> }>}
+ */
+export async function extractGoproAll(path, opts = {}) {
+  const groupTimes = opts.rate ? Math.round(1000 / opts.rate) : opts.groupTimes;
+  const cfg = { stream: ["GPS"], ...(groupTimes ? { groupTimes } : {}) };
   const extracted = await gpmfExtract(fileFeeder(path));
-  const telemetry = await goproTelemetry(extracted, {
-    stream: ["GPS"], // auto-selects GPS5 (Hero5-10) or GPS9 (Hero11+)
-    timeIn: "GPS", // derive sample time from GPS UTC, not the camera clock
-    timeOut: "date", // we only need the per-sample date
-    ...(groupTimes ? { groupTimes } : {}),
-  });
+  const telemetry = await goproTelemetry(extracted, { ...cfg, timeIn: "GPS", timeOut: "date" });
+  const mediaTel = await goproTelemetry(extracted, { ...cfg, timeIn: "MP4", timeOut: "cts" });
+  // every stream (no filter), on the media-cts clock, at native rate — the aux channels
+  const allTel = await goproTelemetry(extracted, { timeIn: "MP4", timeOut: "cts" });
+  return { points: buildGpsPoints(telemetry, mediaTel), streams: buildAuxStreams(allTel) };
+}
 
+// Collapse every NON-GPS stream of a parsed telemetry object into raw cts-timed
+// samples (GPS is excluded — it's the `points` channel, processed separately).
+function buildAuxStreams(tel) {
+  const out = {};
+  for (const device of Object.values(tel ?? {})) {
+    for (const [key, stream] of Object.entries(device?.streams ?? {})) {
+      if (key.startsWith("GPS")) continue;
+      out[key] = {
+        name: stream.name ?? null,
+        units: stream.units ?? null,
+        samples: (stream.samples ?? []).map((s) => ({
+          cts: typeof s.cts === "number" ? s.cts : null,
+          value: s.value,
+        })),
+      };
+    }
+  }
+  return out;
+}
+
+// Build GPS TrackPoints by zipping the two GPS passes: `telemetry` (timeOut:'date'
+// → UTC `time`) with `mediaTel` (timeOut:'cts' → media `cts`) by sample index (same
+// stream + groupTimes ⇒ same order/count; a length guard drops cts if that fails).
+function buildGpsPoints(telemetry, mediaTel) {
+  const mediaCts = [];
+  for (const device of Object.values(mediaTel ?? {})) {
+    for (const [key, stream] of Object.entries(device?.streams ?? {})) {
+      if (!key.startsWith("GPS")) continue;
+      for (const s of stream.samples ?? []) mediaCts.push(typeof s.cts === "number" ? s.cts : null);
+    }
+  }
   const points = [];
   for (const device of Object.values(telemetry ?? {})) {
     const streams = device?.streams ?? {};
@@ -157,9 +303,14 @@ export async function extractGoproPoints(path, opts = {}) {
           speed: speed == null ? null : speed,
           fix,
           hdop,
+          cts: null, // filled by the media-cts zip below
         });
       }
     }
   }
+  // zip media cts onto the points by index; only when the two passes agree in count
+  if (mediaCts.length === points.length) {
+    for (let i = 0; i < points.length; i++) points[i].cts = mediaCts[i];
+  }
   return points;
 }

package/src/group.js

@@ -0,0 +1,152 @@
+// Grouping policy for gpx-from-gopro: decide which extracted files merge into one
+// GPX and how their points split into <trkseg>s. Kept pure (no IO) so it is unit
+// testable; the CLI does the extraction/timezone/skip work and hands entries here.
+import { basename } from "node:path";
+
+const PLACEHOLDER = (p) => p.lat === 0 && p.lon === 0; // null-island pre-lock fix
+
+// A single continuous recording's kept points are contiguous (chapter rollover is ~1 s); only a
+// real break — a stop/restart a shared file-number missed, or a GPS-fix dropout that left no
+// surviving points — exceeds this. Split there into a new <trkseg>. See buildGroups (signal A).
+const BIG_GAP_MS = 120_000;
+
+/**
+ * Camera "family" from a GoPro filename: the coarse identity used when a file has
+ * no body serial. A session's first file (GOPR####) and its continuation chapters
+ * (GP01####, GP02####…) share the "GOPR" family; GX/GH are the newer scheme.
+ * @param {string} file
+ * @returns {string}
+ */
+export function family(file) {
+  const b = basename(file).toUpperCase();
+  if (/^GOPR\d+\./.test(b)) return "GOPR";
+  if (/^GP\d\d\d+\./.test(b)) return "GOPR";
+  if (/^GX\d\d\d+\./.test(b)) return "GX";
+  if (/^GH\d\d\d+\./.test(b)) return "GH";
+  const m = b.match(/^([A-Z]+)/);
+  return m ? m[1] : "MISC";
+}
+
+/**
+ * GoPro recording "file-number": the 4-digit id a recording's chapters share, so it keys a
+ * recording session. `GOPR5134` / `GP015134` → "5134"; `GX015131` / `GX115131` → "5131" (the
+ * leading 2 digits are the chapter index). A new recording — or a crash restart — gets a fresh
+ * number. Null when the name has no 4-digit tail (an unknown scheme falls back to a time split).
+ * @param {string} file
+ * @returns {string | null}
+ */
+export function fileNumber(file) {
+  const m = basename(file).match(/(\d{4})\.[^.]+$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * @typedef {object} GroupEntry one extracted file's grouping inputs
+ * @property {string} family    filename family (see {@link family})
+ * @property {string} date      local date YYYYMMDD
+ * @property {string | null} serial    body serial (udta CAME), or null
+ * @property {string | null} session   recording id = filename file-number (a recording's
+ *   chapters share it; a new recording / crash restart gets a new one), or null
+ * @property {import("gpx-stabilizer").TrackPoint[]} points
+ */
+
+/**
+ * @typedef {object} GpxGroup one output GPX
+ * @property {string} name      file stem (no extension)
+ * @property {import("gpx-stabilizer").TrackPoint[][]} segments  one per <trkseg>
+ * @property {number | null} startMs  earliest real fix (epoch ms), for meta.time
+ */
+
+/**
+ * Group extracted files into output GPX tracks.
+ *
+ * - **Merge key = (camera, day).** Camera is the body `serial` (udta CAME) when
+ *   known — so two same-model bodies shot the same day stay separate — and the
+ *   filename `family` otherwise. `date` keeps each group to a single day, so a
+ *   session GoPro split across a crash (several files, same serial+date) is
+ *   rejoined into the day's file.
+ * - **Segments = recording sessions**, split by two composed signals:
+ *   - **(B) file-number** — the primary key: a recording's chapters share it, so they merge;
+ *     a new recording or a crash restart gets a new number, so it splits. (Replaces the old
+ *     udta-GUMI key, which is per-chapter on some bodies (Hero10) and over-splits — see
+ *     TODO.md.) `session` is null when the filename has no parseable number.
+ *   - **(A) time gap** — a refinement applied *within* each file-number: a jump > BIG_GAP_MS
+ *     between kept points starts a new segment (a same-number restart, or a dropout hole). It
+ *     only ever sub-splits, never merges across file-numbers; for files with no number it is the
+ *     sole clusterer (they share one fallback bucket that A then cleaves by time).
+ *   A crash still lands in the one daily file (merge key is serial+date) as a separate segment.
+ * - Placeholder (0,0) pre-lock fixes are dropped per segment; a session that never
+ *   locks drops to empty, and a group with no real fix lands in `skipped`.
+ *
+ * @param {GroupEntry[]} entries
+ * @returns {{ groups: GpxGroup[], skipped: string[] }}
+ */
+export function buildGroups(entries) {
+  // gkey -> { date, family, serial, sessions: Map<fileNumber, points[]> }
+  const groups = new Map();
+  for (const e of entries) {
+    const gkey = e.serial ? `${e.date}|s:${e.serial}` : `${e.date}|f:${e.family}`;
+    if (!groups.has(gkey)) {
+      groups.set(gkey, {
+        date: e.date,
+        family: e.family,
+        serial: e.serial ?? null,
+        sessions: new Map(),
+      });
+    }
+    const sessions = groups.get(gkey).sessions;
+    // (B) bucket by file-number; files with none share one fallback bucket that (A) below splits.
+    const skey = e.session ?? "__nofilenum__";
+    if (!sessions.has(skey)) sessions.set(skey, []);
+    // loop-push, not push(...points): a file can carry tens of thousands of points
+    // and spreading that many args overflows the call stack.
+    const bucket = sessions.get(skey);
+    for (const p of e.points) bucket.push(p);
+  }
+
+  // Name a group <date>-<family>; only when two cameras collide on the same
+  // family+date do we disambiguate with a short serial suffix, so the common
+  // single-camera case keeps the readable name.
+  const clash = new Map(); // "date-family" -> distinct group count
+  for (const g of groups.values()) {
+    const base = `${g.date}-${g.family}`;
+    clash.set(base, (clash.get(base) ?? 0) + 1);
+  }
+
+  const out = [];
+  const skipped = [];
+  for (const g of groups.values()) {
+    const base = `${g.date}-${g.family}`;
+    const name = clash.get(base) > 1 && g.serial ? `${base}-${g.serial.slice(0, 8)}` : base;
+    const segments = [];
+    for (const pts of g.sessions.values()) {
+      const clean = pts.filter((p) => !PLACEHOLDER(p));
+      if (clean.length === 0) continue;
+      clean.sort((a, b) => (a.time ?? 0) - (b.time ?? 0));
+      // (A) sub-split this session wherever consecutive kept points jump more than BIG_GAP_MS.
+      let run = [clean[0]];
+      for (let i = 1; i < clean.length; i++) {
+        if ((clean[i].time ?? 0) - (clean[i - 1].time ?? 0) > BIG_GAP_MS) {
+          segments.push(run);
+          run = [];
+        }
+        run.push(clean[i]);
+      }
+      segments.push(run);
+    }
+    if (segments.length === 0) {
+      skipped.push(name);
+      continue;
+    }
+    // order segments by start time so the day's trksegs read chronologically
+    segments.sort((A, B) => (A[0].time ?? 0) - (B[0].time ?? 0));
+    let startMs = null;
+    for (const seg of segments) {
+      for (const p of seg) {
+        if (p.time != null && (startMs === null || p.time < startMs)) startMs = p.time;
+      }
+    }
+    out.push({ name, segments, startMs });
+  }
+  return { groups: out, skipped };
+}

package/src/index.js

@@ -3,10 +3,13 @@
 // gpx-stabilizer package so the contract's "section A" surface stays reachable
 // from this single entry.
 export { stabilize } from "gpx-stabilizer";
-export { extractGoproPoints, probeGoproMeta } from "./gopro.js";
+export { extractGoproAll, extractGoproPoints, probeGoproMeta } from "./gopro.js";
 export {
+  readGoproSamples,
   readGoproTelemetry,
   recordingStartUtc,
+  regressStartUtc,
+  resolveStartUtc,
   timezoneAt,
   timezoneOfPoints,
 } from "./telemetry.js";

package/src/telemetry.js

@@ -3,9 +3,11 @@
 // concepts leak here; the consumer maps this to its own model. See
 // docs/export-contract.md.
 
-import { stabilize } from "gpx-stabilizer";
+import { statSync } from "node:fs";
+import { resample, stabilize } from "gpx-stabilizer";
 import tzlookup from "tz-lookup";
-import { extractGoproPoints, probeGoproMeta } from "./gopro.js";
+import { extractGoproAll, probeGoproMeta } from "./gopro.js";
+import { CACHE_V, readCache, resolveCachePath, writeCache } from "./gopro-cache.js";
 
 function isFiniteNum(n) {
   return typeof n === "number" && Number.isFinite(n);
@@ -61,35 +63,206 @@ export function recordingStartUtc(points) {
   return { startUtc: isFiniteNum(p.time) ? p.time : null, fix: p.fix };
 }
 
+// Gates for trusting the regression extrapolation.
+const MIN_REG_POINTS = 5; // too few points → slope is noise
+const MIN_REG_SPAN_MS = 5000; // <5 s of media offset → extrapolating to 0 is unreliable
+const SLOPE_TOL = 0.05; // |slope−1| must be within this (UTC ms vs media ms ⇒ ≈1)
+
+/**
+ * True recording-start instant (UTC) by **linear regression** of each good-fix
+ * sample's UTC `time` against its media offset `cts`: `time ≈ intercept +
+ * slope·cts`. The recording starts at `cts = 0`, so the intercept is the
+ * wall-clock instant of the first video frame — *before* GPS lock, recovering the
+ * pre-lock delay that the first-good-fix anchor ignores. `slope` should be ≈ 1
+ * (both axes are milliseconds); a slope far from 1 means the GPS UTC and media
+ * clocks disagree, so the extrapolation is not trustworthy.
+ *
+ * @param {import("gpx-stabilizer").TrackPoint[]} points  raw points (need `cts` + `time` + `fix`)
+ * @returns {{ startUtc: number, slope: number, n: number } | null}  null when too
+ *   few points, too short a media span, or `cts` is unavailable
+ */
+export function regressStartUtc(points) {
+  const pts = (points ?? []).filter(
+    (p) => p && (p.fix === "3d" || p.fix === "2d") && isFiniteNum(p.time) && isFiniteNum(p.cts),
+  );
+  const n = pts.length;
+  if (n < MIN_REG_POINTS) return null;
+  // Centre x (cts) and y (time) before the least-squares sums: UTC ms (~1.7e12)
+  // and cts ms make the raw normal equations lose precision to catastrophic
+  // cancellation; centring keeps the magnitudes small and the slope/intercept
+  // accurate.
+  let sx = 0;
+  let sy = 0;
+  let minC = Number.POSITIVE_INFINITY;
+  let maxC = Number.NEGATIVE_INFINITY;
+  for (const p of pts) {
+    sx += p.cts;
+    sy += p.time;
+    if (p.cts < minC) minC = p.cts;
+    if (p.cts > maxC) maxC = p.cts;
+  }
+  if (maxC - minC < MIN_REG_SPAN_MS) return null;
+  const mx = sx / n;
+  const my = sy / n;
+  let sxx = 0;
+  let sxy = 0;
+  for (const p of pts) {
+    const dx = p.cts - mx;
+    sxx += dx * dx;
+    sxy += dx * (p.time - my);
+  }
+  if (sxx === 0) return null;
+  const slope = sxy / sxx;
+  const intercept = my - slope * mx; // UTC at cts = 0
+  return { startUtc: Math.round(intercept), slope, n };
+}
+
+/**
+ * Best recording-start anchor + how much to trust it. Prefers the regression
+ * true-start when its slope passes the quality gate; otherwise falls back to the
+ * first good fix (the pre-lock delay is then unknown and left in).
+ * @param {import("gpx-stabilizer").TrackPoint[]} points  raw points
+ * @returns {{ startUtc: number | null, confidence: 'gps' | null, verified: boolean, slope: number | null }}
+ */
+export function resolveStartUtc(points) {
+  const reg = regressStartUtc(points);
+  const verified = reg != null && Math.abs(reg.slope - 1) <= SLOPE_TOL;
+  const startUtc = verified ? reg.startUtc : recordingStartUtc(points).startUtc;
+  return {
+    startUtc,
+    confidence: startUtc != null ? "gps" : null,
+    verified,
+    slope: reg ? reg.slope : null,
+  };
+}
+
 /**
  * @typedef {object} TelemetryResult
  * @property {import("./gopro.js").GoproMeta} meta   geometry / fps / durationS / hasGps
- * @property {import("gpx-stabilizer").TrackPoint[]} points  raw, or stabilized per opts
+ * @property {import("gpx-stabilizer").TrackPoint[]} points  raw, or stabilized per opts;
+ *   with `resample`, the flat concatenation of `segments` (back-compat single array)
+ * @property {import("gpx-stabilizer").TrackPoint[][]} segments  one entry per `<trkseg>`:
+ *   `[points]` normally, but `resample` splits at gaps > maxGap into several (always present)
  * @property {string | null} timezone   = timezoneOfPoints(raw points)
- * @property {number | null} startUtc    = recordingStartUtc(raw points).startUtc
+ * @property {number | null} startUtc    best recording-start anchor: the regression
+ *   true-start when verified, else the first good fix (= clock.startUtc)
+ * @property {{ startUtc: number|null, confidence: 'gps'|null, verified: boolean, slope: number|null }} clock
+ *   the start anchor + trust: `verified` true ⇒ regression-extrapolated true start
+ *   (slope ≈ 1); false ⇒ first-good-fix fallback (pre-lock delay left in)
  */
 
 /**
- * One-call convenience the adapter actually uses: probe + extract [+ stabilize]
- * + timezone + start anchor in a single await. Short-circuits on a video with no
- * GPS track.
+ * Cached probe + extract: a video's GoPro samples plus its metadata, as
+ * `{ meta, points, fromCache }`. The expensive whole-stream extraction (and the
+ * moov probe) are skipped entirely on a cache hit.
+ *
+ * Caching is **ON by default** — a sidecar `<file>.gpxcache.json` is written
+ * next to the source, keyed by file size+mtime+rate+schema-version, so a repeat
+ * read (or a killed run) returns instantly. Pass `cache: false` to disable
+ * (pure, no file writes) or `cache: { dir }` to keep records in a managed
+ * directory instead of beside the media.
+ *
+ * `points` is `[]` for a video with no GPS track (`meta.hasGps === false`). The
+ * record also carries `streams` — every non-GPS GPMF channel (IMU `ACCL`/`GYRO`,
+ * `SCEN`, exposure, …) as raw cts-timed samples (`{}` when no GPS track), so the
+ * one extraction populates the cache for later multi-sensor work at ~0 extra IO.
  * @param {string} path
- * @param {{ rate?: number, stabilize?: boolean | Parameters<typeof stabilize>[1] }} [opts]
- *   rate in Hz (omit = native ~18 Hz); stabilize cleans the points first.
+ * @param {{ rate?: number, cache?: boolean | { dir?: string | null } }} [opts]
+ *   rate in Hz (omit = native ~18 Hz); cache controls the on-disk record (default on).
+ * @returns {Promise<{ meta: import("./gopro.js").GoproMeta, points: import("gpx-stabilizer").TrackPoint[], streams: Record<string, import("./gopro.js").GoproStream>, fromCache: boolean }>}
+ */
+export async function readGoproSamples(path, opts = {}) {
+  const { rate, cache } = opts;
+  const groupTimes = rate ? Math.round(1000 / rate) : undefined;
+  const cp = resolveCachePath(path, cache);
+  const ident = { v: CACHE_V, size: 0, mtime: 0, rate: groupTimes ?? null };
+  if (cp) {
+    try {
+      const st = statSync(path);
+      ident.size = st.size;
+      ident.mtime = Math.round(st.mtimeMs);
+    } catch {
+      // unstattable -> leave size/mtime 0 (guaranteed miss); probe surfaces the error
+    }
+    const hit = readCache(cp, ident);
+    if (hit) {
+      return {
+        meta: hit.meta,
+        points: hit.points ?? [],
+        streams: hit.streams ?? {},
+        fromCache: true,
+      };
+    }
+  }
+  const meta = await probeGoproMeta(path);
+  const { points, streams } = meta.hasGps
+    ? await extractGoproAll(path, groupTimes ? { groupTimes } : {})
+    : { points: [], streams: {} };
+  if (cp) {
+    const dir = cache && typeof cache === "object" ? (cache.dir ?? null) : null;
+    writeCache(cp, { ...ident, meta, points, streams }, dir);
+  }
+  return { meta, points, streams, fromCache: false };
+}
+
+/**
+ * One-call convenience the adapter actually uses: (cached) probe + extract
+ * [+ stabilize] + timezone + start anchor in a single await. Short-circuits on
+ * a video with no GPS track.
+ * @param {string} path
+ * @param {{ rate?: number, stabilize?: boolean | Parameters<typeof stabilize>[1],
+ *   resample?: boolean | "fps" | { RESAMPLE_HZ?: number | "fps", maxGap?: number },
+ *   cache?: boolean | { dir?: string | null } }} [opts]
+ *   `rate` in Hz (omit = native ~18 Hz); `stabilize` cleans the points first; `resample`
+ *   regularises the cleaned points onto a uniform time grid (see {@link resample}) — it
+ *   **implies** `stabilize` (resampling raw, uncleaned points is meaningless), and
+ *   `RESAMPLE_HZ: "fps"` (or `resample: "fps"`) uses the video frame rate (`meta.fps`) so
+ *   there is one point per frame; `cache` controls the on-disk extraction record.
  * @returns {Promise<TelemetryResult>}
  */
 export async function readGoproTelemetry(path, opts = {}) {
-  const meta = await probeGoproMeta(path);
+  const { meta, points: raw } = await readGoproSamples(path, {
+    rate: opts.rate,
+    cache: opts.cache,
+  });
   if (!meta.hasGps) {
-    return { meta, points: [], timezone: null, startUtc: null };
+    return {
+      meta,
+      points: [],
+      segments: [],
+      timezone: null,
+      startUtc: null,
+      clock: { startUtc: null, confidence: null, verified: false, slope: null },
+    };
   }
-  const raw = await extractGoproPoints(path, opts.rate != null ? { rate: opts.rate } : {});
   // tz + anchor are derived from the RAW points: stabilize() reduces a point to
-  // {lat,lon,ele,time}, dropping the `fix` that good-fix selection relies on.
+  // {lat,lon,ele,time}, dropping the `fix` + `cts` that good-fix selection and the
+  // start regression rely on.
   const timezone = timezoneOfPoints(raw);
-  const { startUtc } = recordingStartUtc(raw);
-  const points = opts.stabilize
-    ? stabilize(raw, opts.stabilize === true ? {} : opts.stabilize)
-    : raw;
-  return { meta, points, timezone, startUtc };
+  const clock = resolveStartUtc(raw);
+
+  // resample runs on cleaned survivors, so it IMPLIES stabilize; an explicit
+  // `stabilize: false` alongside `resample` is contradictory.
+  if (opts.resample && opts.stabilize === false) {
+    throw new Error("readGoproTelemetry: `resample` requires cleaning — drop `stabilize: false`");
+  }
+  const cleaned =
+    opts.stabilize || opts.resample
+      ? stabilize(raw, opts.stabilize && opts.stabilize !== true ? opts.stabilize : {})
+      : raw;
+
+  let points = cleaned;
+  let segments = cleaned.length ? [cleaned] : [];
+  if (opts.resample) {
+    const ro = typeof opts.resample === "object" ? { ...opts.resample } : {};
+    // "fps" (shorthand `resample: "fps"` or `RESAMPLE_HZ: "fps"`) → one point per video frame
+    if (opts.resample === "fps" || ro.RESAMPLE_HZ === "fps") {
+      if (!meta.fps)
+        throw new Error("readGoproTelemetry: resample 'fps' but meta.fps is unavailable");
+      ro.RESAMPLE_HZ = meta.fps;
+    }
+    segments = resample(cleaned, ro);
+    points = segments.flat();
+  }
+  return { meta, points, segments, timezone, startUtc: clock.startUtc, clock };
 }