Python API Reference

The affvisionpy module — the native SDK wrapped for Python. Methods are snake_case, enum values are lowercase, and metric maps are plain dictionaries. This page documents exactly what the Python binding exposes; anything not listed here (for example the sensor/connector pipeline) is available only in C++.

Module

import affvisionpy as af

Attribute	Value / type	Description
af.__version__	str, e.g. "5.4.0.123"	full SDK version
af.DEFAULT_PROCESSING_FRAME_RATE	30.0	default target processing rate (fps)
af.DEFAULT_MAX_NUM_FACES	1	default maximum tracked faces
af.DEFAULT_MAX_THREAD_POOL_SIZE	0	0 = “use number of CPU cores − 1” analysis threads
af.ALL_FEATURES, af.ALL_EXPRESSIONS, af.ALL_EMOTIONS, af.ALL_MEASUREMENTS, af.ALL_FACE_POINTS, af.ALL_QUALITIES	collections	every value of the corresponding enum

af.Frame

Wraps one image and its timestamp. pixels is any object exposing the buffer protocol — a NumPy array works directly, so an OpenCV image (numpy.ndarray in BGR order) can be passed as-is.

af.Frame.ColorFormat

rgb, bgr, rgba, bgra, yuv_nv21, yuv_i420, yuv_yuy2, gray — pixel channel orderings; OpenCV images are bgr.

af.Frame.Rotation

upright, cw_90, cw_180, cw_270 — how the image is rotated (clockwise) relative to an upright face. Declaring the rotation avoids rotating pixel buffers yourself.

Detectors

af.SyncFrameDetector — synchronous

Processes every pushed frame (never drops) and invokes callbacks on the thread that called process(), which blocks until the frame’s callbacks complete. Best for offline video analysis.

Method	Description
start(license_key="")	validates the license and initializes processing; an empty string falls back to the AFFECTIVA_LICENSE_KEY environment variable
stop()	stops processing and deallocates resources
reset()	re-initializes for a new session; timestamps may restart at 0
is_running()	True after start() and before stop()
process(frame)	processes an af.Frame; callbacks fire before it returns
set_face_listener(listener)	register an af.FaceListener
set_image_listener(listener) Deprecated	register an af.ImageListener
enable_feature(feature) / enable_features({...})	add to the enabled feature set
disable_feature(feature) / disable_features({...})	remove from the enabled feature set
is_enabled(feature) / is_enabled({features})	True if the feature — or all features in the set — are enabled
get_enabled_features()	the currently enabled set

af.FrameDetector — asynchronous

Queues frames for a native background thread with real-time semantics: if input outpaces process_frame_rate, excess frames are dropped. Callbacks arrive on the background thread.

Methods are the same as af.SyncFrameDetector with three differences:

Method	Description
is_feature_enabled(feature)	True if the feature is enabled (this class’s spelling of is_enabled)
are_features_enabled({features})	True only if all given features are enabled
process(frame) / stop()	release the GIL while native code runs, so your capture loop is not blocked

af.Face

One tracked face in a processed frame, delivered to your listener as a dict keyed by face id.

Method	Returns
get_id()	int — tracking identifier, stable while the face stays in view
get_confidence()	float — confidence in the presence of the face, 0–100
get_expressions()	dict {af.Expression: float}
get_emotions()	dict {af.Emotion: float}
get_measurements()	dict {af.Measurement: float}
get_qualities()	dict {af.Quality: float}
get_bounding_box()	list of two af.Points: top-left, then bottom-right
get_face_points()	dict {af.FacePoint: af.Point}

af.Point

A 2-D pixel coordinate with read/write attributes x and y. Constructors: af.Point(), af.Point(x, y).

af.BoundingBox

A rectangle built from two points: af.BoundingBox(tl, br), with get_top_left() and get_bottom_right().

Listeners

af.FaceListener

Subclass it, override all three methods, and register with set_face_listener() before start(). Keep a reference to the listener for as long as it is registered.

Callback	Called when
face_found(timestamp, face_id)	the tracker starts tracking a new face
face_lost(timestamp, face_id)	a tracked face is no longer found
results_updated(faces, frame)	a frame has been processed; faces is dict {int: af.Face}, frame the processed af.Frame

af.ImageListener Deprecated

Superseded by af.FaceListener. Callbacks: results_updated(faces, frame) and image_captured(frame) (fires for every input frame, including frames the asynchronous detector chose not to process).

Enumerations

The tables below give concise definitions. For a full explanation of each metric — the facial actions behind it, value semantics, and interpretation guidance — see the Metrics guide.

af.Feature

faces, expressions, emotions — the metric families a detector can compute. Face tracking metrics (bounding box, face points, measurements, qualities, confidence) are always delivered for tracked faces.

af.Expression

Continuous metrics range 0 (absent) to 100 (fully present); event metrics report 0 or 100.

Value	Description	Range
smile	upward pull of the lip corners	0–100
inner_brow_raise	raising of the inner brow corners	0–100
brow_raise	raising of both brows	0–100
brow_furrow	lowering/drawing together of the brows	0–100
nose_wrinkle	wrinkling of the nose	0–100
upper_lip_raise	raising of the upper lip	0–100
lip_corner_depressor	downward pull of the lip corners	0–100
chin_raise	upward push of the chin boss	0–100
lip_pucker	puckering of the lips	0–100
lip_press	pressing the lips together	0–100
lip_suck	pulling the lips inward	0–100
mouth_open	parting of the lips	0–100
smirk	asymmetric lip corner pull	0–100
eye_closure	both eyelids closed	0–100
speaking	the person is speaking	0–100
attention	visual attention toward the camera (head orientation)	0–100
eye_widen	widening of the eyes	0–100
cheek_raise	raising of the cheeks	0–100
lid_tighten	tightening of the eyelids	0–100
dimpler	tightening of the lip corners (dimpling)	0–100
lip_stretch	horizontal stretching of the lips	0–100
jaw_drop	lowering of the jaw	0–100
blink	a blink occurred	0 / 100
blink_rate	blinks per minute; NaN during the first 10 s after a face is detected	blinks/min
yawn	a yawn occurred	0 / 100
pain	continuous estimate that the person is expressing pain; 50 is the model’s decision threshold, so values above 50 mean pain is more likely present than not	0–100

af.Emotion

0–100 except the valence metrics (−100 to +100).

Value	Description	Range
joy	degree of expressed joy	0–100
fear	degree of expressed fear	0–100
disgust	degree of expressed disgust	0–100
sadness	degree of expressed sadness	0–100
anger	degree of expressed anger	0–100
surprise	degree of expressed surprise	0–100
contempt	degree of expressed contempt	0–100
neutral	degree to which the face shows no emotion	0–100
sentimentality	degree of expressed sentimentality	0–100
confusion	degree of expressed confusion	0–100
valence	overall positivity (+) or negativity (−) of the expression	−100–100
engagement	overall facial expressiveness	0–100
conversational_valence	valence variant tuned for conversational settings	−100–100
conversational_engagement	engagement variant tuned for conversational settings	0–100
adaptive_valence	valence variant that adapts to the individual’s baseline	−100–100
adaptive_engagement	engagement variant that adapts to the individual’s baseline	0–100

af.Measurement

Value	Description	Unit
pitch	positive = head tilted up, negative = tilted down	degrees
yaw	positive = head turned to the person’s right, negative = to their left	degrees
roll	positive = head tilted to the person’s left, negative = to their right	degrees
interocular_distance	distance between the two outer eye corner landmarks	pixels

af.FacePoint

outer_right_eye, outer_left_eye, nose_tip, chin_tip — landmark identifiers for get_face_points().

af.Quality

brightness (0–100) — useful for detecting under- or over-exposed capture conditions.

af.BaselineMode

OFF — metrics calculated statically (default); ON — metrics calculated against a rolling-average “baseline” that adapts to the individual’s neutral expression. Passed as the first constructor argument of either detector.

Errors & threading

• Native SDK exceptions are raised as RuntimeError, with nested causes appended to the message (e.g. a missing license key on start()).
• The C++ ProcessStatusListener is not exposed in Python. With af.SyncFrameDetector, errors propagate directly out of process(); prefer it when robust error handling matters.
• With af.FrameDetector, listener callbacks run on the SDK’s background thread — hand results to your main thread via a queue.Queue or similar rather than touching shared state directly.