T-Timers expected time estimates

packages/blueprints-integration/src/context/tTimersContext.ts

@@ -71,6 +71,51 @@ export interface IPlaylistTTimer {
 	 * @returns True if the timer was restarted, false if it could not be restarted
 	 */
 	restart(): boolean
+
+	/**
+	 * Clear any estimate (manual or anchor-based) for this timer
+	 * This removes both manual estimates set via setEstimateTime/setEstimateDuration
+	 * and automatic estimates based on anchor parts set via setEstimateAnchorPart.
+	 */
+	clearEstimate(): void
+
+	/**
+	 * Set the anchor part for automatic estimate calculation
+	 * When set, the server automatically calculates when we expect to reach this part
+	 * based on remaining part durations, and updates the estimate accordingly.
+	 * Clears any manual estimate set via setEstimateTime/setEstimateDuration.
+	 * @param partId The ID of the part to use as timing anchor
+	 */
+	setEstimateAnchorPart(partId: string): void
+
+	/**
+	 * Set the anchor part for automatic estimate calculation, looked up by its externalId.
+	 * This is a convenience method when you know the externalId of the part (e.g. set during ingest)
+	 * but not its internal PartId. If no part with the given externalId is found, this is a no-op.
+	 * Clears any manual estimate set via setEstimateTime/setEstimateDuration.
+	 * @param externalId The externalId of the part to use as timing anchor
+	 */
+	setEstimateAnchorPartByExternalId(externalId: string): void
+
+	/**
+	 * Manually set the estimate as an absolute timestamp
+	 * Use this when you have custom logic for calculating when you expect to reach a timing point.
+	 * Clears any anchor part set via setAnchorPart.
+	 * @param time Unix timestamp (milliseconds) when we expect to reach the timing point
+	 * @param paused If true, we're currently delayed/pushing (estimate won't update with time passing).
+	 *               If false (default), we're progressing normally (estimate counts down in real-time).
+	 */
+	setEstimateTime(time: number, paused?: boolean): void
+
+	/**
+	 * Manually set the estimate as a relative duration from now
+	 * Use this when you want to express the estimate as "X milliseconds from now".
+	 * Clears any anchor part set via setAnchorPart.
+	 * @param duration Milliseconds until we expect to reach the timing point
+	 * @param paused If true, we're currently delayed/pushing (estimate won't update with time passing).
+	 *               If false (default), we're progressing normally (estimate counts down in real-time).
+	 */
+	setEstimateDuration(duration: number, paused?: boolean): void
 }
 
 export type IPlaylistTTimerState =

packages/corelib/src/dataModel/RundownPlaylist.ts

@@ -130,21 +130,61 @@ export interface RundownTTimerModeTimeOfDay {
  * Timing state for a timer, optimized for efficient client rendering.
  * When running, the client calculates current time from zeroTime.
  * When paused, the duration is frozen and sent directly.
+ * pauseTime indicates when the timer should automatically pause (when current part ends and overrun begins).
+ *
+ * Client rendering logic:
+ * ```typescript
+ * if (state.paused === true) {
+ *   // Manually paused by user or already pushing/overrun
+ *   duration = state.duration
+ * } else if (state.pauseTime && now >= state.pauseTime) {
+ *   // Auto-pause at overrun (current part ended)
+ *   duration = state.zeroTime - state.pauseTime
+ * } else {
+ *   // Running normally
+ *   duration = state.zeroTime - now
+ * }
+ * ```
  */
 export type TimerState =
 	| {
 			/** Whether the timer is paused */
 			paused: false
 			/** The absolute timestamp (ms) when the timer reaches/reached zero */
 			zeroTime: number
+			/** Optional timestamp when the timer should pause (when current part ends) */
+			pauseTime?: number | null
 	  }
 	| {
 			/** Whether the timer is paused */
 			paused: true
 			/** The frozen duration value in milliseconds */
 			duration: number
+			/** Optional timestamp when the timer should pause (null when already paused/pushing) */
+			pauseTime?: number | null
 	  }
 
+/**
+ * Calculate the current duration for a timer state.
+ * Handles paused, auto-pause (pauseTime), and running states.
+ *
+ * @param state The timer state
+ * @param now Current timestamp in milliseconds
+ * @returns The current duration in milliseconds
+ */
+export function timerStateToDuration(state: TimerState, now: number): number {
+	if (state.paused) {
+		// Manually paused by user or already pushing/overrun
+		return state.duration
+	} else if (state.pauseTime && now >= state.pauseTime) {
+		// Auto-pause at overrun (current part ended)
+		return state.zeroTime - state.pauseTime
+	} else {
+		// Running normally
+		return state.zeroTime - now
+	}
+}
+
 export type RundownTTimerIndex = 1 | 2 | 3
 
 export interface RundownTTimer {
@@ -168,15 +208,18 @@ export interface RundownTTimer {
 	/** The estimated time when we expect to reach the anchor part, for calculating over/under diff.
 	 *
 	 * Based on scheduled durations of remaining parts and segments up to the anchor.
-	 * Running means we are progressing towards the anchor (estimate moves with real time).
-	 * Paused means we are pushing (e.g. overrunning the current segment, so the anchor is being delayed).
+	 * The over/under diff is calculated as the difference between this estimate and the timer's target (state.zeroTime).
+	 *
+	 * Running means we are progressing towards the anchor (estimate moves with real time)
+	 * Paused means we are pushing (e.g. overrunning the current segment, so the anchor is being delayed)
 	 *
-	 * Calculated automatically when anchorPartId is set, or can be set manually by a blueprint.
+	 * Calculated automatically when anchorPartId is set, or can be set manually by a blueprint if custom logic is needed.
 	 */
 	estimateState?: TimerState
 
-	/** The target Part that this timer is counting towards (the "timing anchor").
+	/** The target Part that this timer is counting towards (the "timing anchor")
 	 *
+	 * This is typically a "break" part or other milestone in the rundown.
 	 * When set, the server calculates estimateState based on when we expect to reach this part.
 	 * If not set, estimateState is not calculated automatically but can still be set manually by a blueprint.
 	 */

packages/corelib/src/worker/studio.ts

@@ -126,6 +126,12 @@ export enum StudioJobs {
 	 */
 	OnTimelineTriggerTime = 'onTimelineTriggerTime',
 
+	/**
+	 * Recalculate T-Timer estimates based on current playlist state
+	 * Called after setNext, takes, and ingest changes to update timing anchor estimates
+	 */
+	RecalculateTTimerEstimates = 'recalculateTTimerEstimates',
+
 	/**
 	 * Update the timeline with a regenerated Studio Baseline
 	 * Has no effect if a Playlist is active
@@ -412,6 +418,8 @@ export type StudioJobFunc = {
 	[StudioJobs.OnPlayoutPlaybackChanged]: (data: OnPlayoutPlaybackChangedProps) => void
 	[StudioJobs.OnTimelineTriggerTime]: (data: OnTimelineTriggerTimeProps) => void
 
+	[StudioJobs.RecalculateTTimerEstimates]: () => void
+
 	[StudioJobs.UpdateStudioBaseline]: () => string | false
 	[StudioJobs.CleanupEmptyPlaylists]: () => void
 

packages/job-worker/src/blueprints/context/OnSetAsNextContext.ts

@@ -50,7 +50,7 @@ export class OnSetAsNextContext
 		public readonly manuallySelected: boolean
 	) {
 		super(contextInfo, context, showStyle, watchedPackages)
-		this.#tTimersService = TTimersService.withPlayoutModel(playoutModel)
+		this.#tTimersService = TTimersService.withPlayoutModel(playoutModel, context)
 	}
 
 	public get quickLoopInfo(): BlueprintQuickLookInfo | null {

packages/job-worker/src/blueprints/context/OnTakeContext.ts

@@ -66,7 +66,7 @@ export class OnTakeContext extends ShowStyleUserContext implements IOnTakeContex
 	) {
 		super(contextInfo, _context, showStyle, watchedPackages)
 		this.isTakeAborted = false
-		this.#tTimersService = TTimersService.withPlayoutModel(_playoutModel)
+		this.#tTimersService = TTimersService.withPlayoutModel(_playoutModel, _context)
 	}
 
 	async getUpcomingParts(limit: number = 5): Promise<ReadonlyDeep<IBlueprintPart[]>> {

packages/job-worker/src/blueprints/context/RundownActivationContext.ts

@@ -48,7 +48,7 @@ export class RundownActivationContext extends RundownEventContext implements IRu
 		this._previousState = options.previousState
 		this._currentState = options.currentState
 
-		this.#tTimersService = TTimersService.withPlayoutModel(this._playoutModel)
+		this.#tTimersService = TTimersService.withPlayoutModel(this._playoutModel, this._context)
 	}
 
 	get previousState(): IRundownActivationContextState {

packages/job-worker/src/blueprints/context/SyncIngestUpdateToPartInstanceContext.ts

@@ -3,6 +3,7 @@ import { PieceInstance } from '@sofie-automation/corelib/dist/dataModel/PieceIns
 import { normalizeArrayToMap, omit } from '@sofie-automation/corelib/dist/lib'
 import { protectString, protectStringArray, unprotectStringArray } from '@sofie-automation/corelib/dist/protectedString'
 import { PlayoutPartInstanceModel } from '../../playout/model/PlayoutPartInstanceModel.js'
+import { PlayoutModel } from '../../playout/model/PlayoutModel.js'
 import { ReadonlyDeep } from 'type-fest'
 import _ from 'underscore'
 import { ContextInfo } from './CommonContext.js'
@@ -45,6 +46,7 @@ export class SyncIngestUpdateToPartInstanceContext
 	implements ISyncIngestUpdateToPartInstanceContext
 {
 	readonly #context: JobContext
+	readonly #playoutModel: PlayoutModel
 	readonly #proposedPieceInstances: Map<PieceInstanceId, ReadonlyDeep<PieceInstance>>
 	readonly #tTimersService: TTimersService
 	readonly #changedTTimers = new Map<RundownTTimerIndex, RundownTTimer>()
@@ -61,6 +63,7 @@ export class SyncIngestUpdateToPartInstanceContext
 
 	constructor(
 		context: JobContext,
+		playoutModel: PlayoutModel,
 		contextInfo: ContextInfo,
 		studio: ReadonlyDeep<JobStudio>,
 		showStyleCompound: ReadonlyDeep<ProcessedShowStyleCompound>,
@@ -80,12 +83,18 @@ export class SyncIngestUpdateToPartInstanceContext
 		)
 
 		this.#context = context
+		this.#playoutModel = playoutModel
 		this.#partInstance = partInstance
 
 		this.#proposedPieceInstances = normalizeArrayToMap(proposedPieceInstances, '_id')
-		this.#tTimersService = new TTimersService(playlist.tTimers, (updatedTimer) => {
-			this.#changedTTimers.set(updatedTimer.index, updatedTimer)
-		})
+		this.#tTimersService = new TTimersService(
+			playlist.tTimers,
+			(updatedTimer) => {
+				this.#changedTTimers.set(updatedTimer.index, updatedTimer)
+			},
+			this.#playoutModel,
+			this.#context
+		)
 	}
 
 	getTimer(index: RundownTTimerIndex): IPlaylistTTimer {

packages/job-worker/src/blueprints/context/adlibActions.ts

@@ -117,7 +117,7 @@ export class ActionExecutionContext extends ShowStyleUserContext implements IAct
 		private readonly partAndPieceInstanceService: PartAndPieceInstanceActionService
 	) {
 		super(contextInfo, _context, showStyle, watchedPackages)
-		this.#tTimersService = TTimersService.withPlayoutModel(_playoutModel)
+		this.#tTimersService = TTimersService.withPlayoutModel(_playoutModel, _context)
 	}
 
 	async getUpcomingParts(limit: number = 5): Promise<ReadonlyDeep<IBlueprintPart[]>> {

packages/job-worker/src/blueprints/context/services/TTimersService.ts

@@ -3,7 +3,10 @@ import type {
 	IPlaylistTTimerState,
 } from '@sofie-automation/blueprints-integration/dist/context/tTimersContext'
 import type { RundownTTimer, RundownTTimerIndex } from '@sofie-automation/corelib/dist/dataModel/RundownPlaylist'
-import { assertNever } from '@sofie-automation/corelib/dist/lib'
+import type { TimerState } from '@sofie-automation/corelib/dist/dataModel/RundownPlaylist'
+import type { PartId } from '@sofie-automation/corelib/dist/dataModel/Ids'
+import { assertNever, literal } from '@sofie-automation/corelib/dist/lib'
+import { protectString, unprotectString } from '@sofie-automation/corelib/dist/protectedString'
 import type { PlayoutModel } from '../../../playout/model/PlayoutModel.js'
 import { ReadonlyDeep } from 'type-fest'
 import {
@@ -14,27 +17,36 @@ import {
 	restartTTimer,
 	resumeTTimer,
 	validateTTimerIndex,
+	recalculateTTimerEstimates,
 } from '../../../playout/tTimers.js'
 import { getCurrentTime } from '../../../lib/time.js'
+import type { JobContext } from '../../../jobs/index.js'
 
 export class TTimersService {
 	readonly timers: [PlaylistTTimerImpl, PlaylistTTimerImpl, PlaylistTTimerImpl]
 
 	constructor(
 		timers: ReadonlyDeep<RundownTTimer[]>,
-		emitChange: (updatedTimer: ReadonlyDeep<RundownTTimer>) => void
+		emitChange: (updatedTimer: ReadonlyDeep<RundownTTimer>) => void,
+		playoutModel: PlayoutModel,
+		jobContext: JobContext
 	) {
 		this.timers = [
-			new PlaylistTTimerImpl(timers[0], emitChange),
-			new PlaylistTTimerImpl(timers[1], emitChange),
-			new PlaylistTTimerImpl(timers[2], emitChange),
+			new PlaylistTTimerImpl(timers[0], emitChange, playoutModel, jobContext),
+			new PlaylistTTimerImpl(timers[1], emitChange, playoutModel, jobContext),
+			new PlaylistTTimerImpl(timers[2], emitChange, playoutModel, jobContext),
 		]
 	}
 
-	static withPlayoutModel(playoutModel: PlayoutModel): TTimersService {
-		return new TTimersService(playoutModel.playlist.tTimers, (updatedTimer) => {
-			playoutModel.updateTTimer(updatedTimer)
-		})
+	static withPlayoutModel(playoutModel: PlayoutModel, jobContext: JobContext): TTimersService {
+		return new TTimersService(
+			playoutModel.playlist.tTimers,
+			(updatedTimer) => {
+				playoutModel.updateTTimer(updatedTimer)
+			},
+			playoutModel,
+			jobContext
+		)
 	}
 
 	getTimer(index: RundownTTimerIndex): IPlaylistTTimer {
@@ -50,6 +62,8 @@ export class TTimersService {
 
 export class PlaylistTTimerImpl implements IPlaylistTTimer {
 	readonly #emitChange: (updatedTimer: ReadonlyDeep<RundownTTimer>) => void
+	readonly #playoutModel: PlayoutModel
+	readonly #jobContext: JobContext
 
 	#timer: ReadonlyDeep<RundownTTimer>
 
@@ -96,9 +110,18 @@ export class PlaylistTTimerImpl implements IPlaylistTTimer {
 		}
 	}
 
-	constructor(timer: ReadonlyDeep<RundownTTimer>, emitChange: (updatedTimer: ReadonlyDeep<RundownTTimer>) => void) {
+	constructor(
+		timer: ReadonlyDeep<RundownTTimer>,
+		emitChange: (updatedTimer: ReadonlyDeep<RundownTTimer>) => void,
+		playoutModel: PlayoutModel,
+		jobContext: JobContext
+	) {
 		this.#timer = timer
 		this.#emitChange = emitChange
+		this.#playoutModel = playoutModel
+		this.#jobContext = jobContext
+
+		validateTTimerIndex(timer.index)
 	}
 
 	setLabel(label: string): void {
@@ -168,4 +191,58 @@ export class PlaylistTTimerImpl implements IPlaylistTTimer {
 		this.#emitChange(newTimer)
 		return true
 	}
+
+	clearEstimate(): void {
+		this.#timer = {
+			...this.#timer,
+			anchorPartId: undefined,
+			estimateState: undefined,
+		}
+		this.#emitChange(this.#timer)
+	}
+
+	setEstimateAnchorPart(partId: string): void {
+		this.#timer = {
+			...this.#timer,
+			anchorPartId: protectString<PartId>(partId),
+			estimateState: undefined, // Clear manual estimate
+		}
+		this.#emitChange(this.#timer)
+
+		// Recalculate estimates immediately since we already have the playout model
+		recalculateTTimerEstimates(this.#jobContext, this.#playoutModel)
+	}
+
+	setEstimateAnchorPartByExternalId(externalId: string): void {
+		const part = this.#playoutModel.getAllOrderedParts().find((p) => p.externalId === externalId)
+		if (!part) return
+
+		this.setEstimateAnchorPart(unprotectString(part._id))
+	}
+
+	setEstimateTime(time: number, paused: boolean = false): void {
+		const estimateState: TimerState = paused
+			? literal<TimerState>({ paused: true, duration: time - getCurrentTime() })
+			: literal<TimerState>({ paused: false, zeroTime: time })
+
+		this.#timer = {
+			...this.#timer,
+			anchorPartId: undefined, // Clear automatic anchor
+			estimateState,
+		}
+		this.#emitChange(this.#timer)
+	}
+
+	setEstimateDuration(duration: number, paused: boolean = false): void {
+		const estimateState: TimerState = paused
+			? literal<TimerState>({ paused: true, duration })
+			: literal<TimerState>({ paused: false, zeroTime: getCurrentTime() + duration })
+
+		this.#timer = {
+			...this.#timer,
+			anchorPartId: undefined, // Clear automatic anchor
+			estimateState,
+		}
+		this.#emitChange(this.#timer)
+	}
 }