Crate videre_api 

Facade over videre’s faces-labeling operations. Plain functions over an open rusqlite::Connection, returning serde types and a shared Error. Transport-agnostic on purpose: the axum --faces server is the in-repo caller, but nothing here depends on it.

Structs

ClusterData

One unassigned cluster (green section in the labeling UI).

ClusterDetail

Cluster detail: every face in one unassigned cluster.

ClusterFaceData

One face row on a cluster detail page.

FaceLookup

The single-row query face_image_bytes needs before it can do any image work, split out so a caller holding a shared/locked Connection (the axum server serializes every request on one Mutex<Connection>) can release that lock immediately after this cheap lookup, instead of holding it for the entire decode/crop/resize/encode/cache-write below, which otherwise fully serializes every thumbnail request behind the lock, turning a many-thousand-singleton library into one thumbnail at a time.

FacesData

Top-level payload for the labeling page.

LibraryStats

OriginalLookup

The single-row query original_image_bytes needs before any image I/O. See FaceLookup for why this split matters for concurrency.

PersonData

One labeled person: their confirmed faces plus a representative face id (the primary, or lowest id) used as the card thumbnail.

PersonDetail

Person detail: every confirmed face for one person.

PersonFaceData

One face row on a person detail page. is_primary marks the current default photo (the person’s thumbnail on the labeling page).

PipelineRunStatus

SingletonData

One unclustered, unassigned face (orange section).

Enums

Error

Errors returned by videre-api operations. Each consumer maps these to its own convention (axum -> StatusCode, other embedders -> their own error type).

Functions

assign

Assign faces to an existing/new person: sets person_label + confirmed. Rejects an empty label after sanitizing.

cluster_detail

Every face in one unassigned cluster (for the cluster detail page).

delete_person

Reset every face of a person back to unassigned. Deliberately does NOT touch cluster_id, so a face rejoins its cluster’s unassigned group rather than scattering to singletons.

dissolve_cluster

Ungroup a bad cluster: its faces become unassigned singletons (not deleted).

face_bytes_from_lookup

The expensive part of face_image_bytes: cache check, decode/crop/encode, write-through. Takes no Connection, so it can run without holding the shared DB lock.

face_image_bytes

JPEG bytes for a single aligned face thumbnail (140px), reading the disk cache first and converting from the source image (HEIC via QuickLook) on a miss, writing through to the cache. Returns Error::NotFound if the face id is unknown or the crop cannot be produced. Synchronous: callers that need async should run this on a blocking thread.

face_lookup

The cheap part of face_image_bytes: just the DB row. No image I/O.

faces_list

People / unassigned clusters / singletons for the labeling page.

library_stats

make_face_thumb

Load, crop, and orientation-correct a face thumbnail.

mime_for_ext

new_person

Create a person from faces. Same effect as assign; kept as a distinct operation because callers treat “new person” and “assign to existing” as separate user intents.

original_bytes_from_lookup

The expensive part of original_image_bytes: read/convert/cache. Takes no Connection, so it can run without holding the shared DB lock.

original_image_bytes

Bytes for the full original image behind a face (raw for common formats, QuickLook-converted JPEG for HEIC, with the HEIC result cached). Returns the MIME type alongside the bytes. Error::NotFound if the id is unknown or the file cannot be read/converted. Synchronous.

original_lookup

The cheap part of original_image_bytes: just the DB row. No image I/O.

person_detail

Every confirmed face for one person, primary first and flagged.

pipeline_status

remove_face

Reset one face to fully unassigned (cluster, label, confirmed, primary).

rename_person

Rename a person. NotFound if old_label has no faces; Conflict if new_label (after sanitizing) already belongs to a different person; Invalid if the new label sanitizes to empty.

sanitize_person_label

Trim, collapse internal whitespace, and cap length (60 code points) so a caller that bypasses UI sanitization can’t stretch layout or bloat the DB. Returns None when nothing usable remains. Filters control and bidi/ zero-width format characters but deliberately keeps U+200C (ZWNJ) and U+200D (ZWJ), which are required for Persian/Indic text and emoji ZWJ sequences. Not homoglyph-proof, and the cap truncates by code point.

search_person

Image paths for confirmed faces of a person (prefix match), for the person-name autocomplete. Delegates to the existing core search.

set_primary

Mark one face as the person’s primary (their labeling-page thumbnail), clearing any previous primary in the same transaction so exactly one remains. The target update is guarded by person_label so it can’t steal a face from another person.

Type Aliases

Result