Skip to content

Video issues and solutions#

This section describes common video streaming failure scenarios and troubleshooting methods.

Before diagnosing complex scenarios, it is recommended to perform basic checks:

  • Check that your credentials are available and up-to-date;

  • Ensure that the camera URL is correct and accessible from the network where the server is located;

  • Check that the maximum number of connections to the camera itself has not been reached.

If basic checks reveal no issues, but streams continue to disconnect, consider the following typical scenarios.

1․ Problem: The stream is created, but immediately goes into a 'failure' state with a codec initialization error.

Signs of the problem:

  • In the stream's video_info section, all parameters are zero or have default values, indicating no data.

  • The FaceStream logs contain errors such as: initCodec - avcodec_open2 failed! Generic error in an external library, openVideo - initCodec failed!, Stream: ... got error: Couldn't find or init appropriate codec for stream source.

Possible cause:

The video card's hardware decoder (NVDEC) is overloaded. When its usage reaches ~99%, it stops initializing new streams and starts returning errors.

Solution:

  • Enable mixed decoding. To do this, set the mixed_decode parameter in the FaceStream settings. This parameter determines the percentage of streams decoded on the CPU and can range from 0 to 100%. The optimal value is determined experimentally depending on the processor performance and load. Recommended initial values ​​are from 5 to 10, then increased in increments of 5 until the processor can handle the load.

Important! Changing this parameter requires restarting the FaceStream service for the configuration to apply.

  • Check load balancing. Ensure that streams are distributed evenly across all available GPUs. Body detection generates the heaviest load, followed by the combined detection and face detection. This must be taken into account when distributing.

2․ Problem: The stream operates normally for some time, after which it suddenly shuts down.

Signs of the problem:

  • the stream was in the "in_progress" status for a while, then went into "failure";

  • the FaceStream logs contain an error like Interrupt by timeout while reading video frame: 1000 ms..

Possible cause:

The server is unable to receive video data from the camera within the configured timeout. This may be caused by high network load or an unstable network connection to the camera.

Solution: Increase the timeout value. It can be set in the body of the stream creation request ("create stream") in the policies > healthcheck > timeout section. It is recommended to set the value in the range of 3000–10000 ms (3–10 seconds) instead of the default 1000 ms. A good starting point is 3000 ms.

3․ Problem: The stream does not restart automatically after an abnormal termination.

Signs of the problem:

After an error, the stream remains in the "failure" status and does not automatically resume operation, even after a container reboot.

Possible Cause:

  1. The number of restart attempts has been exhausted (if the attempt_count parameter is set and exceeded).
  2. A critical error has occurred that is considered unrecoverable by the system. In this case, an automatic restart will not occur, regardless of the attempt_count value.

Solution:

  1. Increase the number of automatic restart attempts. This value can be set in the body of the stream update request ("put stream") in the autorestart > attempt_count section.
  2. Recreate the stream manually if the error is critical.