.. _liveness-api:

Liveness Detection as Standalone Service
======================================================

.. seealso::
   :ref:`liveness`

You can harness :ref:`face liveness detection <liveness>` as a standalone service ``findface-liveness-api``. The service takes a specific number of frames from a video fragment and returns the best quality face, and decimal liveness result averaged across the taken frames.  If configured, the service can also return full-frame and normalized face images and save the detection result in the ``findface-sf-api`` cache, returning ``detection_id``.


.. rubric:: In this section:

.. contents::
   :local:

Install and Configure ``findface-liveness-api``
--------------------------------------------------

To install ``findface-liveness-api``, do the following:

#. :ref:`Install <install-repo>` the FindFace Security APT repository. 

#. From the APT repository, install the service as such:

   .. code::  

      sudo apt update
      sudo apt install findface-liveness-api

#. If necessary, configure the ``findface-liveness-api`` parameters:

   .. code::

      sudo vi /etc/findface-liveness-api.ini

      listen: :18301
      liveness-threshold: 0.75   
      fullframe-jpeg-quality: 75
      max-decoded-frames: 30
      min-selected-frames: 10
   
      extraction-api:
        request-batch-size: 16
        timeouts:
          connect: 5s
          response_header: 30s
          overall: 35s
          idle_connection: 10s
        extraction-api: http://127.0.0.1:18666

      sf-api:
        timeouts:
          connect: 5s
          response_header: 30s
          overall: 35s
          idle_connection: 10s
        sf-api: http://127.0.0.1:18411

      limits:
        video-size: 10485760
        video-length-sec: 60
        video-fps: 30
        video-width-px: 1920
        video-height-px: 1080

   +----------------------------+----------------------------------------------------------------------------------------------+
   | Parameter                  | Description                                                                                  |
   +============================+==============================================================================================+
   | ``fullframe-jpeg-quality`` | JPEG quality of full frames in the ``photo`` field.                                          |
   +----------------------------+----------------------------------------------------------------------------------------------+
   | ``max-decoded-frames``     | Finish decoding after reaching the specified number of frames.                               |
   +----------------------------+----------------------------------------------------------------------------------------------+
   | ``min-selected-frames``    | The minimum number of final frames successfully passed                                       |
   |                            | through decoding and liveness extraction. Must be equal or less than ``max-decoded-frames``. |
   +----------------------------+----------------------------------------------------------------------------------------------+
   | ``extraction-api`` ->      | Batch size for liveness extraction.                                                          |
   | ``request-batch-size``     |                                                                                              |
   +----------------------------+----------------------------------------------------------------------------------------------+
   | ``limits`` ->              | Maximum video size, bytes.                                                                   |
   | ``video-size``             |                                                                                              |
   +----------------------------+----------------------------------------------------------------------------------------------+
   | ``limits`` ->              | Maximum video length, seconds.                                                               | 
   | ``video-length-sec``       |                                                                                              |
   +----------------------------+----------------------------------------------------------------------------------------------+
   | ``limits`` ->              | Maximum video FPS.                                                                           |
   | ``video-fps``              |                                                                                              |
   +----------------------------+----------------------------------------------------------------------------------------------+
   | ``limits`` ->              | Maximum video width, pixels.                                                                 |
   | ``video-width-px``         |                                                                                              | 
   +----------------------------+----------------------------------------------------------------------------------------------+
   | ``limits`` ->              | Maximum video height, pixels.                                                                |
   | ``video-height-px``        |                                                                                              | 
   +----------------------------+----------------------------------------------------------------------------------------------+

#. In the ``findface-extraction-api`` configuration file, specify the neural network model that provides the liveness standalone service: ``liveness.alleyn.cpu.fnk``/``liveness.alleyn.gpu.fnk``.

   .. code::

      sudo vi /etc/findface-extraction-api.ini

      extractors:
        ...
        models:
         ...
         liveness: faceattr/liveness.alleyn.cpu.fnk
         ...
        ...

      extractors:
        ...
        models:
         ...
         liveness: faceattr/liveness.alleyn.gpu.fnk
         ...
        ...

#. Start the ``findface-liveness-api`` service and enable its autostart.

   .. code::

      sudo systemctl enable findface-liveness-api.service && sudo systemctl start findface-liveness-api.service



Liveness API Usage
--------------------

To interact with the ``findface-liveness-api`` service, use HTTP API requests. In the example below, the POST request is sent with the following optional parameters:

* ``return_detection`` (``default=False``): save the best face in the ``findface-sf-api`` cache and return its ``detection_id``.
* ``return_normalized`` (``default=False``): return the face normalized image in the ``normalized`` field.
* ``return_photo`` (``default=False``): return the full frame in the ``photo`` field.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -i -X POST \
     'http://127.0.0.1:18301/v1/video-liveness?return_detection=true&return_normalized=true&return_photo=true' \
     -H 'Content-Type: video/mp4' \
     --data-binary '@/home/my_video.mp4'

.. rubric:: Response

.. code::

   HTTP/1.1 100 Continue
   HTTP/1.1 200 OK
   Content-Type: application/json
   X-Request-Id: LA:WSP2NcHc
   Date: Mon, 07 Sep 2020 15:30:05 GMT
   Transfer-Encoding: chunked
   {
           "alive": true,
           "average_liveness": 0.8706386,
           "best_face": {
                   "liveness": 0.74768883,
                   "quality": 0.89638597,
                   "bbox": {
                           "left": 0,
                           "top": 578,
                           "right": 307,
                           "bottom": 1154
                   },
                   "detection_id": "btb53vbp688s1njt3bv0",
                   "photo": "/9j/2wCEAAgGBgcGBQgHBwcJ...",
                   "normalized": "iVBORw0KGgoAAAANSUhEU...",
                   "frame_no": 1,
                   "frame_ts": 0.033275817
           }
   }