video-loader/analysis
Source: analysis.js:10
Pure numerical helpers and trigger policy for the seekable-video analyser. The module deliberately has no DOM or model dependencies so thresholds, baseline selection, and event decisions can be tested without loading the large vendored runtimes.
Instance Methods
evaluate(sample: Object): Object
Evaluates one lightweight sample.
Parameters
sample(Object) — Current sample.
Returns
Object— Trigger decision.
markFaceApi(mediaTime: number): void
Records completion of a face-api pass.
Parameters
mediaTime(number) — Video timestamp in seconds.
Returns
void
reset(): void
Clears temporal state before analysing another source.
Returns
void
Static Methods
euclideanDistance(
left: ArrayLike.<number>,
right: ArrayLike.<number>,
): number
Computes Euclidean distance between equal-length vectors. The Video Loader uses this metric for face-api descriptors: buildFaceBaseline() uses it to choose the representative descriptor and measure baseline spread, while the controller uses it to compare later face-api checks with that baseline and the configured 0.6 identity-distance threshold.
Parameters
left(ArrayLike.<number>) — First vector.right(ArrayLike.<number>) — Second vector.
Returns
number— L2 distance.
Throws
Error— When vector lengths differ.
cosineSimilarity(
left: ArrayLike.<number>,
right: ArrayLike.<number>,
): number
Computes cosine similarity between equal-length vectors. It is used only for MediaPipe ImageEmbedder vectors from aligned face crops. The baseline medoid and every later visual-drift sample use 1 - cosineSimilarity(...); this value is a generic appearance-change signal, not an identity score.
Parameters
left(ArrayLike.<number>) — First vector.right(ArrayLike.<number>) — Second vector.
Returns
number— Similarity in the range -1..1, or zero for a zero vector.
Throws
Error— When vector lengths differ.
median(values: Array.<number>): number
Returns the median without mutating the caller's collection. Baseline construction uses it to summarise face-api descriptor spread and the centre of ImageEmbedder drift; medianAbsoluteDeviation() calls it again to derive the adaptive visual-change threshold from baseline noise.
Parameters
values(Array.<number>) — Numeric values.
Returns
number— Median, or zero for an empty collection.
medianAbsoluteDeviation(values: Array.<number>): number
Computes median absolute deviation, a robust estimate of baseline noise.
Parameters
values(Array.<number>) — Numeric values.
Returns
number— Median absolute deviation.
vectorMedoid(
vectors: Array.<ArrayLike.<number>>,
metric: function,
): Object
Picks the real vector with the smallest total distance to its peers. Both baseline builders use this helper: cosine distance selects a representative ImageEmbedder vector, and Euclidean distance selects a representative face-api descriptor. Keeping an observed vector, instead of an arithmetic mean, also lets the controller associate the visual baseline with a real sampled timestamp.
Parameters
vectors(Array.<ArrayLike.<number>>) — Candidate vectors.metric(function) — Distance metric.
Returns
Object— Medoid and distances to it.
Throws
Error— When no vector is provided.
buildEmbeddingBaseline(
embeddings: Array.<ArrayLike.<number>>,
options?: object,
): Object
Builds a robust ImageEmbedder baseline and its adaptive drift threshold.
ImageEmbedder is a generic visual model, not a biometric matcher. The threshold therefore comes from the current video's stable baseline rather than a universal identity claim.
Parameters
embeddings(Array.<ArrayLike.<number>>) — Stable aligned-face embeddings.options(object, optional) — Threshold tuning.options.minimumDelta(number, optional) — Minimum drift above baseline noise.options.madMultiplier(number, optional) — Robust-noise multiplier.
Returns
Object— Baseline model.
buildFaceBaseline(
descriptors: Array.<ArrayLike.<number>>,
): Object
Builds the face-api descriptor baseline as a medoid and reports its spread.
Parameters
descriptors(Array.<ArrayLike.<number>>) — Stable face-api descriptors.
Returns
Object— Baseline descriptor.
buildAnchoredEmbeddingBaseline(
embeddings: Array.<ArrayLike.<number>>,
referenceIndex: number,
options?: object,
): Object
Uses the human-selected ImageEmbedder vector as the actual baseline while nearby vectors estimate normal visual noise. The Video Loader uses this variant only for an explicitly anchored baseline, ensuring that later visual drift is computed from the frame the person selected rather than a medoid several seconds later.
Parameters
embeddings(Array.<ArrayLike.<number>>) — Nearby stable embeddings.referenceIndex(number) — Index of the explicitly selected frame.options(object, optional) — Adaptive-trigger tuning.options.minimumDelta(number, optional) — Minimum drift above baseline noise.options.madMultiplier(number, optional) — Robust-noise multiplier.
Returns
Object— Anchored baseline model.
buildAnchoredFaceBaseline(
descriptors: Array.<ArrayLike.<number>>,
referenceIndex: number,
): Object
Uses the face-api descriptor from the human-selected frame as the identity baseline and measures nearby descriptor spread around it. The Video Loader uses this for explicit baseline selection so every later L2 distance truly originates from the visible baseline card.
Parameters
descriptors(Array.<ArrayLike.<number>>) — Nearby stable descriptors.referenceIndex(number) — Index of the selected frame descriptor.
Returns
Object— Anchored face-api baseline.
visualDrift(
embedding: ArrayLike.<number>,
baseline: ArrayLike.<number>,
): number
Computes ImageEmbedder visual drift from a baseline embedding.
Parameters
embedding(ArrayLike.<number>) — Current aligned-face embedding.baseline(ArrayLike.<number>) — Baseline aligned-face embedding.
Returns
number— Cosine distance where zero means identical direction.
createTriggerDetector(options?: object): Object
Creates the stateful policy that decides when expensive face-api work is justified. The policy retains numeric samples only; it never retains frames.
Parameters
options(object, optional) — Trigger policy overrides.options.heartbeatSeconds(number, optional, default: 4) — Maximum gap between identity checks.options.minimumFaceApiGapSeconds(number, optional, default: 0.75) — Cooldown between expensive checks.options.jumpDelta(number, optional, default: 0.035) — Single-sample visual-drift jump.options.requiredVotes(number, optional, default: 2) — Above-threshold samples required.options.voteWindow(number, optional, default: 3) — Recent samples considered for votes.
Returns
Object— Trigger detector.
Other
DEFAULT_FACE_DISTANCE_THRESHOLD
Default face-api descriptor distance used by the vendored FaceMatcher.