tools/recorder/configuration_reference.md

Go to the documentation of this file.

# Copyright (c) 2020-2021 NVIDIA CORPORATION.  All rights reserved.

@page dwx_config_ref Configuration Reference
@tableofcontents

DriveWorks recording tools use a DriveWorks @ref rigconfiguration_usecase0 "Rig Configuration File" to specify which sensors are to be recorded.

An example of a Rig Configuration file is available at

    /usr/local/driveworks/tools/capture/configs/hyperion7_1/release.json

@section dwx_config_ref_params Recorder-Specific Parameters

In addition to the the standard sensor parameters documented in the
@ref sensors_usecase2 section, there are additional recorder-specific sensor parameters.
When required these parameters should be updated in the sensor parameter string
in the rig configuration file.

@subsection dwx_config_ref_params_encodeformat Camera Encoding Format

This mandatory parameter specifies the encoding format for a camera sensor recording. <br>
It can be specified as:

    ...,format=[raw,lraw,h264],...

The `format` selected also dictates which `output-format` parameter must be
specified for a camera sensor. The table below describes the compatibility
between these two parameters:

| Encoding Format | `format` | `output-format` |
| ----------------| ---------| ----------------|
| RAW             | `raw`    | `raw+yuv`           |
| LRAW            | `lraw`   | `raw+yuv`       |
| H264            | `h264`   | `yuv`           |
| H265            | `h265`   | `yuv`           |
| MP4             | `mp4`    | `yuv`           |

@note This parameter is only applicable to camera sensors.

@subsection dwx_config_ref_params_filebuffer File Buffer Size

This optional parameter specifies the size (in bytes) of the Operating System
write file buffer. It can be specified as:

    ...,file-buffer-size=XXXXX,...

@note This is an advanced tunable, and it is currently recommended to not
specify `file-buffer-size`

@subsection dwx_config_ref_params_bitrate Recording Bit Rate

This optional parameter specifies the bit rate (in bps) for compressed
recording formats in Constant Bit Rate (CBR) mode. It can be specified as:

    ...,bitrate=XXXXXXXX,...

The default bit rate is 8mbps.

@subsection dwx_config_ref_params_quality Recording Quality

This optional parameter specifies the quantization parameter for
constant quality in compressed recording formats. It can be specified as:

    ...,quality=XX,...

The default mode is CBR so there is no default quality. Quality of 0 is
lossless. Higher numbers are worse quality, but smaller in size. The maximum
quantization parameter is 50, resulting in the worst quality.

@subsection dwx_config_ref_params_asynchronusRecord Asynchronus recording

This optional parameter specifies whether to record the sensor in asynchronus mode and
it can be specified as:

    ...,async-record=1,...

@subsection dwx_config_ref_params_cameraFrameSkip Recording Nth Camera Frame

This optional parameter specifies to record every Nth camera frame and
it can be specified as:

    ...,frame-mod=XXX,...

Ex: frame-mod=5 records every 5th frame and skips the other frames.

@subsection dwx_config_ref_params_encoderInstance Selection of Encoder Instance

This optional parameter allows specification of which hardware encoder will
be used for a given sensor, for example to manually allocate hardware resources.
It can be specified as:

    ...,encoder-instance=0,...

Valid options vary based on hardware. On Xavier options are 0 and 1.

@subsection dwx_config_ref_params_entropy Selection of Encoder Entropy

This optional parameter allows specification of the H264 Entropy encoder type.

    ...,entropy=cavlc,...

Valid options are 'cabac' and 'cavlc'. The default is 'cabac'.

@subsection dwx_config_ref_params_gopLength Selection of Encoder GOP-length

This optional parameter allows specification of the GOP Length of the encoded video.
GOP length holds the number of pictures in one GOP

    ...,gop-length=XXX,...

Ex: gop-length=10 will be 1 I frame followed by 9 P frames

@subsection dwx_config_ref_params_newcodecstack Toggle to switch between the old and the new codec stack

This optional parameter allows use to specify which codec to use for serializing sensor data.
The value supplied to the parameter should either be 0 or 1.

    ...,newcodecstack=[0|1],...

@section dwx_config_ref_distributed Distributed Recording

Distributed recording across multiple Xavier processors is supported via
both @ref dwx_recorder_textui_tool and @ref dwx_gui_recording2_tool

Instead of passing a single rig file, a `rig_directory` containing a rig file
per Xavier processor should be passed to the respective tool. <br> Below is an example
of the directory structure:

    <rig_directory>
    |___10.42.0.28<_rigConfiguration_seqNum>.json
    |___10.42.0.29<_rigConfiguration_seqNum>.json
    |___setup.sh

rigConfiguration is the rig name generated in aux_info, if its not provided then 'default' is generated as rig name in aux_info

For master-slave recording:
The seqNum determines order of the initialization, which is important when some sensors are in master/slave combination. SeqNum is used for orchestration of recorders, for all the masters seqNum should be provided(in ascending order in the format of IP_rigConfiguration_seqNum) and for slaves its optional. If seqNum is not provided ordering will be same as the internal file system order.

As shown above, the IP address of each Xavier is specified within the rig file name.
In additional, if any of the following scripts are present in the `rig_directory`, they will be run based
on the respective trigger cadence on each target processor/IP provided via the input rigs.

| File name                       | Trigger cadence         | Arguments          |
| ------------------------------- | ----------------------- |------------------- |
| `recorder-platform-setup.sh`    | App launch              | None               |
| `recorder-platform-cleanup.sh`  | App exit                | None               |
| `recorder-pre-start.sh`         | Recording session start | List of disk sinks |
| `recorder-post-stop.sh`         | Recording session end   | List of disk sinks |