gpx-from-gopro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zordius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# gpx-from-gopro
+
+Extract a GoPro video's GPS telemetry (GPMF `gpmd` track) as merged GPX, or as a render-agnostic
+telemetry bundle (points + video metadata + recording UTC anchor + timezone). Node ESM. The MP4 is
+streamed through mp4box so multi-GB files never load whole into RAM.
+
+Part of the [gpx-stabilizer monorepo](https://github.com/zordius/gpx-stabilizer); builds on the
+core [`gpx-stabilizer`](https://www.npmjs.com/package/gpx-stabilizer) package for GPX writing and
+point stabilization.
+
+## Install
+
+```sh
+npm install gpx-from-gopro
+```
+
+## CLI
+
+```sh
+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`
+overrides the longitude-guessed local date.
+
+## Library — telemetry export
+
+A render-agnostic API (telemetry samples + video metadata + recording UTC anchor + timezone) for a
+renderer to consume. Full contract:
+[`docs/export-contract.md`](https://github.com/zordius/gpx-stabilizer/blob/main/docs/export-contract.md).
+
+```js
+import { readGoproTelemetry } from "gpx-from-gopro";
+
+// one call: probe + extract [+ stabilize] + timezone + start anchor
+const { meta, points, timezone, startUtc } = await readGoproTelemetry("clip.mp4", {
+  rate: 1,            // Hz; omit for native ~18 Hz
+  stabilize: true,    // clean the points first (boolean | StabilizeOptions)
+});
+```
+
+Short-circuits to empty `points` / null `timezone` / null `startUtc` on a video with no GPS track.
+
+Also exported:
+
+- `probeGoproMeta(path)` — cheap moov-only probe (geometry / fps / duration / `hasGps` gate).
+- `extractGoproPoints(path, { rate? })` — raw `TrackPoint[]` (native ~18 Hz; `rate` in Hz to downsample).
+- `timezoneAt({ lat, lon })` / `timezoneOfPoints(points)` — offline IANA timezone lookup.
+- `recordingStartUtc(points)` — `{ startUtc, fix }` from the first good-fix sample.
+- `stabilize` — re-exported from the core package for convenience.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "gpx-from-gopro",
+  "version": "0.1.0",
+  "description": "Extract a GoPro video's GPS telemetry as GPX or render-agnostic TrackPoints (points + meta + timezone + UTC anchor).",
+  "keywords": [
+    "gopro",
+    "gpx",
+    "gps",
+    "telemetry",
+    "gpmf",
+    "mp4"
+  ],
+  "author": "zordius",
+  "type": "module",
+  "bin": {
+    "gpx-from-gopro": "src/gopro-cli.js"
+  },
+  "exports": "./src/index.js",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zordius/gpx-stabilizer.git",
+    "directory": "packages/gopro"
+  },
+  "dependencies": {
+    "gpx-stabilizer": "^0.1.0",
+    "gopro-telemetry": "^1.2.11",
+    "gpmf-extract": "^0.3.3",
+    "mp4box": "^0.5.4",
+    "tz-lookup": "^6.1.25"
+  }
+}

package/src/gopro-cache.js

@@ -0,0 +1,65 @@
+// Per-file extraction cache so a killed gpx-from-gopro run resumes cheaply.
+// A record is keyed by the source's identity (v + size + mtime + rate); a rerun
+// reuses it only when all four match, and writes are atomic (temp then rename)
+// so a crash never leaves a half-written record a later run would trust.
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+
+/**
+ * Cache-record path for a source file: sidecar `<file>.gpxcache.json` by
+ * default, or a hashed name inside `cacheDir` (keeps the media tree clean).
+ * @param {string} file
+ * @param {string | null} [cacheDir]
+ * @returns {string}
+ */
+export function cachePath(file, cacheDir = null) {
+  if (cacheDir) {
+    const h = createHash("sha1").update(resolve(file)).digest("hex").slice(0, 16);
+    return join(cacheDir, `${basename(file)}.${h}.json`);
+  }
+  return `${file}.gpxcache.json`;
+}
+
+/**
+ * Read a cache record, returning it only when it matches `ident`
+ * (v + size + mtime + rate); missing/unreadable/stale all return null.
+ * @param {string} path
+ * @param {{ v: number, size: number, mtime: number, rate: number | null }} ident
+ * @returns {object | null}
+ */
+export function readCache(path, ident) {
+  let rec;
+  try {
+    rec = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null; // missing or unreadable -> miss
+  }
+  const fresh =
+    rec.v === ident.v &&
+    rec.size === ident.size &&
+    rec.mtime === ident.mtime &&
+    rec.rate === ident.rate;
+  return fresh ? rec : null;
+}
+
+/**
+ * Atomically write a cache record (temp file then rename), creating `cacheDir`
+ * if given. Best-effort: returns false instead of throwing on failure, since a
+ * cache is only an optimization.
+ * @param {string} path
+ * @param {object} record
+ * @param {string | null} [cacheDir]
+ * @returns {boolean} whether the write succeeded
+ */
+export function writeCache(path, record, cacheDir = null) {
+  try {
+    if (cacheDir) mkdirSync(cacheDir, { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(record));
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/gopro-cli.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// gpx-from-gopro — extract GoPro GPS into merged GPX, grouped by camera family + 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.
+// - 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 ".").
+// - 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)
+
+const VIDEO_RE = /\.(mp4|mov|m4v|360)$/i;
+const MEDIAN_N = 30;
+const LOCAL_TZ = -new Date().getTimezoneOffset() / 60; // hours, may be fractional
+
+// ---- args ----
+const argv = process.argv.slice(2);
+const WITH_VALUE = new Set(["out", "tz", "rate", "cache-dir"]);
+const inputs = [];
+const opts = {};
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith("--")) {
+    const name = a.slice(2);
+    if (WITH_VALUE.has(name)) opts[name] = argv[++i];
+    else opts[name] = true;
+  } else inputs.push(a);
+}
+if (inputs.length === 0) {
+  console.error(
+    "usage: gpx-from-gopro <dir|file.mp4> [...] [--out DIR] [--tz HOURS] [--rate HZ] [--cache-dir DIR | --no-cache]",
+  );
+  process.exit(1);
+}
+const outDir = opts.out ?? ".";
+const manualTZ = opts.tz != null ? Number(opts.tz) : null;
+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";
+}
+
+// ---- timezone from median longitude of the first valid fixes ----
+function medianLon(points) {
+  const lons = [];
+  for (const p of points) {
+    if (p.lat === 0 && p.lon === 0) continue;
+    lons.push(p.lon);
+    if (lons.length >= MEDIAN_N) break;
+  }
+  if (lons.length === 0) return null;
+  lons.sort((a, b) => a - b);
+  const mid = Math.floor(lons.length / 2);
+  return lons.length % 2 ? lons[mid] : (lons[mid - 1] + lons[mid]) / 2;
+}
+function decideTZ(lon) {
+  if (manualTZ != null) return manualTZ;
+  if (lon == null || Number.isNaN(lon)) return LOCAL_TZ;
+  const approx = Math.round(lon / 15);
+  return Math.abs(approx - LOCAL_TZ) <= 1 ? LOCAL_TZ : approx;
+}
+// epoch ms + tz offset -> YYYYMMDD local date
+function localDate(ms, tz) {
+  return new Date(ms + tz * 3600e3).toISOString().slice(0, 10).replaceAll("-", "");
+}
+
+// ---- collect video files ----
+function walk(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    console.error(`skip dir ${dir}: ${e.message}`);
+    return out;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith("._")) continue; // macOS AppleDouble sidecar
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p));
+    else if (VIDEO_RE.test(e.name)) out.push(p);
+  }
+  return out;
+}
+function collect(input) {
+  let st;
+  try {
+    st = statSync(input);
+  } catch (e) {
+    console.error(`skip ${input}: ${e.message}`);
+    return [];
+  }
+  if (st.isDirectory()) return walk(input);
+  return VIDEO_RE.test(input) ? [input] : [];
+}
+
+// ---- main ----
+const videos = inputs.flatMap(collect).sort();
+if (videos.length === 0) {
+  console.error("no video files found");
+  process.exit(0);
+}
+console.log(`found ${videos.length} video file(s)`);
+
+const groups = new Map(); // key "YYYYMMDD-FAMILY" -> { points, family, date }
+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 };
+  try {
+    const st = statSync(file);
+    ident.size = st.size;
+    ident.mtime = Math.round(st.mtimeMs);
+  } catch (e) {
+    console.error(`  FAILED stat ${basename(file)}: ${e.message}`);
+    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);
+  }
+
+  const fam = family(file);
+  const fix = points.find((p) => !(p.lat === 0 && p.lon === 0)) ?? points[0];
+  const tz = decideTZ(medianLon(points));
+  const date = fix.time != null ? localDate(fix.time, tz) : null;
+  if (date == null) {
+    console.error(`  bad time, skip: ${basename(file)}`);
+    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)" : ""}`);
+  ok++;
+}
+
+mkdirSync(outDir, { recursive: true });
+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;
+  const track = {
+    segments: [g.points],
+    meta: {
+      name: key,
+      time: startMs != null ? new Date(startMs).toISOString() : null,
+      type: null,
+    },
+  };
+  const path = join(outDir, `${key}.gpx`);
+  saveGpx(track, path, { creator: "gpx-from-gopro" });
+  written.push(`${key}.gpx (${g.points.length} pts)`);
+}
+
+console.log(`\ndone. processed=${ok} skipped=${skipped} failed=${failed}`);
+for (const w of written) console.log(`  -> ${join(outDir, w)}`);

package/src/gopro.js

@@ -0,0 +1,165 @@
+// 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.
+import { open } from "node:fs/promises";
+import goproTelemetry from "gopro-telemetry";
+import gpmfExtract from "gpmf-extract";
+import MP4Box from "mp4box";
+
+const CHUNK = 1 << 24; // 16 MiB read blocks
+const PROBE_CHUNK = 1 << 16; // 64 KiB — enough to reach moov via mp4box's seek hints
+
+// GPSF lock type (0 none / 2 2D / 3 3D) -> GPX <fix> token
+function gpsFix(n) {
+  return n === 3 ? "3d" : n === 2 ? "2d" : n === 0 ? "none" : null;
+}
+
+// gpmf-extract's Node "function" input mode: it hands us the mp4box file object
+// and we feed the bytes ourselves, so we control memory for huge files.
+function fileFeeder(path) {
+  return async (mp4boxFile) => {
+    const fh = await open(path, "r");
+    try {
+      const buf = Buffer.allocUnsafe(CHUNK);
+      let offset = 0;
+      for (;;) {
+        const { bytesRead } = await fh.read(buf, 0, CHUNK, offset);
+        if (bytesRead === 0) break;
+        const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + bytesRead);
+        ab.fileStart = offset; // mp4box needs the absolute offset of each block
+        mp4boxFile.appendBuffer(ab);
+        offset += bytesRead;
+      }
+      mp4boxFile.flush();
+    } finally {
+      await fh.close();
+    }
+  };
+}
+
+/**
+ * @typedef {object} GoproMeta
+ * @property {boolean} hasGps      whether a GPMF 'gpmd' track with samples is present
+ * @property {number} gpmdSamples  number of gpmd payloads (GPS data chunks)
+ * @property {number | null} width  video width in pixels
+ * @property {number | null} height video height in pixels
+ * @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
+ */
+
+/**
+ * Read only the MP4 moov to report the metadata we use, without extracting any
+ * samples. mp4box's appendBuffer returns the next byte offset it needs, which
+ * skips past the (multi-GB) mdat straight to the moov — so this reads on the
+ * order of the moov size (tens of KB to ~1 MB), not the whole file. Use the
+ * returned `hasGps` as a cheap gate before the full (expensive) extraction.
+ * @param {string} path
+ * @returns {Promise<GoproMeta>}
+ */
+export async function probeGoproMeta(path) {
+  const fh = await open(path, "r");
+  try {
+    const { size } = await fh.stat();
+    const file = MP4Box.createFile();
+    let info = null;
+    let error = null;
+    file.onReady = (i) => {
+      info = i;
+    };
+    file.onError = (e) => {
+      error = e;
+    };
+    const buf = Buffer.allocUnsafe(PROBE_CHUNK);
+    let pos = 0;
+    while (pos < size && info === null && error === null) {
+      const { bytesRead } = await fh.read(buf, 0, PROBE_CHUNK, pos);
+      if (bytesRead === 0) break;
+      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);
+      // mp4box tells us where it wants data next — this hops over mdat to the moov
+      pos = typeof next === "number" && next > pos ? next : pos + bytesRead;
+    }
+    if (error !== null) throw new Error(`mp4 parse failed: ${error}`);
+    const tracks = info?.tracks ?? [];
+    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;
+    return {
+      hasGps: gpmd != null && gpmd.nb_samples > 0,
+      gpmdSamples: gpmd?.nb_samples ?? 0,
+      width: video?.video?.width ?? video?.track_width ?? null,
+      height: video?.video?.height ?? video?.track_height ?? null,
+      codec: video?.codec ?? null,
+      fps: video && durationS ? video.nb_samples / durationS : null,
+      durationS,
+    };
+  } finally {
+    await fh.close();
+  }
+}
+
+/**
+ * Extract GPS samples from a GoPro MP4 as package TrackPoints, in capture order.
+ * @param {string} path
+ * @param {{ rate?: number, groupTimes?: number }} [opts] rate in Hz (public knob;
+ *   omit for native ~18 Hz). `groupTimes` (ms) is the internal equivalent kept for
+ *   existing callers; `rate` wins when both are given (groupTimes = 1000 / rate).
+ * @returns {Promise<import("gpx-stabilizer").TrackPoint[]>}
+ */
+export async function extractGoproPoints(path, opts = {}) {
+  const groupTimes = opts.rate ? Math.round(1000 / opts.rate) : opts.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 points = [];
+  for (const device of Object.values(telemetry ?? {})) {
+    const streams = device?.streams ?? {};
+    for (const [key, stream] of Object.entries(streams)) {
+      if (!key.startsWith("GPS")) continue;
+      // GPS5 reports fix/precision once per ~1 Hz payload as sticky values; sticky
+      // semantics are "applies to all successive samples", so carry them forward
+      // onto every (18 Hz) point. precision is DOP x100. GPS9 (Hero11+) instead
+      // carries them per-sample in value[7..8] = [DOP, fix] — read those directly.
+      const isGps9 = key === "GPS9";
+      let fix = null;
+      let hdop = null;
+      for (const s of stream.samples ?? []) {
+        const v = s.value;
+        if (!Array.isArray(v)) continue;
+        // GPS5 and GPS9 share value[0..3] = [lat, lon, altitude, 2D speed]
+        const [lat, lon, ele, speed] = v;
+        const time = s.date != null ? new Date(s.date).getTime() : Number.NaN;
+        if (isGps9) {
+          // value = [lat, lon, alt, 2Dspeed, 3Dspeed, days, secs, DOP, fix]
+          fix = gpsFix(v[8]);
+          // GPS9 DOP is already in DOP units (not x100 like GPS5's sticky.precision).
+          // [TBC] exact scale unverified — no Hero11+ sample on hand to confirm.
+          hdop = typeof v[7] === "number" ? v[7] : null;
+        } else {
+          const sticky = s.sticky ?? {};
+          if (sticky.fix != null) fix = gpsFix(sticky.fix);
+          if (typeof sticky.precision === "number") hdop = sticky.precision / 100;
+        }
+        points.push({
+          lat,
+          lon,
+          ele: ele == null ? null : ele,
+          time: Number.isNaN(time) ? null : time,
+          speed: speed == null ? null : speed,
+          fix,
+          hdop,
+        });
+      }
+    }
+  }
+  return points;
+}

package/src/index.js

@@ -0,0 +1,12 @@
+// Public surface of gpx-from-gopro — the render-agnostic telemetry export
+// contract (docs/export-contract.md). `stabilize` is re-exported from the core
+// 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 {
+  readGoproTelemetry,
+  recordingStartUtc,
+  timezoneAt,
+  timezoneOfPoints,
+} from "./telemetry.js";

package/src/telemetry.js

@@ -0,0 +1,95 @@
+// Render-agnostic telemetry export: turn a GoPro video into the neutral shape a
+// renderer needs — points + meta + timezone + recording UTC anchor. No renderer
+// concepts leak here; the consumer maps this to its own model. See
+// docs/export-contract.md.
+
+import { stabilize } from "gpx-stabilizer";
+import tzlookup from "tz-lookup";
+import { extractGoproPoints, probeGoproMeta } from "./gopro.js";
+
+function isFiniteNum(n) {
+  return typeof n === "number" && Number.isFinite(n);
+}
+
+// First sample with a usable GPS lock: prefer a 3D fix, fall back to 2D, and
+// require finite lat/lon. tz and the start anchor are both constant within one
+// video (cross-timezone travel is out of v1 scope), so the first good fix
+// suffices. Returns the point, or null if none.
+function firstGoodFix(points) {
+  const list = points ?? [];
+  return (
+    list.find((p) => p && p.fix === "3d" && isFiniteNum(p.lat) && isFiniteNum(p.lon)) ??
+    list.find((p) => p && p.fix === "2d" && isFiniteNum(p.lat) && isFiniteNum(p.lon)) ??
+    null
+  );
+}
+
+/**
+ * Raw lat/lon → IANA timezone lookup (offline, via tz-lookup).
+ * @param {{ lat: number, lon: number }} coord
+ * @returns {string | null}  e.g. "Asia/Tokyo"; null on non-finite or out-of-range input
+ */
+export function timezoneAt({ lat, lon } = {}) {
+  if (!isFiniteNum(lat) || !isFiniteNum(lon)) return null;
+  try {
+    return tzlookup(lat, lon);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * IANA timezone for a track, from its first good-fix point.
+ * @param {import("gpx-stabilizer").TrackPoint[]} points
+ * @returns {string | null}  null if no good-fix point exists
+ */
+export function timezoneOfPoints(points) {
+  const p = firstGoodFix(points);
+  return p ? timezoneAt({ lat: p.lat, lon: p.lon }) : null;
+}
+
+/**
+ * Recording start instant (UTC) = the UTC ms of the first good-fix sample, the
+ * wall-clock anchor a renderer pins the segment to. `fix` reports that sample's
+ * fix so the consumer knows the confidence.
+ * @param {import("gpx-stabilizer").TrackPoint[]} points
+ * @returns {{ startUtc: number | null, fix: string | null }}
+ */
+export function recordingStartUtc(points) {
+  const p = firstGoodFix(points);
+  if (!p) return { startUtc: null, fix: null };
+  return { startUtc: isFiniteNum(p.time) ? p.time : null, fix: p.fix };
+}
+
+/**
+ * @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 {string | null} timezone   = timezoneOfPoints(raw points)
+ * @property {number | null} startUtc    = recordingStartUtc(raw points).startUtc
+ */
+
+/**
+ * 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.
+ * @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.
+ * @returns {Promise<TelemetryResult>}
+ */
+export async function readGoproTelemetry(path, opts = {}) {
+  const meta = await probeGoproMeta(path);
+  if (!meta.hasGps) {
+    return { meta, points: [], timezone: null, startUtc: 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.
+  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 };
+}