API reference

Everything public lives in com.knight98.facevity (simple API) and com.knight98.facevity.kit (FaceUnity-style API). The library is built in Kotlin explicit-API mode; everything else is internal.

Facevity

Facevity implements FrameProcessor. Create one per camera pipeline.

Member	Thread	Notes
Facevity.initialize(context, options = FacevityOptions())	any	Creates an engine and starts loading the face model
Facevity.VERSION		"0.3.2"
setBeautyEnabled(Boolean), isBeautyEnabled	any	Off = exact pass-through
setParams(BeautyParams), params	any	All levels at once
setSmoothIntensity(0..100), setBrightness(0..100), setSkinTone(-100..100), setRosy, setEvenTone, setOverallIntensity(0..100)	any	Convenience setters (clamped)
setLipstick(shade, level), setTeethWhitening(level), setBacklightFix(level)	any	0.3
availableProps(): List<PropInfo>, setProp(id), clearProp(), currentProp, propIcon(id), addPropsDirectory(dir)	any	0.3.1, AR accessories
capabilities(): FacevityCapabilities, prepareCapabilities(), addCapabilitiesListener, removeCapabilitiesListener	any	0.3, what this licence supports
processTexture(TextureFrame): Int	GL	Returns the input id (pass-through) or an engine-owned 2D texture
processBuffer(BufferFrame): Boolean	any	In place; false = untouched
processFrame(...)		Aliases of the two methods above
isActive	any	false when nothing would be done
onGlContextDestroyed()	GL	Frees GL objects of the current context
resetTracking(), facesDetected	any
stats(): FacevityStats, resetStats()	any	Counters and timings
release()	any	Frees the buffer thread and the face model
licenseInfo, setLicenseToken(String), setLicenseFile(String / InputStream), activateLicense(key, listener?), refreshLicense(), addLicenseListener, removeLicenseListener	any	No network on the frame path

BeautyParams

Immutable and clamped. Kotlin: BeautyParams(smooth = 60) or params.toBuilder().smooth(70).build(). Java: new BeautyParams.Builder().smooth(60).lipstick(BeautyColors.LIP_RED, 60).build().

Slider scale (since 0.3.0). Every 0..100 level follows one curve: 0 = off, 50 = natural, 100 = strong but still realistic. Levels stored by a 0.2 app should be converted once; see the migration guide.

Field	Range	Default
smooth	0..100	55
brightness	0..100	40
skinTone	-100..100	0
rosy	0..100	42
sharpen (clarity on eyes, brows, hair)	0..100	40
eyeBrighten (iris lift, whites cleared)	0..100	0
underEye (dark circles)	0..100	43
evenTone	0..100	30
foldSoften (smile lines)	0..100	0
teethWhitening	0..100	0
teethBrighten (extra lift on whitened teeth)	0..100	40
backlightFix (automatic, acts only on backlit faces)	0..100	50
lipColor (natural boost, or lipstick opacity when a shade is set)	0..100	0
lipShade	BeautyColors.NATURAL or a colour 0xRRGGBB	NATURAL
lipGloss	0 matte .. 100 gloss	30
slimFace, jawSlim, bigEyes	0..100	0
filter	origin, natural, warm, cool, fresh, vivid, soft, rose, mono	origin (none)
filterLevel	0..100	54
overall	0..100	100

Builder shortcuts: lipstick(shade, level), lipShade, lipGloss, teethBrighten, backlightFix. Presets: NATURAL, GLAM, DEFAULT, NONE (NONE also turns backlight off). Helpers: isIdentity, usesReshape, usesMakeup, clampLevel, fromUnit(Float) (maps a 0..1 slider value to a level).

BeautyColors

• Lipstick: LIP_NUDE, LIP_ROSE, LIP_RED, LIP_BERRY, LIP_CORAL, LIP_PLUM, and LIP_SHADES (id to colour).
• NATURAL (no shade), rgb(r, g, b) for any other colour.

FacevityCapabilities

What this licence supports, so you can hide controls that would have no effect. Cheap; any thread.

Field	Meaning
lipstickSupported	Lipstick shades (beauty.makeup)
teethWhiteningSupported, backlightSupported	Teeth whitening and backlight compensation
reshapeSupported	Slim face, jaw and eye enlarging (beauty.reshape)
propsSupported	AR accessories (ar.props)

All of them work from the face landmarks on every device.

Call prepareCapabilities() early (it starts loading the segmenter) and listen with addCapabilitiesListener { caps -> }; changes are checked every 30 processed frames.

AR accessories (props)

Member	Notes
availableProps()	PropInfo(id, name, anchor) in display order; anchor is eyes, forehead, head_top, nose, ears or face
setProp(id) / clearProp()	Shows one prop on every tracked face; false for an unknown id. The image is decoded in the background and appears a frame or two later
currentProp	Id shown now, or null
propIcon(id)	128×128 tile bitmap for a picker
addPropsDirectory(dir)	Adds a downloaded pack: one folder per prop with prop.json, prop.png, icon.png. Returns the ids added

Built-in ids: aviator, wayfarer, sport_goggles, round_glasses, heart_glasses, baseball_cap, beanie, crown, flower_headband, cat_ears, earring. Needs the ar.props licence feature.

FacevityOptions

Build with FacevityOptions.Builder().

Option	Range / values	Default
maxFaces	1..4	1
detectionLongSide	160..640 px	320
bufferBudgetMs	5..200	40 (used until the frame interval is known)
adaptiveBufferBudget	75% of the measured frame interval	true
maxBufferBudgetMs	cap for the adaptive budget	80
bufferPipelining	one frame of latency when the GPU is slow	true
segmentation	SegmentationMode.AUTO (GPU only), ON, OFF	AUTO
unlicensedBehavior	WATERMARK, PASSTHROUGH	WATERMARK
licenseToken	signed token	none
licenseServerUrl	URL	none
offlineGraceDays	1..30	7
yuvFullRange	true = full-range BT.601, false = video range	true
measureGpuTime	debug profiling	false
allowDevLicenses	null = debuggable builds only	null
licenseAsset	asset path	facevity/license.fvl

Frames

• TextureFrame(textureId, isOes, width, height, rotation = 0, mirrored = false, timestampNs, transformMatrix = null, outputLayout = OutputLayout.RAW). OutputLayout.RAW or SAME_AS_INPUT. rotation refers to the raw buffer.
• BufferFrame(data, format, width, height, rotation, mirrored, timestampNs) with PixelFormat.NV21, NV12 or I420. BufferFrame.requiredSize(w, h).
• FrameOrientation: uprightRotation(sensorOrientation, displayRotation, front), displayRotationOfDeviceOrientation(deviceOrientation), displayMatrix(rotation, mirror), stripCameraTransform(m), cameraTransform(m), cameraTransformOf(m).
• YuvPlanes: packI420(...), unpackI420(...) for strided planes.
• FrameProcessor: isActive, onGlContextCreated(), onGlContextDestroyed(), processTexture(), processBuffer(). This is the interface to depend on in your own video pipeline.

FacevityStats

framesIn, framesProcessed, framesPassedThrough, framesDropped, framesRepeated, framesFailed, avgProcessMs, maxProcessMs, avgDetectMs, detectFps, processFps, facesTracked, detectorReady, lastError, effectOffEvents, plus stageSummary (CPU time per pipeline stage), trackingSummary and segmentationSummary. Debug views: setDebugMaskView(0..6) (5 = lipstick weight; 6 = backlight lift, region and beard zone).

Licensing types

• LicenseInfo: status, type (TRIAL, PRODUCTION, INTERNAL), environment, licence id, customer, features, issue and expiry dates, watermark, offline flag.
• LicenseStatus: VALID and OFFLINE_GRACE are licensed. Not licensed: NONE, EXPIRED, OFFLINE_GRACE_EXCEEDED, NOT_YET_VALID, INVALID_SIGNATURE, UNKNOWN_KEY, MALFORMED, WRONG_ISSUER, WRONG_AUDIENCE, WRONG_DEVICE, WRONG_CERTIFICATE, WRONG_ENVIRONMENT, SUSPENDED, REVOKED.
• LicenseFeatures: beauty.basic, beauty.reshape, buffer.path, beauty.segmentation, beauty.makeup (lipstick shades), ar.props (accessories). See Licensing.
• LicenseListener: onLicenseChanged(info).

FaceUnity-style kit API

Package com.knight98.facevity.kit:

• FVRenderManager.setup(context, licenseToken, callback, options), setupWithKey(context, serverUrl, key, callback), licenseInfo, sdkVersion
• FVRenderKit.getInstance(): faceBeauty, aiKit, renderWithInput(FVRenderInputData), release(), releaseAll(), stats(), capabilities(), prepareCapabilities(), setProp(id), clearProp(), availableProps()
• FVAIKit: loadAIProcessor(path, FVAIType.FACE_PROCESSOR), setMaxFaces, isTracking(), resetTrackStatus(), releaseAIProcessor
• FVFaceBeauty: intensity properties (see the migration guide), including lipstickColor, lipGlossIntensity, teethBrightIntensity, backlightIntensity; applyParams(BeautyParams)
• FVRenderInputData (texture: FVTexture, imageBuffer: FVImageBuffer, renderConfig: FVRenderConfig) → FVRenderOutputData (texture, image)
• Enums: FVInputTextureType, FVBufferFormat, FVExternalInputType, FVCameraFacing, FVTransformMatrix, FVCodes