retold-remote 0.0.23 → 0.0.26

package/source/server/RetoldRemote-UltravisorOperations.js

@@ -159,16 +159,17 @@ function _buildPipelineOperation(pConfig)
 				Address: '{~D:Record.Operation.' + pConfig.AddressParam + '~}'
 			},
 			['Address'],
-			['URL', 'Filename', 'BeaconName']),
+			['URL', 'Filename', 'BeaconName', 'LocalPath', 'Strategy']),
 
 		_taskNode(tmpTransferHash, 'file-transfer', 'File Transfer', 490, 180,
 			{
 				SourceURL: '{~D:Record.TaskOutputs.' + tmpResolveHash + '.URL~}',
+				SourceLocalPath: '{~D:Record.TaskOutputs.' + tmpResolveHash + '.LocalPath~}',
 				Filename: '{~D:Record.TaskOutputs.' + tmpResolveHash + '.Filename~}',
 				TimeoutMs: pConfig.TransferTimeoutMs || 300000
 			},
-			['SourceURL', 'Filename', 'TimeoutMs'],
-			['LocalPath', 'BytesTransferred', 'DurationMs']),
+			['SourceURL', 'SourceLocalPath', 'Filename', 'TimeoutMs'],
+			['LocalPath', 'BytesTransferred', 'DurationMs', 'Strategy']),
 
 		_taskNode(tmpProcessHash, pConfig.ProcessType, pConfig.ProcessTitle, 760, 180,
 			pConfig.ProcessData,
@@ -207,6 +208,16 @@ function _buildPipelineOperation(pConfig)
 		Data: {}
 	});
 
+	// Resolve LocalPath → transfer SourceLocalPath (shared-fs zero-copy fast path)
+	tmpConnections.push({
+		Hash: tmpHash + '-s4',
+		SourceNodeHash: tmpResolveHash,
+		SourcePortHash: tmpResolveHash + '-so-LocalPath',
+		TargetNodeHash: tmpTransferHash,
+		TargetPortHash: tmpTransferHash + '-si-SourceLocalPath',
+		Data: {}
+	});
+
 	// Transfer LocalPath → process InputFile
 	tmpConnections.push({
 		Hash: tmpHash + '-s3',
@@ -299,14 +310,15 @@ function getOperations()
 		_startNode(tmpVfe, 50, 200),
 		_taskNode(tmpVfe + '-resolve', 'resolve-address', 'Resolve Address', 220, 180,
 			{ Address: '{~D:Record.Operation.VideoAddress~}' },
-			['Address'], ['URL', 'Filename', 'BeaconName']),
+			['Address'], ['URL', 'Filename', 'BeaconName', 'LocalPath', 'Strategy']),
 		_taskNode(tmpVfe + '-transfer', 'file-transfer', 'File Transfer', 440, 180,
 			{
 				SourceURL: '{~D:Record.TaskOutputs.' + tmpVfe + '-resolve.URL~}',
+				SourceLocalPath: '{~D:Record.TaskOutputs.' + tmpVfe + '-resolve.LocalPath~}',
 				Filename: '{~D:Record.TaskOutputs.' + tmpVfe + '-resolve.Filename~}',
 				TimeoutMs: 1800000
 			},
-			['SourceURL', 'Filename', 'TimeoutMs'], ['LocalPath', 'BytesTransferred', 'DurationMs']),
+			['SourceURL', 'SourceLocalPath', 'Filename', 'TimeoutMs'], ['LocalPath', 'BytesTransferred', 'DurationMs', 'Strategy']),
 		_taskNode(tmpVfe + '-probe', 'beacon-mediaconversion-mediaprobe', 'Probe Video', 660, 180,
 			{
 				AffinityKey: '{~D:Record.Operation.VideoAddress~}',
@@ -335,6 +347,8 @@ function getOperations()
 	tmpVfeConns.push({ Hash: tmpVfe + '-s2', SourceNodeHash: tmpVfe + '-resolve', SourcePortHash: tmpVfe + '-resolve-so-Filename', TargetNodeHash: tmpVfe + '-transfer', TargetPortHash: tmpVfe + '-transfer-si-Filename', Data: {} });
 	tmpVfeConns.push({ Hash: tmpVfe + '-s3', SourceNodeHash: tmpVfe + '-transfer', SourcePortHash: tmpVfe + '-transfer-so-LocalPath', TargetNodeHash: tmpVfe + '-probe', TargetPortHash: tmpVfe + '-probe-si-InputFile', Data: {} });
 	tmpVfeConns.push({ Hash: tmpVfe + '-s4', SourceNodeHash: tmpVfe + '-transfer', SourcePortHash: tmpVfe + '-transfer-so-LocalPath', TargetNodeHash: tmpVfe + '-extract', TargetPortHash: tmpVfe + '-extract-si-InputFile', Data: {} });
+	// Resolve LocalPath → transfer SourceLocalPath (shared-fs zero-copy fast path)
+	tmpVfeConns.push({ Hash: tmpVfe + '-s5', SourceNodeHash: tmpVfe + '-resolve', SourcePortHash: tmpVfe + '-resolve-so-LocalPath', TargetNodeHash: tmpVfe + '-transfer', TargetPortHash: tmpVfe + '-transfer-si-SourceLocalPath', Data: {} });
 	tmpOperations.push({
 		Hash: tmpVfe,
 		Name: 'Video Frame Extraction',
@@ -348,6 +362,72 @@ function getOperations()
 		InitialOperationState: {}
 	});
 
+	// ── 3b. Video Frames (BATCH) ────────────────────────────────
+	// Single dispatch that resolves the address once, transfers the file
+	// once (with shared-fs zero-copy when available), and extracts ALL N
+	// frames in a single beacon work item. Used by the video explorer to
+	// avoid the previous N×operation-graph dispatch storm where N frames
+	// produced 21 separate file transfers (1 probe + N extracts).
+	//
+	// Trigger Parameters:
+	//   { VideoAddress, OutputDir, Frames, Width }
+	//   OutputDir — absolute writable directory where frames will land. Set
+	//               to retold-remote's per-video cache directory; works in
+	//               stack mode (shared filesystem) and on multi-host setups
+	//               that bind-mount the same content tree.
+	//   Frames    — JSON-encoded [{ Timestamp, Filename }, ...]
+	//
+	// Returns (no send-result; read TaskOutputs[<extract-node>].Result):
+	//   JSON string with { FrameCount, SuccessCount, OutputDir, Frames: [...] }
+	let tmpVfb = 'rr-video-frames-batch';
+	let tmpVfbNodes = [
+		_startNode(tmpVfb, 50, 200),
+		_taskNode(tmpVfb + '-resolve', 'resolve-address', 'Resolve Address', 220, 180,
+			{ Address: '{~D:Record.Operation.VideoAddress~}' },
+			['Address'], ['URL', 'Filename', 'BeaconName', 'LocalPath', 'Strategy']),
+		_taskNode(tmpVfb + '-transfer', 'file-transfer', 'File Transfer', 440, 180,
+			{
+				SourceURL: '{~D:Record.TaskOutputs.' + tmpVfb + '-resolve.URL~}',
+				SourceLocalPath: '{~D:Record.TaskOutputs.' + tmpVfb + '-resolve.LocalPath~}',
+				Filename: '{~D:Record.TaskOutputs.' + tmpVfb + '-resolve.Filename~}',
+				TimeoutMs: 1800000
+			},
+			['SourceURL', 'SourceLocalPath', 'Filename', 'TimeoutMs'],
+			['LocalPath', 'BytesTransferred', 'DurationMs', 'Strategy']),
+		_taskNode(tmpVfb + '-extract', 'beacon-mediaconversion-videoextractframes', 'Extract Frames Batch', 660, 180,
+			{
+				OutputDir: '{~D:Record.Operation.OutputDir~}',
+				Frames: '{~D:Record.Operation.Frames~}',
+				Width: '{~D:Record.Operation.Width~}',
+				AffinityKey: '{~D:Record.Operation.VideoAddress~}',
+				TimeoutMs: 1800000
+			},
+			['InputFile', 'OutputDir', 'Frames', 'Width'],
+			['Result', 'StdOut']),
+		_endNode(tmpVfb, 880, 260)
+	];
+	let tmpVfbConns = _chainConnections(tmpVfb,
+		[tmpVfb + '-start', tmpVfb + '-resolve', tmpVfb + '-transfer', tmpVfb + '-extract'],
+		tmpVfb + '-end');
+	// State wires
+	tmpVfbConns.push({ Hash: tmpVfb + '-s1', SourceNodeHash: tmpVfb + '-resolve', SourcePortHash: tmpVfb + '-resolve-so-URL', TargetNodeHash: tmpVfb + '-transfer', TargetPortHash: tmpVfb + '-transfer-si-SourceURL', Data: {} });
+	tmpVfbConns.push({ Hash: tmpVfb + '-s2', SourceNodeHash: tmpVfb + '-resolve', SourcePortHash: tmpVfb + '-resolve-so-Filename', TargetNodeHash: tmpVfb + '-transfer', TargetPortHash: tmpVfb + '-transfer-si-Filename', Data: {} });
+	tmpVfbConns.push({ Hash: tmpVfb + '-s3', SourceNodeHash: tmpVfb + '-transfer', SourcePortHash: tmpVfb + '-transfer-so-LocalPath', TargetNodeHash: tmpVfb + '-extract', TargetPortHash: tmpVfb + '-extract-si-InputFile', Data: {} });
+	// Resolve LocalPath → transfer SourceLocalPath (shared-fs zero-copy fast path)
+	tmpVfbConns.push({ Hash: tmpVfb + '-s4', SourceNodeHash: tmpVfb + '-resolve', SourcePortHash: tmpVfb + '-resolve-so-LocalPath', TargetNodeHash: tmpVfb + '-transfer', TargetPortHash: tmpVfb + '-transfer-si-SourceLocalPath', Data: {} });
+	tmpOperations.push({
+		Hash: tmpVfb,
+		Name: 'Video Frames Batch',
+		Description: 'Single-dispatch batch frame extraction. resolve → transfer → extract-many. Trigger with Parameters: { VideoAddress, OutputDir, Frames (JSON), Width }. Result is JSON metadata only — frames are written to OutputDir and read directly by the dispatcher.',
+		Tags: ['retold-remote', 'media', 'video', 'frames', 'batch'],
+		Author: 'retold-remote',
+		Version: '3.0.0',
+		Graph: { Nodes: tmpVfbNodes, Connections: tmpVfbConns, ViewState: { PanX: 0, PanY: 0, Zoom: 1, SelectedNodeHash: null, SelectedConnectionHash: null } },
+		SavedLayouts: [],
+		InitialGlobalState: {},
+		InitialOperationState: {}
+	});
+
 	// ── 4. Audio Waveform ───────────────────────────────────────
 	tmpOperations.push(_buildPipelineOperation(
 	{
@@ -461,23 +541,56 @@ function getOperations()
 	}));
 
 	// ── 9. Media Probe ─────────────────────────────────────────
-	tmpOperations.push(_buildPipelineOperation(
-	{
-		Hash: 'rr-media-probe',
+	// Custom graph (NOT _buildPipelineOperation) because MediaProbe returns
+	// its result as a JSON string in the work item's Outputs.Result field —
+	// it does NOT write a file to staging. The pipeline helper would tack on
+	// a send-result node looking for `probe.json` and log a noisy error every
+	// time the operation runs. Skip send-result entirely; the dispatcher
+	// reads the JSON directly from `pResult.TaskOutputs['rr-media-probe-process'].Result`.
+	let tmpMp = 'rr-media-probe';
+	let tmpMpNodes = [
+		_startNode(tmpMp, 50, 200),
+		_taskNode(tmpMp + '-resolve', 'resolve-address', 'Resolve Address', 220, 180,
+			{ Address: '{~D:Record.Operation.MediaAddress~}' },
+			['Address'], ['URL', 'Filename', 'BeaconName', 'LocalPath', 'Strategy']),
+		_taskNode(tmpMp + '-transfer', 'file-transfer', 'File Transfer', 440, 180,
+			{
+				SourceURL: '{~D:Record.TaskOutputs.' + tmpMp + '-resolve.URL~}',
+				SourceLocalPath: '{~D:Record.TaskOutputs.' + tmpMp + '-resolve.LocalPath~}',
+				Filename: '{~D:Record.TaskOutputs.' + tmpMp + '-resolve.Filename~}',
+				TimeoutMs: 300000
+			},
+			['SourceURL', 'SourceLocalPath', 'Filename', 'TimeoutMs'],
+			['LocalPath', 'BytesTransferred', 'DurationMs', 'Strategy']),
+		_taskNode(tmpMp + '-process', 'beacon-mediaconversion-mediaprobe', 'Probe Metadata', 660, 180,
+			{
+				AffinityKey: '{~D:Record.Operation.MediaAddress~}',
+				TimeoutMs: 300000
+			},
+			['InputFile'],
+			['Result', 'StdOut']),
+		_endNode(tmpMp, 880, 260)
+	];
+	let tmpMpConns = _chainConnections(tmpMp,
+		[tmpMp + '-start', tmpMp + '-resolve', tmpMp + '-transfer', tmpMp + '-process'],
+		tmpMp + '-end');
+	tmpMpConns.push({ Hash: tmpMp + '-s1', SourceNodeHash: tmpMp + '-resolve', SourcePortHash: tmpMp + '-resolve-so-URL', TargetNodeHash: tmpMp + '-transfer', TargetPortHash: tmpMp + '-transfer-si-SourceURL', Data: {} });
+	tmpMpConns.push({ Hash: tmpMp + '-s2', SourceNodeHash: tmpMp + '-resolve', SourcePortHash: tmpMp + '-resolve-so-Filename', TargetNodeHash: tmpMp + '-transfer', TargetPortHash: tmpMp + '-transfer-si-Filename', Data: {} });
+	tmpMpConns.push({ Hash: tmpMp + '-s3', SourceNodeHash: tmpMp + '-transfer', SourcePortHash: tmpMp + '-transfer-so-LocalPath', TargetNodeHash: tmpMp + '-process', TargetPortHash: tmpMp + '-process-si-InputFile', Data: {} });
+	// Resolve LocalPath → transfer SourceLocalPath (shared-fs zero-copy fast path)
+	tmpMpConns.push({ Hash: tmpMp + '-s4', SourceNodeHash: tmpMp + '-resolve', SourcePortHash: tmpMp + '-resolve-so-LocalPath', TargetNodeHash: tmpMp + '-transfer', TargetPortHash: tmpMp + '-transfer-si-SourceLocalPath', Data: {} });
+	tmpOperations.push({
+		Hash: tmpMp,
 		Name: 'Media Probe',
-		Description: 'Extract metadata from a media file via ffprobe. Pipeline: resolve → download → probe → send result. Trigger with Parameters: { MediaAddress }.',
+		Description: 'Extract metadata from a media file via ffprobe. Custom graph: resolve → transfer → probe → end. Result is JSON metadata only (no send-result; read TaskOutputs[<process>].Result). Trigger with Parameters: { MediaAddress }.',
 		Tags: ['media', 'probe', 'metadata'],
-		AddressParam: 'MediaAddress',
-		ProcessType: 'beacon-mediaconversion-mediaprobe',
-		ProcessTitle: 'Probe Metadata',
-		ProcessData:
-		{
-			TimeoutMs: 300000
-		},
-		ProcessSettings: ['InputFile'],
-		ProcessOutputs: ['Result', 'StdOut'],
-		OutputFile: 'probe.json'
-	}));
+		Author: 'retold-remote',
+		Version: '3.0.0',
+		Graph: { Nodes: tmpMpNodes, Connections: tmpMpConns, ViewState: { PanX: 0, PanY: 0, Zoom: 1, SelectedNodeHash: null, SelectedConnectionHash: null } },
+		SavedLayouts: [],
+		InitialGlobalState: {},
+		InitialOperationState: {}
+	});
 
 	return tmpOperations;
 }

package/source/server/RetoldRemote-VideoFrameService.js

@@ -54,6 +54,25 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 		// Ultravisor dispatcher — set via setDispatcher()
 		this._dispatcher = null;
 
+		// Operation broadcaster — set via setBroadcaster()
+		this._broadcaster = null;
+
+		// One-time local ffprobe detection. If ffprobe is on this machine we
+		// always prefer to use it directly — running ffprobe locally is a
+		// metadata-only call (microseconds for an indexed file) and avoids the
+		// entire resolve→transfer→probe→result Ultravisor pipeline. Only when
+		// ffprobe is missing locally do we fall back to dispatching the probe
+		// to a beacon.
+		this._ffprobeLocalAvailable = this._detectLocalFfprobe();
+		if (this._ffprobeLocalAvailable)
+		{
+			this.fable.log.info('Video Frame Service: local ffprobe detected — probes will run in-process (no dispatch).');
+		}
+		else
+		{
+			this.fable.log.info('Video Frame Service: local ffprobe NOT found — will dispatch probes to a beacon.');
+		}
+
 		// Apply explorer state persistence mixin (initializeState,
 		// _buildExplorerStateKey, loadExplorerState, saveExplorerState)
 		libExplorerStateMixin.apply(this, EXPLORER_STATE_SOURCE, 'video-explorer');
@@ -75,6 +94,42 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 		this._dispatcher = pDispatcher;
 	}
 
+	/**
+	 * Set the operation broadcaster for progress events and cancellation.
+	 *
+	 * @param {object} pBroadcaster - RetoldRemoteOperationBroadcaster instance
+	 */
+	setBroadcaster(pBroadcaster)
+	{
+		this._broadcaster = pBroadcaster;
+	}
+
+	/**
+	 * Helper: emit a progress event if a broadcaster is attached and the
+	 * caller supplied an operation id. Safe to call without either.
+	 *
+	 * @param {string} pOperationId - Opaque client-supplied operation id
+	 * @param {object} pPayload - { Phase, Current, Total, Message }
+	 */
+	_emitProgress(pOperationId, pPayload)
+	{
+		if (this._broadcaster && pOperationId)
+		{
+			this._broadcaster.broadcastProgress(pOperationId, pPayload);
+		}
+	}
+
+	/**
+	 * Helper: check whether the current operation has been cancelled.
+	 *
+	 * @param {string} pOperationId
+	 * @returns {boolean}
+	 */
+	_isCancelled(pOperationId)
+	{
+		return !!(this._broadcaster && pOperationId && this._broadcaster.isCancelled(pOperationId));
+	}
+
 	/**
 	 * Install video-specific explorer state methods that need read-merge-write
 	 * behavior (merging custom frames, preserving selection across saves).
@@ -229,9 +284,40 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 		return this.fable.ParimeBinaryStorage.resolvePath('video-frames', tmpHash);
 	}
 
+	/**
+	 * One-time check for local ffprobe at constructor time. Synchronous because
+	 * the constructor is, and we want the cached answer ready before the first
+	 * probe call. The check itself is cheap (~50ms) and only runs once per
+	 * service lifetime.
+	 *
+	 * @returns {boolean} true if `ffprobe -version` returns 0 on this host
+	 */
+	_detectLocalFfprobe()
+	{
+		try
+		{
+			libChildProcess.execSync('ffprobe -version', { stdio: 'ignore', timeout: 5000 });
+			return true;
+		}
+		catch (pError)
+		{
+			return false;
+		}
+	}
+
 	/**
 	 * Probe a video file with ffprobe to get its duration.
-	 * Tries Ultravisor dispatch first, falls back to local execution.
+	 *
+	 * Strategy ordering (most efficient first):
+	 *   1. LOCAL ffprobe — when this process has the binary on PATH. ffprobe
+	 *      reads the container index and returns metadata in milliseconds; no
+	 *      Ultravisor pipeline involvement, no file copies, no shared-fs
+	 *      negotiation. This is the right call for stack-mode deployments
+	 *      where retold-remote and orator-conversion live in the same image.
+	 *   2. DISPATCHED probe — only when the local binary is missing. Goes
+	 *      through the rr-media-probe operation graph (resolve → transfer →
+	 *      probe → result). With shared-fs the file isn't actually copied,
+	 *      but the operation graph still runs.
 	 *
 	 * @param {string} pAbsPath - Absolute path to the video
 	 * @param {Function} fCallback - Callback(pError, { duration, width, height, codec })
@@ -240,7 +326,18 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 	{
 		let tmpSelf = this;
 
-		// Try Ultravisor operation trigger first
+		// Local-first: if ffprobe is on this host, just run it. The previous
+		// version did this BACKWARDS and dispatched even when local was
+		// available, which made every video frame extraction pay an extra
+		// Ultravisor round trip just to read the duration.
+		if (this._ffprobeLocalAvailable)
+		{
+			return this._probeVideoLocal(pAbsPath, fCallback);
+		}
+
+		// No local ffprobe — fall back to dispatching the probe through the
+		// Ultravisor mesh. This requires the dispatcher to be available and
+		// the file to be addressable through the File context.
 		if (this._dispatcher && this._dispatcher.isAvailable())
 		{
 			let tmpRelPath;
@@ -270,13 +367,15 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 							{
 								let tmpData = JSON.parse(tmpProcessOutput.Result);
 								let tmpParsed = tmpSelf._parseProbeData(tmpData);
-								tmpSelf.fable.log.info(`ffprobe via operation trigger for ${tmpRelPath}`);
+								tmpSelf.fable.log.info(`ffprobe via operation trigger for ${tmpRelPath} (no local ffprobe)`);
 								return fCallback(null, tmpParsed);
 							}
 						}
 						catch (pParseError)
 						{
-							// Fall through to local
+							// Fall through to a final local attempt — even though
+							// the constructor said ffprobe was missing, the binary
+							// could have been installed since startup.
 						}
 					}
 
@@ -286,6 +385,8 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 			}
 		}
 
+		// Last resort: try local even though detection said it was missing.
+		// Returns the original ENOENT or similar if ffprobe really isn't there.
 		return this._probeVideoLocal(pAbsPath, fCallback);
 	}
 
@@ -543,6 +644,9 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 		let tmpHeight = parseInt(pOptions.height, 10) || this.options.DefaultFrameHeight;
 		let tmpFormat = pOptions.format || this.options.DefaultFrameFormat;
 
+		// Operation tracking (optional — passed by caller via X-Op-Id)
+		let tmpOpId = pOptions.OperationId || null;
+
 		// Clamp values
 		tmpCount = Math.min(Math.max(tmpCount, 1), 100);
 		tmpWidth = Math.min(Math.max(tmpWidth, 64), 1920);
@@ -575,6 +679,7 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 			{
 				let tmpManifest = JSON.parse(libFs.readFileSync(tmpManifestPath, 'utf8'));
 				this.fable.log.info(`Video frames cache hit for ${pRelPath}`);
+				this._emitProgress(tmpOpId, { Phase: 'cached', Message: 'Cached frames available' });
 				return fCallback(null, tmpManifest);
 			}
 			catch (pError)
@@ -584,6 +689,7 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 		}
 
 		// Probe the video for duration
+		this._emitProgress(tmpOpId, { Phase: 'probing', Message: 'Probing video metadata' });
 		this._probeVideo(pAbsPath,
 			(pError, pVideoInfo) =>
 			{
@@ -592,6 +698,11 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 					return fCallback(new Error('Could not probe video. ffprobe may not be available.'));
 				}
 
+				if (tmpSelf._isCancelled(tmpOpId))
+				{
+					return fCallback(new Error('Cancelled'));
+				}
+
 				let tmpDuration = pVideoInfo.duration;
 
 				// Calculate timestamps
@@ -609,9 +720,15 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 
 				tmpSelf.fable.log.info(`Extracting ${tmpTimestamps.length} frames from ${pRelPath} (${tmpDuration.toFixed(1)}s)`);
 
-				// Use async serial extraction when dispatcher is available,
-				// otherwise use synchronous loop for backward compatibility
-				let tmpUseAsync = !!(tmpSelf._dispatcher && tmpSelf._dispatcher.isAvailable());
+				// Three execution paths, in order of preference:
+				//   1. BATCH dispatch (dispatcher available) — single Ultravisor
+				//      operation that resolves the address once, transfers/short-
+				//      circuits the file once, and extracts all N frames in one
+				//      beacon work item. Replaces the previous N-trigger storm.
+				//   2. Local async loop (dispatcher unavailable, ffmpeg local) —
+				//      sequential extracts in-process, no Ultravisor.
+				//   3. Local sync loop (final fallback for ancient code paths)
+				let tmpUseBatch = !!(tmpSelf._dispatcher && tmpSelf._dispatcher.isAvailable());
 
 				let _finishExtraction = () =>
 				{
@@ -653,9 +770,20 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 					return fCallback(null, tmpResult);
 				};
 
-				if (tmpUseAsync)
+				// Emit initial progress before starting extraction
+				tmpSelf._emitProgress(tmpOpId,
+				{
+					Phase: 'extracting',
+					Current: 0,
+					Total: tmpTimestamps.length,
+					Message: 'Extracting 0 of ' + tmpTimestamps.length + ' frames',
+					Cancelable: true
+				});
+
+				// Local serial-async fallback used by both the "no batch" path
+				// and the "batch failed" recovery path.
+				let _runLocalAsync = () =>
 				{
-					// Serial async extraction
 					let tmpFrameIndex = 0;
 
 					let _extractNext = () =>
@@ -665,6 +793,13 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 							return _finishExtraction();
 						}
 
+						// Cooperative cancellation check before each frame
+						if (tmpSelf._isCancelled(tmpOpId))
+						{
+							tmpSelf.fable.log.info('[VideoFrameService] cancelled mid-extraction for ' + pRelPath);
+							return fCallback(new Error('Cancelled'));
+						}
+
 						let tmpI = tmpFrameIndex;
 						let tmpTimestamp = tmpTimestamps[tmpI];
 						let tmpFrameFilename = `frame_${String(tmpI).padStart(4, '0')}.${tmpFormat}`;
@@ -695,17 +830,166 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 										// Frame file disappeared — skip
 									}
 								}
+								tmpSelf._emitProgress(tmpOpId,
+								{
+									Phase: 'extracting',
+									Current: tmpExtractedCount,
+									Total: tmpTimestamps.length,
+									Message: 'Extracting ' + tmpExtractedCount + ' of ' + tmpTimestamps.length + ' frames',
+									Cancelable: true
+								});
 								_extractNext();
 							});
 					};
 
 					_extractNext();
+				};
+
+				if (tmpUseBatch)
+				{
+					// ── BATCH path ──────────────────────────────────────────
+					// Build the per-frame spec list and dispatch a single batch
+					// operation. The orator-conversion beacon writes all frame
+					// files directly into our cache directory because we share
+					// the filesystem. After the operation completes we just stat
+					// each frame file and build our normal manifest.
+					let tmpRelPath;
+					try
+					{
+						tmpRelPath = libPath.relative(tmpSelf.contentPath, pAbsPath);
+					}
+					catch (pRelErr)
+					{
+						tmpRelPath = null;
+					}
+
+					if (!tmpRelPath || tmpRelPath.startsWith('..'))
+					{
+						tmpSelf.fable.log.warn(`[VideoFrameService] could not derive content-relative path for ${pAbsPath}; falling back to local extraction`);
+						return _runLocalAsync();
+					}
+
+					let tmpFrameSpecs = [];
+					let tmpFilenameToMeta = {};
+					for (let i = 0; i < tmpTimestamps.length; i++)
+					{
+						let tmpTimestamp = tmpTimestamps[i];
+						let tmpFrameFilename = `frame_${String(i).padStart(4, '0')}.${tmpFormat}`;
+						let tmpTimeStr = tmpSelf._formatFfmpegTimestamp(tmpTimestamp);
+						tmpFrameSpecs.push({ Timestamp: tmpTimeStr, Filename: tmpFrameFilename });
+						tmpFilenameToMeta[tmpFrameFilename] =
+							{
+								Index: i,
+								Timestamp: tmpTimestamp,
+								TimestampFormatted: tmpSelf._formatTimestamp(tmpTimestamp)
+							};
+					}
+
+					if (tmpSelf._isCancelled(tmpOpId))
+					{
+						return fCallback(new Error('Cancelled'));
+					}
+
+					tmpSelf.fable.log.info(`[VideoFrameService] dispatching batch extraction (${tmpFrameSpecs.length} frames) for ${pRelPath}`);
+
+					tmpSelf._dispatcher.triggerOperation('rr-video-frames-batch',
+						{
+							VideoAddress: '>retold-remote/File/' + tmpRelPath,
+							OutputDir: tmpCacheDir,
+							Frames: JSON.stringify(tmpFrameSpecs),
+							Width: tmpWidth,
+							TimeoutMs: 1800000
+						},
+						(pBatchError, pBatchResult) =>
+						{
+							if (pBatchError || !pBatchResult)
+							{
+								tmpSelf.fable.log.warn(`[VideoFrameService] batch dispatch failed: ${pBatchError ? pBatchError.message : 'no result'}; falling back to local`);
+								return _runLocalAsync();
+							}
+
+							// Pull the manifest out of the extract task's Result
+							let tmpManifest = null;
+							try
+							{
+								let tmpExtractOutputs = pBatchResult.TaskOutputs && pBatchResult.TaskOutputs['rr-video-frames-batch-extract'];
+								if (tmpExtractOutputs && tmpExtractOutputs.Result)
+								{
+									tmpManifest = JSON.parse(tmpExtractOutputs.Result);
+								}
+							}
+							catch (pParseError)
+							{
+								tmpSelf.fable.log.warn(`[VideoFrameService] could not parse batch result manifest: ${pParseError.message}`);
+							}
+
+							if (!tmpManifest || !Array.isArray(tmpManifest.Frames))
+							{
+								tmpSelf.fable.log.warn('[VideoFrameService] batch result missing manifest; falling back to local');
+								return _runLocalAsync();
+							}
+
+							// Walk the manifest, stat each output file, build our
+							// frames array. Skip any that didn't actually land on
+							// disk (filesystem races, partial failures, etc).
+							for (let i = 0; i < tmpManifest.Frames.length; i++)
+							{
+								let tmpEntry = tmpManifest.Frames[i];
+								if (!tmpEntry || !tmpEntry.Success || !tmpEntry.Filename)
+								{
+									continue;
+								}
+								let tmpFramePath = libPath.join(tmpCacheDir, tmpEntry.Filename);
+								try
+								{
+									let tmpFrameStat = libFs.statSync(tmpFramePath);
+									let tmpMeta = tmpFilenameToMeta[tmpEntry.Filename] || {};
+									tmpFrames.push(
+										{
+											Index: tmpMeta.Index !== undefined ? tmpMeta.Index : i,
+											Timestamp: tmpMeta.Timestamp,
+											TimestampFormatted: tmpMeta.TimestampFormatted,
+											Filename: tmpEntry.Filename,
+											Size: tmpFrameStat.size
+										});
+									tmpExtractedCount++;
+								}
+								catch (pStatErr)
+								{
+									// File missing — skip
+								}
+							}
+
+							tmpSelf._emitProgress(tmpOpId,
+							{
+								Phase: 'extracting',
+								Current: tmpExtractedCount,
+								Total: tmpTimestamps.length,
+								Message: 'Extracting ' + tmpExtractedCount + ' of ' + tmpTimestamps.length + ' frames',
+								Cancelable: true
+							});
+
+							if (tmpExtractedCount === 0)
+							{
+								tmpSelf.fable.log.warn('[VideoFrameService] batch returned 0 successful frames; falling back to local');
+								return _runLocalAsync();
+							}
+
+							return _finishExtraction();
+						});
 				}
 				else
 				{
 					// Synchronous extraction (original behavior)
 					for (let i = 0; i < tmpTimestamps.length; i++)
 					{
+						// Cooperative cancellation check before each frame
+						if (tmpSelf._isCancelled(tmpOpId))
+						{
+							tmpSelf.fable.log.info('[VideoFrameService] cancelled mid-extraction for ' + pRelPath);
+							return fCallback(new Error('Cancelled'));
+						}
+
 						let tmpTimestamp = tmpTimestamps[i];
 						let tmpFrameFilename = `frame_${String(i).padStart(4, '0')}.${tmpFormat}`;
 						let tmpFramePath = libPath.join(tmpCacheDir, tmpFrameFilename);
@@ -726,6 +1010,15 @@ class RetoldRemoteVideoFrameService extends libFableServiceProviderBase
 							});
 							tmpExtractedCount++;
 						}
+
+						tmpSelf._emitProgress(tmpOpId,
+						{
+							Phase: 'extracting',
+							Current: tmpExtractedCount,
+							Total: tmpTimestamps.length,
+							Message: 'Extracting ' + tmpExtractedCount + ' of ' + tmpTimestamps.length + ' frames',
+							Cancelable: true
+						});
 					}
 
 					_finishExtraction();