### Starting the Preview Stream

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

To start the preview stream, configure the `LiveStreamParam` with desired settings such as video resolution and bitrate, and then call the `StartLiveStreaming` interface. A resolution of 1920x960 is recommended.

```APIDOC
## Starting the Preview Stream

### Description
To start the preview stream, configure the `LiveStreamParam` with desired settings such as video resolution and bitrate, and then call the `StartLiveStreaming` interface. A resolution of 1920x960 is recommended.

### Method
`StartLiveStreaming(const ins_camera::LiveStreamParam& param)`

### Parameters
#### Request Body
- **param** (ins_camera::LiveStreamParam) - Required - Live stream parameters.
  - **video_resolution** (ins_camera::VideoResolution) - Recommended: `RES_1920_960P30`.
  - **lrv_video_resulution** (ins_camera::VideoResolution) - Recommended: `RES_1920_960P30`.
  - **video_bitrate** (uint32_t) - Example: `1024 * 1024 / 2`.
  - **enable_audio** (bool) - Set to `false` for preview stream.
  - **using_lrv** (bool) - Set to `false` for preview stream.

### Request Example
```c++
ins_camera::LiveStreamParam param;
param.video_resolution = ins_camera::VideoResolution::RES_1920_960P30;
param.lrv_video_resulution = ins_camera::VideoResolution::RES_1920_960P30;
param.video_bitrate = 1024 * 1024 / 2;
param.enable_audio = false;
param.using_lrv = false;
if (cam->StartLiveStreaming(param)) {
    std::cout << "successfully started live stream" << std::endl;
}
```
```

--------------------------------

### Start Live Streaming Preview

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Configure `LiveStreamParam` with desired resolution and bitrate, then call `StartLiveStreaming`. The recommended preview resolution is 1920x960. Ensure `enable_audio` and `using_lrv` are set appropriately.

```c++
ins_camera::LiveStreamParam param;
param.video_resolution = ins_camera::VideoResolution::RES_1920_960P30;
param.lrv_video_resulution = ins_camera::VideoResolution::RES_1920_960P30;
param.video_bitrate = 1024 * 1024 / 2;
param.enable_audio = false;
param.using_lrv = false;
if (cam->StartLiveStreaming(param)) {
    std::cout << "successfully started live stream" << std::endl;
}
```

--------------------------------

### Start Normal Video Recording C++

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Use this to start normal video recording. Ensure the camera is in normal video mode and capture parameters are set correctly. Note that bitrate settings may not always take effect.

```c++
// 1. Switch mode to normal video mode
bool ret = camera->SetVideoSubMode(ins_camera::SubVideoMode::VIDEO_NORMAL);
if (!ret) {
    std::cout << "change sub mode failed!" << std::endl;
    continue;
}

// 2. Set current resolution, frame rate, and bitrate
auto function_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_VIDEO;
ins_camera::RecordParams record_params;
// Set 5.7K 60FPS
record_params.resolution = ins_camera::VideoResolution::RES_2880_2880P60;
record_params.bitrate = 1024 * 1024 * 10;
// Set bitrate to 10MB, this parameter may not take effect, as certain camera models or settings may have a fixed bitrate
if (!camera->SetVideoCaptureParams(record_params, function_mode)) {
    std::cerr << "failed to set capture settings." << std::endl;
}
else {
// 3. Start recording
    const auto ret = camera->StartRecording();
    if (ret) {
        std::cerr << "success!" << std::endl;
    }
    else {
        std::cerr << "failed to start recording" << std::endl;
    }
}
```

--------------------------------

### Install libusb-dev on Debian/Ubuntu

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Installs the libusb development libraries required for camera communication on Debian-based Linux distributions.

```bash
sudo apt-get install libusb-dev
sudo apt-get install libudev-dev
```

--------------------------------

### Build libusb from source on Linux

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Compiles and installs the libusb library from its source code. This is an alternative to using package managers.

```bash
wget http://sourceforge.net/projects/libusb/files/libusb-1.0/libusb-1.0.9/libusb-1.0.9.tar.bz2
tar xjf libusb-1.0.9.tar.bz2
cd libusb-1.0.9
./configure 
make
sudo make install
```

--------------------------------

### Retrieve Camera File List

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Obtain a list of all recorded files on the camera's SD card. The output shows example file paths.

```C++
auto file_list = camera->GetCameraFilesList();
for(const auto& file : file_list) {
    std::cout << file << std::endl;
}

// print output
/DCIM/Camera01/VID_20250122_071405_00_001.insv
/DCIM/Camera01/LRV_20250122_071405_01_001.lrv
/DCIM/Camera01/VID_20250214_063916_00_002.insv
/DCIM/Camera01/LRV_20250214_063916_01_002.lrv
```

--------------------------------

### Start Timelapse Recording C++

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Initiates timelapse recording. Requires setting the camera to timelapse mode, defining resolution and frame rate, and configuring timelapse parameters like duration and interval. Note the specific parameters for mobile timelapse.

```c++
// 1. Switch the camera mode to timelapse mode
bool ret = cam->SetVideoSubMode(ins_camera::SubVideoMode::VIDEO_TIMELAPSE);
if (!ret) {
    std::cout << "change sub mode failed!" << std::endl;
    continue;
}

// 2. Set the resolution and frame rate for the current mode
auto function_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_MOBILE_TIMELAPSE;
ins_camera::RecordParams record_params;
// 8K30 resolution
record_params.resolution = ins_camera::VideoResolution::RES_3840_3840P30;
if (!cam->SetVideoCaptureParams(record_params, function_mode )) {
    std::cerr << "failed to set capture settings." << std::endl;
    break;
}

// 3. Set the parameters for mobile timelapse
auto timelapse_mode = ins_camera::CameraTimelapseMode::MOBILE_TIMELAPSE_VIDEO;
const uint32_t record_duration_s = 10;  // Recording duration: 10 seconds
const uint32_t lapseTime_ms = 1000;     // Interval duration: 1 second
ins_camera::TimelapseParam param = { timelapse_mode, 10, 1000, 0 };
if (!cam->SetTimeLapseOption(param)) {
    std::cerr << "failed to set capture settings." << std::endl;
}
else {
// 4. Start recording
    const auto ret = cam->StartTimeLapse(param.mode);
    if (ret) {
        std::cerr << "success!" << std::endl;
    } 
    else {
        std::cerr << "failed to start timelapse" << std::endl;
    }
}
```

--------------------------------

### Start HDR Photo Capture

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Initiates an HDR photo capture. For X4, it captures a single merged HDR image. For older cameras, it captures multiple exposures.

```C++
ins_camera::PhotoSize photo_size = ins_camera::PhotoSize::Size_6912_3456;
if (camera_type == ins_camera::CameraType::Insta360X4) {
    photo_size = ins_camera::PhotoSize::Size_5952_2976;
}
camera->StartHDRCapture(photo_size);
```

--------------------------------

### Retrieve Camera Media Time

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Get the current media time from the camera. This is useful for synchronizing with the metadata of recorded files.

```C++
GetCameraMediaTime()
```

--------------------------------

### Get White Balance Parameters for Photo Mode

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Retrieves the current white balance parameters for the Photo Mode using the GetCaptureSettings interface. This allows accessing the current white balance settings.

```c++
// Get White Balance parameters for the Photo Mode
const auto funtion_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE;
auto capture_setting = camera->GetCaptureSettings(funtion_mode);
auto value = settings->GetIntValue(ins_camera::CaptureSettings::SettingsType::CaptureSettings_WhiteBalance);
```

--------------------------------

### Configure Exposure Parameters for Photo Mode

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Configures exposure parameters for a specific Photo Mode by first getting the current settings, then modifying values like EV Bias, ISO, and Shutter Speed, and finally applying them with SetExposureSettings.

```c++
// 1. Get exposure parameters for Photo mode
const auto funtion_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE;
auto exposure_settings = camera->GetExposureSettings(funtion_mode);

// 2. Set exposure parameters
exposure_settings->SetEVBias(bias); // range -80 ~ 80, default 0, step 1
exposure_settings->SetIso(800);
exposure_settings->SetShutterSpeed(1.0 / 120.0);

// 3. Apply exposure settings to the camera
camera->SetExposureSettings(funtion_mode,exposure_settings);
```

--------------------------------

### Get Exposure Parameters for Photo Mode

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Retrieves the current exposure parameters for a specified Photo Mode using the GetExposureSettings interface. This allows reading ISO and Shutter Speed values.

```c++
// Get exposure parameters for Photo mode
const auto funtion_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE;
auto exposure_settings = camera->GetExposureSettings(funtion_mode);
auto iso = exposure_settings->Iso();
auto shutter_speed = exposure_settings->ShutterSpeed();
// ...
```

--------------------------------

### Get SD Card Storage State

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Retrieve the current status of the SD card, including its state (e.g., normal, no card, insufficient space) and available space. The StorageStatus struct provides this information.

```C++
// These definitions are provided in the SDK's header file
enum CardState {
    STOR_CS_PASS = 0,          // Normal
    STOR_CS_NOCARD = 1,        // No card
    STOR_CS_NOSPACE = 2,       // Insufficient space
    STOR_CS_INVALID_FORMAT = 3,// Incorrect card format
    STOR_CS_WPCARD = 4,        // Write-protected card
    STOR_CS_OTHER_ERROR = 5    // Other errors
};

struct StorageStatus {
    CardState state;       // SD card status
    uint64_t free_space;   // Remaining space on the SD card
    uint64_t total_space;  // Total space on the SD card
};

StorageStatus status;
bool successed = camera->GetStorageState(status);
```

--------------------------------

### Get Battery Status

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Obtain the camera's current battery information, including power source type and battery level percentage. The BatteryStatus struct contains the relevant details.

```C++
// These definitions are provided in the SDK's header file
enum PowerType {
    BATTERY = 0,
    ADAPTER = 1,
};

struct BatteryStatus {
    PowerType power_type;   // Power source type
    uint32_t battery_level; // Current battery percentage (0~100)
    uint32_t battery_scale; // This value is not used.
};

BatteryStatus status;
bool successed = camera->GetBatteryStatus(status);
```

--------------------------------

### Run Camera SDK Demo with sudo on Ubuntu

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Executes the Camera SDK demo application with superuser privileges, necessary for accessing USB devices on Linux systems.

```bash
sudo ./CameraSDKDemo   // for Ubuntu
```

--------------------------------

### Camera::Open

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Establishes a connection to the camera.

```APIDOC
## Camera::Open

### Description
Attempts to open a connection to the camera instance.

### Method
`bool Open()`

### Parameters
None

### Response
- `bool`: Returns `true` if the connection was successful, `false` otherwise.

### Example
```cpp
bool success = camera->Open();
if(!success) {
    std::cout << "failed to open camera" << std::endl;
    return -1;
}
```
```

--------------------------------

### Create Insta360 Camera Instance

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Create a camera instance using the Camera and DeviceDescriptor interfaces after obtaining camera information. This generates a camera control instance.

```c++
// Get the necessary parameter information from the camera list
auto camera_info = list[0].info;
auto camera = std::make_shared<ins_camera::Camera>(camera_info);
// Once successfully created, a camera instance is generated
```

--------------------------------

### Download Camera File with Progress

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Download a media file from the camera to a local device. A callback function is provided to track download progress. Ensure the local directory exists and the service port is available before initiating the download.

```C++
// Camera-side file path
std::string camera_file = "/DCIM/Camera01/VID_20250122_071405_00_001.insv";
// Local save path
std::string local_save_file = "/path/to/local/VID_20250122_071405_00_001.insv";

// Start download
bool ret = camera->DownloadCameraFile(camera_file, local_save_file, [](int64_t current, int64_t total_size) {
    //Display Progress
    std::cout << "current :" << current << "; total_size: " << total_size << std::endl;
});

// Download result
if(ret) {
   std::cout << "successed to download file" << std::end;
}
```

--------------------------------

### Implement Camera StreamDelegate Interface

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Inherit from `ins_camera::StreamDelegate` to receive callbacks for audio, video, gyro, and exposure data. Implement `OnVideoData` to handle video frames, noting that resolutions above 5.7K yield two streams.

```c++
class TestStreamDelegate : public ins_camera::StreamDelegate {
public:
    TestStreamDelegate() {}

    // Callback for audio data
    void OnAudioData(const uint8_t* data, size_t size, int64_t timestamp) override {}

    // Callback for video data
    void OnVideoData(const uint8_t* data, size_t size, int64_t timestamp, uint8_t streamType, int stream_index) override {
        if (stream_index == 0) {
            // First video stream
        }
        if (stream_index == 1) {
            // Second video stream
        }
    }

    // Callback for gyro data
    void OnGyroData(const std::vector<ins_camera::GyroData>& data) override {}

    // Callback for exposure data
    void OnExposureData(const ins_camera::ExposureData& data) override {}
};
```

--------------------------------

### Camera::Camera

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Creates an instance of the Camera class using the provided device connection information.

```APIDOC
## Camera Constructor

### Description
Initializes a new `Camera` object, preparing it for connection and control.

### Method
`std::make_shared<ins_camera::Camera>(DeviceConnectionInfo info)`

### Parameters
- **info** (`DeviceConnectionInfo`): Information required to establish a connection with the camera.

### Response
- `std::shared_ptr<ins_camera::Camera>`: A shared pointer to the newly created `Camera` instance.

### Example
```cpp
// Assuming 'list' is a std::vector<DeviceDescriptor> obtained from GetAvailableDevices()
auto camera_info = list[0].info;
auto camera = std::make_shared<ins_camera::Camera>(camera_info);
```
```

--------------------------------

### Implementing StreamDelegate Interface

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Inherit from `ins_camera::StreamDelegate` to receive raw video, audio, gyro, and exposure data. Implement the `OnAudioData`, `OnVideoData`, `OnGyroData`, and `OnExposureData` methods to process the respective data streams. The `OnVideoData` callback provides data for one or two video streams depending on the resolution, encoded in H.265 or H.264.

```APIDOC
## Implementing StreamDelegate Interface

### Description
Inherit from `ins_camera::StreamDelegate` to receive raw video, audio, gyro, and exposure data. Implement the `OnAudioData`, `OnVideoData`, `OnGyroData`, and `OnExposureData` methods to process the respective data streams. The `OnVideoData` callback provides data for one or two video streams depending on the resolution, encoded in H.265 or H.264.

### Code Example
```c++
class TestStreamDelegate : public ins_camera::StreamDelegate {
public:
    TestStreamDelegate() {}

    // Callback for audio data
    void OnAudioData(const uint8_t* data, size_t size, int64_t timestamp) override {}

    // Callback for video data
    void OnVideoData(const uint8_t* data, size_t size, int64_t timestamp, uint8_t streamType, int stream_index) override {
        if (stream_index == 0) {
            // First video stream
        }
        if (stream_index == 1) {
            // Second video stream
        }
    }

    // Callback for gyro data
    void OnGyroData(const std::vector<ins_camera::GyroData>& data) override {}

    // Callback for exposure data
    void OnExposureData(const ins_camera::ExposureData& data) override {}
};
```
```

--------------------------------

### Setting the Stream Delegate

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

After implementing the `StreamDelegate` interface, create an instance of your delegate and assign it to the camera instance using the `SetStreamDelegate` method.

```APIDOC
## Setting the Stream Delegate

### Description
After implementing the `StreamDelegate` interface, create an instance of your delegate and assign it to the camera instance using the `SetStreamDelegate` method.

### Code Example
```c++
auto delegate = std::make_shared<TestStreamDelegate>();
camera->SetStreamDelegate(delegate);
```
```

--------------------------------

### Set SDK Log Path

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Use this to specify the directory where the SDK will save its log information. Ensure the path is valid and accessible.

```C++
void SetLogPath(const std::string log_path)
```

--------------------------------

### Open Insta360 Camera Connection

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Open the camera connection using the Open interface. Check the return value to ensure the connection was successful.

```c++
bool success = camera->Open();
if(!success) {
    std::cout << "failed to open camera" << std::endl;
    return -1;
}
```

--------------------------------

### Set Video Capture Parameters

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

This snippet shows how to configure video recording parameters such as resolution and bitrate using the `SetVideoCaptureParams` interface. This is applicable only to video modes and not photo modes.

```APIDOC
## Set Video Capture Parameters

### Description
This code demonstrates how to configure video recording parameters such as resolution and bitrate using the `SetVideoCaptureParams` interface. This is applicable only to video modes and not photo modes.

### Method
```C++
// Video Modes
enum CameraFunctionMode {
    FUNCTION_MODE_MOBILE_TIMELAPSE = 2,  // Mobile Timelapse Mode
    FUNCTION_MODE_NORMAL_VIDEO = 7,      // Normal Video Mode
    FUNCTION_MODE_HDR_VIDEO = 9,         // HDR Video Mode
    FUNCTION_MODE_INTERVAL_VIDEO = 10,   // Interval Video Mode
    FUNCTION_MODE_STATIC_TIMELAPSE = 11, // Timelapse Mode
    FUNCTION_MODE_TIMESHIFT = 12,        // Timeshift Mode
    FUNCTION_MODE_LOOP_RECORDING_VIDEO = 17 // Loop Recording Mode
};

// This structure defines recording resolution, frame rate, and bitrate
struct RecordParams {
    VideoResolution resolution;
    int32_t bitrate{ 0 };
};

auto function_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_VIDEO;
ins_camera::RecordParams record_params;
// Set 5.7K 60FPS
record_params.resolution = ins_camera::VideoResolution::RES_2880_2880P60;
// Set bitrate to 10MB. This value may not be valid, and certain bitrates might cause write failures during recording.
record_params.bitrate = 1024 * 1024 * 10;
if (!cam->SetVideoCaptureParams(record_params, function_mode)) {
    std::cerr << "failed to set capture settings." << std::endl;
}
```
```

--------------------------------

### Assign StreamDelegate to Camera Instance

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

After implementing the `StreamDelegate` interface, create an instance and assign it to the camera object using `SetStreamDelegate`. This enables the camera to send stream data to your delegate.

```c++
auto delegate = std::make_shared<TestStreamDelegate>();
camera->SetStreamDelegate(delegate);
```

--------------------------------

### Set Video Mode

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Demonstrates how to set the camera's video mode using the SetVideoSubMode interface. Supported modes include Normal, Bullet Time, Timelapse, HDR, Timeshift, and Loop Recording.

```C++
enum SubVideoMode {
    VIDEO_NORMAL = 0,         // Normal Video
    VIDEO_BULLETTIME = 1,     // Bullet Time
    VIDEO_TIMELAPSE = 2,      // Timelapse
    VIDEO_HDR = 3,            // HDR Video
    VIDEO_TIMESHIFT = 4,      // Timeshift
    VIDEO_LOOPRECORDING = 6   // Loop Recording
};

// Use the interface to switch video modes
camera->SetVideoSubMode(SubVideoMode::VIDEO_NORMAL);
```

--------------------------------

### Firmware Upgrade for X4 and Later Cameras

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Upload firmware to upgrade the camera. Only supported for X4 and later models. The camera must be powered off after a successful upload and restarted to complete the upgrade.

```C++
// Set the firmware file name
const std::string fireware_name = "Insta360X4FW.bin";
std::string file_name = "Insta360X4FW.bin";
if (camera_type == ins_camera::CameraType::Insta360X5) {
    file_name = "Insta360X5FW.bin";
}

const auto ret = cam->UploadFile(local_path, file_name,
// Specify the local path of the firmware
const std::string local_file = "/path/to/fireware/Insta360X4FW.bin"；

// Start uploading
bool ret = cam->UploadFile(local_file, fireware_name ,
    [](int64_t current, int64_t total_size) {
      // Firmware upload progress display
      std::cout << "current :" << current << ";total_size: " << total_size << std::endl;
});

if (ret) {
    std::cout << "succeeded to upload file" << std::endl;
}

//After a successful upload, the camera must be powered off. Once the upgrade is complete, recreate the camera instance (the camera needs to restart for the upgrade).
camera->close();
```

--------------------------------

### Set Video Capture Parameters

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Configures video recording parameters such as resolution and bitrate using the SetVideoCaptureParams interface. This is only applicable to video modes and not photo modes.

```C++
// Video Modes
enum CameraFunctionMode {
    FUNCTION_MODE_MOBILE_TIMELAPSE = 2,  // Mobile Timelapse Mode
    FUNCTION_MODE_NORMAL_VIDEO = 7,      // Normal Video Mode
    FUNCTION_MODE_HDR_VIDEO = 9,         // HDR Video Mode
    FUNCTION_MODE_INTERVAL_VIDEO = 10,   // Interval Video Mode
    FUNCTION_MODE_STATIC_TIMELAPSE = 11, // Timelapse Mode
    FUNCTION_MODE_TIMESHIFT = 12,        // Timeshift Mode
    FUNCTION_MODE_LOOP_RECORDING_VIDEO = 17 // Loop Recording Mode
};

// This structure defines recording resolution, frame rate, and bitrate
struct RecordParams {
    VideoResolution resolution;
    int32_t bitrate{ 0 };
};

auto function_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_VIDEO;
ins_camera::RecordParams record_params;
// Set 5.7K 60FPS
record_params.resolution = ins_camera::VideoResolution::RES_2880_2880P60;
// Set bitrate to 10MB. This value may not be valid, and certain bitrates might cause write failures during recording.
record_params.bitrate = 1024 * 1024 * 10;
if (!cam->SetVideoCaptureParams(record_params, function_mode)) {
    std::cerr << "failed to set capture settings." << std::endl;
}
```

--------------------------------

### Retrieve Camera Log File URL

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Obtain the URL for the camera's log file. This URL can then be used with a download interface to save the log locally.

```C++
std::string GetCameraLogFileUrl() const;
```

--------------------------------

### DownloadCameraFile

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Downloads a specified media file from the camera or SD card to the local device. Supports progress callbacks.

```APIDOC
## DownloadCameraFile

### Description
Downloads a specified media file from the camera or SD card to the local device. This is a synchronous call that returns after the download is complete or has failed. A callback can be provided to monitor the download progress.

### Method
Not specified (assumed to be a method call on a camera object).

### Endpoint
N/A (SDK Interface)

### Parameters
- **camera_file** (string) - Required - The path to the file on the camera.
- **local_save_file** (string) - Required - The path on the local device where the file will be saved.
- **callback** (function) - Optional - A callback function that receives `current` (int64_t) and `total_size` (int64_t) to report download progress.

### Request Example
```cpp
// Camera-side file path
std::string camera_file = "/DCIM/Camera01/VID_20250122_071405_00_001.insv";
// Local save path
std::string local_save_file = "/path/to/local/VID_20250122_071405_00_001.insv";

// Start download
bool ret = camera->DownloadCameraFile(camera_file, local_save_file, [](int64_t current, int64_t total_size) {
    // Display Progress
    std::cout << "current :" << current << "; total_size: " << total_size << std::endl;
});

// Download result
if(ret) {
   std::cout << "successed to download file" << std::endl;
} else {
   std::cout << "failed to download file" << std::endl;
}
```

### Response
#### Success Response
- **return value** (boolean) - `true` if the download was successful, `false` otherwise.
```

--------------------------------

### Stop Live Streaming Preview

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Call the `StopLiveStreaming` interface on the camera object to terminate the preview stream. This action should be performed when the preview is no longer needed.

```c++
cam->StopLiveStreaming();
```

--------------------------------

### Camera Notification Interfaces

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Sets up callbacks for various camera notifications, including low battery, SD card full, recording stoppage, and overheating.

```APIDOC
## Camera Notification Interfaces

### Description
These interfaces are used to set up callbacks for various camera notifications.

### Methods
- **SetBatteryLowNotification(BatteryLowCallBack callback)**: Sets the low battery notification.
- **SetStorageFullNotification(StorageFullCallBack callback)**: Sets the SD card full notification.
- **SetCaptureStoppedNotification(CaptureStoppedCallBack callback)**: Sets the camera recording interruption notification.
- **SetTemperatureHighNotification(TemperatureHighCallBack callback)**: Sets the camera high-temperature notification.

### Parameters
Each method accepts a callback function specific to the notification type.
```

--------------------------------

### White Balance Parameters

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

The White Balance interface is stored in the CaptureSettings interface. Current parameters are obtained using GetCaptureSettings and configured using SetCaptureSettings.

```APIDOC
## White Balance Parameters

### Description
The **White Balance** interface is stored in the **CaptureSettings** interface, which contains **White Balance** and other parameters. 

### Get White Balance Parameters
The **current White Balance parameters** are obtained using the **GetCaptureSettings** interface. Refer to the following code:

```c++
// Get White Balance parameters for the Photo Mode
const auto funtion_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE;
auto capture_setting = camera->GetCaptureSettings(funtion_mode);
auto value = settings->GetIntValue(ins_camera::CaptureSettings::SettingsType::CaptureSettings_WhiteBalance);
```

### Set White Balance Parameters
Use the **SetCaptureSettings** interface to configure the White Balance parameters. Example:

```c++
// 1. Get White Balance parameters
const auto funtion_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE;
auto capture_setting = camera->GetCaptureSettings(funtion_mode);

// 2. Set White Balance parameters
capture_setting->SetWhiteBalance(ins_camera::PhotographyOptions_WhiteBalance::WB_6500K);

// 3. Apply the parameters to the camera
camera->SetCaptureSettings(funtion_mode, capture_setting);
```
```

--------------------------------

### UploadFile (Firmware Upgrade)

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Upgrades the camera's firmware. This interface is currently only supported for X4 and later cameras. It requires the local path to the firmware file and the firmware file name.

```APIDOC
## UploadFile (Firmware Upgrade)

### Description
Upgrades the firmware version of the camera. Only supported for X4 and later cameras.

### Method
`UploadFile`

### Parameters
#### Path Parameters
- **local_path** (string) - Required - The local path to the firmware file.
- **file_name** (string) - Required - The name of the firmware file (e.g., "Insta360X4FW.bin").

### Request Example
```cpp
// Set the firmware file name
const std::string fireware_name = "Insta360X4FW.bin";
std::string file_name = "Insta360X4FW.bin";
if (camera_type == ins_camera::CameraType::Insta360X5) {
    file_name = "Insta360X5FW.bin";
}

// Specify the local path of the firmware
const std::string local_file = "/path/to/fireware/Insta360X4FW.bin";

// Start uploading
bool ret = cam->UploadFile(local_file, fireware_name ,
    [](int64_t current, int64_t total_size) {
      // Firmware upload progress display
      std::cout << "current :" << current << ";total_size: " << total_size << std::endl;
});

if (ret) {
    std::cout << "succeeded to upload file" << std::endl;
}

// After a successful upload, the camera must be powered off. Once the upgrade is complete, recreate the camera instance (the camera needs to restart for the upgrade).
camera->close();
```
```

--------------------------------

### Capture Normal Photo

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

This snippet demonstrates how to set the camera to normal photo mode, configure the photo size (with specific settings for X3 and X4), and capture a single photo.

```APIDOC
## Capture Normal Photo

### Description
This code demonstrates how to set the camera to normal photo mode, configure the photo size (with specific settings for X3 and X4), and capture a single photo.

### Method
```C++
// Set to Photo Mode
camera->SetPhotoSubMode(SubPhotoMode::PHOTO_SINGLE)

// Set resolution to 18MP. This applies to X3. For X4, set to Size_5952_2976
ins_camera::PhotoSize photo_size = ins_camera::PhotoSize::Size_6912_3456;
if (camera_type == ins_camera::CameraType::Insta360X4) {
    photo_size = ins_camera::PhotoSize::Size_5952_2976;
}
camera->SetPhotoSize(CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE,photo_size);

// Capture photo
camera->takePhoto();
```
```

--------------------------------

### Capture HDR Photo

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

This snippet shows how to initiate an HDR photo capture. It includes setting the photo size, with specific handling for X4 cameras where the output is a single, pre-merged HDR image.

```APIDOC
## Capture HDR Photo

### Description
This code demonstrates how to initiate an HDR photo capture. It includes setting the photo size, with specific handling for X4 cameras where the output is a single, pre-merged HDR image.

### Method
```C++
ins_camera::PhotoSize photo_size = ins_camera::PhotoSize::Size_6912_3456;
if (camera_type == ins_camera::CameraType::Insta360X4) {
    photo_size = ins_camera::PhotoSize::Size_5952_2976;
}
camera->StartHDRCapture(photo_size);
```
```

--------------------------------

### Set Photo Resolution

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

The SetPhotoSize interface allows setting the photo size. This interface can only be applied to photo modes and does not support video modes. Currently, X4 and X3 support 72M and 18M formats.

```c++
// Photo Resolution Options
enum PhotoSize {
    Size_6912_3456 = 0,   // X3 18MP
    Size_6272_3136 = 1,
    Size_6080_3040 = 2,
    Size_4000_3000 = 3,
    Size_4000_2250 = 4,
    Size_5212_3542 = 5,
    Size_5312_2988 = 6,
    Size_8000_6000 = 7,
    Size_8000_4500 = 8,
    Size_2976_2976 = 9,
    Size_5984_5984 = 10,
    Size_11968_5984 = 11,  // 72MP
    Size_5952_2976 = 12,   // X4 18MP
};

// Photo Modes
enum CameraFunctionMode {
    FUNCTION_MODE_NORMAL = 0,             // Default Mode
    FUNCTION_MODE_INTERVAL_SHOOTING = 3,  // Interval Shooting Mode
    FUNCTION_MODE_BURST = 5,              // Burst Mode
    FUNCTION_MODE_NORMAL_IMAGE = 6,       // Photo Mode
    FUNCTION_MODE_HDR_IMAGE = 8,          // HDR Photo Mode
    FUNCTION_MODE_AEB_NIGHT_IMAGE = 13,   
    FUNCTION_MODE_STARLAPSE_IMAGE = 18,   // Starlapse Mode
    ...
};

//Example: Setting a Photo Mode to 72MP Resolution
camera->SetPhotoSize(CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE,PhotoSize::Size_11968_5984)
```

--------------------------------

### Set Video Mode

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

This snippet illustrates how to switch between different video recording modes using the `SetVideoSubMode` interface. Supported modes include Normal, Bullet Time, Timelapse, HDR, Timeshift, and Loop Recording.

```APIDOC
## Set Video Mode

### Description
This code demonstrates how to switch between different video recording modes using the `SetVideoSubMode` interface. Supported modes include Normal, Bullet Time, Timelapse, HDR, Timeshift, and Loop Recording.

### Method
```C++
enum SubVideoMode {
    VIDEO_NORMAL = 0,         // Normal Video
    VIDEO_BULLETTIME = 1,     // Bullet Time
    VIDEO_TIMELAPSE = 2,      // Timelapse
    VIDEO_HDR = 3,            // HDR Video
    VIDEO_TIMESHIFT = 4,      // Timeshift
    VIDEO_LOOPRECORDING = 6   // Loop Recording
};

// Use the interface to switch video modes
camera->SetVideoSubMode(SubVideoMode::VIDEO_NORMAL);
```
```

--------------------------------

### Set SDK Log Level

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Configure the verbosity of the SDK's log output by setting the desired log level. This helps in debugging and monitoring.

```C++
void SetLogLevel(LogLevel level)
```

--------------------------------

### Set White Balance Parameters for Photo Mode

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Configures the White Balance parameters for the Photo Mode by first obtaining the current capture settings, then setting the desired white balance value, and finally applying the updated settings to the camera.

```c++
// 1. Get White Balance parameters
const auto funtion_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE;
auto capture_setting = camera->GetCaptureSettings(funtion_mode);

// 2. Set White Balance parameters
capture_setting->SetWhiteBalance(ins_camera::PhotographyOptions_WhiteBalance::WB_6500K);

// 3. Apply the parameters to the camera
camera->SetCaptureSettings(funtion_mode, capture_setting);
```

--------------------------------

### Setting Photo Resolution

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

The SetPhotoSize interface allows setting the photo size. Currently, X4 and X3 support formats mainly 72M and 18M. This interface can only be applied to photo modes.

```APIDOC
## Setting Photo Resolution

### Description
The **SetPhotoSize** interface allows setting the photo size. Currently, **X4** **and** **X3** support formats mainly **72M** and **18M**.

**Note**: This interface can only be applied to the photo modes in the **CameraFunctionMode** enumeration. **Video modes do not support the PhotoSize interface.**

### Enum `PhotoSize`
```c++
// Photo Resolution Options
enum PhotoSize {
    Size_6912_3456 = 0,   // X3 18MP
    Size_6272_3136 = 1,
    Size_6080_3040 = 2,
    Size_4000_3000 = 3,
    Size_4000_2250 = 4,
    Size_5212_3542 = 5,
    Size_5312_2988 = 6,
    Size_8000_6000 = 7,
    Size_8000_4500 = 8,
    Size_2976_2976 = 9,
    Size_5984_5984 = 10,
    Size_11968_5984 = 11,  // 72MP
    Size_5952_2976 = 12,   // X4 18MP
};
```

### Enum `CameraFunctionMode`
```c++
// Photo Modes
enum CameraFunctionMode {
    FUNCTION_MODE_NORMAL = 0,             // Default Mode
    FUNCTION_MODE_INTERVAL_SHOOTING = 3,  // Interval Shooting Mode
    FUNCTION_MODE_BURST = 5,              // Burst Mode
    FUNCTION_MODE_NORMAL_IMAGE = 6,       // Photo Mode
    FUNCTION_MODE_HDR_IMAGE = 8,          // HDR Photo Mode
    FUNCTION_MODE_AEB_NIGHT_IMAGE = 13,   
    FUNCTION_MODE_STARLAPSE_IMAGE = 18,   // Starlapse Mode
    ...
};
```

### Example Usage
```c++
//Example: Setting a Photo Mode to 72MP Resolution
camera->SetPhotoSize(CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE,PhotoSize::Size_11968_5984)
```
```

--------------------------------

### Switch Camera Photo Mode

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Use the SetPhotoSubMode interface to switch between different Photo Modes. Supported modes include Single, HDR, Interval, Burst, and Starlapse.

```c++
enum SubPhotoMode {
    PHOTO_SINGLE = 0,    // Photo
    PHOTO_HDR = 1,       // HDR Photo
    PHOTO_INTERVAL = 2,  // Interval
    PHOTO_BURST = 3,     // Burst
    PHOTO_STARLAPSE = 7  // Starlapse 
};  
// Use the interface to switch Photo Modes  
camera->SetPhotoSubMode(SubPhotoMode::PHOTO_SINGLE)
```

--------------------------------

### SetLogPath

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Sets the SDK's log path, specifying where log information will be saved.

```APIDOC
## SetLogPath

### Description
Sets the SDK's log path, where the SDK's log information can be saved.

### Method Signature
```C++
void SetLogPath(const std::string log_path)
```
```

--------------------------------

### GetStorageState

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Retrieves the current status of the SD card, including its state and available space.

```APIDOC
## GetStorageState

### Description
Obtains the current status of the SD card, including its state and available space.

### Method
`GetStorageState`

### Parameters
#### Output Parameters
- **status** (StorageStatus) - Output - A struct containing storage information.
  - **state** (CardState) - SD card status (e.g., STOR_CS_PASS, STOR_CS_NOCARD).
  - **free_space** (uint64_t) - Remaining space on the SD card.
  - **total_space** (uint64_t) - Total space on the SD card.

### Response Example
```cpp
StorageStatus status;
bool successed = camera->GetStorageState(status);
```
```

--------------------------------

### GetCameraFilesList

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Retrieves a list of all recorded files on the camera's SD card.

```APIDOC
## GetCameraFilesList

### Description
Retrieves a list of all recorded files on the camera's SD card.

### Method
Not specified (assumed to be a method call on a camera object).

### Endpoint
N/A (SDK Interface)

### Parameters
None explicitly mentioned.

### Request Example
```cpp
auto file_list = camera->GetCameraFilesList();
for(const auto& file : file_list) {
    std::cout << file << std::endl;
}
```

### Response
#### Success Response
- **file_list** (array of strings) - A list of file paths on the camera.
```

--------------------------------

### DeviceDiscovery::GetAvailableDevices

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Discovers available Insta360 cameras connected to the system and returns a list of their descriptors. The DeviceDescriptor struct contains basic camera information such as camera type, serial number, firmware version, and connection information.

```APIDOC
## GetAvailableDevices

### Description
Retrieves a list of all available Insta360 camera devices connected to the system.

### Method
`std::vector<DeviceDescriptor> GetAvailableDevices()`

### Parameters
None

### Response
- `std::vector<DeviceDescriptor>`: A list of `DeviceDescriptor` objects, each containing information about a discovered camera.

### DeviceDescriptor Structure
- `CameraType camera_type`: The type of the camera (e.g., X3, X4).
- `std::string serial_number`: The unique serial number of the camera.
- `std::string fw_version`: The firmware version of the camera.
- `DeviceConnectionInfo info`: Connection information for the device (currently unused for PC SDK, which only supports USB).

### Example
```cpp
ins_camera::DeviceDiscovery discovery;
std::vector<DeviceDescriptor> list = discovery.GetAvailableDevices();
```
```

--------------------------------

### Capture Normal Photo

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Sets the camera to single photo mode, configures the resolution (18MP for X3, 5952x2976 for X4), and captures a normal photo.

```C++
// Set to Photo Mode
camera->SetPhotoSubMode(SubPhotoMode::PHOTO_SINGLE)

// Set resolution to 18MP. This applies to X3. For X4, set to Size_5952_2976
ins_camera::PhotoSize photo_size = ins_camera::PhotoSize::Size_6912_3456;
if (camera_type == ins_camera::CameraType::Insta360X4) {
    photo_size = ins_camera::PhotoSize::Size_5952_2976;
}
camera->SetPhotoSize(CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE,photo_size);

// Capture photo
camera->takePhoto();
```

--------------------------------

### Set Camera Notification Callbacks

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Register callback functions for various camera events, including low battery, SD card full, recording interruption, and high temperature. These allow the application to react to critical camera states.

```C++
// This interface is used to set the low battery notification
void SetBatteryLowNotification(BatteryLowCallBack callback);

// This interface is used to set the SD card full notification
void SetStorageFullNotification(StorageFullCallBack callback);

// This interface is used to set the camera recording interruption notification
void SetCaptureStoppedNotification(CaptureStoppedCallBack callback);

// This interface is used to set the camera high-temperature notification
void SetTemperatureHighNotification(TemperatureHighCallBack callback);
```

--------------------------------

### GetRecordingFiles

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

Retrieves the names of files that are currently being recorded by the camera.

```APIDOC
## GetRecordingFiles

### Description
Retrieves the names of files that are currently being recorded by the camera.

### Method
Not specified (assumed to be a method call on a camera object).

### Endpoint
N/A (SDK Interface)

### Parameters
None explicitly mentioned.

### Request Example
```cpp
// Assuming 'camera' is an instance of the camera object
auto recording_files = camera->GetRecordingFiles();
```

### Response
#### Success Response
- **recording_files** (array of strings) - A list of names of files currently being recorded.
```

--------------------------------

### Exposure Parameters

Source: https://github.com/insta360develop/desktop-camerasdk-cpp/blob/master/README.md

The ExposureSettings interface is used to store exposure parameters including ISO, Shutter Speed, Exposure Mode, and Exposure Compensation (EV Bias).

```APIDOC
## Exposure Parameters

### Description
The **ExposureSettings** interface is used to store exposure parameters. The ExposureSettings interface includes **ISO,** **Shutter** **Speed, Exposure Mode**, and **Exposure Compensation (EV Bias)**. Refer to the following code example:

### Class `ExposureSettings`
```c++
class CAMERASDK_API ExposureSettings {
    public:
        friend class Camera;
        ExposureSettings();
 
        void SetIso(int32_t value);
        void SetShutterSpeed(double speed);
        void SetExposureMode(PhotographyOptions_ExposureMode mode);
        void SetEVBias(int32_t value);

        int32_t Iso() const;
        double ShutterSpeed() const;
        PhotographyOptions_ExposureMode ExposureMode() const;
        int32_t EVBias() const;

    private:
        std::shared_ptr<ExposureSettingsPrivate> private_impl_;
    };
```

### Get Exposure Settings
Use the **GetExposureSettings** interface to obtain the exposure parameters for each Photo Mode. Refer to the following example:

```c++
// Get exposure parameters for Photo mode
const auto funtion_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE;
auto exposure_settings = camera->GetExposureSettings(funtion_mode);
auto iso = exposure_settings->Iso();
auto shutter_speed = exposure_settings->ShutterSpeed();
// ...
```

### Set Exposure Settings
Use the **SetExposureSettings** interface to configure the exposure parameters for each Photo Mode. Refer to the following example:

```c++
// 1. Get exposure parameters for Photo mode
const auto funtion_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_NORMAL_IMAGE;
auto exposure_settings = camera->GetExposureSettings(funtion_mode);

// 2. Set exposure parameters
exposure_settings->SetEVBias(bias); // range -80 ~ 80, default 0, step 1
exposure_settings->SetIso(800);
exposure_settings->SetShutterSpeed(1.0 / 120.0);

// 3. Apply exposure settings to the camera
camera->SetExposureSettings(funtion_mode,exposure_settings);
```
```