From 121d58240ff06d9a7ef6b7261593cd58f3d13e46 Mon Sep 17 00:00:00 2001
From: Matt Dawkins <matt.dawkins@kitware.com>
Date: Wed, 5 Aug 2026 16:02:55 -0400
Subject: [PATCH 1/5] Frame label mode: rapid whole-frame event labeling

Hotkeys 1-9 start a full-frame interval track at the current frame with
forward-fill until the next event; 0 ends the open segment. Segments are
ordinary tracks so timeline, export, and classifier training work unchanged.
---
 .../components/FrameLabelPanel.vue            | 165 ++++++++++++++++++
 client/dive-common/components/Viewer.vue      |  50 ++++++
 client/dive-common/store/settings.ts          |   7 +
 client/src/use/index.ts                       |   2 +
 client/src/use/useFrameLabelMode.spec.ts      | 132 ++++++++++++++
 client/src/use/useFrameLabelMode.ts           | 121 +++++++++++++
 6 files changed, 477 insertions(+)
 create mode 100644 client/dive-common/components/FrameLabelPanel.vue
 create mode 100644 client/src/use/useFrameLabelMode.spec.ts
 create mode 100644 client/src/use/useFrameLabelMode.ts

diff --git a/client/dive-common/components/FrameLabelPanel.vue b/client/dive-common/components/FrameLabelPanel.vue
new file mode 100644
index 000000000..4a8ce24b1
--- /dev/null
+++ b/client/dive-common/components/FrameLabelPanel.vue
@@ -0,0 +1,165 @@
+<script lang="ts">
+import {
+  computed, defineComponent, ref,
+} from 'vue';
+import { useTrackStyleManager } from 'vue-media-annotator/provides';
+import { clientSettings } from 'dive-common/store/settings';
+
+export default defineComponent({
+  name: 'FrameLabelPanel',
+
+  props: {
+    value: {
+      type: Boolean,
+      default: false,
+    },
+    activeLabel: {
+      type: String,
+      default: null,
+    },
+    disabled: {
+      type: Boolean,
+      default: false,
+    },
+  },
+
+  setup() {
+    const { typeStyling } = useTrackStyleManager();
+    const newLabel = ref('');
+    const labels = computed(() => clientSettings.frameLabelSettings.labels);
+
+    function addLabel() {
+      const label = newLabel.value.trim();
+      if (label && !labels.value.includes(label) && labels.value.length < 9) {
+        clientSettings.frameLabelSettings.labels.push(label);
+      }
+      newLabel.value = '';
+    }
+
+    function removeLabel(label: string) {
+      const index = labels.value.indexOf(label);
+      if (index >= 0) {
+        clientSettings.frameLabelSettings.labels.splice(index, 1);
+      }
+    }
+
+    return {
+      labels,
+      newLabel,
+      addLabel,
+      removeLabel,
+      typeStyling,
+    };
+  },
+});
+</script>
+
+<template>
+  <div class="px-2 py-1">
+    <v-divider />
+    <div class="d-flex align-center">
+      <v-switch
+        :input-value="value"
+        :disabled="disabled || labels.length === 0"
+        label="Frame label mode"
+        dense
+        hide-details
+        class="my-1 py-0"
+        @change="$emit('input', !!$event)"
+      />
+      <v-spacer />
+      <v-tooltip
+        open-delay="200"
+        bottom
+        max-width="300"
+      >
+        <template #activator="{ on }">
+          <v-icon
+            small
+            class="mr-1"
+            v-on="on"
+          >
+            mdi-help-circle
+          </v-icon>
+        </template>
+        <span>
+          While enabled, keys 1-9 label all frames from the current frame
+          forward with the corresponding label, until the next labeled event
+          or the end of the video. Press 0 to end the current label without
+          starting a new one. Labels are saved as full-frame tracks.
+        </span>
+      </v-tooltip>
+    </div>
+    <div
+      v-if="value && activeLabel !== null"
+      class="text-caption mb-1"
+    >
+      Current frame:
+      <v-chip
+        x-small
+        :color="typeStyling.color(activeLabel)"
+        class="ml-1"
+      >
+        {{ activeLabel }}
+      </v-chip>
+    </div>
+    <div
+      v-for="(label, index) in labels"
+      :key="label"
+      class="d-flex align-center my-1"
+    >
+      <v-chip
+        x-small
+        outlined
+        class="mr-2 px-1 hotkey-chip"
+      >
+        {{ index + 1 }}
+      </v-chip>
+      <span
+        class="text-body-2 text-truncate"
+        :style="{ color: typeStyling.color(label) }"
+      >
+        {{ label }}
+      </span>
+      <v-spacer />
+      <v-btn
+        icon
+        x-small
+        :disabled="disabled"
+        @click="removeLabel(label)"
+      >
+        <v-icon x-small>
+          mdi-close
+        </v-icon>
+      </v-btn>
+    </div>
+    <v-text-field
+      v-model="newLabel"
+      :disabled="disabled || labels.length >= 9"
+      label="Add label"
+      dense
+      hide-details
+      class="my-1"
+      @keydown.enter="addLabel"
+    >
+      <template #append>
+        <v-btn
+          icon
+          x-small
+          :disabled="!newLabel.trim()"
+          @click="addLabel"
+        >
+          <v-icon small>
+            mdi-plus
+          </v-icon>
+        </v-btn>
+      </template>
+    </v-text-field>
+  </div>
+</template>
+
+<style scoped>
+.hotkey-chip {
+  font-family: monospace;
+}
+</style>
diff --git a/client/dive-common/components/Viewer.vue b/client/dive-common/components/Viewer.vue
index 9e18ebd9c..a4fd4fbf7 100644
--- a/client/dive-common/components/Viewer.vue
+++ b/client/dive-common/components/Viewer.vue
@@ -10,6 +10,7 @@ import { cloneDeep, debounce } from 'lodash';
 /* VUE MEDIA ANNOTATOR */
 import {
   useAttributes,
+  useFrameLabelMode,
   useImageEnhancements,
   useLineChart,
   useTimeObserver,
@@ -93,6 +94,7 @@ import MultiCamToolbar from './MultiCamToolbar.vue';
 import AlignedViewToggle from './AlignedViewToggle.vue';
 import PrimaryAttributeTrackFilter from './PrimaryAttributeTrackFilter.vue';
 import UserSettingsDialog from './UserSettingsDialog.vue';
+import FrameLabelPanel from './FrameLabelPanel.vue';
 
 export interface ImageDataItem {
   url: string;
@@ -127,6 +129,7 @@ export default defineComponent({
     ConfidenceSubsection,
     AttributeSubsection,
     AttributeEditor,
+    FrameLabelPanel,
   },
 
   // TODO: remove this in vue 3
@@ -624,6 +627,41 @@ export default defineComponent({
       alignedView.setSuspended(picking);
     }, { immediate: true });
 
+    const frameLabelMode = useFrameLabelMode({
+      cameraStore,
+      selectedCamera,
+      labels: computed(() => clientSettings.frameLabelSettings.labels),
+      getMaxFrame: () => aggregateController.value.maxFrame.value,
+      getFullFrameBounds: () => {
+        const bounds = aggregateController.value
+          .getController(selectedCamera.value).originalBounds.value;
+        return [bounds.left, bounds.top, bounds.right, bounds.bottom];
+      },
+    });
+    const frameLabelMousetrap = computed(() => {
+      if (!frameLabelMode.enabled.value || readonlyState.value) {
+        return [];
+      }
+      const binds = clientSettings.frameLabelSettings.labels.slice(0, 9)
+        .map((label, index) => ({
+          bind: `${index + 1}`,
+          handler: () => frameLabelMode.labelFrame(label, time.frame.value),
+        }));
+      binds.push({ bind: '0', handler: () => frameLabelMode.endLabel(time.frame.value) });
+      return binds;
+    });
+    const frameLabelActive = computed(() => {
+      if (!frameLabelMode.enabled.value) {
+        return null;
+      }
+      // pendingSaveCount registers annotation edits as a dependency; the
+      // track stores themselves are not deeply reactive
+      if (pendingSaveCount.value < 0) {
+        return null;
+      }
+      return frameLabelMode.labelAtFrame(time.frame.value);
+    });
+
     /**
      * Every camera pane calls updateTime() from its own seek/play/pause, but
      * useTime()'s frame/flick is a single shared value consumed app-wide as
@@ -1978,6 +2016,9 @@ export default defineComponent({
       editingMode,
       editingDetails,
       eventChartData,
+      frameLabelEnabled: frameLabelMode.enabled,
+      frameLabelMousetrap,
+      frameLabelActive,
       groupChartData,
       imageData,
       lineChartData,
@@ -2310,6 +2351,13 @@ export default defineComponent({
         @track-seek="seekToFrame($event)"
       >
         <template>
+          <v-divider />
+          <frame-label-panel
+            :value="frameLabelEnabled"
+            :active-label="frameLabelActive"
+            :disabled="readonlyState"
+            @input="frameLabelEnabled = $event"
+          />
           <v-divider />
           <primary-attribute-track-filter
             :toggle="context.toggle"
@@ -2342,6 +2390,7 @@ export default defineComponent({
             { bind: 'r', handler: () => resetAggregateZoom() },
             { bind: 'esc', handler: () => handler.trackAbort() },
             { bind: 'e', handler: () => multiCamList.length === 1 && selectedTrackId !== null && handler.trackEdit(selectedTrackId) },
+            ...frameLabelMousetrap,
           ]"
           class="d-flex flex-column grow"
         >
@@ -2444,6 +2493,7 @@ export default defineComponent({
             { bind: 'esc', handler: () => handler.trackAbort() },
             { bind: 'e', handler: () => multiCamList.length === 1 && selectedTrackId !== null && handler.trackEdit(selectedTrackId) },
             { bind: 'a', handler: () => sidebarMode === 'bottom' && toggleBottomRightPanel() },
+            ...frameLabelMousetrap,
           ]"
           class="d-flex flex-column grow"
           style="min-height: 0; min-width: 0;"
diff --git a/client/dive-common/store/settings.ts b/client/dive-common/store/settings.ts
index ee2282bd8..a09d1ec6f 100644
--- a/client/dive-common/store/settings.ts
+++ b/client/dive-common/store/settings.ts
@@ -90,6 +90,10 @@ interface AnnotationSettings {
     loading: boolean;
     loadingMessage: string;
   };
+  frameLabelSettings: {
+    // Track types managed by frame label mode, in hotkey (1-9) order
+    labels: string[];
+  };
 }
 
 const defaultSettings: AnnotationSettings = {
@@ -183,6 +187,9 @@ const defaultSettings: AnnotationSettings = {
     loading: false,
     loadingMessage: '',
   },
+  frameLabelSettings: {
+    labels: [],
+  },
 };
 const MIN_AUTO_SAVE_DELAY_SECONDS = 10;
 
diff --git a/client/src/use/index.ts b/client/src/use/index.ts
index 7e8e9e97b..71879b77b 100644
--- a/client/src/use/index.ts
+++ b/client/src/use/index.ts
@@ -1,5 +1,6 @@
 import useAttributes from './useAttributes';
 import useEventChart from './useEventChart';
+import useFrameLabelMode from './useFrameLabelMode';
 import useLineChart from './useLineChart';
 import useTimeObserver from './useTimeObserver';
 import useImageEnhancements from './useImageEnhancements';
@@ -8,6 +9,7 @@ import useVirtualScrollTo from './useVirtualScrollTo';
 export {
   useAttributes,
   useEventChart,
+  useFrameLabelMode,
   useImageEnhancements,
   useLineChart,
   useTimeObserver,
diff --git a/client/src/use/useFrameLabelMode.spec.ts b/client/src/use/useFrameLabelMode.spec.ts
new file mode 100644
index 000000000..19eba2f66
--- /dev/null
+++ b/client/src/use/useFrameLabelMode.spec.ts
@@ -0,0 +1,132 @@
+import { ref } from 'vue';
+import CameraStore from '../CameraStore';
+import useFrameLabelMode from './useFrameLabelMode';
+
+const LABELS = ['event-1', 'event-2', 'possible-event'];
+const MAX_FRAME = 100;
+const BOUNDS: [number, number, number, number] = [0, 0, 1920, 1080];
+
+function setup() {
+  const cameraStore = new CameraStore({ markChangesPending: () => undefined });
+  const mode = useFrameLabelMode({
+    cameraStore,
+    selectedCamera: ref('singleCam'),
+    labels: ref(LABELS),
+    getMaxFrame: () => MAX_FRAME,
+    getFullFrameBounds: () => BOUNDS,
+  });
+  const { trackStore } = cameraStore.camMap.value.get('singleCam')!;
+  return { cameraStore, trackStore, mode };
+}
+
+function ranges(trackStore: ReturnType<typeof setup>['trackStore']) {
+  const result: [string, number, number][] = [];
+  trackStore.annotationMap.forEach((t) => {
+    result.push([t.getType()[0], t.begin, t.end]);
+  });
+  return result.sort((a, b) => a[1] - b[1]);
+}
+
+describe('useFrameLabelMode', () => {
+  it('creates a segment extending to the end of the video', () => {
+    const { trackStore, mode } = setup();
+    mode.labelFrame('event-1', 10);
+    expect(ranges(trackStore)).toEqual([['event-1', 10, MAX_FRAME]]);
+    const track = trackStore.annotationMap.values().next().value!;
+    expect(track.featureIndex).toEqual([10, MAX_FRAME]);
+    expect(track.features[10].bounds).toEqual(BOUNDS);
+    expect(track.features[10].interpolate).toBe(true);
+    expect(track.features[MAX_FRAME].keyframe).toBe(true);
+  });
+
+  it('truncates the previous segment when a new event begins', () => {
+    const { trackStore, mode } = setup();
+    mode.labelFrame('event-1', 10);
+    mode.labelFrame('event-2', 40);
+    expect(ranges(trackStore)).toEqual([
+      ['event-1', 10, 39],
+      ['event-2', 40, MAX_FRAME],
+    ]);
+  });
+
+  it('inserts an event between existing segments', () => {
+    const { trackStore, mode } = setup();
+    mode.labelFrame('event-1', 10);
+    mode.labelFrame('event-2', 40);
+    mode.labelFrame('possible-event', 20);
+    expect(ranges(trackStore)).toEqual([
+      ['event-1', 10, 19],
+      ['possible-event', 20, 39],
+      ['event-2', 40, MAX_FRAME],
+    ]);
+  });
+
+  it('relabels a segment when pressed at its begin frame', () => {
+    const { trackStore, mode } = setup();
+    mode.labelFrame('event-1', 10);
+    mode.labelFrame('event-2', 40);
+    mode.labelFrame('possible-event', 40);
+    expect(ranges(trackStore)).toEqual([
+      ['event-1', 10, 39],
+      ['possible-event', 40, MAX_FRAME],
+    ]);
+  });
+
+  it('is a no-op when the frame already has that label', () => {
+    const { trackStore, mode } = setup();
+    mode.labelFrame('event-1', 10);
+    mode.labelFrame('event-1', 50);
+    expect(ranges(trackStore)).toEqual([['event-1', 10, MAX_FRAME]]);
+  });
+
+  it('endLabel truncates or deletes the covering segment', () => {
+    const { trackStore, mode } = setup();
+    mode.labelFrame('event-1', 10);
+    mode.endLabel(50);
+    expect(ranges(trackStore)).toEqual([['event-1', 10, 49]]);
+    mode.endLabel(10);
+    expect(ranges(trackStore)).toEqual([]);
+    mode.endLabel(70);
+    expect(ranges(trackStore)).toEqual([]);
+  });
+
+  it('single-frame segment when the next segment starts on the next frame', () => {
+    const { trackStore, mode } = setup();
+    mode.labelFrame('event-1', 10);
+    mode.labelFrame('event-2', 11);
+    mode.labelFrame('possible-event', 10);
+    expect(ranges(trackStore)).toEqual([
+      ['possible-event', 10, 10],
+      ['event-2', 11, MAX_FRAME],
+    ]);
+    const single = trackStore.annotationMap.get(
+      [...trackStore.annotationMap.values()].find((t) => t.begin === 10)!.id,
+    )!;
+    expect(single.featureIndex).toEqual([10]);
+  });
+
+  it('ignores tracks whose type is not in the label set', () => {
+    const { cameraStore, trackStore, mode } = setup();
+    const fish = trackStore.add(0, 'fish', undefined, cameraStore.getNewTrackId());
+    fish.setFeature({
+      frame: 0, bounds: [5, 5, 10, 10], keyframe: true, interpolate: false,
+    });
+    mode.labelFrame('event-1', 0);
+    expect(ranges(trackStore)).toEqual([
+      ['fish', 0, 0],
+      ['event-1', 0, MAX_FRAME],
+    ]);
+    expect(mode.labelAtFrame(0)).toBe('event-1');
+  });
+
+  it('labelAtFrame reports the active label', () => {
+    const { mode } = setup();
+    expect(mode.labelAtFrame(20)).toBeNull();
+    mode.labelFrame('event-1', 10);
+    mode.labelFrame('event-2', 40);
+    expect(mode.labelAtFrame(5)).toBeNull();
+    expect(mode.labelAtFrame(15)).toBe('event-1');
+    expect(mode.labelAtFrame(40)).toBe('event-2');
+    expect(mode.labelAtFrame(MAX_FRAME)).toBe('event-2');
+  });
+});
diff --git a/client/src/use/useFrameLabelMode.ts b/client/src/use/useFrameLabelMode.ts
new file mode 100644
index 000000000..b96b43efa
--- /dev/null
+++ b/client/src/use/useFrameLabelMode.ts
@@ -0,0 +1,121 @@
+import { ref, Ref } from 'vue';
+import type CameraStore from '../CameraStore';
+import type Track from '../track';
+import type { RectBounds } from '../utils';
+
+export interface UseFrameLabelModeParams {
+  cameraStore: CameraStore;
+  selectedCamera: Ref<string>;
+  /** Track types managed by frame label mode, in hotkey order. */
+  labels: Readonly<Ref<string[]>>;
+  getMaxFrame: () => number;
+  getFullFrameBounds: () => RectBounds;
+}
+
+/**
+ * Frame label mode: rapid whole-frame labeling with event semantics.  Each
+ * label press starts a full-frame interval track at the current frame; the
+ * previous open segment is truncated, and the new segment extends forward
+ * until the next existing segment or the end of the video.  Segments are
+ * ordinary tracks (type = label) so filtering, styling, timeline display,
+ * export, and frame classifier training all work unchanged.
+ */
+export default function useFrameLabelMode({
+  cameraStore,
+  selectedCamera,
+  labels,
+  getMaxFrame,
+  getFullFrameBounds,
+}: UseFrameLabelModeParams) {
+  const enabled = ref(false);
+
+  function getTrackStore() {
+    const store = cameraStore.camMap.value.get(selectedCamera.value)?.trackStore;
+    if (!store) {
+      throw new Error(`No trackStore for camera ${selectedCamera.value}`);
+    }
+    return store;
+  }
+
+  /** All frame-label segments, ordered by begin frame. */
+  function segments(): Track[] {
+    const labelSet = new Set(labels.value);
+    const result: Track[] = [];
+    getTrackStore().annotationMap.forEach((track) => {
+      if (labelSet.has(track.getType()[0])) {
+        result.push(track);
+      }
+    });
+    return result.sort((a, b) => a.begin - b.begin);
+  }
+
+  function fullFrameFeature(frame: number) {
+    return {
+      frame,
+      bounds: getFullFrameBounds(),
+      keyframe: true,
+      interpolate: true,
+    };
+  }
+
+  /** Move a segment's end to newEnd, dropping any keyframes beyond it. */
+  function truncateSegment(track: Track, newEnd: number) {
+    track.setFeature(fullFrameFeature(newEnd));
+    const beyond = track.featureIndex.filter((frame) => frame > newEnd);
+    beyond.forEach((frame) => track.deleteFeature(frame));
+  }
+
+  /**
+   * Label frames from `frame` forward until the next segment begins (or the
+   * end of the video).  Any segment covering `frame` ends at `frame - 1`.
+   */
+  function labelFrame(label: string, frame: number): number | null {
+    const segs = segments();
+    const covering = segs.find((t) => t.begin <= frame && t.end >= frame);
+    if (covering && covering.getType()[0] === label) {
+      return covering.id;
+    }
+    if (covering && covering.begin === frame) {
+      covering.setType(label);
+      return covering.id;
+    }
+    if (covering) {
+      truncateSegment(covering, frame - 1);
+    }
+    const next = segs.find((t) => t.begin > frame);
+    const end = next ? next.begin - 1 : Math.max(getMaxFrame(), frame);
+    const store = getTrackStore();
+    const track = store.add(frame, label, undefined, cameraStore.getNewTrackId());
+    track.setFeature(fullFrameFeature(frame));
+    if (end > frame) {
+      track.setFeature(fullFrameFeature(end));
+    }
+    return track.id;
+  }
+
+  /** End the segment covering `frame` at `frame - 1` (unlabeled from here). */
+  function endLabel(frame: number) {
+    const covering = segments().find((t) => t.begin <= frame && t.end >= frame);
+    if (!covering) {
+      return;
+    }
+    if (covering.begin === frame) {
+      getTrackStore().remove(covering.id);
+    } else {
+      truncateSegment(covering, frame - 1);
+    }
+  }
+
+  /** The label active at `frame`, or null when unlabeled. */
+  function labelAtFrame(frame: number): string | null {
+    const covering = segments().find((t) => t.begin <= frame && t.end >= frame);
+    return covering ? covering.getType()[0] : null;
+  }
+
+  return {
+    enabled,
+    labelFrame,
+    endLabel,
+    labelAtFrame,
+  };
+}

From 3c9664d048f7a3f7f736ef839af91fb26020ab80 Mon Sep 17 00:00:00 2001
From: Matt Dawkins <matt.dawkins@kitware.com>
Date: Wed, 5 Aug 2026 17:06:19 -0400
Subject: [PATCH 2/5] divecli import: bulk media ingest with frame label
 presets

New import command creates datasets from a video, image directory, or (with
--bulk) every video/subdirectory in a folder. --frame-label defines the
dataset's frame label set; --default-frame-label covers the whole dataset
with one full-frame track. Restores the missing divecli bin build (build:cli).
---
 client/dive-common/apispec.ts                 |   4 +-
 .../components/FrameLabelPanel.vue            |  33 ++++-
 client/dive-common/components/Viewer.vue      |  15 +-
 client/package.json                           |   1 +
 client/platform/desktop/backend/cli.ts        | 103 ++++++++++++-
 .../desktop/backend/importMetaUrlShim.js      |   8 +
 .../platform/desktop/backend/native/common.ts |   3 +
 .../backend/native/frameLabels.spec.ts        |  43 ++++++
 .../desktop/backend/native/frameLabels.ts     | 137 ++++++++++++++++++
 .../desktop/backend/native/mediaJobs.ts       |   7 +
 .../platform/desktop/backend/native/viame.ts  |   2 +-
 .../desktop/backend/rendererBridge.ts         |  18 +++
 client/platform/desktop/background.ts         |   2 +
 13 files changed, 363 insertions(+), 13 deletions(-)
 create mode 100644 client/platform/desktop/backend/importMetaUrlShim.js
 create mode 100644 client/platform/desktop/backend/native/frameLabels.spec.ts
 create mode 100644 client/platform/desktop/backend/native/frameLabels.ts
 create mode 100644 client/platform/desktop/backend/rendererBridge.ts

diff --git a/client/dive-common/apispec.ts b/client/dive-common/apispec.ts
index 5517d29a8..fd0e068dc 100644
--- a/client/dive-common/apispec.ts
+++ b/client/dive-common/apispec.ts
@@ -245,9 +245,11 @@ interface DatasetConfigMutable {
   cameraTransformTypes?: CameraTransformTypes;
   /** Producer provenance of the camera registration (see RegistrationSource). */
   cameraRegistrationSource?: RegistrationSource | null;
+  /** Frame label mode label set defined by the dataset, in hotkey order. */
+  frameLabels?: string[];
   error?: string;
 }
-const DatasetConfigMutableKeys = ['attributes', 'confidenceFilters', 'timeFilters', 'imageEnhancements', 'customTypeStyling', 'customGroupStyling', 'attributeTrackFilters', 'datasetInfo', 'cameraHomographies', 'cameraCorrespondences', 'cameraTransformTypes', 'cameraRegistrationSource'];
+const DatasetConfigMutableKeys = ['attributes', 'confidenceFilters', 'timeFilters', 'imageEnhancements', 'customTypeStyling', 'customGroupStyling', 'attributeTrackFilters', 'datasetInfo', 'cameraHomographies', 'cameraCorrespondences', 'cameraTransformTypes', 'cameraRegistrationSource', 'frameLabels'];
 /**
  * Mutable keys the multicam/stereo viewer loads from the parent dataset.
  * Camera-targeted imports sync only these onto the parent — not per-camera
diff --git a/client/dive-common/components/FrameLabelPanel.vue b/client/dive-common/components/FrameLabelPanel.vue
index 4a8ce24b1..67fe3d833 100644
--- a/client/dive-common/components/FrameLabelPanel.vue
+++ b/client/dive-common/components/FrameLabelPanel.vue
@@ -1,7 +1,5 @@
 <script lang="ts">
-import {
-  computed, defineComponent, ref,
-} from 'vue';
+import { defineComponent, ref } from 'vue';
 import { useTrackStyleManager } from 'vue-media-annotator/provides';
 import { clientSettings } from 'dive-common/store/settings';
 
@@ -13,6 +11,18 @@ export default defineComponent({
       type: Boolean,
       default: false,
     },
+    labels: {
+      type: Array as () => string[],
+      default: () => [],
+    },
+    /**
+     * True when the label set comes from the dataset itself; the list is
+     * fixed and the global-list editing controls are hidden.
+     */
+    datasetDefined: {
+      type: Boolean,
+      default: false,
+    },
     activeLabel: {
       type: String,
       default: null,
@@ -26,25 +36,24 @@ export default defineComponent({
   setup() {
     const { typeStyling } = useTrackStyleManager();
     const newLabel = ref('');
-    const labels = computed(() => clientSettings.frameLabelSettings.labels);
 
     function addLabel() {
       const label = newLabel.value.trim();
-      if (label && !labels.value.includes(label) && labels.value.length < 9) {
-        clientSettings.frameLabelSettings.labels.push(label);
+      const stored = clientSettings.frameLabelSettings.labels;
+      if (label && !stored.includes(label) && stored.length < 9) {
+        stored.push(label);
       }
       newLabel.value = '';
     }
 
     function removeLabel(label: string) {
-      const index = labels.value.indexOf(label);
+      const index = clientSettings.frameLabelSettings.labels.indexOf(label);
       if (index >= 0) {
         clientSettings.frameLabelSettings.labels.splice(index, 1);
       }
     }
 
     return {
-      labels,
       newLabel,
       addLabel,
       removeLabel,
@@ -123,6 +132,7 @@ export default defineComponent({
       </span>
       <v-spacer />
       <v-btn
+        v-if="!datasetDefined"
         icon
         x-small
         :disabled="disabled"
@@ -133,7 +143,14 @@ export default defineComponent({
         </v-icon>
       </v-btn>
     </div>
+    <div
+      v-if="datasetDefined"
+      class="text-caption text--secondary mb-1"
+    >
+      Labels defined by this dataset
+    </div>
     <v-text-field
+      v-else
       v-model="newLabel"
       :disabled="disabled || labels.length >= 9"
       label="Add label"
diff --git a/client/dive-common/components/Viewer.vue b/client/dive-common/components/Viewer.vue
index a4fd4fbf7..e0c829605 100644
--- a/client/dive-common/components/Viewer.vue
+++ b/client/dive-common/components/Viewer.vue
@@ -627,10 +627,16 @@ export default defineComponent({
       alignedView.setSuspended(picking);
     }, { immediate: true });
 
+    // A dataset may define its own frame label set (e.g. presets applied at
+    // import); it takes precedence over the user's global label list.
+    const datasetFrameLabels = ref([] as string[]);
+    const frameLabels = computed(() => (datasetFrameLabels.value.length
+      ? datasetFrameLabels.value
+      : clientSettings.frameLabelSettings.labels));
     const frameLabelMode = useFrameLabelMode({
       cameraStore,
       selectedCamera,
-      labels: computed(() => clientSettings.frameLabelSettings.labels),
+      labels: frameLabels,
       getMaxFrame: () => aggregateController.value.maxFrame.value,
       getFullFrameBounds: () => {
         const bounds = aggregateController.value
@@ -642,7 +648,7 @@ export default defineComponent({
       if (!frameLabelMode.enabled.value || readonlyState.value) {
         return [];
       }
-      const binds = clientSettings.frameLabelSettings.labels.slice(0, 9)
+      const binds = frameLabels.value.slice(0, 9)
         .map((label, index) => ({
           bind: `${index + 1}`,
           handler: () => frameLabelMode.labelFrame(label, time.frame.value),
@@ -1442,6 +1448,7 @@ export default defineComponent({
           resetMulticamAlignment();
         }
         /* Otherwise, complete loading of the dataset */
+        datasetFrameLabels.value = meta.frameLabels ?? [];
         trackStyleManager.populateTypeStyles(meta.customTypeStyling);
         groupStyleManager.populateTypeStyles(meta.customGroupStyling);
         if (meta.customTypeStyling) {
@@ -2019,6 +2026,8 @@ export default defineComponent({
       frameLabelEnabled: frameLabelMode.enabled,
       frameLabelMousetrap,
       frameLabelActive,
+      frameLabels,
+      datasetFrameLabels,
       groupChartData,
       imageData,
       lineChartData,
@@ -2354,6 +2363,8 @@ export default defineComponent({
           <v-divider />
           <frame-label-panel
             :value="frameLabelEnabled"
+            :labels="frameLabels"
+            :dataset-defined="datasetFrameLabels.length > 0"
             :active-label="frameLabelActive"
             :disabled="readonlyState"
             @input="frameLabelEnabled = $event"
diff --git a/client/package.json b/client/package.json
index 3093b4efb..498b40c13 100644
--- a/client/package.json
+++ b/client/package.json
@@ -18,6 +18,7 @@
     "build:web": "vite build",
     "build:electron": "electron-vite build && electron-builder --config electron-builder.json",
     "build:electron:dir": "electron-vite build && electron-builder --config electron-builder.json --dir",
+    "build:cli": "esbuild platform/desktop/backend/cli.ts --bundle --platform=node --target=node18 --format=cjs --external:electron --inject:platform/desktop/backend/importMetaUrlShim.js --define:import.meta.url=import_meta_url --alias:yargs=./node_modules/yargs/index.cjs --alias:vue-media-annotator=./src --alias:platform=./platform --alias:dive-common=./dive-common --outfile=bin/platform/desktop/backend/cli.js",
     "divecli": "node ./bin/platform/desktop/backend/cli.js",
     "lint": "eslint --ext .js,.ts,.vue src/ dive-common/ platform/",
     "lint:templates": "eslint --ext vue src/ dive-common/ platform/",
diff --git a/client/platform/desktop/backend/cli.ts b/client/platform/desktop/backend/cli.ts
index 1e618b0c1..c79bb8e8e 100755
--- a/client/platform/desktop/backend/cli.ts
+++ b/client/platform/desktop/backend/cli.ts
@@ -19,10 +19,14 @@ import Track from 'vue-media-annotator/track';
 import { DesktopJobUpdate, RunPipeline, RunTraining } from 'platform/desktop/constants';
 import { loadAnnotationFile, loadJsonConfig } from 'platform/desktop/backend/native/common';
 import { RectBounds } from 'vue-media-annotator/utils';
+import mime from 'mime-types';
+
+import { otherVideoTypes, websafeVideoTypes } from 'dive-common/constants';
 import linux from './native/linux';
 import win32 from './native/windows';
 import * as common from './native/common';
-import { checkMedia } from './native/mediaJobs';
+import { checkMedia, convertMedia } from './native/mediaJobs';
+import { parseFrameLabelPresets, applyFrameLabelPresets } from './native/frameLabels';
 import { parseFile, serialize } from './serializers/viame';
 import { exportNist, loadNistFile } from './serializers/nist';
 import KPF from './serializers/kpf';
@@ -149,6 +153,31 @@ const { argv } = yargs
       type: 'string',
     }).demandOption('file');
   })
+  .command('import [path]', 'Import media as new dataset(s)', () => {
+    settingsArgs();
+    yargs.positional('path', {
+      description: 'Media to import: a video, an image-sequence directory, or (with --bulk) a directory whose videos and subdirectories each become a dataset',
+      type: 'string',
+    }).demandOption('path');
+    yargs.option('bulk', {
+      describe: 'Import every video file and subdirectory inside path as its own dataset',
+      type: 'boolean',
+      default: false,
+    });
+    yargs.option('fps', {
+      describe: 'Annotation frame rate for the new dataset(s)',
+      type: 'number',
+    });
+    yargs.option('frame-label', {
+      describe: 'Frame label preset, repeatable: becomes part of the dataset\'s frame label set shown by the annotator\'s frame label mode',
+      type: 'string',
+    });
+    yargs.array('frame-label');
+    yargs.option('default-frame-label', {
+      describe: 'One of the --frame-label names, applied to the entire dataset as a full-frame track on import',
+      type: 'string',
+    });
+  })
   .command('list-config', 'List viame pipeline configuration', settingsArgs)
   .command('run-pipeline', 'Run a pipeline', () => {
     settingsArgs();
@@ -229,6 +258,78 @@ if (argv._.includes('viame2json')) {
     console.log(out);
   };
   run();
+} else if (argv._.includes('import')) {
+  const settings = getSettings();
+  const run = async () => {
+    const presets = parseFrameLabelPresets(
+      (argv.frameLabel ?? []) as string[],
+      argv.defaultFrameLabel as string | undefined,
+    );
+    const root = npath.resolve(argv.path as string);
+
+    const targets: string[] = [];
+    if (argv.bulk) {
+      const children = await fs.readdir(root, { withFileTypes: true });
+      children.sort((a, b) => a.name.localeCompare(b.name));
+      children.forEach((child) => {
+        if (child.isDirectory()) {
+          targets.push(npath.join(root, child.name));
+        } else {
+          const mimetype = mime.lookup(child.name);
+          if (mimetype && (websafeVideoTypes.includes(mimetype)
+            || otherVideoTypes.includes(mimetype))) {
+            targets.push(npath.join(root, child.name));
+          }
+        }
+      });
+      if (targets.length === 0) {
+        throw new Error(`No videos or subdirectories to import in ${root}`);
+      }
+    } else {
+      targets.push(root);
+    }
+
+    // Imports run sequentially: concurrent imports can fail behind the scenes.
+    /* eslint-disable no-restricted-syntax, no-await-in-loop */
+    for (const target of targets) {
+      try {
+        const payload = await common.beginMediaImport(target);
+        if (argv.fps) {
+          payload.jsonMeta.fps = argv.fps as number;
+        }
+        const conversionArgs = await common.finalizeMediaImport(settings, payload);
+        const datasetId = conversionArgs.meta.id;
+        await applyFrameLabelPresets(settings, datasetId, presets);
+        if (conversionArgs.mediaList.length > 0) {
+          stdout.write(`Transcoding media for ${conversionArgs.meta.name}...\n`);
+          await new Promise((resolve, reject) => {
+            convertMedia(
+              settings,
+              conversionArgs,
+              updater,
+              (jobKey, meta) => {
+                common.completeConversion(settings, datasetId, jobKey, meta)
+                  .then(resolve, reject);
+              },
+              (_jobKey, meta, errorMessage) => {
+                common.failConversion(settings, datasetId, meta, errorMessage)
+                  .then(() => reject(new Error(errorMessage)), reject);
+              },
+              true,
+            ).catch(reject);
+          });
+        }
+        stdout.write(`Imported ${conversionArgs.meta.name} as ${datasetId}\n`);
+      } catch (err) {
+        stderr.write(`Failed to import ${target}: ${err}\n`);
+        if (!argv.bulk) {
+          process.exitCode = 1;
+        }
+      }
+    }
+    /* eslint-enable no-restricted-syntax, no-await-in-loop */
+  };
+  run();
 } else if (argv._.includes('list-config')) {
   const settings = getSettings();
   const run = async () => {
diff --git a/client/platform/desktop/backend/importMetaUrlShim.js b/client/platform/desktop/backend/importMetaUrlShim.js
new file mode 100644
index 000000000..faba4e0f4
--- /dev/null
+++ b/client/platform/desktop/backend/importMetaUrlShim.js
@@ -0,0 +1,8 @@
+/**
+ * esbuild inject shim for the CJS divecli bundle: rewrites import.meta.url
+ * (used by ESM-only dependencies) to the equivalent file URL. Paired with
+ * --define:import.meta.url=import_meta_url in the build:cli script.
+ */
+/* eslint-disable no-var, vars-on-top, camelcase, global-require,
+   import/prefer-default-export, import/no-mutable-exports */
+export var import_meta_url = require('url').pathToFileURL(__filename).href;
diff --git a/client/platform/desktop/backend/native/common.ts b/client/platform/desktop/backend/native/common.ts
index 5a0b904bb..5e3ca69bf 100644
--- a/client/platform/desktop/backend/native/common.ts
+++ b/client/platform/desktop/backend/native/common.ts
@@ -916,6 +916,9 @@ async function saveConfig(settings: Settings, datasetId: string, args: DatasetCo
   if (args.datasetInfo) {
     existing.datasetInfo = args.datasetInfo;
   }
+  if (args.frameLabels) {
+    existing.frameLabels = args.frameLabels;
+  }
 
   // The camera registration (transforms + the points behind them) is
   // persisted as standalone <camera>_to_<reference>_registration.json files
diff --git a/client/platform/desktop/backend/native/frameLabels.spec.ts b/client/platform/desktop/backend/native/frameLabels.spec.ts
new file mode 100644
index 000000000..c036fdc50
--- /dev/null
+++ b/client/platform/desktop/backend/native/frameLabels.spec.ts
@@ -0,0 +1,43 @@
+import { parseFrameLabelPresets, buildDefaultLabelTrack } from './frameLabels';
+
+const BOUNDS: [number, number, number, number] = [0, 0, 1920, 1080];
+
+describe('parseFrameLabelPresets', () => {
+  it('collects labels in order and accepts a default', () => {
+    const presets = parseFrameLabelPresets(['alpha', 'beta', 'gamma'], 'alpha');
+    expect(presets.labels).toEqual(['alpha', 'beta', 'gamma']);
+    expect(presets.defaultLabel).toBe('alpha');
+  });
+
+  it('accepts no default', () => {
+    expect(parseFrameLabelPresets(['alpha']).defaultLabel).toBeUndefined();
+  });
+
+  it('rejects empty names, duplicates, and unknown defaults', () => {
+    expect(() => parseFrameLabelPresets([''])).toThrow('may not be empty');
+    expect(() => parseFrameLabelPresets(['a', 'a'])).toThrow('Duplicate frame label');
+    expect(() => parseFrameLabelPresets(['a'], 'b')).toThrow('not one of the given labels');
+  });
+});
+
+describe('buildDefaultLabelTrack', () => {
+  it('covers every frame with interpolated full-frame keyframes', () => {
+    const track = buildDefaultLabelTrack('alpha', 100, BOUNDS);
+    expect([track.begin, track.end]).toEqual([0, 99]);
+    expect(track.confidencePairs).toEqual([['alpha', 1]]);
+    expect(track.features).toEqual([
+      {
+        frame: 0, bounds: BOUNDS, keyframe: true, interpolate: true,
+      },
+      {
+        frame: 99, bounds: BOUNDS, keyframe: true, interpolate: true,
+      },
+    ]);
+  });
+
+  it('handles single-frame media and honors trackId', () => {
+    const track = buildDefaultLabelTrack('alpha', 1, BOUNDS, 7);
+    expect([track.id, track.begin, track.end]).toEqual([7, 0, 0]);
+    expect(track.features).toHaveLength(1);
+  });
+});
diff --git a/client/platform/desktop/backend/native/frameLabels.ts b/client/platform/desktop/backend/native/frameLabels.ts
new file mode 100644
index 000000000..9a6ae82c9
--- /dev/null
+++ b/client/platform/desktop/backend/native/frameLabels.ts
@@ -0,0 +1,137 @@
+/**
+ * Frame label presets for imported datasets.
+ *
+ * A preset names the dataset's frame label set (shown as hotkeys by the
+ * annotator's frame label mode).  One label may additionally be marked as the
+ * default: it seeds a single full-frame interval track covering the whole
+ * dataset, ready for review and correction in the annotator.
+ */
+import npath from 'path';
+
+import type { TrackData } from 'vue-media-annotator/track';
+import type { RectBounds } from 'vue-media-annotator/utils';
+
+import { Settings } from 'platform/desktop/constants';
+import { checkMedia } from './mediaJobs';
+import * as common from './common';
+
+export interface FrameLabelPresets {
+  /** All label names, in the order given (hotkey order). */
+  labels: string[];
+  /** Label applied to the entire dataset on import, if any. */
+  defaultLabel?: string;
+}
+
+/** Validate label names and the optional whole-dataset default. */
+export function parseFrameLabelPresets(
+  specs: string[],
+  defaultLabel?: string,
+): FrameLabelPresets {
+  const labels: string[] = [];
+  specs.forEach((spec) => {
+    const label = spec.trim();
+    if (!label) {
+      throw new Error('Frame label names may not be empty');
+    }
+    if (labels.includes(label)) {
+      throw new Error(`Duplicate frame label: "${label}"`);
+    }
+    labels.push(label);
+  });
+  if (defaultLabel !== undefined) {
+    if (!labels.includes(defaultLabel)) {
+      throw new Error(
+        `Default frame label "${defaultLabel}" is not one of the given labels`,
+      );
+    }
+  }
+  return { labels, defaultLabel };
+}
+
+/** A single full-frame interval track covering every frame. */
+export function buildDefaultLabelTrack(
+  label: string,
+  frameCount: number,
+  bounds: RectBounds,
+  trackId = 0,
+): TrackData {
+  const end = Math.max(0, frameCount - 1);
+  const features = [{
+    frame: 0,
+    bounds,
+    keyframe: true,
+    interpolate: true,
+  }];
+  if (end > 0) {
+    features.push({
+      frame: end,
+      bounds,
+      keyframe: true,
+      interpolate: true,
+    });
+  }
+  return {
+    id: trackId,
+    meta: {},
+    attributes: {},
+    confidencePairs: [[label, 1]] as [string, number][],
+    features,
+    begin: 0,
+    end,
+  };
+}
+
+/**
+ * Apply frame label presets to a dataset: record the label set on its
+ * metadata and, when a default label is given, cover the whole dataset with
+ * one full-frame track of that label.
+ */
+export async function applyFrameLabelPresets(
+  settings: Settings,
+  datasetId: string,
+  presets: FrameLabelPresets,
+): Promise<void> {
+  if (presets.labels.length === 0) {
+    return;
+  }
+  const projectInfo = await common.getValidatedProjectDir(settings, datasetId);
+  const meta = await common.loadJsonConfig(projectInfo.datasetFileAbsPath);
+
+  await common.saveConfig(settings, datasetId, { frameLabels: presets.labels });
+
+  if (!presets.defaultLabel) {
+    return;
+  }
+  let frameCount: number;
+  let bounds: RectBounds;
+  if (meta.type === 'video') {
+    const media = await checkMedia(
+      npath.join(meta.originalBasePath, meta.originalVideoFile),
+    );
+    if (!media.videoDuration) {
+      throw new Error(`Could not determine duration of ${meta.originalVideoFile}`);
+    }
+    frameCount = Math.max(1, Math.floor(media.videoDuration * meta.fps));
+    bounds = [0, 0, media.videoDimensions.width, media.videoDimensions.height];
+  } else if (meta.type === 'image-sequence') {
+    frameCount = meta.originalImageFiles.length;
+    const media = await checkMedia(
+      npath.join(meta.originalBasePath, meta.originalImageFiles[0]),
+    );
+    bounds = [0, 0, media.videoDimensions.width, media.videoDimensions.height];
+  } else {
+    throw new Error(`Default frame labels are not supported for ${meta.type} datasets`);
+  }
+
+  const existing = await common.loadAnnotationFile(projectInfo.trackFileAbsPath);
+  const trackId = Object.keys(existing.tracks)
+    .reduce((high, id) => Math.max(high, Number.parseInt(id, 10) + 1), 0);
+
+  await common.saveDetections(settings, datasetId, {
+    tracks: {
+      upsert: [buildDefaultLabelTrack(presets.defaultLabel, frameCount, bounds, trackId)],
+      delete: [],
+    },
+    groups: { upsert: [], delete: [] },
+  });
+}
diff --git a/client/platform/desktop/backend/native/mediaJobs.ts b/client/platform/desktop/backend/native/mediaJobs.ts
index 5290bf510..dab3b87ff 100644
--- a/client/platform/desktop/backend/native/mediaJobs.ts
+++ b/client/platform/desktop/backend/native/mediaJobs.ts
@@ -49,6 +49,9 @@ interface FFProbeResults {
     width?: number;
     height?: number;
   }];
+  format?: {
+    duration?: string;
+  };
 }
 
 interface CheckMediaResults {
@@ -56,6 +59,8 @@ interface CheckMediaResults {
   originalFpsString: string;
   originalFps: number;
   videoDimensions: { width: number; height: number };
+  /** Container duration in seconds; absent for still images. */
+  videoDuration?: number;
 }
 
 function frameRateStringFromProbeStream(stream: {
@@ -178,12 +183,14 @@ async function checkMedia(file: string): Promise<CheckMediaResults> {
       height: videoStream[0].height || 0,
     };
     const misAligned = await checkFrameMisalignment(file);
+    const duration = Number.parseFloat(ffprobeJSON.format?.duration ?? '');
 
     return {
       websafe: !!websafe.length && !misAligned,
       originalFps,
       originalFpsString,
       videoDimensions,
+      ...(Number.isFinite(duration) ? { videoDuration: duration } : {}),
     };
   }
   throw Error(`FFProbe did not return a valid value for ${file}`);
diff --git a/client/platform/desktop/backend/native/viame.ts b/client/platform/desktop/backend/native/viame.ts
index 23c6c5a9a..0645929bb 100644
--- a/client/platform/desktop/backend/native/viame.ts
+++ b/client/platform/desktop/backend/native/viame.ts
@@ -13,7 +13,7 @@ import { cleanString } from 'platform/desktop/sharedUtils';
 import { serialize } from 'platform/desktop/backend/serializers/viame';
 import { observeChild } from 'platform/desktop/backend/native/processManager';
 import { convertMedia } from 'platform/desktop/backend/native/mediaJobs';
-import sendToRenderer from 'platform/desktop/background';
+import sendToRenderer from 'platform/desktop/backend/rendererBridge';
 
 import {
   MultiType,
diff --git a/client/platform/desktop/backend/rendererBridge.ts b/client/platform/desktop/backend/rendererBridge.ts
new file mode 100644
index 000000000..f4962490a
--- /dev/null
+++ b/client/platform/desktop/backend/rendererBridge.ts
@@ -0,0 +1,18 @@
+/**
+ * Backend-to-renderer messaging without importing the electron main module.
+ * The electron entrypoint registers a sender at startup; headless consumers
+ * (the divecli tool) never register one, and sends become no-ops.
+ */
+type RendererSender = (channel: string, payload?: unknown) => void;
+
+let sender: RendererSender | null = null;
+
+export function registerRendererSender(fn: RendererSender | null) {
+  sender = fn;
+}
+
+export default function sendToRenderer(channel: string, payload?: unknown) {
+  if (sender) {
+    sender(channel, payload);
+  }
+}
diff --git a/client/platform/desktop/background.ts b/client/platform/desktop/background.ts
index 4fb8d2a13..7fde8127a 100644
--- a/client/platform/desktop/background.ts
+++ b/client/platform/desktop/background.ts
@@ -6,6 +6,7 @@ import os from 'os';
 import path from 'path';
 
 import { closeAll as closeChildren } from './backend/native/processManager';
+import { registerRendererSender } from './backend/rendererBridge';
 import { listen, close as closeServer } from './backend/server';
 import ipcListen from './backend/ipcService';
 import {
@@ -394,3 +395,4 @@ export default function sendToRenderer(channel: string, payload?: unknown) {
     win.webContents.send(channel, payload);
   }
 }
+registerRendererSender(sendToRenderer);

From 212e6d7a6b7c04fc48848551fe9f7130c2dd87ad Mon Sep 17 00:00:00 2001
From: Matt Dawkins <matt.dawkins@kitware.com>
Date: Wed, 5 Aug 2026 17:09:24 -0400
Subject: [PATCH 3/5] divecli import: --native-playback to skip transcoding

---
 client/platform/desktop/backend/cli.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/client/platform/desktop/backend/cli.ts b/client/platform/desktop/backend/cli.ts
index c79bb8e8e..0a5043052 100755
--- a/client/platform/desktop/backend/cli.ts
+++ b/client/platform/desktop/backend/cli.ts
@@ -168,6 +168,11 @@ const { argv } = yargs
       describe: 'Annotation frame rate for the new dataset(s)',
       type: 'number',
     });
+    yargs.option('native-playback', {
+      describe: 'Skip transcoding; videos play via native frame extraction',
+      type: 'boolean',
+      default: false,
+    });
     yargs.option('frame-label', {
       describe: 'Frame label preset, repeatable: becomes part of the dataset\'s frame label set shown by the annotator\'s frame label mode',
       type: 'string',
@@ -297,6 +302,9 @@ if (argv._.includes('viame2json')) {
         if (argv.fps) {
           payload.jsonMeta.fps = argv.fps as number;
         }
+        if (argv.nativePlayback) {
+          payload.useNativePlayback = true;
+        }
         const conversionArgs = await common.finalizeMediaImport(settings, payload);
         const datasetId = conversionArgs.meta.id;
         await applyFrameLabelPresets(settings, datasetId, presets);

From 4090a917b7ce689d4ae43743cf22649fb1c9b919 Mon Sep 17 00:00:00 2001
From: Matt Dawkins <matt.dawkins@kitware.com>
Date: Wed, 5 Aug 2026 21:13:53 -0400
Subject: [PATCH 4/5] divecli import: --native-fps and fix the --fps payload
 field name

---
 client/platform/desktop/backend/cli.ts | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/client/platform/desktop/backend/cli.ts b/client/platform/desktop/backend/cli.ts
index 0a5043052..62ce96de5 100755
--- a/client/platform/desktop/backend/cli.ts
+++ b/client/platform/desktop/backend/cli.ts
@@ -165,9 +165,14 @@ const { argv } = yargs
       default: false,
     });
     yargs.option('fps', {
-      describe: 'Annotation frame rate for the new dataset(s)',
+      describe: 'Annotation frame rate for the new dataset(s); capped at the native video rate',
       type: 'number',
     });
+    yargs.option('native-fps', {
+      describe: 'Annotate videos at their native frame rate with no downsampling',
+      type: 'boolean',
+    });
+    yargs.conflicts('native-fps', 'fps');
     yargs.option('native-playback', {
       describe: 'Skip transcoding; videos play via native frame extraction',
       type: 'boolean',
@@ -300,7 +305,10 @@ if (argv._.includes('viame2json')) {
       try {
         const payload = await common.beginMediaImport(target);
         if (argv.fps) {
-          payload.jsonMeta.fps = argv.fps as number;
+          payload.jsonConfig.fps = argv.fps as number;
+        }
+        if (argv.nativeFps && payload.jsonConfig.originalFps > 0) {
+          payload.jsonConfig.fps = payload.jsonConfig.originalFps;
         }
         if (argv.nativePlayback) {
           payload.useNativePlayback = true;

From 03e8e573c25930ea8dcfa9acb85322a91ba660e0 Mon Sep 17 00:00:00 2001
From: Matt Dawkins <matt.dawkins@kitware.com>
Date: Wed, 5 Aug 2026 21:16:09 -0400
Subject: [PATCH 5/5] divecli import: videos default to their native frame rate

---
 client/platform/desktop/backend/cli.ts | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/client/platform/desktop/backend/cli.ts b/client/platform/desktop/backend/cli.ts
index 62ce96de5..ec62236f1 100755
--- a/client/platform/desktop/backend/cli.ts
+++ b/client/platform/desktop/backend/cli.ts
@@ -165,14 +165,9 @@ const { argv } = yargs
       default: false,
     });
     yargs.option('fps', {
-      describe: 'Annotation frame rate for the new dataset(s); capped at the native video rate',
+      describe: 'Annotation frame rate for the new dataset(s), capped at the native video rate; videos default to their native rate',
       type: 'number',
     });
-    yargs.option('native-fps', {
-      describe: 'Annotate videos at their native frame rate with no downsampling',
-      type: 'boolean',
-    });
-    yargs.conflicts('native-fps', 'fps');
     yargs.option('native-playback', {
       describe: 'Skip transcoding; videos play via native frame extraction',
       type: 'boolean',
@@ -306,8 +301,7 @@ if (argv._.includes('viame2json')) {
         const payload = await common.beginMediaImport(target);
         if (argv.fps) {
           payload.jsonConfig.fps = argv.fps as number;
-        }
-        if (argv.nativeFps && payload.jsonConfig.originalFps > 0) {
+        } else if (payload.jsonConfig.type === 'video' && payload.jsonConfig.originalFps > 0) {
           payload.jsonConfig.fps = payload.jsonConfig.originalFps;
         }
         if (argv.nativePlayback) {