fix: ignore pieces that are replaced before the in-point by another piece.

Author: justandras

packages/job-worker/src/playout/lookahead/index.ts

@@ -24,6 +24,7 @@ import { LookaheadTimelineObject } from './findObjects'
 import { hasPieceInstanceDefinitelyEnded } from '../timeline/lib'
 import { DBPart } from '@sofie-automation/corelib/dist/dataModel/Part'
 import { ReadonlyDeep } from 'type-fest'
+import { filterPieceInstancesForNextPartWithOffset } from './lookaheadOffset'
 
 const LOOKAHEAD_OBJ_PRIORITY = 0.1
 
@@ -118,7 +119,10 @@ export async function getLookeaheadObjects(
 					part: partInstancesInfo0.next.partInstance,
 					onTimeline: !!partInstancesInfo0.current?.partInstance?.part?.autoNext, //TODO -QL
 					nowInPart: partInstancesInfo0.next.nowInPart,
-					allPieces: partInstancesInfo0.next.pieceInstances,
+					allPieces: filterPieceInstancesForNextPartWithOffset(
+						partInstancesInfo0.next.pieceInstances,
+						playoutModel.playlist.nextTimeOffset
+					),
 					calculatedTimings: partInstancesInfo0.next.calculatedTimings,
 			  })
 			: undefined,

packages/job-worker/src/playout/lookahead/lookaheadOffset.ts

@@ -6,19 +6,16 @@ import { getBestPieceInstanceId, LookaheadTimelineObject } from './findObjects'
 import { PartAndPieces, PieceInstanceWithObjectMap } from './util'
 import { TimelineEnable } from 'superfly-timeline'
 import { TimelineObjectCoreExt } from '@sofie-automation/blueprints-integration'
-
-export type StartInfo = { start: number } | { while: number } | undefined
+import { PieceInstanceWithTimings } from '@sofie-automation/corelib/dist/playout/processAndPrune'
 
 /**
  * Computes a full {@link LookaheadTimelineObject} for a given piece/object pair,
- * including the correct `lookaheadOffset` based on explicit numeric `start` or
- * `while > 1` expressions.
+ * including the correct `lookaheadOffset` based on explicit numeric `start` or `while` expressions.
  *
  * This function:
  * - Ignores objects whose `enable` is an array (unsupported for lookahead)
  * - Extracts a usable numeric start reference from both the object and its parent piece
- * - Supports lookahead semantics where `enable.while > 1` acts like an implicit start value
- *   but the offset is added *to the while value* instead of replacing start
+ * - Supports lookahead semantics where `enable.while >= 1` acts like an implicit start value
  * - Returns `undefined` when lookahead cannot be computed safely
  *
  * @param obj - The timeline object associated with the piece and layer. If `undefined`,
@@ -50,17 +47,16 @@ export function computeLookaheadObject(
 
 	if (Array.isArray(enable)) return undefined
 
-	const startInfo = getStartInfoFromEnable(enable)
-	const pieceStartInfo = getStartInfoFromEnable(rawPiece.piece.enable)
+	const objStart = getStartValueFromEnable(enable)
+	const pieceStart = getStartValueFromEnable(rawPiece.piece.enable)
 
 	// We make sure to only consider objects for lookahead that have an explicit numeric start/while value. (while = 1 and 0 is considered boolean)
-	if (!pieceStartInfo) return undefined
+	if (pieceStart === undefined) return undefined
 
 	let lookaheadOffset: number | undefined
 	// Only calculate lookaheadOffset if needed
 	if (nextTimeOffset) {
-		const pieceStart = 'start' in pieceStartInfo ? pieceStartInfo.start : pieceStartInfo.while
-		lookaheadOffset = computeLookaheadOffset(nextTimeOffset, pieceStart, startInfo)
+		lookaheadOffset = computeLookaheadOffset(nextTimeOffset, pieceStart, objStart)
 	}
 
 	return literal<LookaheadTimelineObject>({
@@ -70,108 +66,144 @@ export function computeLookaheadObject(
 		pieceInstanceId: getBestPieceInstanceId(rawPiece),
 		infinitePieceInstanceId: rawPiece.infinite?.infiniteInstanceId,
 		partInstanceId: partInstanceId ?? protectString(unprotectString(partInfo.part._id)),
-		lookaheadOffset,
+		...(lookaheadOffset !== undefined ? { lookaheadOffset } : {}),
 	})
 }
 
 /**
- * Computes a lookahead offset for an object based on the next part's start time,
- * the piece's start time, and the object's enable expression (represented as a {@link StartInfo}).
- *
- * This function supports two mutually exclusive modes:
- *
- * **1. `start` mode (`{ start: number | undefined }`)**
- *    - A numeric `start` value is treated as the object's explicit start time.
- *    - The offset is calculated as:
- *      ```
- *      offset = nextTimeOffset - pieceStart - start
- *      ```
- *    - Returns `undefined` if the resulting offset is not positive.
- *
- * **2. `while` mode (`{ while: number | undefined }`)**
- *    - `while = 0` is treated as a boolean "false" → no lookahead offset.
- *    - `while = 1` is treated as a boolean "true" equivalent to `start = 0`,
- *      meaning the object starts immediately.
- *    - Any `while > 1` value is treated as a timestamp signifying when the object
- *      is considered to begin, and the lookahead offset is added *on top of*
- *      the while value. Example:
- *      ```
- *      effectiveStart = (while === 1 ? 0 : while)
- *      offset = nextTimeOffset - pieceStart - effectiveStart
- *      returned = while + offset
- *      ```
- *    - Returns `undefined` if the computed offset is not positive.
+ * Computes a lookahead offset for an object based on the piece's start time
+ * and the object's start time, relative to the next part's start time.
  *
  * @param nextTimeOffset - The upcoming part's start time (or similar time anchor).
  *                         If undefined, no lookahead offset is produced.
  * @param pieceStart - The start time of the piece this object belongs to.
- * @param info - A `StartInfo` discriminated union describing whether the object
- *               uses a numeric `start` or a `while` expression.
+ * @param objStart - The explicit start time of the object (relative to the piece's start time).
  *
  * @returns A positive lookahead offset, or `undefined` if lookahead cannot be
  *          determined or would be non-positive.
  */
 function computeLookaheadOffset(
 	nextTimeOffset: number | undefined,
 	pieceStart: number,
-	info: StartInfo
+	objStart?: number
 ): number | undefined {
-	if (nextTimeOffset === undefined || !info) return undefined
-
-	if ('start' in info) {
-		const offset = nextTimeOffset - pieceStart - info.start
-		return offset > 0 ? offset : undefined
-	}
-
-	if ('while' in info) {
-		// while == 0 is treated as false
-		if (info.while !== 0) {
-			// while == 1 is treated as true which is equal to start == 0. Any other value means the object starts at that timestamp and doesn't have an end.
-			const offset = nextTimeOffset - pieceStart - info.while === 1 ? 0 : info.while
-			return offset > 0 ? info.while + offset : undefined
-		}
-	}
+	if (nextTimeOffset === undefined || objStart === undefined) return undefined
 
-	return undefined
+	const offset = nextTimeOffset - pieceStart - objStart
+	return offset > 0 ? offset : undefined
 }
 
 /**
- * Extracts a numeric start reference from a {@link TimelineEnable} object,
- * returning a {@link StartInfo} describing how lookahead should be calculated.
+ * Extracts a numeric start reference from a {@link TimelineEnable} object
  *
- * The function handles two mutually exclusive modes:
+ * The function handles two mutually exclusive cases:
  *
  * **1. `start` mode (`{ start: number }`)**
  *    - If `enable.start` is a numeric value, it is returned as `start`.
  *    - If `enable.start` is the string `"now"`, it is treated as `0`.
  *
  * **2. `while` mode (`{ while: number }`)**
- *    - If `enable.while` is numeric and greater than 1, it is returned as `while`.
- *    - This indicates the object should be considered as starting at this
- *      timestamp, with any lookahead offset added on top.
+ *    - If `enable.while` is numeric and greater than 1, it's value is returned as is.
+ *    - If `enable.while` is numeric and equal to 1 it's treated as `0`.
  *
  * If no usable numeric `start` or `while` expression exists, the function returns `undefined`.
  *
  * @param enable - The timeline object's enable expression to extract start info from.
- * @returns A {@link StartInfo} object containing either `start` or `while`, or `undefined`
- *          if no numeric value is available for lookahead calculations.
+ * @returns the relative start value of the object or undefined if there is no explicit value.
  */
-function getStartInfoFromEnable(enable: TimelineEnable): StartInfo {
+function getStartValueFromEnable(enable: TimelineEnable): number | undefined {
 	// Case: start is a number
 	if (typeof enable.start === 'number') {
-		return { start: enable.start }
+		return enable.start
 	}
 
 	// Case: start is "now"
 	if (enable.start === 'now') {
-		return { start: 0 }
+		return 0
 	}
 
-	// Case: while is numeric and > 1 → offset must be added to while
-	if (typeof enable.while === 'number' && enable.while > 1) {
-		return { while: enable.while }
+	// Case: while is numeric
+	if (typeof enable.while === 'number') {
+		// while > 1 we treat it as a start value
+		if (enable.while > 1) {
+			return enable.while
+		}
+		// while === 1 we treat it as a `0` start value
+		else if (enable.while === 1) {
+			return 0
+		}
 	}
 
 	// No usable numeric expressions
 	return undefined
 }
+
+/**
+ * Filters piece instances for the "next" part when a `nextTimeOffset` is defined.
+ *
+ * This function ensures that we only take into account each layer's relevant piece before
+ * or at the `nextTimeOffset`, while also preserving all pieces starting after the offset.
+ *
+ * This is needed to ignore pieces that start before the offset, but then are replaced by another piece at the offset.
+ * Without ignoring them the lookahead logic would treat the next part as if it was queued from it's start.
+ *
+ * **Filtering rules:**
+ * - If `nextTimeOffset` is not set (0, null, undefined), the original list is returned.
+ * - Pieces are grouped based on their `outputLayerId`.
+ * - For each layer:
+ *   - We only keep pieces with the **latest start time** where `start/while <= nextTimeOffset`
+ *   - All pieces *after* `nextTimeOffset` are kept for future lookaheads.
+ *
+ * The result is a flattened list of the selected pieces across all layers.
+ *
+ * @param {PieceInstanceWithTimings[]} pieces
+ *        The list of piece instances to filter.
+ *
+ * @param {number | null | undefined} nextTimeOffset
+ *        The time offset (in part time) that defines relevance.
+ *        Pieces are compared based on their enable.start value.
+ *
+ * @returns {PieceInstanceWithTimings[]}
+ *          A filtered list of pieces containing only the relevant pieces per layer.
+ */
+export function filterPieceInstancesForNextPartWithOffset(
+	pieces: PieceInstanceWithTimings[],
+	nextTimeOffset: number | null | undefined
+): PieceInstanceWithTimings[] {
+	if (!nextTimeOffset) return pieces
+
+	// Group pieces by layer
+	const layers = new Map<string, PieceInstanceWithTimings[]>()
+	for (const p of pieces) {
+		const layer = p.piece.outputLayerId || '__noLayer__'
+		if (!layers.has(layer)) layers.set(layer, [])
+		layers.get(layer)!.push(p)
+	}
+
+	const result: PieceInstanceWithTimings[] = []
+
+	for (const layerPieces of layers.values()) {
+		const beforeOrAt: PieceInstanceWithTimings[] = []
+		const after: PieceInstanceWithTimings[] = []
+
+		for (const piece of layerPieces) {
+			const pieceStart = getStartValueFromEnable(piece.piece.enable)
+
+			if (pieceStart !== undefined) {
+				if (pieceStart <= nextTimeOffset) beforeOrAt.push(piece)
+				else after.push(piece)
+			}
+		}
+
+		// Pick the relevant piece before/at nextTimeOffset
+		if (beforeOrAt.length > 0) {
+			const best = beforeOrAt.reduce((a, b) => (a.piece.enable.start > b.piece.enable.start ? a : b))
+			result.push(best)
+		}
+
+		// Keep all pieces after nextTimeOffset for future lookaheads.
+		result.push(...after)
+	}
+
+	return result
+}