video-loader/controller
Source: controller.js:10
Seekable local-video analysis controller. MediaPipe FaceLandmarker supplies frequent presence and geometry, MediaPipe ImageEmbedder supplies an aligned visual-change signal, and the heavier face-api recognition path runs only for baseline capture, trigger verification, and a bounded heartbeat.
Instance Methods
waitForMediaEvent(
media: HTMLMediaElement,
eventName: string,
timeoutMs?: number,
): Promise.<void>
Waits for a one-shot media event with a timeout that prevents a corrupt source from hanging the analysis forever.
Parameters
media(HTMLMediaElement) — Media element.eventName(string) — Event name.timeoutMs(number, optional, default: 15000) — Timeout in milliseconds.
Returns
Promise.<void>— Resolves when the event fires.
seekVideo(
video: HTMLVideoElement,
mediaTime: number,
): Promise.<void>
Seeks to a decoded video frame.
Parameters
video(HTMLVideoElement) — Seekable video element.mediaTime(number) — Target media timestamp in seconds.
Returns
Promise.<void>— Resolves after Chromium reports the seek complete.
unpackEmbedding(result: object): Array.<number> | null
Extracts a numeric float embedding from a MediaPipe ImageEmbedder result.
Parameters
result(object) — MediaPipe result.
Returns
Array.<number> | null— Serializable embedding.
drawAlignedFaceCrop(
video: HTMLVideoElement,
landmarks: Array.<{x: number, y: number}>,
canvas: HTMLCanvasElement,
): Object
Draws an eye-levelled face crop using MediaPipe's normalised landmarks. The crop removes most background and normalises roll and scale before the generic ImageEmbedder sees any pixels.
Parameters
video(HTMLVideoElement) — Source video.landmarks(Array.<{x: number, y: number}>) — FaceLandmarker mesh.canvas(HTMLCanvasElement) — Reusable square crop surface.
Returns
Object— Geometry metrics.
measureCropQuality(canvas: HTMLCanvasElement): Object
Measures crop exposure and gradient energy. Sharpness is a ranking signal, not a universal accept/reject threshold.
Parameters
canvas(HTMLCanvasElement) — Aligned crop.
Returns
Object— Quality metrics and a low-resolution RGB signature.
appearanceDistance(
left: Array.<number>,
right: Array.<number>,
): number
Computes mean absolute difference between equal-length appearance signatures.
Parameters
left(Array.<number>) — First RGB grid.right(Array.<number>) — Second RGB grid.
Returns
number— Mean absolute channel difference in the range 0..1.
captureSourceFrame(
video: HTMLVideoElement,
mediaTime: number,
sharpness: number,
reason: string,
): Object
Captures the decoded source frame at native video resolution.
Parameters
video(HTMLVideoElement) — Source video.mediaTime(number) — Current video timestamp.sharpness(number) — Crop sharpness associated with the frame.reason(string) — Selection reason.
Returns
Object— Frame artifact.
Static Methods
createVideoAnalysisController(
video: HTMLVideoElement,
overrides?: Partial.<VideoLoaderConfig>,
): object
Creates the seekable-video analysis controller.
Parameters
video(HTMLVideoElement) — Local video element.overrides(Partial.<VideoLoaderConfig>, optional) — Configuration overrides.
Returns
object— Controller API.
Other
VideoLoaderConfig: object
Properties
sampleIntervalSeconds(number) — Media-time interval between lightweight samples.baselineEmbeddingSamples(number) — Stable ImageEmbedder samples required.baselineFaceSamples(number) — Stable face-api descriptors required.anchoredBaselineEmbeddingSamples(number) — Comparable neighbours used around a selected frame.anchoredBaselineFaceSamples(number) — Face descriptors used around a selected frame.faceDistanceThreshold(number) — Face-api L2 distance threshold.heartbeatSeconds(number) — Maximum media-time gap between face-api checks.minimumFaceApiGapSeconds(number) — Minimum media-time gap between face-api checks.minimumVisualDelta(number) — Minimum ImageEmbedder drift above baseline noise.visualMadMultiplier(number) — Baseline MAD multiplier for adaptive visual drift.visualJumpDelta(number) — One-sample visual drift jump threshold.maximumBaselineAppearanceStep(number) — Largest accepted low-resolution crop change.maximumBaselineRollStep(number) — Largest accepted roll change in degrees.maximumBaselineYawStep(number) — Largest accepted approximate yaw change.maximumBaselineScaleStep(number) — Largest accepted face-width ratio change.maximumBaselineFaceSpread(number) — Largest accepted face-api baseline spread.maximumAnchoredBaselineFaceSpread(number) — Largest spread accepted around a human-selected frame.anchoredBaselineWindowSeconds(number) — Maximum local calibration span after a selected frame.alignedCropSize(number) — ImageEmbedder crop edge in pixels.evidenceRefinementRadiusSeconds(number) — Neighbourhood around a confirmed event.evidenceRefinementStepSeconds(number) — MediaPipe-only refinement cadence.evidenceRefinementFaceApiCandidates(number) — Maximum refined candidates verified by face-api.
DEFAULT_VIDEO_LOADER_CONFIG: VideoLoaderConfig
FACE_MESH
MediaPipe landmark indices used only to normalise the face crop.