General information

The export is described in the proto files ExportService.proto and Export.proto.

The following 6 methods are used for export:

  1. ListSessions − is used to get a list of all export operations.
  2. StartSession − to start a new export operation.
  3. GetSessionState − to get the status of a specific operation.
  4. StopSession − to stop the operation.
  5. DestroySession − to delete the operation along with the export results.
  6. DownloadFile − to download the export results.

Export tasks are performed not by gRPC channel, but by the export agent. Currently, it is impossible to create an export agent via gRPC API, only manually in the Client.

When at least one export agent is created, it can be used to perform operations. If there are several export agents and none of them is explicitly specified in the StartSession method, then the agent with index 1 will be used.

The export operation starts on the node where the camera is located. If the export is started for several cameras, then the first node is used. Note that it is not necessary to connect to each node − the tasks will be forwarded to them automatically.

Export results are generated on the local Axxon One Server and can be passed by downloading the files using the DownloadFile method, which supports downloading from an arbitrary location in the file.

StartSession method

The method passes the export options, which are described in the Options message.


message Options
{
    oneof mode
    {
        LiveMode live = 1;
        ArchiveMode archive = 2;
    }
    oneof output_type
    {
        SnapshotType snapshot = 3;
        StreamType stream = 4;
    }
    repeated CommonSetting settings = 5;
    // Maximum size of output file.
    // New file will be created on reaching this value.
    uint64 max_file_size = 6;
    string export_agent_access_point = 100;
}


where,

Using the combination of mode and output_type, you can create 4 export types:

  1. LiveMode + SnapshotType − export a frame from live video.
  2. LiveMode + StreamType − export a video clip from live video.
  3. ArchiveMode + SnapshotType − export a frame from archive.
  4. ArchiveMode + StreamType − export a video clip from archive.

The LiveMode, ArchiveMode, SnapshotType and StreamType messages contain the parameters for this export type. The CommonSetting message is used to pass general settings for the export operation.

The list of main export parameters:


ParameterExport typeDescription
Options max_file_sizeExport a video clipMaximum file size (see Configuring export options).
Options export_agent_access_pointAllExport agent id.
StreamType formatExport a video clipOutput file format.
SnapshotType formatExport a frameOutput file format.
ArchiveMode/LiveMode Source originAllVideo source (see Get video cameras list and their parameters using gRPC API methods (DomainService)).
ArchiveMode Source storagesExport from archiveArchive (see Get video cameras list and their parameters using gRPC API methods (DomainService)).
ArchiveMode start_timestampExport from archiveTimestamp of the export interval start.
ArchiveMode end_timestampExport from archiveTimestamp of the export interval end.
CommonSetting commentAllComment.
CommonSetting timestamp_formatAllTimestamp format.
CommonSetting text_placeAllPlace for comment.
CommonSetting text_colorAllComment text color.
CommonSetting burn_subtitleAllText overlay (yes or no).
CommonSetting apply_maskAllMask overlay (yes or no).
StreamSetting video_qualityExport a video clipVideo stream quality.
StreamSetting video_codecExport a video clipVideo codec.
StreamSetting audio_qualityExport a video clipAudio stream quality.
StreamSetting audio_codecExport a video clipAudio codec.
StreamSetting frame_frequencyExport a video clipFrame frequency.
SnapshotSetting pdf_layoutExport a framePDF file orientation.
SnapshotSetting snapshot_placeExport a frameFrame location in the PDF file.
SnapshotSetting comment_placeExport a frameComment location in the PDF file.
SnapshotSetting timestamp_placeExport a frameTimestamp location in the PDF file.
SourceSetting crop_areaAllExport area (see Configuring export area and masks).
SourceSetting mask_spaceAllMask.
SourceSetting text_placeAllPlace for comment.
SourceSetting text_colorAllComment text color.


For each export type, there are timeouts after which the operation is stopped if the GetSessionState method was not executed.

The timeout is counted from the moment the export operation was started and/or from the moment the GetSessionState method was last executed.

The timeout for exporting a video clip from live video is 5 minutes, for all other export types − 30 minutes.

The id of the export operation will be received as the response to this method.

ListSessions method

The SessionInfo message for each export operation will be received as the response to this method. If one response does not fit all the operations, then there will also be the next_page_token for the next page.

The SessionInfo message contains:

  1. id of the export operation and its properties.

  2. export status.

    enum EState
{
    S_NONE      = 0;
    S_RUNNING   = 1;
    S_COMPLETED = 2;
    S_REMOVED   = 3;
}

    where the S_COMPLETED status does not guarantee that the export was successful.

  3. If there are export operation results, then a Result message will be received.

    message Result
{
    message File
    {
        string path = 1;
        uint64 size = 2;
        string min_timestamp = 3;
        string max_timestamp = 4;
        string mime_type = 5;
    }
    repeated File files = 1;
    bool succeeded = 2;
}

    where,

    1. succeeded − indicates that the export was successful;

    2. message File − describes the list of files ready for download, including the conditional path to be used in the DownloadFile method and size.

After the export operation status changes to S_COMPLETED, you have 1 hour to download the files from the Server. Note that the timeout is reset to zero after the GetSessionState and DownloadFile methods are executed.

If the timeout is exceeded, the files will be deleted from the Server.

GetSessionState method

The id of the export operation is passed in the method.

Its EState status will be received in response to this method.

If there are export operation results, then a Result message will be received.

StopSession method

The id of the export operation is passed in the method.

Its updated EState status will be received in response to this method.

DownloadFile method

The method can be used only after the export operation is completed.

The following data is passed in the method:

  1. export operation id;
  2. path to the file;
  3. chunk_size_kb − data block size;
  4. start_from_chunk_index − serial number of the data block.

In response to this method, FileChunk messages will be received with file data blocks, which will be coming until the entire file is downloaded.

DestroySession method

The id of the export operation is passed in the method.