Streams management configuration#

The application supports simultaneous work with several stream sources.

Parameters for stream management are set in the LUNA Streams service. The service enables you to create and store streams in the LUNA Streams database.

Several types of sources are supported:

tcp, udp – real-time video signal sources. These can be both USB cameras and IP cameras (via RTSP protocol);
videofile – video files;
images – a set of frames in the form of separate image files.

Note that the streams management settings are not stored in the LUNA Configurator service and can only be set using HTTP requests to the LUNA Streams service. A detailed description of requests and example requests can be found in the Open API specification of LUNA Streams service. The LUNA Streams settings set in LUNA Configurator are described in the section "LUNA Streams settings".

Account_id parameter#

The parameter specifies the mandatory "account_id" field, which is passed to LUNA PLATFORM 5 service API in the request header.

Account ID is set in the UUID4 format. You can find the requirements for the Account ID in the LUNA PLATFORM 5 documentation.

The parameter is used to bind the received data to a specific user.

"account_id" : {
    "value" : "aaba1111-2111-4111-a7a7-5caf86621b5a",
    "description" : "Luna_account_id header value for Luna api version 6 or higher ('' by default)."
}

Name parameter#

Source name. It is used to identify the source of the sent frames.

"name": "stream_0",

Recorded in the "source" field of the LP event.

Description parameter#

User description of the stream.

"description": "Stream on Arbat street",

This parameter is not recorded to the LP event.

Data section#

The general parameters required to configure stream are listed below.

Type parameter#

The type of stream transmission. The application can use one of the following types of stream transmission:

tcp - network protocol to receive video data
udp - network protocol to receive video data
images - set of frames as separate image files
videofile - video file

"type": "tcp",

TCP Protocol implements an error control mechanism that minimizes the loss of information and the skip of the reference frames at the cost of increasing the network delay. Key frames are the basis of various compression algorithms used in video codecs (for example, h264). Only the reference frames contain enough information to restore (decode) the image completely, while the intermediate frames contain only differences between adjacent reference frames.

In terms of broadcasting on the network, there is a risk of package loss due to imperfect communication channels. In case of loss of the package containing the data keyframe, the stream fragment cannot be correctly decoded. Consequently, distinctive artifacts appear, that are easily and visually distinguishable. These artifacts do not allow the face detector to operate in normal mode.

The UDP protocol does not implement an error control mechanism, so the stream is not protected from damage. The use of this protocol is recommended only, if there is a high-quality network infrastructure.

With a large number of streams (10 or more), it is strongly recommended to use the UDP protocol. When using the TCP protocol, there may be problems with reading streams.

Reference parameter#

Full path to the source (for "tcp"/"udp" type):

"reference": "rtsp://some_stream_address"

USB device number (for "tcp"/"udp" type):

"reference": "/dev/video0"

To use USB device, you should specify the --device flag with the address of the USB device when launching the FaceStream Docker container. See the "Launching keys" section of the FaceStream installation manual.

Full path to the video file (for "videofile" type):

"reference": https://127.0.0.1:0000/super_server/

Full path to the directory with the images (for "images" type).

"reference": "/example1/path/to/images/"

To use video files and images, you should first move them to a docker container.

Roi parameter#

This parameter is used only for working with faces.

ROI specifies the region of interest in which the face detection and tracking are performed.

The specified rectangular area is cut out from the frame and FaceStream performs further processing using this image.

Correct exploitation of the "roi" parameter significantly improves the performance of FaceStream.

Region of interest (ROI) on the original frame is set in pixels as array [x, y width, height], where (x, y) are the coordinates of the upper-left point of the region of interest. Coordinate system is set in the same way as it is shown on the picture below.

When the values of width and height are set to "0", the entire frame will be the region of interest.

"roi": [0, 0, 0, 0],

Droi parameter#

This parameter is used only for working with faces.

The parameter specifies the region of interest within the ROI zone. Face detection is performed in ROI, but the best shot is selected only in the DROI area. Face detection must be completely within the DROI zone for the frame to be considered as a best shot.

DROI is recommended to use when working with Access Control Systems and when the "use_mask_liveness_filtration" mode is enabled.

For example, it can be used, if there are several turnstiles close to each other and their cameras should find faces only in a small area and simultaneously perform Liveness check. Using DROI enables to limit the area of the best shot selection without losing information about the background.

Desired region of interest (DROI) on the original frame is set in pixels as array [x, y width, height], where (x, y) are the coordinates of the upper-left point of the desired region of interest. When calculating DROI, one must take into account that this region of interest is calculated relative to the original frame, and not relative to ROI.

Coordinate system is set in the same way as it is shown in the picture below.

When the ROI size is changed and the DROI size remains the default (0, 0, 0, 0), the DROI is not considered. If you change the size of the DROI, it will be considered when choosing the best frame.

"droi": [0, 0, 0, 0],

Rotation parameter#

The rotation angle of the image source. It is used when the incoming stream is rotated, for example, if the camera is installed on the ceiling. Rotation is clockwise.

"rotation": 0,

Preferred_program_stream_frame_width parameter#

This parameter is used only for tcp or udp types and is intended to work with protocols that imply the presence of several channels with different bitrates and resolutions (for example, HLS).

If the stream has several such channels, then this parameter will enable you to select from all the channels of the whole stream the channel whose frame width is closer to the value specified in this parameter.

For example, there are 4 channels whose frame widths are 100, 500, 1000 and 1400. If the parameter "preferred_program_stream_frame_width" is equal to "800", then a channel with a frame width of 1000 will be selected.

If the stream has only one channel, this parameter will be ignored.

The default value is 800.

"preferred_program_stream_frame_width": 800

Endless parameter#

This parameter enables you to control the restart of the stream when a network error is received (the error is determined by the system as an eof (end-of-file) marker).

The parameter is available only for the "udp" and "tcp" source types.

If the endless parameter takes the value true, then in case of receiving eof and successful reconnection, the processing of the stream will continue. If all reconnection attempts failed (see the "healthcheck" section), then the stream will take the "failure" status. If the parameter takes the value false, then the processing of the stream will not continue and the status of the stream will take the "done" status.

When using a video file as a "tcp" or "udp" source, it is assumed to use the value false. This will avoid re-processing an already processed fragment of the video file when receiving eof. If, when using a video file, the value of the endless parameter is true, then after the processing is completed, the video file will be processed from the beginning.

"endless": true

Mask parameter#

This parameter is used only for the images type and is a mandatory parameter.

A mask of file names in the directory with images. The mask allows FaceStream to understand which files from the specified folder should be used and in what order.

If you set the mask "Img_%02d.jpg", then FaceStream will take from the folder files which names consist of: Prefix (Img_) + two-digit number (%02d) + format (.jpg)

The following images will be taken in turn:

Img_00.jpg
Img_01.jpg
Img_02.jpg
Img_03.jpg

Another example of a mask is Photo-%09d.jpg. The following images will be taken:

Photo-000000000.jpg
Photo-000000001.jpg
Photo-000000002.jpg
Photo-000000003.jpg

FaceStream processes files in numerical order and does not skip nonexistent files. If there is a missing file in the file sequence FaceStream stops files processing.

The specified mask "example1_%04d.jpg" in the example will result in image processing, which name is composed of an "example1_" prefix and of a sequential frame number, of 4 characters size (for example: example1_0001.jpg, example1_0002.jpg, etc.).

"mask": "example1_%04d.jpg"

Event_handler section#

This section defines the parameters of the handler created in the LUNA PLATFORM, with which video streams will be processed. Different handlers should be used for the face and bodies. Handler should be created in LP 5 in advance.

For more information about handlers, see the LUNA PLATFORM administrator manual.

Origin parameter#

The full network path to the API service of the deployed LUNA PLATFORM, which includes the LUNA Handlers and LUNA Events services necessary to generate an event by handler.

"origin": "http://luna_address:port/"

luna_address - the LUNA API service address,

port - the port used by the LUNA API service. The default port is 5000.

Api_version parameter#

The API version for generating events in the LUNA PLATFORM. Currently, version 6 of the API is supported.

Handler_id parameter of bestshot_handler section#

The parameter enables you to use the external "handler_id" LUNA PLATFORM to process face or body samples according to the specified rules. When using this handler, LUNA PLATFORM generates an event that contains all the information received from FaceStream and processes it in accordance with the processing rules.

"handler_id": "aaba1111-2111-4111-a7a7-5caf86621b5a",

Handler should be created in LP 5 in advance.

Handler_id parameter of detection_handler section#

The parameter enables you to use the external dynamic "handler_id" LUNA PLATFORM for working with bodies. This parameter is used in conjunction with the minimal_body_track_length_to_send parameter and their interaction enables you to send detections with human body coordinates (x, y, width and height) along with the bestshots.

Handler should be created in LP 5 in advance.

"handler_id": "aaba1111-2111-4111-a7a7-5caf86621b5a",

This parameter is optional and is required only if it is necessary to detect the coordinates of the human body.

For more information about dynamic handlers, see the LUNA PLATFORM administrator manual.

Frame_store parameter#

This parameter sets a URL for saving the source frames of faces or bodies in LUNA PLATFORM 5.

As the URL, you can specify either the address to the LUNA Image Store service bucket, or the address to the "/images" resource of the LUNA API service. When specifying the address to the "/images" resource, the source frame will be saved under the "image_id".

The send_source_frame option should be enabled for sending source frames.

Example of address to LUNA Image Store bucket:

"frame_store": "http://127.0.0.1:5020/1/buckets/<frames>/images"

127.0.0.1 - IP address where the LUNA Image Store service is deployed;

5020 - the default Image Store service port.

1 - API version of the LUNA Image Store service;

<frames> - the name of the LUNA Image Store bucket where the source image of face or body should be saved. The bucket should be created in advance.

An example of the "source-images" bucket creation:

curl -X POST http://127.0.0.1:5020/1/buckets?bucket=source-images

Example of address to "/images" resource of LUNA API service:

"frame_store": "http://127.0.0.1:5000/6/images"

127.0.0.1 - IP address where the LUNA API service is deployed;

6 - API version of the LUNA API service;

5000 - default port of the API service.

See the LUNA PLATFORM 5 administrator's manual for more information about buckets and the "/images" resource.

Authorization section#

In this section, either token or account_id are set to make requests to the LUNA API service.

The event_handler > authorization > account_id parameter must match the account_id parameter specified in the request. If the authorization field is not filled in, then the account_id specified when the stream was created will be used (see Account_id parameter).

See the LUNA PLATFORM 5 administrator manual for details on LUNA PLATFORM authorization.

"authorization": {
  "account_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515"
}

Policies section#

Sending section#

This section defines a period during which frames will be analyzed to select the bestshot, as well as all parameters associated with compiling a collection of the bestshots.

"sending": {
    "time_period_of_searching": -1,
    "silent_period" : 0,
    "type" : "sec",
    "number_of_bestshots_to_send": 1
    "send_only_full_set": true
    "delete_track_after_sending" false
},

Time_period_of_searching parameter#

Interval in track after the end of which a best shot is sent to the server (period starts with the first detection – person appears in the frame). Lowering this parameter speeds up recognition but decreases precision.

The measurement type is set in the "type" parameter (see below). If the value equals "-1" (by default), analysis is conducted on all frames until the end of track. Once the track is over (person leaves the frame), best shot is sent to an external service.

"time_period_of_searching": -1,

Silent_period parameter#

Interval between period. Once the analysis period is over, the system holds this silent_period before starting next period of frame analysis.

The measurement type is set in the "type" parameter (see below). If the value equals "-1", system holds silent period indefinitely.

"silent_period" : 0,

Type parameter#

The parameter specifies the measurement type for the "silent_period" and "time_period_of_searing" parameters. It can take two values - "frames" or "sec".

"type" : "sec",

Number_of_bestshots_to_send parameter#

Number of bestshots that the user sets to receive from the track or certain periods of this track. This parameter enables collection of bestshots from a track or a certain period of a track set in parameter time_period_of_searching.

"number_of_bestshots_to_send": 1

Increasing parameter’s value increases the probability of correct object recognition but affects the network load.

Send_only_full_set parameter#

This parameter is used only for working with bodies.

This parameter enables to send data only if the required number of best shots ("number_of_bestshots_to_send" parameter of FaceStream settings) and detections with human body coordinates ( "minimal_body_track_length_to_send" parameter of FaceStream settings) have been collected.

"send_only_full_set" : true

Delete_track_after_sending parameter#

This parameter is used only for working with bodies.

This parameter enables to delete the best shots and detections with human body coordinates after sending the data. If the value is "false" (by default), then the data will remain in memory.

"delete_track_after_sending" : false

Primary_track_policy section#

This section is used only for working with faces.

This section is designed to work with Access Control Systems (ACS, turnstiles at the entrances to banks/office buildings) to simplify the control and the introduction of facial recognition technology at the entrance to a protected area. The parameters group is not used for the "images" type.

Use_primary_track_policy parameter#

Use_primary_track_policy parameter is used in cases of Access Control Systems (turnstiles/gates at the office/bank entrances) for easier control and face recognition implementation in a secured area.

If the parameter value is "true", the primary track implementation mode is enabled.

Out of all detections, one of the biggest sizes is selected and its track becomes the primary one. Further analysis is conducted on this track. The best shot from this track is then sent to the server.

All other tracks are processed in regular mode. However, the best shot is sent only from the primary track.

As soon as another face reaches a larger size than the face from the primary track, this face track becomes primary and the processing is performed for it.

While using this parameter at the access control checkpoint, only the best shots of the person who is the closest to the turnstiles will be sent to the server (here the biggest detection size condition is held)

"use_primary_track_policy": false,

Best_shot_min_size parameter#

The parameter is used when "use_primary_track_policy" parameter is enabled.

Best_shot_min_size parameter sets the minimal height of detection in pixels at which the analysis of frames and bestshot definition begins.

"best_shot_min_size": 70,

Best_shot_proper_size parameter#

The parameter is used when "use_primary_track_policy" parameter is enabled.

Best_shot_proper_size parameter sets the height of detection in pixels for Primary track policy. When a detection reaches the defined value, track immediately sends all its best shots to the server.

"best_shot_proper_size": 140

Liveness section#

This section is used only for working with faces.

Liveness is used to check whether a person in the frame is real and prevents fraud when printed photos or images on the phone are used to pass the Liveness check.

It is recommended to use this functionality only after discussing it with the VisionLabs team.

The parameters group is not used for the "images" type.

General recommendations for Liveness usage#

Liveness can be used at access control checkpoints only. This is a case when a person does not stay in front of the camera for more than ten seconds.

Liveness is used to minimize the risk of fraud when someone is trying to enter a secured area using a printed photo or a photo on a phone of someone who has the access rights.

Liveness returns a value, which defines the degree of the system certainty on whether the person in the frame is real. The value is in the range of 0 to 1.

Camera placement requirements

The following conditions must be met for Liveness check set up:

Face should remain within a frame. The distance from left and right edges of the frame should be greater than or equal to the width of the face, the distance from the top and bottom edges of the frame should be greater than or equal to the height of the face;
The frame should include the chest region;
A camera should be located about waist height and should look upwards capturing the body and head;
The frame should not include rectangular elements framing the face area from all four sides (such as doorways or windows).

An example of the correct camera location is given in the image below.

FS starts collecting frames and selecting the bestshot at a distance of 3-4 meters when a camera is placed properly.

Foreign objects and people who do not pass through the turnstile do not get into the camera view zone.

FS sends the bestshot when a person is at a distance of 1 meter from the camera. At this distance, the face reaches the size required for sending.

An example of inappropriate camera placement is given in the image below.

Inappropriate camera placement for Liveness

If the camera is not configured correctly:

The person gets into the frame too late. FS does not have time to get the required number of frames for processing;
The person looks upside-down at the camera. This degrades the quality of the frame for subsequent processing;
The camera field of view covers the area outside the area of interest. This space may contain people or objects that interfere with the correct operation of the FS.

Recommendations for configuring FS

The recommended values for the "Liveness" section parameters are given below.

"use_shoulders_liveness_filtration": true,
"use_mask_liveness_filtration": true,
"use_flying_faces_liveness_filtration": true,
"liveness_mode": 1,
"number_of_liveness_checks": 10,
"liveness_threshold": 0.8,
"livenesses_weights": [0.0, 0.25, 0.75],
"mask_backgrounds_count": 300

We do not recommend changing these settings.

The "best_shot_min_size" parameter should be set based on the fact that the person is at a distance of 3-4 meters from the turnstile.

The "best_shot_proper_size" parameter should be set based on the fact that the person is at a distance of 1 meter from the turnstile.

To control the selection of the right person, use the "droi" parameter. The rectangle is selected so that people who have the intention to approach this turnstile appear in the rectangle as early as possible. This is true for turnstiles located close to each other. People from neighboring queues can get into the view zone of the cameras of such turnstiles.

FAQ Liveness

Stream processing is slow when using Liveness

When the camera resolution is 1920 x 1080 and higher, Mask Liveness is working slowly.

To solve the problem, you should manually reduce the resolution in the camera to 720p. This will not affect the quality of recognition and the work of Liveness, because they work without loss of quality with faces that are approximately 100 pixels in size.

People cannot pass the Liveness check under the default FS settings

Possible causes:

The default settings in the Liveness section have been changed.

Do not change the settings in the Liveness section, except for the "liveness_threshold" setting.

The value of the "liveness_threshold" parameter can be reduced, but it should not be lower than "0.6".

Liveness is not applied to the target case.

FS Liveness is not intended for authorization processes and cases of a long stay in front of the camera.

Unacceptable objects fall into the camera's view zone.

For example, if there is a screen broadcasting a video in the background, Liveness will not work.

The camera is set to the wrong resolution.

Check the camera resolution. See "Stream processing is slow when using Liveness".

There is a delay in the transmission of frames.

If the camera does not transmit frames in real-time, then the frames may arrive with a delay.

The value "best_shot_min_size" is set incorrectly.

If the "best_shot_min_size" parameter is too high, Liveness does not have time to accumulate the required number of different frames.

Use_shoulders_liveness_filtration parameter#

The parameter enables checking the presence of a real person in the frame based on the head and shoulder areas.

"use_shoulders_liveness_filtration": false,

Use_mask_liveness_filtration parameter#

The parameter enables checking the presence of a real person in the frame based on backgrounds.

The check performance depends on the size of the video frames. If the processing speed decreases when the parameter is enabled, it is necessary to reduce the video resolution in the camera settings (e.g., up to 1280x720).

"use_mask_liveness_filtration": false,

Use_flying_faces_liveness_filtration parameter#

The parameter enables checking the presence of a real person in the frame based on the facial surrounding.

"use_flying_faces_liveness_filtration": false,

Liveness_mode parameter#

This parameter enables to specify which frames from a track will undergo Liveness check. There are three options for selecting a frame:

0 - First N frames;
1 - Last N frames before the best shot sending (recommended value);
2 - All frames in a track.

N value is specified in the number_of_liveness_checks parameter.

"liveness_mode": 0,

Number_of_liveness_checks parameter#

The parameter enables to specify the number of frames to check fo Liveness. The specified value is used in the liveness_mode parameter.

It is not recommended to set a value less than 10.

"number_of_liveness_checks": 10,

Liveness_threshold parameter#

The liveness_threshold parameter value is used to define the presence of a real person in a frame. The system confirms that it is a real person in the frame, and not a photo, only if Liveness returned a value higher than the one specified in the parameter.

The recommended value is "0.8". It is not recommended to set a value lower than "0.6".

"liveness_threshold": 0.8,

Liveness_weights parameter#

The parameter determines the involvement of each liveness check type (shoulders, mask, and flying_faces) in the resulting estimation of the presence of a human face in the frame.

User must specify three values assigned to different types of liveness. Values are specified in decimals in the following order:

Use_shoulders_liveness_filtration,
Use_mask_liveness_filtration,
Use_flying_faces_liveness_filtration.

In the example present (which is the system default) below 0.0 determines that 5% of liveness estimation will be based on shoulders_liveness, 0.25 - 25% on mask_liveness, and 0.75 - 75% on flying_faces_liveness.

The ratio is always calculated based on liveness_weights values, even if they don’t add up to one, or not all liveness types are active.

"livenesses_weights": [0.0, 0.25, 0.75]

Mask_backgrounds_count parameter#

The number of background frames that are used for the corresponding checks.

Do not change this parameter.

"mask_backgrounds_count": 300

Filtering section#

The section describes the filter object parameters and modes of sending the resulting bestshots.

"filtering": {
    "min_score": 0.5187,
    "detection_yaw_threshold": 40,
    "detection_pitch_threshold": 40,
    "detection_roll_threshold": 30,
    "yaw_number": 1,
    "yaw_collection_mode": false,
    "mouth_occlusion_threshold" : 0.0
},

Min_score parameter#

Min_score, also known as Approximate Garbage Score (AGS) for faces or Detector score for bodies – score that defines detection quality, threshold for filtering detections sent to the server. All detections with score higher than the value of this parameter can be sent to the server as HTTP-requests, otherwise detections are considered as not appropriate for further analysis.

If a new detection has a higher threshold than those in the existing collection, it will replace the detection with lowest threshold.

Recommended value was established through research and analysis of detections on various face and body images.

"min_score" : 0.5187,

Detection_yaw_threshold parameter#

This parameter is used only for working with faces.

This parameter sets the maximum value of head yaw angle in relation to camera.

If, in a frame, head yaw angle is above the value of this parameter, the frame is considered as not appropriate for further analysis.

"detection_yaw_threshold" : 40,

Detection_pitch_threshold parameter#

This parameter is used only for working with faces.

This parameter sets the maximum value of head pitch angle in relation to camera.

If, in a frame, head pitch angle is above the value of this parameter, the frame is considered as not appropriate for further analysis.

"detection_pitch_threshold" : 40,

Detection_roll_threshold parameter#

This parameter is used only for working with faces.

This parameter sets the maximum value of head yaw angle in relation to camera.

If, in a frame, head roll angle is above the value of this parameter, the frame is considered as not appropriate for further analysis.

"detection_roll_threshold" : 30,

Yaw_number parameter#

This parameter is used only for working with faces.

This parameter defines the number of frames for image filtration based on head yaw angle. This filter removes images where head’s yaw angle is too high.

How it works:

Parameter specifies the number of frames to analyze. A special algorithm analyzes head yaw angles on each of those frames. If on one of them the angle is significantly different from the average value of angles, the frame will not be considered as a candidate for best shot.

Example. Parameter value is set "7", meaning 7 frames will be analyzed. If on six of the frames the rotation angle is in the range between 50-60 degrees and the angle on the seventh frame is estimated at 0, the angle on the seventh frame is, most likely, estimated incorrectly. Reason is: a person cannot turn his head so abruptly in such short period of time. The seventh frame will not be considered for best shot.

By default, the parameter is disabled, the value is "1". The recommended value is "7".

"yaw_number": 1,

Yaw_collection_mode parameter#

This parameter is used only for working with faces.

This parameter sets the number of frames the system must collect the number of frames specified in the "yaw_number" parameter to analyze the head yaw angle.

If "yaw_collection_mode" parameter is disabled, the system will analyze the frames sequentially, meaning it analyzes one frame, then two, then three and so on. Maximum number of frames to analyze is set in "yaw_number" parameter.

Parameter is disabled by default.

"yaw_collection_mode" : false,

The purpose of utilizing "yaw_number" and "yaw_collection_mode" parameters is to increase the accuracy of best shot selection from a track.

Mouth_occlusion_threshold parameter#

This parameter is used only for working with faces.

This parameter determines how much the mouth can be obscured in the frame.

I.e. when the value is equal to "0.5", 50% of the mouth can be occluded.

If mouth occlusion of a face in a frame exceeds the value of this threshold, the frame is considered as not appropriate for further analysis.

The filtration is performed when the set value is "0.3" or higher. When the value is lover, the filtration is disabled.

"mouth_occlusion_threshold" : 0.0,

Min_body_size_threshold parameter#

The parameter sets the body detection size, less than which it will not be sent for processing. It is calculated as the square root of the product of the body detection height (in pixels) by its width (in pixels).

Example: min_body_size_threshold = sqrt (64*128) = 90.5

If the value is "0", then filtering of body detection by size will not be performed.

"min_body_size_threshold" : 0,

Frame_processing_mode parameter#

This parameter is used for "tcp", "udp" and "videofile" types only.

This parameter is similar to convert_full_frame, but is set for a specific FaceStream instance.

If the value is set to "full", the frame is immediately converted to RGB image of the required size after decoding. This results in a better image quality and reduces the speed of frames processing.

When set to "scale", the image is scaled according to the settings in the TrackEngine configuration (standard behavior for releases 3.2.4 and earlier).

The default value is "auto". In this case, one of the two modes is selected automatically.

"frame_processing_mode": "auto",

Real_time_mode_fps parameter#

This parameter is used for "videofile" type only.

This parameter enables you to set the number of FPS with which the video stream will be processed.

If a video has high FPS value and FaceStream cannot work with the specified number of frames per second, frames are skipped.

Thus, the video file emits a stream from a real video camera. It can be useful for performance tuning. The video will be played at the specified speed, which is convenient for load testing and subsequent analysis.

This parameter is disabled when set to "0".

"real_time_mode_fps" : 0

Ffmpeg_threads_number#

The parameter enables to specify the number of threads for decoding video using FFMPEG.

The number of processor cores involved in decoding process increases according to the number of threads. An increase in the number of threads is recommended when processing high-resolution video (4K or higher).

"ffmpeg_threads_number" : 0

Health_check section#

The section is used only for the "tcp", "udp" and "videofile" types.

In this group, you can set the parameters for reconnecting to the stream when errors occur while the video is streamed.

Max_error_count parameter#

The maximum number of errors when playing the stream.

The parameter works in conjunction with the "period" and "retry_delay" parameters. After receiving the first error, the wait specified in the "retry_delay" parameter is performed, and then the connection to the stream is retried. If during the time specified in the "period" parameter, the number of errors greater than or equal to the number specified in "max_error_count" was accumulated, then the processing of the stream will be terminated and its status will change to "failure".

For example, when it is unable to retrieve or decode a frame. Network problems or inaccessibility of a video can cause the errors.

"max_error_count": 10,

Period parameter#

The parameter represents the period during which the number of errors is calculated. The value is set in seconds.

The parameter works in conjunction with the "retry_delay" and "max_error_count" parameters. See the description of working with this parameter in the "max_error_count" section.

"period": 3600,

Retry_delay parameter#

The parameter specifies the period after which the reconnection attempt is performed. The value is set in seconds.

The parameter works in conjunction with the "period" and "max_error_count" parameters. See the description of working with this parameter in the "max_error_count" section.

"retry_delay": 5

Location section#

This section includes information about the location of the video source.

"city"
"area"
"district"
"street"
"house_number"
"geo_position" - latitude and longitude in degrees. Geo position is considered as properly specified if both longitude and latitude are set.

The send_location_data parameter enables the sending of location data of the video source.

"location": {
    "send_location_data" : false,
    "city": "Moscow",
    "area": "CAO",
    "district": "Arbat",
    "street": "Arbat",
    "house_number": "37",
    "geo_position": {
    "longitude": 36.616,
    "latitude": 55.752
    }
}

This parameter is used to generate events in the LUNA PLATFORM (see the LUNA PLATFORM documentation).

Autorestart section#

This section enables you to configure the automatic restart of the stream. Three parameters are available:

restart - whether to use automatic restart of the stream
attempt_count - number of attempts to automatically restart the thread (default 10)
delay - stream automatic restart delay, in seconds (default 60 seconds)

"autorestart": {
    "restart": 1,
    "attempt_count": 7,
    "delay": 600
}

Status parameter#

The status at the start of processing. Two states are available - "pending" and "pause".

"status": "pending"

In addition to the two states at the start of processing, other states that occur during FaceStream operation are also available (see the "Stream distribution in LUNA Streams" section).

Group_name and group_id parameters#

Parameters for linking a stream to a group. You can specify either the "group_id" or "group_name".

"group_id": "426542d6-5509-4e5b-8a01-e2abd5c0a8c6"

"group_name": "hd_stream_2"