.. _video-about: How to Use Video Object Detection API --------------------------------------------------------------- .. rubric:: In this section: .. contents:: :local: Job Life Cycle ^^^^^^^^^^^^^^^^^^^^^^^^ |videomanager-statuses_en| .. |videomanager-statuses_en| image:: /_static/videomanager-statuses_en.png :scale: 55% * AWAITING – the job is waiting for a suitable instance of the ``video-worker``. The job gets this status immediately after the creation, or after stopping with an error if ``single_pass==false`` and it can be restarted. A job can be in this status while it has not yet been assigned, when there are no instances of the ``video-worker`` with suitable labels, or when the maximum number of video streams that ``video-worker`` allowed to process exceeds the ``capacity`` value. * STARTING – the job has been sent to the ``video-worked``, but hasn't processed any frame yet. * INPROGRESS – the job is being processed by the ``video-worker`` and has processed at least one frame. * COMPLETED – the job was completed successfully at the end of the file or stream. Only jobs with ``single_pass==true`` are permitted to remain in this status for a long time, other ones will be restarted. * INTERRUPTED – the stream processing was interrupted with an error. If the job hasn't ``single_pass`` option, it will be restarted. * MISCONFIGURED – the assigned ``video-worker`` can't process this job due to configuration inaccuracy. The job will try to run on another ``video-worker``. * TOO_MANY_CAMERAS – the stream is unable to be started due to license restrictions. The job can try to run again, if there will be free slots in the license. * NOT_STARTED – the attempt to process is completed by an error without processing any frame. The job can try to run on another ``video-worker``. * DISCONNECTED – the connection with the assigned to process the job ``video-worker`` has been lost. * DISABLED – the job is set to ``enabled: false``. This status is accessible from any status. After changing option ``enabled`` to ``true``, the job will switch to AWAITING. Endpoint ^^^^^^^^^^^^^^^^^^^ Video object detection API requests are to be sent to ``http://:18810/``. API requests are executed by the ``video-manager`` component. .. _job: Job ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Video object detection API operates on a ``job`` object which represents a video processing task (ie, job) that the ``video-manager`` component issues to ``video-worker``. Each ``job`` object has the following attributes: * ``id``: job id. * ``enabled``: active status. * ``stream_url``: URL/address of video stream/file to process. * ``labels``: key-value labels, that will be used by the router component (for example ``facerouter``) to find processing directives for objects detected in this stream. * ``router_url``: URL/address of the router component (for example, ``facerouter``) to receive detected objects from the ``video-worker`` component for processing. * ``router_events_url``: URL/address of the router component (for example, ``facerouter``), that uses events extraction. * ``single_pass``: if true, disable restarting video processing upon error (by default, false). * ``stream_settings``: video stream settings that duplicate :ref:`those ` in the ``video-manager.yaml`` configuration file (while having priority over them). * ``stream_settings_gpu``: deprecated video stream settings. Not recommended for use. Only for compatibility. * ``status``: job status. * ``status_msg``: additional job status info. * ``statistic``: job progress statistics (progress duration, number of posted and not posted objects, processing fps, the number of processed and dropped frames, job start time, etc.). * ``restream_url``: websocket URL where processing stream with detected objects streams live time. * ``restream_direct_url``: websocket URL where original stream with input quality streams live time. * ``shots_url``: HTTP URL where actual stream screenshot can be downloaded. * ``worker_id``: unique id of the ``video worker`` instance with a processing job. * ``version``: job version. Error Reporting ^^^^^^^^^^^^^^^^^^^^^^^^^^ If a method fails, it always returns a response with a HTTP code other than 200, and a JSON body containing the error description. The error body always includes at least two fields: ``code`` and ``desc``. * ``code`` is a short string in ``CAPS_AND_UNDERSCORES``, usable for automatic decoding. * ``desc`` is a human-readable description of the error and should not be interpreted automatically. .. rubric:: Common Error Codes +---------------------------------------------------------------------+-----------------------------------------------------------------------+------------+ | Error code | Description | HTTP code | +=====================================================================+=======================================================================+============+ | ``UNKNOWN_ERROR`` | Error with unknown origin. | 500 | +---------------------------------------------------------------------+-----------------------------------------------------------------------+------------+ | ``BAD_PARAM`` | The request can be read, however, some method parameters are invalid. | 400 | | | This response type contains additional attributes param and ``value`` | | | | to indicate which parameters are invalid. | | +---------------------------------------------------------------------+-----------------------------------------------------------------------+------------+ | ``MALFORMED_REQUEST`` | The request is malformed and cannot be read. | 400 | +---------------------------------------------------------------------+-----------------------------------------------------------------------+------------+ | ``SOURCE_NOT_FOUND`` | Detection not found in cache. | 400 | +---------------------------------------------------------------------+-----------------------------------------------------------------------+------------+ | ``CONFLICT`` | Conflict. | 409 | +---------------------------------------------------------------------+-----------------------------------------------------------------------+------------+ | ``NOT_FOUND`` | Job not found. | 404 | +---------------------------------------------------------------------+-----------------------------------------------------------------------+------------+ | ``EXTRACTION_ERROR | STORAGE_ERROR | LICENSE_ERROR | CACHE_ERROR`` | Service Unavailable. | 523 | +---------------------------------------------------------------------+-----------------------------------------------------------------------+------------+