Skip to content

Additional information#

Activity diagram for Liveness and Primary Track Policy#

Below is a diagram of FaceStream activity when using Liveness and Primary Track Policy.

Activity diagram for Liveness and Primary Track Policy
Activity diagram for Liveness and Primary Track Policy

Nuances of working with stream preview#

In order to write the preview address of the stream (the "preview" > "live" > "url" field) to the LUNA Streams stream, FaceStream must determine its IP address. It determines its IP address in one of two ways:

  • Via connecting to the LUNA Streams service.
  • Via the system environment variable "VL_FACE_HOST". The environment variable can be set by executing the following command in the server terminal: export VL_FACE_HOST=<your_ip_address>.

If the IP address of the "VL_FACE_HOST" variable is set incorrectly, then LUNA Streams will delete streams with an incorrect address, and FaceStream will terminate with the following error Failed to validate input json.

Using an environment variable overrides the way you connect to the LUNA Streams service.

If the IP address of FaceStream is determined by connecting to the LUNA Streams service, then to determine its IP address, FaceStream must always start after LUNA Streams. If for some reason FaceStream started before LUNA Streams (for example, the server was restarted, where both FaceStream and LUNA Streams are running), then FaceStream may terminate with the error Failed to get local IP address. Reason. If the FaceStream IP address is determined through the system environment variable "VL_FACE_HOST", then the above error will not occur.

Proxying requests to LUNA Streams using LUNA API#

If FaceStream is used in conjunction with LUNA PLATFORM, then it is possible to send part of the requests to the LUNA Streams service via the LUNA API service.

To do this, you need to enable and configure the special built-in plugin “luna-streams.py” in the API service. The plugin is located in the API service container at the path /srv/luna_api/plugins and is enabled using the "LUNA_API_ACTIVE_PLUGINS" setting.

See more information about the plugin mechanism in the "Plugins" section of the LUNA PLATFORM administrator manual.

The following settings are available for the plugin, specified in the "LUNA_API_PLUGINS_SETTINGS" configuration of the API service:

  • "luna-streams-address" > "origin" — Protocol, IP address and port of the LUNA Streams service.
  • "luna-streams-address" > "api_version" — API version of the LUNA Streams service.
  • "luna-streams-timeouts" > "connect" — Timeout for establishing a connection when sending an HTTP request to the LUNA Streams service.
  • "luna-streams-timeouts" > "request" — General timeout for completing the entire HTTP request.
  • "luna-streams-timeouts" > "sock_connect" — Timeout for establishing a connection at the socket level.
  • "luna-streams-timeouts" > "sock_read" — Timeout for reading data from the socket after a successful connection.

If the "LUNA_API_PLUGINS_SETTINGS" configuration or the settings described above are not specified, the default values will be applied. See the "LUNA_API_PLUGINS_SETTINGS" section of the LUNA PLATFORM administrator manual for details of the above settings and their default values.

Example of setting the "LUNA_API_PLUGINS_SETTINGS" setting:

{
     "luna-streams": {
         "luna-streams-address": {
             "origin": "http://127.0.0.1:5160",
             "api_version": 2
         },
         "luna-streams-timeouts": {
             "request": 60,
             "connect": 20,
             "sock_connect": 10,
             "sock_read": 60
         }
     }
}

If necessary, you can differentiate access rights for requests to LUNA Streams using token permissions. To do this, you need to create a new or update an existing token by passing a custom "streams" key with permissions for the token.

To proxy requests from the LUNA API service to the LUNA Streams service, you need to specify a permission named "streams". Other custom key names will not work.

You can set the following permissions:

  • "creation" (POST requests)
  • "view" (GET requests)
  • "modification" (PUT requests and PATCH requests)
  • "deletion" (DELETE requests)

Example of specifying a custom key "streams" with all possible permissions in a token creation request body:

{
    "permissions": {
        "streams": [
            "creation",
            "view",
            "modification",
            "deletion"
        ]
    }
}

See detailed information about tokens in the “Accounts, tokens and authorization types" section of the LUNA PLATFORM administrator manual.

The table below shows the ratio of routes in the LUNA API and LUNA Streams, as well as links to requests and possible token resolutions.

LUNA API route LUNA Streams route Requests Token permission
prefix/version /version get version None
prefix/docs/spec /{api_version}/docs/spec get openapi documentation None
prefix/plugins /{api_version}/plugins get list of plugins None
prefix/streams /{api_version}/streams create stream Custom key
get streams
delete streams
prefix/streams/count /{api_version}/streams/count delete streams Custom key
prefix/streams/{stream_id} /{api_version}/streams/{stream_id} get stream Custom key
update stream
put stream
remove stream
prefix/streams/logs /{api_version}/streams/logs get streams logs Custom key
delete streams logs
prefix/streams/{stream_id}/preview/handler/live /{api_version}/streams/{stream_id}/preview/handler/live get live preview Custom key
prefix/streams/{stream_id}/preview/handler/frame /{api_version}/streams/{stream_id}/preview/handler/frame get last frame preview Custom key

Prefix is /6/plugins/luna-streams.

You can send requests to both the first version of the LUNA Streams API and the second. To do this, you need to use the LUNA-STREAMS-API-VERSION header as follows:

  • If the LUNA-STREAMS-API-VERSION header is not specified, the first API version will be automatically selected.
  • If the value of the LUNA-STREAMS-API-VERSION header is "1", the first version will be selected.
  • If the value of the LUNA-STREAMS-API-VERSION header is "2", the second version of the API will be selected.
  • Otherwise an error will be returned.

Event data generated by FaceStream#

By processing streams, FaceStream passes requests to generate events to LUNA PLATFORM. To generate an event, when creating a stream, you must fill in the "event_handler" field, indicating the handler ID in the "bestshot_handler" field, the address and API version of the LUNA API service, and the address where the source frame will be saved (if necessary).

Below is a table explaining what data processed by FaceStream is recorded in the LUNA PLATFORM event.

Parameter name Description
account_id Account ID set during the creation of a stream in LUNA Streams.
create_time Start time of the track (time of event occurrence in the video stream) relative to the server FS time.
end_time End time of the track (time of event completion in the video stream) relative to the server FS time.
handler_id Handler ID set during the creation of a stream in LUNA Streams.
stream_id Stream ID in LUNA Streams.
source Field "name" set during the creation of a stream in LUNA Streams.
track_id FaceStream track ID.
face_detections: Face detection data:
* sample_id: Sample ID, created if the "face_sample_policy" is enabled.
* detect_time: Time of detection of the face best shot relative to the server FS time.
* image_origin: Source frame.
* detect_ts: Time of detection of the face best shot relative to the start of the video file.
* detection: Bounding box coordinates with face detection ("x", "y", width, height).
body_detections: Body detection data:
* sample_id: Sample ID, created if the "body_sample_policy" is enabled.
* detect_time: Time of detection of the body best shot relative to the server FS time.
* image_origin: Source frame.
* detect_ts: Time of detection of the body best shot relative to the start of the video file.
* detection: Bounding box coordinates with body detection ("x", "y", width, height).
location Location data set during the creation of a stream in LUNA Streams.

In addition to the above parameters, the event will be supplemented with parameters generated by the specified handler (for example, "face_id", "match_result", "attach_result", "gender", etc.). The fields "external_id" and "user_data" will always remain empty when generating an event based on a sample transferred from FaceStream.