474 lines
16 KiB
C
474 lines
16 KiB
C
|
/** \file record.h
|
||
|
|
* Copyright (c) Microsoft Corporation. All rights reserved.
|
||
|
|
* Licensed under the MIT License.
|
||
|
|
* Kinect For Azure Recording SDK.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef K4A_RECORD_H
|
||
|
|
#define K4A_RECORD_H
|
||
|
|
|
||
|
|
#include <k4arecord/types.h>
|
||
|
|
#include <k4arecord/k4arecord_export.h>
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
*
|
||
|
|
* \addtogroup Functions
|
||
|
|
*
|
||
|
|
* @{
|
||
|
|
*/
|
||
|
|
|
||
|
|
/** Opens a new recording file for writing.
|
||
|
|
*
|
||
|
|
* \param path
|
||
|
|
* Filesystem path for the new recording.
|
||
|
|
*
|
||
|
|
* \param device
|
||
|
|
* The Azure Kinect device that is being recorded. The device handle is used to store device calibration and serial
|
||
|
|
* number information. May be NULL if recording user-generated data.
|
||
|
|
*
|
||
|
|
* \param device_config
|
||
|
|
* The configuration the Azure Kinect device was started with.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* If successful, this contains a pointer to the new recording handle. Caller must call k4a_record_close()
|
||
|
|
* when finished with recording.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* The file will be created if it doesn't exist, or overwritten if an existing file is specified.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Streaming does not need to be started on the device at the time this function is called, but when it is started
|
||
|
|
* it should be started with the same configuration provided in \p device_config.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Subsequent calls to k4a_record_write_capture() will need to have images in the resolution and format defined
|
||
|
|
* in \p device_config.
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_create(const char *path,
|
||
|
|
k4a_device_t device,
|
||
|
|
const k4a_device_configuration_t device_config,
|
||
|
|
k4a_record_t *recording_handle);
|
||
|
|
|
||
|
|
/** Adds a tag to the recording.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \param name
|
||
|
|
* The name of the tag to write.
|
||
|
|
*
|
||
|
|
* \param value
|
||
|
|
* The string value to store in the tag.
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Tags are global to a file, and should store data related to the entire recording, such as camera configuration or
|
||
|
|
* recording location.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Tag names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* All tags need to be added before the recording header is written.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_add_tag(k4a_record_t recording_handle, const char *name, const char *value);
|
||
|
|
|
||
|
|
/** Adds the track header for recording IMU.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* The track needs to be added before the recording header is written.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_add_imu_track(k4a_record_t recording_handle);
|
||
|
|
|
||
|
|
/** Adds an attachment to the recording.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \param attachment_name
|
||
|
|
* The name of the attachment to be stored in the recording file. This name should be a valid filename with an
|
||
|
|
* extension.
|
||
|
|
*
|
||
|
|
* \param buffer
|
||
|
|
* The attachment data buffer.
|
||
|
|
*
|
||
|
|
* \param buffer_size
|
||
|
|
* The size of the attachment data buffer.
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* All attachments need to be added before the recording header is written.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_add_attachment(const k4a_record_t recording_handle,
|
||
|
|
const char *attachment_name,
|
||
|
|
const uint8_t *buffer,
|
||
|
|
size_t buffer_size);
|
||
|
|
|
||
|
|
/** Adds custom video tracks to the recording.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \param track_name
|
||
|
|
* The name of the custom video track to be added.
|
||
|
|
*
|
||
|
|
* \param codec_id
|
||
|
|
* A UTF8 null terminated string containing the codec ID of the track. Some of the existing formats are listed here:
|
||
|
|
* https://www.matroska.org/technical/specs/codecid/index.html. The codec ID can also be custom defined by the user.
|
||
|
|
* Video codec ID's should start with 'V_'.
|
||
|
|
*
|
||
|
|
* \param codec_context
|
||
|
|
* The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the
|
||
|
|
* codec. It is mapped to the matroska 'CodecPrivate' element.
|
||
|
|
*
|
||
|
|
* \param codec_context_size
|
||
|
|
* The size of the codec context buffer.
|
||
|
|
*
|
||
|
|
* \param track_settings
|
||
|
|
* Additional metadata for the video track such as resolution and framerate.
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Built-in video tracks like the DEPTH, IR, and COLOR tracks will be created automatically when the k4a_record_create()
|
||
|
|
* API is called. This API can be used to add additional video tracks to save custom data.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Track names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* All tracks need to be added before the recording header is written.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Call k4a_record_write_custom_track_data() with the same track_name to write data to this track.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_add_custom_video_track(const k4a_record_t recording_handle,
|
||
|
|
const char *track_name,
|
||
|
|
const char *codec_id,
|
||
|
|
const uint8_t *codec_context,
|
||
|
|
size_t codec_context_size,
|
||
|
|
const k4a_record_video_settings_t *track_settings);
|
||
|
|
|
||
|
|
/** Adds custom subtitle tracks to the recording.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \param track_name
|
||
|
|
* The name of the custom subtitle track to be added.
|
||
|
|
*
|
||
|
|
* \param codec_id
|
||
|
|
* A UTF8 null terminated string containing the codec ID of the track. Some of the existing formats are listed here:
|
||
|
|
* https://www.matroska.org/technical/specs/codecid/index.html. The codec ID can also be custom defined by the user.
|
||
|
|
* Subtitle codec ID's should start with 'S_'.
|
||
|
|
*
|
||
|
|
* \param codec_context
|
||
|
|
* The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the
|
||
|
|
* codec. It is mapped to the matroska 'CodecPrivate' element.
|
||
|
|
*
|
||
|
|
* \param codec_context_size
|
||
|
|
* The size of the codec context buffer.
|
||
|
|
*
|
||
|
|
* \param track_settings
|
||
|
|
* Additional metadata for the subtitle track. If NULL, the default settings will be used.
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Built-in subtitle tracks like the IMU track will be created automatically when the k4a_record_add_imu_track() API is
|
||
|
|
* called. This API can be used to add additional subtitle tracks to save custom data.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Track names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* All tracks need to be added before the recording header is written.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Call k4a_record_write_custom_track_data() with the same track_name to write data to this track.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t
|
||
|
|
k4a_record_add_custom_subtitle_track(const k4a_record_t recording_handle,
|
||
|
|
const char *track_name,
|
||
|
|
const char *codec_id,
|
||
|
|
const uint8_t *codec_context,
|
||
|
|
size_t codec_context_size,
|
||
|
|
const k4a_record_subtitle_settings_t *track_settings);
|
||
|
|
|
||
|
|
/** Writes the recording header and metadata to file.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* This must be called before captures or any track data can be written.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_write_header(k4a_record_t recording_handle);
|
||
|
|
|
||
|
|
/** Writes a camera capture to file.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \param capture_handle
|
||
|
|
* The handle of a capture to write to file.
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Captures must be written in increasing order of timestamp, and the file's header must already be written.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* k4a_record_write_capture() will write all images in the capture to the corresponding tracks in the recording file.
|
||
|
|
* If any of the images fail to write, other images will still be written before a failure is returned.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_write_capture(k4a_record_t recording_handle, k4a_capture_t capture_handle);
|
||
|
|
|
||
|
|
/** Writes an imu sample to file.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \param imu_sample
|
||
|
|
* A structure containing the imu sample data and timestamps.
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Samples must be written in increasing order of timestamp, and the file's header must already be written.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* When writing imu samples at the same time as captures, the samples should be within 1 second of the most recently
|
||
|
|
* written capture.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_write_imu_sample(k4a_record_t recording_handle, k4a_imu_sample_t imu_sample);
|
||
|
|
|
||
|
|
/** Writes data for a custom track to file.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* The handle of a new recording, obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \param track_name
|
||
|
|
* The name of the custom track that the data is going to be written to.
|
||
|
|
*
|
||
|
|
* \param device_timestamp_usec
|
||
|
|
* The timestamp in microseconds for the custom track data. This timestamp should be in the same time domain as the
|
||
|
|
* device timestamp used for recording.
|
||
|
|
*
|
||
|
|
* \param custom_data
|
||
|
|
* The buffer of custom track data.
|
||
|
|
*
|
||
|
|
* \param custom_data_size
|
||
|
|
* The size of the custom track data buffer.
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* Custom track data must be written in increasing order of timestamp, and the file's header must already be written.
|
||
|
|
* When writing custom track data at the same time as captures or IMU data, the custom data should be within 1 second of
|
||
|
|
* the most recently written timestamp.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_write_custom_track_data(const k4a_record_t recording_handle,
|
||
|
|
const char *track_name,
|
||
|
|
uint64_t device_timestamp_usec,
|
||
|
|
uint8_t *custom_data,
|
||
|
|
size_t custom_data_size);
|
||
|
|
|
||
|
|
/** Flushes all pending recording data to disk.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* Handle obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \returns ::K4A_RESULT_SUCCEEDED is returned on success, or ::K4A_RESULT_FAILED if an error occurred.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* k4a_record_flush() ensures that all data passed to the recording API prior to calling flush is written to disk.
|
||
|
|
* If continuing to write recording data, care must be taken to ensure no new timestamps are added from before the
|
||
|
|
* flush.
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* If an error occurs, best effort is made to flush as much data to disk as possible, but the integrity of the file is
|
||
|
|
* not guaranteed.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT k4a_result_t k4a_record_flush(k4a_record_t recording_handle);
|
||
|
|
|
||
|
|
/** Closes a recording handle.
|
||
|
|
*
|
||
|
|
* \param recording_handle
|
||
|
|
* Handle obtained by k4a_record_create().
|
||
|
|
*
|
||
|
|
* \headerfile record.h <k4arecord/record.h>
|
||
|
|
*
|
||
|
|
* \relates k4a_record_t
|
||
|
|
*
|
||
|
|
* \remarks
|
||
|
|
* If there is any unwritten data it will be flushed to disk before closing the recording.
|
||
|
|
*
|
||
|
|
* \xmlonly
|
||
|
|
* <requirements>
|
||
|
|
* <requirement name="Header">record.h (include k4arecord/record.h)</requirement>
|
||
|
|
* <requirement name="Library">k4arecord.lib</requirement>
|
||
|
|
* <requirement name="DLL">k4arecord.dll</requirement>
|
||
|
|
* </requirements>
|
||
|
|
* \endxmlonly
|
||
|
|
*/
|
||
|
|
K4ARECORD_EXPORT void k4a_record_close(k4a_record_t recording_handle);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @}
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
} // extern "C"
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* K4A_RECORD_H */
|