Azure Kinect 播放 API

發行項
06/01/2023

感應器 SDK 提供可以將裝置資料錄製到 Matroska (.mkv) 檔案的 API。 Matroska 容器格式會儲存視訊播放軌、IMU 範例和裝置校正。您可以使用提供的 k4arecorder 命令列公用程式來產生錄製內容。您也可以直接使用錄製 API 來自訂和錄製錄製內容。

如需錄製 API 的詳細資訊，請參閱 k4a_record_create()。

如需 Matroska 檔案格式規格的詳細資訊，請參閱錄製檔案格式頁面。

使用播放 API

您可以使用播放 API 來開啟錄製檔案。播放 API 以和其他感應器 SDK 相同的格式來存取感應器資料。

開啟記錄檔

在下列範例中，我們會使用 k4a_playback_open() 來開啟錄製內容，列印錄製內容的長度，然後使用 k4a_playback_close() 來關閉檔案。

k4a_playback_t playback_handle = NULL;
if (k4a_playback_open("recording.mkv", &playback_handle) != K4A_RESULT_SUCCEEDED)
{
    printf("Failed to open recording\n");
    return 1;
}

uint64_t recording_length = k4a_playback_get_last_timestamp_usec(playback_handle);
printf("Recording is %lld seconds long\n", recording_length / 1000000);

k4a_playback_close(playback_handle);

讀取擷取

檔案開啟之後，我們可以開始從錄製內容中讀取擷取。下一個範例會讀取檔案中的各個擷取。

k4a_capture_t capture = NULL;
k4a_stream_result_t result = K4A_STREAM_RESULT_SUCCEEDED;
while (result == K4A_STREAM_RESULT_SUCCEEDED)
{
    result = k4a_playback_get_next_capture(playback_handle, &capture);
    if (result == K4A_STREAM_RESULT_SUCCEEDED)
    {
        // Process capture here
        k4a_capture_release(capture);
    }
    else if (result == K4A_STREAM_RESULT_EOF)
    {
        // End of file reached
        break;
    }
}
if (result == K4A_STREAM_RESULT_FAILED)
{
    printf("Failed to read entire recording\n");
    return 1;
}

在錄製內容內搜尋

到達檔案結尾時，我們可能會想要回頭重新讀取一次。這個流程可以透過使用 k4a_playback_get_previous_capture() 進行向後讀取來完成，但取決於錄製內容的長度，此流程可能會非常緩慢。我們可以改用 k4a_playback_seek_timestamp() 函式來移動到檔案中的特定時間點。

在此範例中，我們會指定時間戳記 (以微秒為單位) 來搜尋檔案中的各個時間點。

// Seek to the beginning of the file
if (k4a_playback_seek_timestamp(playback_handle, 0, K4A_PLAYBACK_SEEK_BEGIN) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to the end of the file
if (k4a_playback_seek_timestamp(playback_handle, 0, K4A_PLAYBACK_SEEK_END) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to 10 seconds from the start
if (k4a_playback_seek_timestamp(playback_handle, 10 * 1000000, K4A_PLAYBACK_SEEK_BEGIN) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to 10 seconds from the end
if (k4a_playback_seek_timestamp(playback_handle, -10 * 1000000, K4A_PLAYBACK_SEEK_END) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

讀取標籤資訊

錄製內容中也可能包含各種中繼資料，例如裝置序號和韌體版本。此中繼資料會儲存在錄製標記中，且可以用 k4a_playback_get_tag() 函式來存取。

// Print the serial number of the device used to record
char serial_number[256];
size_t serial_number_size = 256;
k4a_buffer_result_t buffer_result = k4a_playback_get_tag(playback_handle, "K4A_DEVICE_SERIAL_NUMBER", &serial_number, &serial_number_size);
if (buffer_result == K4A_BUFFER_RESULT_SUCCEEDED)
{
    printf("Device serial number: %s\n", serial_number);
}
else if (buffer_result == K4A_BUFFER_RESULT_TOO_SMALL)
{
    printf("Device serial number too long.\n");
}
else
{
    printf("Tag does not exist. Device serial number was not recorded.\n");
}

以下清單列出錄製檔案中所有可能包含的預設標籤。其中許多數值可以作為 k4a_record_configuration_t 結構的一部分存取，而且可以用 k4a_playback_get_record_configuration() 函式來讀取。

如果標記不存在，則假設該標籤為預設值。

標記名稱	預設值	`k4a_record_configuration_t` 欄位	備註
`K4A_COLOR_MODE`	「OFF」	`color_format` / `color_resolution`	可能的值：「OFF」、「MJPG_1080P」、「NV12_720P」、「YUY2_720P」等等
`K4A_DEPTH_MODE`	「OFF」	`depth_mode` / `depth_track_enabled`	可能的值：「OFF」、「NFOV_UNBINNED」、「PASSIVE_IR」等等
`K4A_IR_MODE`	「OFF」	`depth_mode` / `ir_track_enabled`	可能的值：「OFF」、「ACTIVE」、「PASSIVE」
`K4A_IMU_MODE`	「OFF」	`imu_track_enabled`	可能的值：「ON」、「OFF」
`K4A_CALIBRATION_FILE`	"calibration.json"	N/A	請參閱`k4a_device_get_raw_calibration()`
`K4A_DEPTH_DELAY_NS`	"0"	`depth_delay_off_color_usec`	以奈秒為單位儲存的值，API 則是微秒。
`K4A_WIRED_SYNC_MODE`	「STANDALONE」	`wired_sync_mode`	可能的值：「STANDALONE」、「MASTER」、「SUBORDINATE」
`K4A_SUBORDINATE_DELAY_NS`	"0"	`subordinate_delay_off_master_usec`	以奈秒為單位儲存的值，API 則是微秒。
`K4A_COLOR_FIRMWARE_VERSION`	""	N/A	裝置色彩韌體版本，例如「1.x.xx」
`K4A_DEPTH_FIRMWARE_VERSION`	""	N/A	裝置深度韌體版本，例如「1.x.xx」
`K4A_DEVICE_SERIAL_NUMBER`	""	N/A	錄製裝置序號
`K4A_START_OFFSET_NS`	"0"	`start_timestamp_offset_usec`	請參閱下面的時間戳記同步處理。
`K4A_COLOR_TRACK`	None	N/A	請參閱錄製檔案格式 - 識別播放軌。
`K4A_DEPTH_TRACK`	None	N/A	請參閱錄製檔案格式 - 識別播放軌。
`K4A_IR_TRACK`	None	N/A	請參閱錄製檔案格式 - 識別播放軌。
`K4A_IMU_TRACK`	None	N/A	請參閱錄製檔案格式 - 識別播放軌。

時間戳記同步處理

Matroska 格式規定，錄製內容必須以數值為零的時間戳記開始。在外部同步處理相機時，各裝置的第一個時間戳記可以是不為零。

為了保留錄製和播放之間的原始裝置時間戳記，檔案會儲存要套用至時間戳記的位移值。

標記 K4A_START_OFFSET_NS 可指定時間戳記位移值，以便在錄製後重新同步處理檔案。這個時間戳記位移值可以加到檔案中的每一個時間戳記，以重建原本的裝置時間戳記。

結構 k4a_record_configuration_t 中也提供起始位移值。