# Holistic Record and Replay

To simplify development and later testing and debugging of your application, you can record and replay test data. This can be done
without any changes to your code with the use of environmental variables and configuration files. You can create a holistic
recording using the [holistic_record.py](https://docs.luxonis.com/software-v3/depthai/examples/record_replay/holistic_record.md)
script and then replay it by setting the DEPTHAI_REPLAY environment variable to the path of the recording.

Holistic record and replay works by recording the calibration, camera features information, and data (messages) of source nodes
used in an application ([Camera](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/camera.md) and
[IMU](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/imu.md)) which can then be replayed as if the source
nodes sent the same data again.

## Holistic Record

Holistic record records enabled source node streams to a tar file. This can be enabled in code:

#### Python

```python
with dai.Pipeline as pipeline:
    config = dai.RecordConfig()
    config.outputDir = "./recordings";
    config.videoEncoding.enabled = True # Use video encoding
    config.videoEncoding.profile = dai.VideoEncoderProperties.Profile.H264_MAIN

    pipeline.enableHolisticRecord(config)
```

#### C++

```cpp
dai::Pipeline pipeline;
dai::RecordConfig config;
config.outputDir = "./recordings";
config.videoEncoding.enabled = true;  // Use video encoding
config.videoEncoding.profile = dai::VideoEncoderProperties::Profile::H264_MAIN;

pipeline.enableHolisticRecord(config);
```

or by using the DEPTHAI_RECORD environment variable:

```bash
DEPTHAI_RECORD="./recordings" python3 application.py
```

### Environment variable configuration

In the above example, the DEPTHAI_RECORD environment variable is set to the recording output directory. This enabled holistic
recording with the default configuration options. If you want more control you set the variable to the path to a configuration
file:

```json
{
    "outputDir": "recordings/",
    "compressionLevel": 3,
    "syncCameraOutputs": true,
    "videoEncoding": {
	"enabled": true,
        "bitrate": 0,
        "lossless": false,
        "profile": "MJPEG",
        "quality": 80
    }
}
```

The configuration parameters are as follows:

 * outputDir sets the output directory of the recording
 * compressionLevel configures the compression of the metadata. It ranges from 0 to 5 (inclusive) which corresponds to the
   following compression levels: NONE, FASTEST, FAST, DEFAULT, SLOW, SLOWEST
 * syncCameraOutputs enables camera output synchronization. This prevents dropped messages from causing issues when replaying into
   [StereoDepth](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/stereo_depth.md) or similar nodes that
   require synchronized frames.
 * videoEncoding configures the
   [VideoEncoder](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/video_encoder.md) that encodes the camera
   stream:
   * enabled enables the [VideoEncoder](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/video_encoder.md).
     When false, the output of the [Camera](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/camera.md) node
     is recorded which can decrease the device CPU usage while increasing bandwidth usage
   * profile sets the encoding profile
   * bitrate sets the [VideoEncoder](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/video_encoder.md)
     bitrate (when set to 0 it is determined automatically)
   * lossless determines whether the encoding should be lossles where applicable
   * quality determines the encoding quality where applicable

## Example of functionality

 * [Holistic Record](https://docs.luxonis.com/software-v3/depthai/examples/record_replay/holistic_record.md)

## Holistic Replay

Holistic replay replays recorded source streams. It automatically loops the input streams and updates message timestamps and
sequence numbers accordingly. Similarly to holistic record it can be enabled in code:

#### Python

```python
with dai.Pipeline as pipeline:
    pipeline.enableHolisticReplay("./recordings/recording.tar")
```

#### C++

```cpp
dai::Pipeline pipeline;
pipeline.enableHolisticReplay("./recordings/recording.tar");
```

or by using the DEPTHAI_REPLAY environment variable:

```bash
DEPTHAI_REPLAY="./recordings/recording.tar" python3 application.py
```

## Example of functionality

 * [Holistic Replay](https://docs.luxonis.com/software-v3/depthai/examples/record_replay/holistic_replay.md)

## Limitations

This functionality is a work in progress and comes with some limitations:

 * As replaying requires sending messages from the host to the device, using this functionality significantly reduces the fps of
   the pipeline.
 * The frame timestamps can drift on each loop when replaying, as the loop timestamp offsets are calculated independently for each
   camera stream. This can cause issues with message synchronization after some time.
 * At this point in time, only single device pipelines can be holistically recorded and replayed.