.. _liveness-api:

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

.. seealso::
   :ref:`liveness`

Besides the :ref:`integrated <liveness>` anti-spoofing system that distinguishes a live face from a face image, FindFace Server provides an API-based face liveness detection service ``liveness-api``.

The ``liveness-api`` service takes a specific number of frames from a provided video fragment and returns the best quality face, along with a decimal liveness result for it, 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 ``sf-api`` cache, returning ``detection_id``.

To install and use the ``liveness-api`` service standalone, see :ref:`liveness installation <deploy_liveness>`.


.. rubric:: In this section:

.. contents::
   :local:


.. _liveness_configure:

Configure ``liveness-api``
--------------------------------------------------

To configure the ``liveness-api`` component, do the following:

#. Create a default ``liveness-api.yaml`` configuration file (e.g., into the ``/opt/ffserver/configs`` directory).

   .. code:: bash

      docker run --rm -ti --name liveness-api-cfg \
          docker.int.ntl/ntech/universe/liveness-api:ffserver-12.240830.2 \
          --config-template > /opt/ffserver/configs/liveness-api.yaml


#. You can configure the ``liveness-api`` parameters according to your needs in the ``/opt/ffserver/configs/liveness-api.yaml`` configuration file. You can find its default content :download:`here <_scripts/default_liveness-api.yaml>`. Enable liveness recognition in the ``/opt/ffserver/configs/extraction-api.yaml`` configuration file by specifying the extraction model in the ``face_liveness`` section. See :ref:`face-features`.

When configuring ``liveness-api``, refer to the following parameters:

.. list-table::
     :widths: 14 8 45
     :header-rows: 1

     * - Command line flags
       - Type
       - Description
     * - ``-attributes``
       - value
       - Array of attributes to extract.
     * - ``-config``
       - string
       - Path to config file
     * - ``-config-template``
       -
       - Output config template and exit.
     * - ``-debug``
       -
       - Debug.
     * - ``-extraction-api-extraction-api``
       - string
       - Extraction API address (default ``http://127.0.0.1:18666``).
     * - ``-extraction-api-request-batch-size``
       - int
       - Extraction API request batch size (default 16).
     * - ``-extraction-api-timeouts-connect``
       - duration
       - extraction-api-timeouts-connect (default 5s).
     * - ``-extraction-api-timeouts-idle-connection``
       - duration
       - extraction-api-timeouts-idle-connection (default 10s).
     * - ``-extraction-api-timeouts-overall``
       - duration
       - extraction-api-timeouts-overall (default 35s).
     * - ``-extraction-api-timeouts-response-header``
       - duration
       - extraction-api-timeouts-response-header (default 30s).
     * - ``-fullframe-jpeg-quality``
       - int
       - JPEG quality of full frames in the ``photo`` field (default 75).
     * - ``-help``
       -
       - Print help information.
     * - ``-limits-video-fps``
       - float
       - Maximum video frames per second (default 60).
     * - ``-limits-video-height-px``
       - int
       - Maximum video height in px (default 1080).
     * - ``-limits-video-length-sec``
       - float
       - Maximum video length in seconds (default 60).
     * - ``-limits-video-size``
       - int
       - Maximum size of video supplied in request body, bytes (default 10485760).
     * - ``-limits-video-width-px``
       - int
       - Maximum video width in pixels (default 1920)
     * - ``-listen``
       - string
       - IP:port to listen on (default ``:18301``).
     * - ``-liveness-threshold``
       - float
       - Liveness threshold (default 0.994).
     * - ``-liveness-variant``
       - string
       - :ref:`Liveness model variant <configure_variant>`.
     * - ``-max-decoded-frames``
       - int
       - Finish decoding after reaching the specified number of frames (default 30).
     * - ``-mf-selector``
       - string
       - Service behavior upon having multiple faces in the video frame: ``reject`` - reject this frame, ``biggest`` - use the biggest face for liveness detection (default ``reject``).
     * - ``-min-selected-frames``
       - int
       - The minimum number of final frames successfully passed through decoding and liveness extraction. Must be equal or less than ``max-decoded-frames``. (default 10).
     * - ``-processing-script``
       - string
       - Path to LUA file with processing_script function (default ``processing_score.lua``).
     * - ``-reject-ignore-secondary-faces-by-proportion``
       - float
       - Proportion of the secondary faces for them to be ignored.
     * - ``-sf-api-sf-api``
       - string
       - SF API address (default ``http://127.0.0.1:18411``).
     * - ``-sf-api-timeouts-connect``
       - duration
       - sf-api-timeouts-connect (default 5s).
     * - ``-sf-api-timeouts-idle-connection``
       - duration
       - sf-api-timeouts-idle-connection (default 10s).
     * - ``-sf-api-timeouts-overall``
       - duration
       - sf-api-timeouts-overall (default 35s).
     * - ``-sf-api-timeouts-response-header``
       - duration
       - sf-api-timeouts-response-header (default 30s).


The format of environment variable for flag ``-my-flag`` is ``CFG_MY_FLAG``.

Priority:

#. Defaults from source code (lowest priority).
#. Configuration file.
#. Environment variables.
#. Command line.

.. note::

  When working with ``processing_<attribute>.lua`` don't forget to get the appropriate attribute by setting it in the configuration file in the ``attributes`` section.

The default ``processing_score.lua`` file describes the logic of choosing the best face:

.. code:: lua

  function process(candidates)

      local best_frame_idx = nil
      local best_score = nil
      for idx, candidate in pairs(candidates) do
          local score = candidate.score
          if (best_frame_idx == nil) or (best_score < score) then
              best_score = score
              best_frame_idx = idx
          end
      end

      return best_frame_idx
  end


.. _configure_variant:

Configure Attribute Variant
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you use :ref:`multiple extraction models <multiple_extraction_models>` for a ``face_liveness`` attribute, specify a variant in the ``liveness-variant`` field of the ``liveness-api.yaml`` configuration file. Thus, you will be able to use the configured liveness variant in requests to :ref:`extraction-api <extraction_api>` without specifying the ``liveness_variant`` parameter in requests to :ref:`liveness-api <liveness_api_requests>`. Do the following:

.. code::

   sudo vi /path/to/ffserver-12.240830.2/configs/liveness-api.yaml

   ...   
   liveness-variant: "pvn"
   ...

For any other attribute, specify a variant in the ``attributes`` parameter of the ``liveness-api.yaml`` configuration file. Thus, you will be able to use the configured attribute variant in requests to :ref:`extraction-api <extraction_api>` without specifying the attribute variant parameter in requests to :ref:`liveness-api <liveness_api_requests>`. Do the following:

.. code::

   sudo vi /path/to/ffserver-12.240830.2/configs/liveness-api.yaml

   ...   
   attributes:
     - face_age|v3
   ... 


.. _liveness_api_requests:

HTTP API Requests to ``liveness-api``
------------------------------------------------

To interact with the ``liveness-api`` service, use HTTP API requests to ``http://liveness-api:18301/``.

.. code::

  POST /v1/video-liveness

This method determines liveness by video.

.. rubric:: Query string parameters:

* ``return_detection`` (``required=false``, ``default=False``): boolean, save the best face in the ``sf-api`` cache and return its ``detection_id``.
* ``return_normalized`` (``required=false``, ``default=False``): boolean, return the face normalized image in the ``normalized`` field.
* ``return_photo`` (``required=false``, ``default=False``): boolean, return the full frame in the ``photo`` field.
* ``liveness_variant`` (``required=false``, ``default=""``): string, use a variant of the ``face_liveness`` extractor. Read more :ref:`here <multiple_extraction_models>`. There's an option to :ref:`specify a variant <configure_variant>` in the ``liveness-api.yaml`` configuration file to use it constantly in requests to the ``extraction-api`` service.

.. rubric:: Request Body:

Contains a video file.

.. rubric:: Responses with Common Codes:

.. list-table::
     :widths: 8 45
     :header-rows: 1

     * - Code
       - Description
     * - 200
       - OK. Returns ``application/json``.
     * - 400
       - Bad Request.
     * - 405
       - Invalid input.
     * - 406
       - Not Acceptable.
     * - 500
       - Internal Server Error.


.. rubric:: Example

.. rubric:: Request

.. code:: bash

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

.. rubric:: Response

.. code::

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
      "alive":true,
      "average_liveness":0.9521886,
      "best_face":{
         "liveness":0.9557304,
         "quality":0.91568387,
         "bbox":{
            "left":138,
            "top":172,
            "right":363,
            "bottom":468
         },
         "detection_id":"btfiva1o8cjc1k44q1vg",
         "photo":"/9j/2wCEAAgGBgcGBQgHBwcJ...",
         "normalized":"iVBORw0KGgoAAAANSUU...",
         "frame_no":14,
         "frame_ts":0.56
      }
   }