HTTP API
BlinkEasy offers a simple way to interface with your own application by letting you define a callback url. This advanced option can be used to implement custom analytics or to control IOT-devices. For example, to adjust lighting based on blink rate in a smart home scenario (ESP32 code sample).
- In the settings page under API enter the desired url (http or https).
Requests will be made immediately when an event occurs and periodically to submit statistics like the current blink rate. - If desired, the current video frame can be send as well for further image processing.
- Custom parameters are supported, for example to submit credentials or to distinguish between devices.
Parameters send with every request:
| event | ID of the event. Possible values: BLINK, START, END, BPM, ALERT, BREAK |
| timestamp | Milliseconds elapsed since Jan 01 1970 (UTC). |
Example:
http://localhost:3000/myscript.php?event=START×tamp=1723321032811
Possible events:
BLINK
Send when a blink was detected.
Parameters:
| duration | Blink duration in milliseconds |
| bpm | Current Blinkrate (blinks per minute) |
Example:
http://localhost:3000/myscript.php?event=BLINK&bpm=13.2&duration=185×tamp=1723321032811
START
Send when a face was detected for the first time, starting the session.
Example:
http://localhost:3000/myscript.php?event=START×tamp=1723321032811
END
Send when for timeout milliseconds no faces were detected, ending the current session.
Parameters:
| timeout | Current session timeout in milliseconds. The last time a face was recognized is the events timestamp minus the timeout. |
Example:
http://localhost:3000/myscript.php?event=END&timeout=60×tamp=1723321032811
BPM
Periodic event
Parameters:
| bpm | Current blink rate in blinks per minute. |
Example:
http://localhost:3000/myscript.php?event=BPM&bpm=13.2×tamp=1723321032811
ALERT
Send when the user's blink rate has fallen under the given threshold. This event will also be send when blink reminders are disabled.
Parameters:
| bpm | Current blink rate in blinks per minute. |
| target | The threshold that the current blink rate has fallen below. |
| duration | Number of milliseconds below the target until the alert was issued. |
Example:
http://localhost:3000/myscript.php?event=ALERT&bpm=13.2&target=15.0&duration=12×tamp=1723321032811
BREAK
A break reminder was issued.
Parameters:
none
Example:
http://localhost:3000/myscript.php?event=BREAK×tamp=1723321032811
Video Frame Parameters:
When activated, the BLINK and START events will upload the current video frame as a JPEG image.
| frame | The current videoframe. Jpeg compressed and encoded as multipart/formdata (same way you would normally handle file uploads in a webapp). |
| frame_width | Width in pixels. |
| frame_height | Height in pixels. |
| face_x | If detected, the pixel position and dimensions of the user's face and eyes. If not detected, facial features will have neither width nor height. It is possible that a face but no eyes, or only one eye was detected. |
| face_y | |
| face_width | |
| face_height | |
| eye_left_x | |
| eye_right_x | |
| eye_left_y | |
| eye_right_y | |
| eye_left_width | |
| eye_right_width | |
| eye_left_height | |
| eye_right_height |