Relative run mode (#1512)

* inti relative mode * send imediat update on mode change * add relative to test * don't persist offset mode * add test relative and update calc function * pass data from ssocket * add dev guard * spelling and comments * show relative in offset overview * remove comments * refactor: move totalDelay to _rundown * update clear naming and comments * remove old testing values
2026-08-12 19:03:47 +00:00 · 2025-04-19 21:36:54 +02:00
parent a94b10cb0f
commit dce87c3a81
17 changed files with 543 additions and 114 deletions
@@ -1,3 +1,6 @@
+import { OffsetMode } from 'ontime-types';
+import { dayInMs } from 'ontime-utils';
+
 import { calculateTimeUntilStart, formatTime, nowInMillis } from '../time';

 describe('nowInMillis()', () => {
@@ -40,82 +43,255 @@ describe('formatTime()', () => {
 });

 describe('calculateTimeUntilStart()', () => {
-  test('ontime', () => {
+  describe('Absolute offset mode', () => {
+    test('ontime', () => {
+      const test = {
+        timeStart: 100,
+        dayOffset: 0,
+        delay: 0,
+        currentDay: 0,
+        totalGap: 0,
+        clock: 90,
+        offset: 0,
+        offsetMode: OffsetMode.Absolute,
+        actualStart: null,
+        plannedStart: null,
+      };
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(10);
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(10);
+    });
+
+    test('running behind', () => {
+      const test = {
+        timeStart: 100,
+        dayOffset: 0,
+        delay: 0,
+        currentDay: 0,
+        totalGap: 0,
+        clock: 90,
+        offset: -20,
+        offsetMode: OffsetMode.Absolute,
+        actualStart: null,
+        plannedStart: null,
+      };
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(30);
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(30);
+    });
+
+    test('running ahead', () => {
+      const test = {
+        timeStart: 100,
+        dayOffset: 0,
+        delay: 0,
+        currentDay: 0,
+        totalGap: 0,
+        clock: 80,
+        offset: 10,
+        offsetMode: OffsetMode.Absolute,
+        actualStart: null,
+        plannedStart: null,
+      };
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(20); // <-- when running ahead the unlinked timer stays put
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(10);
+    });
+
+    test('running behind with enough gaps', () => {
+      const test = {
+        timeStart: 100,
+        dayOffset: 0,
+        delay: 0,
+        currentDay: 0,
+        totalGap: 20,
+        clock: 50,
+        offset: -20,
+        offsetMode: OffsetMode.Absolute,
+        actualStart: null,
+        plannedStart: null,
+      };
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(50); // <-- when gap is enough to compensate for the running behind
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(70); // This should not be possible
+    });
+
+    test('running behind with too little gaps', () => {
+      const test = {
+        timeStart: 100,
+        dayOffset: 0,
+        delay: 0,
+        currentDay: 0,
+        totalGap: 10,
+        clock: 50,
+        offset: -20,
+        offsetMode: OffsetMode.Absolute,
+        actualStart: 0,
+        plannedStart: 0,
+      };
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(60); // <-- when gap is not enough to compensate for the running behind it absorbs at much as possible
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(70); // This should not be possible
+    });
+  });
+
+  describe('Relative offset mode', () => {
+    test('basic function', () => {
+      const test = {
+        timeStart: 0,
+        dayOffset: 0,
+        delay: 0,
+        currentDay: 0,
+        totalGap: 0,
+        clock: 100,
+        actualStart: 100,
+        plannedStart: 0,
+        offset: 0,
+        offsetMode: OffsetMode.Relative,
+      };
+
+      const timeStartEvent2 = 10;
+      const timeStartEvent3 = 20;
+
+      //event 1 is the currently running event
+
+      //event 2
+      expect(calculateTimeUntilStart({ ...test, timeStart: timeStartEvent2, isLinkedToLoaded: true })).toBe(10);
+      expect(calculateTimeUntilStart({ ...test, timeStart: timeStartEvent2, isLinkedToLoaded: false })).toBe(10);
+
+      //event 3
+      expect(calculateTimeUntilStart({ ...test, timeStart: timeStartEvent3, isLinkedToLoaded: true })).toBe(20);
+      expect(calculateTimeUntilStart({ ...test, timeStart: timeStartEvent3, isLinkedToLoaded: false })).toBe(20);
+
+      // When clock advances by 5ms, time until start should decrease by 5ms
+      test.clock = 105;
+
+      //event 2
+      expect(calculateTimeUntilStart({ ...test, timeStart: timeStartEvent2, isLinkedToLoaded: true })).toBe(5);
+      expect(calculateTimeUntilStart({ ...test, timeStart: timeStartEvent2, isLinkedToLoaded: false })).toBe(5);
+
+      //event 3
+      expect(calculateTimeUntilStart({ ...test, timeStart: timeStartEvent3, isLinkedToLoaded: true })).toBe(15);
+      expect(calculateTimeUntilStart({ ...test, timeStart: timeStartEvent3, isLinkedToLoaded: false })).toBe(15);
+    });
+
+    test('gaps', () => {
+      const test = {
+        timeStart: 20,
+        dayOffset: 0,
+        delay: 0,
+        currentDay: 0,
+        totalGap: 10,
+        clock: 100,
+        actualStart: 100,
+        plannedStart: 0,
+        offset: 0,
+        offsetMode: OffsetMode.Relative,
+      };
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(20);
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(20);
+
+      // When clock advances by 5ms, time until start should decrease by 5ms
+      test.clock = 105;
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(15);
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(15);
+    });
+
+    test('added/remove time', () => {
+      const test = {
+        timeStart: 20,
+        dayOffset: 0,
+        delay: 0,
+        currentDay: 0,
+        totalGap: 0,
+        clock: 100,
+        actualStart: 100,
+        plannedStart: 0,
+        offset: 0,
+        offsetMode: OffsetMode.Relative,
+      };
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(20);
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(20);
+
+      test.offset = 5; // remove 5 with addtime - we are ahead of time
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(15);
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(20); // unlocked evets will stay on schedule
+
+      test.offset = -5; // add 5 with addtime - we are behind
+
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(25);
+      expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(25);
+    });
+
+    test('next day', () => {
+      const test = {
+        delay: 0,
+        currentDay: 0,
+        clock: 100,
+        actualStart: 100,
+        plannedStart: 0,
+        offset: 0,
+        offsetMode: OffsetMode.Relative,
+      };
+
+      // this event will start the current day
+      expect(
+        calculateTimeUntilStart({
+          ...test,
+          timeStart: 10,
+          dayOffset: 0,
+          totalGap: 0,
+          isLinkedToLoaded: false,
+        }),
+      ).toBe(10);
+
+      // this event will start the next day
+      // in absolute mode this would start in dayInMs - 100 since the gap would compensate
+      // but in relative mode with and actual start that is 100 offset it starts in dayInMs
+      expect(
+        calculateTimeUntilStart({
+          ...test,
+          timeStart: 0,
+          dayOffset: 1,
+          totalGap: dayInMs - 20,
+          isLinkedToLoaded: false,
+        }),
+      ).toBe(dayInMs);
+
+      // advancing 100ms
+      test.clock = 200;
+
+      expect(
+        calculateTimeUntilStart({
+          ...test,
+          timeStart: 0,
+          dayOffset: 1,
+          totalGap: dayInMs - 20,
+          isLinkedToLoaded: false,
+        }),
+      ).toBe(dayInMs - 100);
+    });
+  });
+
+  test('overlap with negative total gap', () => {
    const test = {
-      timeStart: 100,
      dayOffset: 0,
      delay: 0,
      currentDay: 0,
-      totalGap: 0,
-      clock: 90,
+      clock: 100,
+      actualStart: 100,
+      plannedStart: 0,
      offset: 0,
+      offsetMode: OffsetMode.Relative,
+      isLinkedToLoaded: false,
    };

-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(10);
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(10);
+    // the overlap will be pushed out to the expected available time
+    expect(calculateTimeUntilStart({ ...test, timeStart: 5, totalGap: -5 })).toBe(10);
+
+    test.clock = 105;
  });
-
-  test('running behind', () => {
-    const test = {
-      timeStart: 100,
-      dayOffset: 0,
-      delay: 0,
-      currentDay: 0,
-      totalGap: 0,
-      clock: 90,
-      offset: -20,
-    };
-
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(30);
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(30);
-  });
-
-  test('running ahead', () => {
-    const test = {
-      timeStart: 100,
-      dayOffset: 0,
-      delay: 0,
-      currentDay: 0,
-      totalGap: 0,
-      clock: 80,
-      offset: 10,
-    };
-
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(20); // <-- when running ahead the unlinked timer stays put
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(10);
-  });
-
-  test('running behind with enough gaps', () => {
-    const test = {
-      timeStart: 100,
-      dayOffset: 0,
-      delay: 0,
-      currentDay: 0,
-      totalGap: 20,
-      clock: 50,
-      offset: -20,
-    };
-
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(50);
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(70); // This should not be possible
-  });
-
-  test('running behind with to little gaps', () => {
-    const test = {
-      timeStart: 100,
-      dayOffset: 0,
-      delay: 0,
-      currentDay: 0,
-      totalGap: 10,
-      clock: 50,
-      offset: -20,
-    };
-
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: false })).toBe(60);
-    expect(calculateTimeUntilStart({ ...test, isLinkedToLoaded: true })).toBe(70); // This should not be possible
-  });
-
-  //TODO: more indepth testing,
-  // including day offset handling
-  // and more?
 });
@@ -1,4 +1,4 @@
-import { MaybeNumber, OntimeEvent, Settings, TimeFormat } from 'ontime-types';
+import { MaybeNumber, OffsetMode, OntimeEvent, Settings, TimeFormat } from 'ontime-types';
 import { dayInMs, formatFromMillis, MILLIS_PER_HOUR, MILLIS_PER_MINUTE, MILLIS_PER_SECOND } from 'ontime-utils';

 import { FORMAT_12, FORMAT_24 } from '../../viewerConfig';
@@ -140,8 +140,8 @@ export function useTimeUntilStart(
    isLinkedToLoaded: boolean;
  },
 ): number {
-  const { offset, clock, currentDay } = useTimeUntilData();
-  return calculateTimeUntilStart({ ...data, currentDay, clock, offset });
+  const { offset, clock, currentDay, offsetMode, actualStart, plannedStart } = useTimeUntilData();
+  return calculateTimeUntilStart({ ...data, currentDay, clock, offset, offsetMode, actualStart, plannedStart });
 }

 /**
@@ -160,9 +160,24 @@ export function calculateTimeUntilStart(
    isLinkedToLoaded: boolean;
    clock: number;
    offset: number;
+    offsetMode: OffsetMode;
+    actualStart: MaybeNumber;
+    plannedStart: MaybeNumber;
  },
 ): number {
-  const { timeStart, dayOffset, currentDay, totalGap, isLinkedToLoaded, clock, offset, delay } = data;
+  const {
+    timeStart,
+    dayOffset,
+    currentDay,
+    totalGap,
+    isLinkedToLoaded,
+    clock,
+    offset,
+    delay,
+    offsetMode,
+    actualStart,
+    plannedStart,
+  } = data;

  //How many days from the currently running event to this one
  const relativeDayOffset = dayOffset - currentDay;
@@ -172,20 +187,23 @@ export function calculateTimeUntilStart(
  //The normalised start time of this event relative to the currently running event
  const normalisedTimeStart = delayedStart + relativeDayOffset * dayInMs;

-  const offsetTimestart = normalisedTimeStart - offset;
-  const offsetTimeUntil = offsetTimestart - clock;
+  let relativeStartOffset = 0;
+
+  if (offsetMode === OffsetMode.Relative) {
+    relativeStartOffset = (actualStart ?? 0) - (plannedStart ?? 0);
+  }
+
+  const scheduledTimeUntil = normalisedTimeStart - clock + relativeStartOffset;
+
+  const offsetTimeUntil = scheduledTimeUntil - offset;

  if (isLinkedToLoaded) {
    //if we are directly linked back to the loaded event we just follow the offset
    return offsetTimeUntil;
  }

-  const scheduledTimeUntil = normalisedTimeStart - clock;
-
-  const isAheadOfSchedule = offset >= 0;
-  const gapsCanCompensadeForOffset = totalGap + offset >= 0;
-
-  if (isAheadOfSchedule || gapsCanCompensadeForOffset) {
+  const gapsCanCompensateForOffset = totalGap + offset >= 0;
+  if (gapsCanCompensateForOffset) {
    // if we are ahead of schedule or the gap can compensate for the amount we are behind then expect to start at the scheduled time
    return scheduledTimeUntil;
  }