gpx-from-gopro 0.3.0 → 0.5.0

package/README.md

@@ -20,6 +20,7 @@ No install needed:
 
 ```sh
 npx gpx-from-gopro <dir|file.mp4> [...] [--out DIR] [--tz HOURS] [--rate HZ] [--cache-dir DIR | --no-cache]
+                                  [--organize DIR] [--yes] [--html] [--png [--width N] [--height N]]
 ```
 
 Once installed (`npm install [-g] gpx-from-gopro`), drop the `npx` prefix and just run
@@ -32,6 +33,30 @@ split for restarts/dropouts). A per-file extraction cache (keyed by size+mtime+r
 run resume without re-extracting. `--rate HZ` downsamples from the native ~18 Hz; `--tz HOURS`
 overrides the longitude-guessed local date.
 
+### `--organize DIR` — reorganize the source videos to match the GPX
+
+After every `.gpx` above has been written, moves each source video into
+`<DIR>/<group>/<session>/` — the same `<date>-<family>` group naming as the `.gpx` file, further
+split into one folder per recording session (the filename file-number; `no-session/` when a file
+has none). Each file's extraction cache moves alongside (never deleted — it's free to keep and
+costly to lose); the group's `.gpx` moves in too, *unless* `--out` was explicitly given (then it
+stays where you put it). Never overwrites an existing destination file.
+
+Always previews the full plan first, then asks before touching anything — including whether
+found `.LRV`/`.THM` sidecar files (GoPro's per-chapter low-res preview / thumbnail) should be
+deleted (default) or moved alongside. `--yes` skips both prompts (sidecars default to deleted); a
+non-interactive stdin without `--yes` does nothing rather than hang waiting for input.
+
+### `--html` / `--png` — eval view of each merged group
+
+Additive to the `.gpx` output (never instead of it): renders each group's merged track through
+the same **analyzed** view `gpx-stabilizer`'s own CLI uses (clean track + drop markers, hdop
+overlays), so a group can be eyeballed right after extraction with no separate
+`gpx-stabilizer --html`/`--png` pass on the merged `.gpx`. `--html` writes one
+`<out>/gopro-view.html` (one scrolling panel per group); `--png` writes one
+`<out>/<group>.png` per group (`--width`/`--height`, default 1280×720; needs
+`@resvg/resvg-js` — see [`gpx-stabilizer`](../core)'s `png.js`).
+
 ## Library — telemetry export
 
 A render-agnostic API (telemetry samples + video metadata + recording UTC anchor + timezone) for a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gpx-from-gopro",
-  "version": "0.3.0",
+  "version": "0.5.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,7 @@
     "directory": "packages/gopro"
   },
   "dependencies": {
-    "gpx-stabilizer": "^0.3.0",
+    "gpx-stabilizer": "^0.5.0",
     "egm96-universal": "^1.1.1",
     "gopro-telemetry": "^1.2.11",
     "gpmf-extract": "^0.3.3",

package/src/gopro-cli.js

@@ -1,6 +1,20 @@
 #!/usr/bin/env node
 // 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]
+//                                [--organize DIR] [--yes] [--mode core|ski]
+//                                [--html] [--png [--width N] [--height N]]
+//
+// - --mode core|ski: runs the merged points through gpx-stabilizer's own `stabilizeTrack` (per
+//   recording session — see the `--out` loop below) before writing, instead of shipping today's
+//   default raw extraction. --html/--png (below) render under the SAME mode when both are given,
+//   so the preview always matches what actually got written. Omitting --mode leaves every output
+//   exactly as before (raw, unstabilized) — this is purely additive.
+//
+// - --html / --png: alongside the merged .gpx (never instead of it), also render each group's merged
+//   track through the SAME analyzed view core's own CLI uses (clean track + drop markers) — an eval
+//   aid for eyeballing a group before/after a pipeline change, no separate `gpx-stabilizer` step
+//   needed. --html writes one <out>/gopro-view.html (one panel per group); --png writes one
+//   <out>/<group>.png per group (needs @resvg/resvg-js — see core's png.js).
 //
 // - Recurses directories for video files (mp4/mov/m4v/360); skips .LRV/.THM and ._ AppleDouble.
 // - Groups by (camera, local date): camera = the body serial (udta CAME) when known, so two
@@ -18,10 +32,18 @@
 // - 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";
+// - --organize DIR: AFTER every .gpx has been written, reorganizes the source videos into
+//   <DIR>/<group>/<session>/ (same group/session naming as the .gpx above), moving each file's
+//   cache record alongside and — when --out was NOT explicitly given — the group's .gpx into its
+//   folder too. Always previews the plan and asks before moving anything (--yes skips both
+//   prompts, defaulting .LRV/.THM sidecars to delete); a non-interactive stdin without --yes does
+//   nothing (never blocks waiting for input that will never come). See organize.js.
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { saveGpx } from "gpx-stabilizer";
+import { createInterface } from "node:readline/promises";
+import { analyzedSvg, MODES, saveGpx, savePng, stabilizeTrack, toHtmlAnalyzedFiles } from "gpx-stabilizer";
 import { buildGroups, family, fileNumber } from "./group.js";
+import { cacheMovePlan, executeMove, findSidecars, planMove } from "./organize.js";
 import { readGoproSamples } from "./telemetry.js";
 
 const VIDEO_RE = /\.(mp4|mov|m4v|360)$/i;
@@ -30,7 +52,12 @@ const LOCAL_TZ = -new Date().getTimezoneOffset() / 60; // hours, may be fraction
 
 // ---- args ----
 const argv = process.argv.slice(2);
-const WITH_VALUE = new Set(["out", "tz", "rate", "cache-dir"]);
+const WITH_VALUE = new Set(["out", "tz", "rate", "cache-dir", "organize", "width", "height", "mode"]);
+const KNOWN_BOOL = new Set(["no-cache", "html", "png", "yes"]);
+const USAGE =
+  "usage: gpx-from-gopro <dir|file.mp4> [...] [--out DIR] [--tz HOURS] [--rate HZ]" +
+  " [--cache-dir DIR | --no-cache] [--organize DIR] [--yes] [--mode core|ski]" +
+  " [--html] [--png [--width N] [--height N]]";
 const inputs = [];
 const opts = {};
 for (let i = 0; i < argv.length; i++) {
@@ -38,15 +65,24 @@ for (let i = 0; i < argv.length; i++) {
   if (a.startsWith("--")) {
     const name = a.slice(2);
     if (WITH_VALUE.has(name)) opts[name] = argv[++i];
-    else opts[name] = true;
+    else if (KNOWN_BOOL.has(name)) opts[name] = true;
+    else {
+      // an unrecognized flag must fail loudly -- silently accepting it into `opts` would look like
+      // it took effect while doing nothing.
+      console.error(`gpx-from-gopro: unknown option --${name}\n\n${USAGE}`);
+      process.exit(1);
+    }
   } 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]",
-  );
+  console.error(USAGE);
   process.exit(1);
 }
+if (opts.mode != null && !MODES[opts.mode]) {
+  console.error(`gpx-from-gopro: unknown --mode "${opts.mode}" (use: ${Object.keys(MODES).join(", ")})\n\n${USAGE}`);
+  process.exit(1);
+}
+const outExplicit = opts.out != null; // --organize only sweeps the .gpx along when this is false
 const outDir = opts.out ?? ".";
 const manualTZ = opts.tz != null ? Number(opts.tz) : null;
 if (manualTZ != null && Number.isNaN(manualTZ)) {
@@ -167,7 +203,7 @@ for (const file of videos) {
   }
   // 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 });
+  entries.push({ family: fam, date, serial: meta.serial, session: fileNumber(file), points, file });
   const tag = meta.serial ? `${date}-${fam}#${meta.serial.slice(0, 4)}` : `${date}-${fam}`;
   console.log(`  ${basename(file)}: ${points.length} pts -> ${tag}${fromCache ? " (cached)" : ""}`);
   ok++;
@@ -178,8 +214,18 @@ const { groups, skipped: emptyGroups } = buildGroups(entries);
 for (const name of emptyGroups) console.error(`  no real fix, skip group: ${name}`);
 const written = [];
 for (const g of groups) {
+  // --mode stabilizes each recording session independently (stabilizeTrack analyzes a session's own
+  // <trkseg>s as one continuous stream, same handling core itself gives a multi-segment track) --
+  // sessions themselves stay separate <trk>s, matching buildGroups' own "one <trk> per recording"
+  // design. Omitting --mode ships today's raw extraction unchanged.
+  const tracks = opts.mode
+    ? g.tracks.map((trk) => ({
+        name: trk.name,
+        segments: stabilizeTrack({ segments: trk.segments }, { mode: opts.mode }).segments,
+      }))
+    : g.tracks;
   const track = {
-    segments: g.segments,
+    tracks, // one <trk> per recording session, named after its own original video file
     meta: {
       name: g.name,
       time: g.startMs != null ? new Date(g.startMs).toISOString() : null,
@@ -188,9 +234,117 @@ for (const g of groups) {
   };
   const path = join(outDir, `${g.name}.gpx`);
   saveGpx(track, path, { creator: "gpx-from-gopro" });
-  const npts = g.segments.reduce((s, seg) => s + seg.length, 0);
-  written.push(`${g.name}.gpx (${npts} pts, ${g.segments.length} seg)`);
+  const npts = tracks.reduce((s, t) => s + t.segments.reduce((s2, seg) => s2 + seg.length, 0), 0);
+  const nseg = tracks.reduce((s, t) => s + t.segments.length, 0);
+  written.push(`${g.name}.gpx (${npts} pts, ${tracks.length} trk, ${nseg} seg)`);
 }
 
 console.log(`\ndone. processed=${ok} skipped=${skipped} failed=${failed}`);
 for (const w of written) console.log(`  -> ${join(outDir, w)}`);
+
+// ---- --html / --png: eval visualization of each group's merged track, additive to the .gpx above ----
+// (analyzedLayers/analyzedSvg run core's noise-removal pipeline over the flattened group, under the
+// same --mode as the .gpx above (core's own default when --mode is omitted) — so drop reasons / hdop
+// overlays are visible without a separate `gpx-stabilizer --html` pass on the merged .gpx.)
+if (opts.html || opts.png) {
+  // fed from the RAW groups (not the --mode-stabilized `tracks` written above) -- these views run
+  // their OWN analyze()/stabilize() pass internally, so raw points go in and `analyzeOpts` (below)
+  // carries the SAME --mode through, keeping the preview consistent with the .gpx without double
+  // -stabilizing anything.
+  const tracks = groups.map((g) => ({
+    name: g.name,
+    points: g.tracks.flatMap((t) => t.segments).flat(),
+  }));
+  const analyzeOpts = opts.mode ? { mode: opts.mode } : {};
+  if (opts.html) {
+    const htmlPath = join(outDir, "gopro-view.html");
+    // one toHtmlAnalyzedFiles() call analyzes every group (potentially slow — full analyze() over
+    // each merged day's track) with no other progress signal, so report per-group start/done.
+    const onProgress = ({ name, index, total, phase, ms }) => {
+      if (phase === "start") console.log(`  [${index + 1}/${total}] analyzing ${name}...`);
+      else console.log(`  [${index + 1}/${total}] ${name} done (${(ms / 1000).toFixed(1)}s)`);
+    };
+    writeFileSync(htmlPath, toHtmlAnalyzedFiles(tracks, { ...analyzeOpts, onProgress }));
+    console.log(`html -> ${htmlPath}`);
+  }
+  if (opts.png) {
+    const width = Number(opts.width ?? 1280);
+    const height = Number(opts.height ?? 720);
+    for (const t of tracks) {
+      const pngPath = join(outDir, `${t.name}.png`);
+      await savePng(analyzedSvg(t.points, { ...analyzeOpts, width, height }), pngPath);
+      console.log(`png -> ${pngPath}`);
+    }
+  }
+}
+
+// ---- --organize: only after every .gpx above is safely on disk ----
+async function promptLine(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+if (opts.organize) {
+  const includeGpx = !outExplicit; // --out was explicit -> leave the .gpx where the user put it
+  const plan = planMove(entries, { root: opts.organize, outDir, includeGpx });
+  if (plan.files.length === 0) {
+    console.log("\n--organize: nothing to move (no successfully-extracted videos).");
+  } else {
+    const byDestDir = new Map();
+    let sidecarTotal = 0;
+    let cacheTotal = 0;
+    for (const f of plan.files) {
+      if (!byDestDir.has(f.destDir)) byDestDir.set(f.destDir, []);
+      byDestDir.get(f.destDir).push(f);
+      sidecarTotal += findSidecars(f.file).length;
+      const cp = cacheMovePlan(f.file, f.destPath, cache);
+      if (cp && existsSync(cp.from)) cacheTotal++;
+    }
+
+    console.log(`\n--organize preview: ${plan.files.length} video(s) -> ${opts.organize}`);
+    for (const [destDir, list] of byDestDir) {
+      console.log(`  ${destDir}/`);
+      for (const f of list) console.log(`    ${basename(f.file)}`);
+    }
+    if (plan.gpx.length)
+      console.log(`  + ${plan.gpx.length} .gpx file(s) moving into their group folder`);
+    if (cacheTotal) console.log(`  + ${cacheTotal} cache file(s) moving alongside (never deleted)`);
+    if (sidecarTotal) console.log(`  + ${sidecarTotal} .LRV/.THM sidecar file(s) found`);
+
+    let sidecarAction = "delete";
+    let confirmed = true;
+    if (!opts.yes) {
+      if (!process.stdin.isTTY) {
+        console.log(
+          "--organize: stdin is not interactive — skipping without --yes (nothing moved).",
+        );
+        confirmed = false;
+      } else {
+        if (sidecarTotal > 0) {
+          const raw = await promptLine(
+            `  delete or move the ${sidecarTotal} sidecar file(s)? [delete/move] (default delete): `,
+          );
+          sidecarAction = raw.trim().toLowerCase().startsWith("m") ? "move" : "delete";
+        }
+        const raw = await promptLine(`\nProceed with moving ${plan.files.length} file(s)? [y/N] `);
+        confirmed = ["y", "yes"].includes(raw.trim().toLowerCase());
+      }
+    }
+
+    if (!confirmed) {
+      console.log("--organize: cancelled, nothing moved.");
+    } else {
+      const summary = executeMove(plan, { cache, sidecarAction });
+      console.log(
+        `\n--organize done. moved=${summary.moved} gpxMoved=${summary.gpxMoved} cacheMoved=${summary.cacheMoved} ` +
+          `sidecars(moved=${summary.sidecarsMoved},deleted=${summary.sidecarsDeleted}) ` +
+          `skippedCollisions=${summary.skippedCollisions} errors=${summary.errors.length}`,
+      );
+      for (const e of summary.errors) console.error(`  ERROR ${e.file}: ${e.error}`);
+    }
+  }
+}

package/src/group.js

@@ -48,15 +48,81 @@ export function fileNumber(file) {
  * @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
+ * @property {string} [file]    source video path — optional; also carried through for
+ *   organize.js's planMove() (see ./organize.js), and used by buildGroups() itself to name each
+ *   session's own <trk> after its earliest chapter (see {@link sessionName})
+ */
+
+/**
+ * @typedef {object} GpxTrack one <trk> within a GpxGroup — one recording session
+ * @property {string | null} name  the session's own original video file's basename (no extension),
+ *   or null when no file path was available to derive one (see {@link sessionName})
+ * @property {import("gpx-stabilizer").TrackPoint[][]} segments  one per <trkseg> (a session usually
+ *   has one, but (A)'s time-gap sub-split — see buildGroups — can produce several)
  */
 
 /**
  * @typedef {object} GpxGroup one output GPX
- * @property {string} name      file stem (no extension)
- * @property {import("gpx-stabilizer").TrackPoint[][]} segments  one per <trkseg>
+ * @property {string} name      file stem (no extension) — the day+camera group name
+ * @property {GpxTrack[]} tracks  one per recording session (<trk>), in chronological order
  * @property {number | null} startMs  earliest real fix (epoch ms), for meta.time
  */
 
+/**
+ * A session's own name for its `<trk>`: the earliest (chapter-order) contributing file's basename,
+ * no extension — e.g. chapters `GH010042.MP4`/`GH020042.MP4` sharing file-number "0042" both carry
+ * their file path here, and plain alphabetical sort picks `GH010042` (chapter 1) over `GH020042`
+ * (chapter 2), which also happens to hold for the older GOPR/GP01/GP02 scheme (`"GO" < "GP"`).
+ * `null` when no file path was available at all (e.g. a caller that never set `GroupEntry.file`).
+ * @param {string[]} files
+ * @returns {string | null}
+ */
+function sessionName(files) {
+  if (!files || files.length === 0) return null;
+  const bases = files.map((f) => basename(f).replace(/\.[^.]+$/, ""));
+  bases.sort();
+  return bases[0];
+}
+
+/**
+ * Merge key = (camera, day): serial when known (two same-model bodies stay separate), else
+ * filename family. Exported so organize.js's planMove() can look a file's name up in the Map
+ * groupNames() returns, without recomputing the key by a possibly-drifted copy.
+ * @param {GroupEntry} e
+ * @returns {string}
+ */
+export function gkeyOf(e) {
+  return e.serial ? `${e.date}|s:${e.serial}` : `${e.date}|f:${e.family}`;
+}
+
+/**
+ * The output name for each file's merge group (camera+day) — `<date>-<family>`, disambiguated
+ * with a short serial suffix only when two cameras collide on the same family+date. This is
+ * exactly the naming buildGroups() gives its `.gpx` files; exported so organize.js's planMove()
+ * can name mp4 folders identically without re-deriving the same logic (and risking drift).
+ * @param {GroupEntry[]} entries
+ * @returns {Map<string, string>} gkey -> name
+ */
+export function groupNames(entries) {
+  const seen = new Map(); // gkey -> { date, family, serial }
+  for (const e of entries) {
+    const gkey = gkeyOf(e);
+    if (!seen.has(gkey))
+      seen.set(gkey, { date: e.date, family: e.family, serial: e.serial ?? null });
+  }
+  const clash = new Map(); // "date-family" -> distinct group count
+  for (const g of seen.values()) {
+    const base = `${g.date}-${g.family}`;
+    clash.set(base, (clash.get(base) ?? 0) + 1);
+  }
+  const names = new Map();
+  for (const [gkey, g] of seen) {
+    const base = `${g.date}-${g.family}`;
+    names.set(gkey, clash.get(base) > 1 && g.serial ? `${base}-${g.serial.slice(0, 8)}` : base);
+  }
+  return names;
+}
+
 /**
  * Group extracted files into output GPX tracks.
  *
@@ -77,53 +143,43 @@ export function fileNumber(file) {
  *   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`.
+ * - **Each session becomes its own `<trk>`** (`GpxTrack`), named after its own original video file
+ *   (see {@link sessionName}) — kept distinct from the day+camera group `name` used for the `.gpx`
+ *   file itself, so a multi-session day's file carries one `<trk>` per recording, not one big track.
  *
  * @param {GroupEntry[]} entries
  * @returns {{ groups: GpxGroup[], skipped: string[] }}
  */
 export function buildGroups(entries) {
-  // gkey -> { date, family, serial, sessions: Map<fileNumber, points[]> }
+  const names = groupNames(entries);
+  // gkey -> sessions: Map<fileNumber, { points: [], files: [] }>
   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 gkey = gkeyOf(e);
+    if (!groups.has(gkey)) groups.set(gkey, { 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, []);
+    if (!sessions.has(skey)) sessions.set(skey, { points: [], files: [] });
+    const bucket = sessions.get(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);
+    for (const p of e.points) bucket.points.push(p);
+    if (e.file) bucket.files.push(e.file);
   }
 
   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));
+  for (const [gkey, g] of groups) {
+    const name = names.get(gkey);
+    const tracks = [];
+    for (const { points, files } of g.sessions.values()) {
+      const clean = points.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.
+      // (A) sub-split this session wherever consecutive kept points jump more than BIG_GAP_MS —
+      // all resulting <trkseg>s still belong to this ONE session's <trk>.
+      const segments = [];
       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) {
@@ -133,20 +189,23 @@ export function buildGroups(entries) {
         run.push(clean[i]);
       }
       segments.push(run);
+      tracks.push({ name: sessionName(files), segments });
     }
-    if (segments.length === 0) {
+    if (tracks.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));
+    // order tracks by start time so the day's <trk>s read chronologically
+    tracks.sort((A, B) => (A.segments[0][0].time ?? 0) - (B.segments[0][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;
+    for (const trk of tracks) {
+      for (const seg of trk.segments) {
+        for (const p of seg) {
+          if (p.time != null && (startMs === null || p.time < startMs)) startMs = p.time;
+        }
       }
     }
-    out.push({ name, segments, startMs });
+    out.push({ name, tracks, startMs });
   }
   return { groups: out, skipped };
 }

package/src/organize.js

@@ -0,0 +1,210 @@
+// mp4 directory reorganization for gpx-from-gopro: move each source video into
+// <root>/<group-name>/<session>/, mirroring the exact naming buildGroups() gives the
+// corresponding .gpx (group.js's groupNames()/gkeyOf() — the single source of truth
+// for that name, so the two never drift apart). planMove() is pure (no IO) so it's
+// unit testable; gopro-cli.js prompts/prints and calls executeMove() to touch disk.
+import { copyFileSync, existsSync, mkdirSync, readdirSync, renameSync, unlinkSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { resolveCachePath } from "./gopro-cache.js";
+import { gkeyOf, groupNames } from "./group.js";
+
+const NO_SESSION = "no-session"; // folder for files with no parseable file-number
+const SIDECAR_EXTS = ["lrv", "thm"]; // GoPro's per-chapter low-res preview / thumbnail
+
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * @typedef {object} FilePlan
+ * @property {string} file      source video path
+ * @property {string} group     the file's group name (matches its .gpx base name)
+ * @property {string} destDir   <root>/<group>/<session-or-"no-session">
+ * @property {string} destPath  destDir/basename(file)
+ */
+
+/**
+ * @typedef {object} GpxPlan
+ * @property {string} group  group name
+ * @property {string} from   current .gpx path (in --out)
+ * @property {string} to     <root>/<group>/<group>.gpx
+ */
+
+/**
+ * Plan where each source video — and, when requested, its group's .gpx — should
+ * move to. Pure: no filesystem access, so it's cheap to unit test.
+ * @param {import("./group.js").GroupEntry[]} entries  must carry `file`
+ * @param {{ root: string, outDir?: string, includeGpx?: boolean }} opts
+ *   `includeGpx` moves each group's `<outDir>/<group>.gpx` into its folder too
+ *   (skip when the caller wants gpx left in an explicitly-chosen --out).
+ * @returns {{ files: FilePlan[], gpx: GpxPlan[] }}
+ */
+export function planMove(entries, { root, outDir, includeGpx = false }) {
+  const names = groupNames(entries);
+  const files = [];
+  const groupsSeen = new Set();
+  for (const e of entries) {
+    if (!e.file) continue;
+    const group = names.get(gkeyOf(e));
+    groupsSeen.add(group);
+    const session = e.session ?? NO_SESSION;
+    const destDir = join(root, group, session);
+    files.push({ file: e.file, group, destDir, destPath: join(destDir, basename(e.file)) });
+  }
+  const gpx = [];
+  if (includeGpx && outDir != null) {
+    for (const group of groupsSeen) {
+      gpx.push({
+        group,
+        from: join(outDir, `${group}.gpx`),
+        to: join(root, group, `${group}.gpx`),
+      });
+    }
+  }
+  return { files, gpx };
+}
+
+/**
+ * Sidecar files GoPro drops next to a chapter (same stem, `.LRV`/`.THM`) that
+ * actually exist on disk — a directory listing + case-insensitive match, not a
+ * handful of casing guesses, so it works on both case-sensitive and
+ * case-insensitive filesystems without double-counting.
+ * @param {string} mp4Path
+ * @returns {string[]} existing sidecar paths
+ */
+export function findSidecars(mp4Path) {
+  const dir = dirname(mp4Path);
+  const stem = basename(mp4Path).replace(/\.[^.]+$/, "");
+  const re = new RegExp(`^${escapeRegExp(stem)}\\.(${SIDECAR_EXTS.join("|")})$`, "i");
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names.filter((n) => re.test(n)).map((n) => join(dir, n));
+}
+
+/**
+ * Move src -> dest via rename; falls back to copy+unlink on EXDEV (rename can't
+ * cross filesystems/devices — an SD card to an external drive, most commonly).
+ * `rename` is injectable so the EXDEV fallback is testable without a real
+ * cross-device pair.
+ * @param {string} src
+ * @param {string} dest
+ * @param {(src: string, dest: string) => void} [rename]
+ */
+export function moveFile(src, dest, rename = renameSync) {
+  try {
+    rename(src, dest);
+  } catch (e) {
+    if (e?.code !== "EXDEV") throw e;
+    copyFileSync(src, dest);
+    unlinkSync(src);
+  }
+}
+
+/**
+ * Where a file's cache record currently lives (if caching is on) and where it
+ * should move to alongside the file — reuses resolveCachePath(), the SAME
+ * function the extraction cache itself uses, so this works for both the
+ * default sidecar mode and --cache-dir mode with no special-casing.
+ * @param {string} file
+ * @param {string} destPath
+ * @param {boolean | { dir?: string | null } | null} cache
+ * @returns {{ from: string, to: string } | null}  null when caching is off
+ */
+export function cacheMovePlan(file, destPath, cache) {
+  const from = resolveCachePath(file, cache);
+  if (from == null) return null;
+  return { from, to: resolveCachePath(destPath, cache) };
+}
+
+/**
+ * @typedef {object} MoveSummary
+ * @property {number} moved              mp4 files moved
+ * @property {number} gpxMoved
+ * @property {number} cacheMoved
+ * @property {number} sidecarsMoved
+ * @property {number} sidecarsDeleted
+ * @property {number} skippedCollisions  a destination already existed — never overwritten
+ * @property {{ file: string, error: string }[]} errors
+ */
+
+/**
+ * Execute a plan built by planMove(): create dest dirs, move each mp4 (skip — never
+ * overwrite — on a destination collision), move its cache record alongside
+ * (best-effort; see cacheMovePlan), move each group's .gpx when plan.gpx has entries,
+ * and handle sidecars per `sidecarAction`.
+ * @param {{ files: FilePlan[], gpx: GpxPlan[] }} plan
+ * @param {{ cache?: boolean | { dir?: string|null } | null, sidecarAction?: "delete"|"move"|"skip" }} [opts]
+ * @returns {MoveSummary}
+ */
+export function executeMove(plan, { cache = true, sidecarAction = "delete" } = {}) {
+  const summary = {
+    moved: 0,
+    gpxMoved: 0,
+    cacheMoved: 0,
+    sidecarsMoved: 0,
+    sidecarsDeleted: 0,
+    skippedCollisions: 0,
+    errors: [],
+  };
+
+  for (const f of plan.files) {
+    try {
+      if (existsSync(f.destPath)) {
+        summary.skippedCollisions++;
+        continue;
+      }
+      // sidecars are keyed off the file's ORIGINAL path (dirname/basename of a string,
+      // not a live handle), so finding them before or after the mp4 itself has moved
+      // is equivalent — the mp4's disappearance doesn't affect scanning its old directory.
+      const sidecars = sidecarAction !== "skip" ? findSidecars(f.file) : [];
+      const cachePlan = cacheMovePlan(f.file, f.destPath, cache);
+
+      mkdirSync(f.destDir, { recursive: true });
+      moveFile(f.file, f.destPath);
+      summary.moved++;
+
+      if (cachePlan && existsSync(cachePlan.from)) {
+        try {
+          moveFile(cachePlan.from, cachePlan.to);
+          summary.cacheMoved++;
+        } catch {
+          // best-effort: losing a cache record only costs a future re-extraction
+        }
+      }
+
+      for (const side of sidecars) {
+        if (sidecarAction === "delete") {
+          unlinkSync(side);
+          summary.sidecarsDeleted++;
+        } else {
+          const dest = join(f.destDir, basename(side));
+          if (!existsSync(dest)) {
+            moveFile(side, dest);
+            summary.sidecarsMoved++;
+          }
+        }
+      }
+    } catch (e) {
+      summary.errors.push({ file: f.file, error: e?.message ?? String(e) });
+    }
+  }
+
+  for (const g of plan.gpx) {
+    try {
+      if (!existsSync(g.from)) continue; // nothing written for this group (e.g. it was skipped)
+      if (existsSync(g.to)) {
+        summary.skippedCollisions++;
+        continue;
+      }
+      mkdirSync(dirname(g.to), { recursive: true });
+      moveFile(g.from, g.to);
+      summary.gpxMoved++;
+    } catch (e) {
+      summary.errors.push({ file: g.from, error: e?.message ?? String(e) });
+    }
+  }
+
+  return summary;
+}

package/src/telemetry.js

@@ -4,7 +4,7 @@
 // docs/export-contract.md.
 
 import { statSync } from "node:fs";
-import { resample, stabilize } from "gpx-stabilizer";
+import { loadModule, resample, stabilize } from "gpx-stabilizer";
 import tzlookup from "tz-lookup";
 import { extractGoproAll, probeGoproMeta } from "./gopro.js";
 import { CACHE_V, readCache, resolveCachePath, writeCache } from "./gopro-cache.js";
@@ -217,7 +217,9 @@ export async function readGoproSamples(path, opts = {}) {
  *   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.
+ *   there is one point per frame; `cache` controls the on-disk extraction record. When cleaning
+ *   runs on a HERO10 file, core's `gpsQuality` module is applied automatically (gated on
+ *   `meta.model` — see the module's doc for why it's model-specific, not a general default).
  * @returns {Promise<TelemetryResult>}
  */
 export async function readGoproTelemetry(path, opts = {}) {
@@ -246,9 +248,18 @@ export async function readGoproTelemetry(path, opts = {}) {
   if (opts.resample && opts.stabilize === false) {
     throw new Error("readGoproTelemetry: `resample` requires cleaning — drop `stabilize: false`");
   }
+  // Hero10's GPS chip needs its own quality gate (core's `gpsQuality` module — see its doc): its
+  // hdop baseline runs 5-10x higher than a Hero5's on the same trip, so the threshold is calibrated
+  // to that one chip generation and must not silently apply to every model. `gpsQuality` is opt-in
+  // (not a core builtin) specifically so this decision lives here, where `meta.model` is known.
+  const gxModules = meta.model === "HERO10" ? [await loadModule("gpsQuality")] : [];
+  const stabilizeOpts = opts.stabilize && opts.stabilize !== true ? opts.stabilize : {};
   const cleaned =
     opts.stabilize || opts.resample
-      ? stabilize(raw, opts.stabilize && opts.stabilize !== true ? opts.stabilize : {})
+      ? stabilize(raw, {
+          ...stabilizeOpts,
+          modules: [...(stabilizeOpts.modules ?? []), ...gxModules],
+        })
       : raw;
 
   let points = cleaned;