# Face triggers

> Understand the tracking signals and blink gestures that an authored .nosmai package can use to drive animation and material values.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: core-concepts
Source: https://nosmai.com/docs/effects/concepts/triggers/

## What a trigger does

A trigger maps a face-tracking signal to an authored effect value. Continuous
triggers can move a material value as the signal changes. Event triggers can
start, stop, toggle, or play an animation after a gesture.

Triggers are authored inside the package. Application developers apply the
package normally and do not receive raw face landmarks.

## Available signals

| Signal | Meaning | Typical use |
| --- | --- | --- |
| `faceFound` | A face starts being tracked | Reveal or start an effect |
| `faceLost` | The tracked face is no longer available | Hide or pause an effect |
| `faceScale` | Relative face size in the frame | Drive scale or proximity reactions |
| `headYaw` | Left and right head rotation | Directional animation |
| `headPitch` | Up and down head rotation | Tilt-based animation |
| `headRoll` | Sideways head tilt | Rotate or balance an element |
| `blinkLeft` | Left-eye blink value | Eye-specific or wink interaction |
| `blinkRight` | Right-eye blink value | Eye-specific or wink interaction |
| Blendshape name | A package-requested facial coefficient, when available | Advanced authored deformation or animation |

## Blink gestures

The trigger runtime supports raw values plus `wink`, `longBlink`, and
`doubleBlink` gesture recognition. A gesture can use the left eye, right eye,
or either eye.

Event modes include `toggle`, `momentary`, `oneShot`, and `pingPong`. Authored
timing options control attack, release, delay, hold, thresholds, and the
refractory window.

## Tracking behaviour

An effect should handle temporary face loss without leaving stale content on
screen. Tracking can become less stable at frame edges, under heavy occlusion,
in low light, or during very fast motion. Test the package with glasses, facial
hair, partial faces, and front-camera mirroring.

Nosmai face triggers are not a general emotion-classification API. The public
SDK does not expose raw landmarks for application-defined gesture detection.

## Next steps

- [Add an AR face mask in iOS](/docs/effects/guides/effects/add-an-ar-mask/ios/)
- [Understand authored packages](/docs/effects/concepts/filters-and-effects/)
- [Review limits and performance](/docs/effects/limits-and-performance/)

## References

- [Platform support](/docs/effects/platform-support/)
- [Nosmai Effects](https://nosmai.com/effects/)