Insta360 Desktop CameraSDK (C++)

The connection lifecycle involves creating a camera instance from a DeviceDescriptor, opening the connection, and closing it when finished.

1. Create Instance: Use ins_camera::Camera with the DeviceConnectionInfo from a discovered device. 2. Open Camera: Call Open() to establish the connection. 3. Check Status: Use IsConnected() to verify the connection (avoid calling this while the camera is switching modes). 4. Close Camera: Call Close() to disconnect.

Important: If you perform a firmware upgrade, you must call Close(), then recreate the camera instance after the upgrade completes.

// 1. Create Instance
auto camera_info = list[0].info;
auto camera = std::make_shared<ins_camera::Camera>(camera_info);

// 2. Open Camera
bool success = camera->Open();
if(!success) {
    std::cout << "failed to open camera" << std::endl;
    return -1;
}

// 3. Check Status
// camera->IsConnected();

// 4. Disconnect
camera->Close();

To access raw video, audio, gyro, or exposure data, you must inherit from ins_camera::StreamDelegate and override its virtual methods.

Video Stream Details:

• For resolutions below 5.7K, there is a single video stream.
• For resolutions 5.7K or higher, there are two video streams (representing two fisheye images). The data is not stitched.
• The encoding format (H.264 or H.265) can be identified via GetVideoEncodeType.
• The recommended preview resolution is 1920×960.

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 {}
};

Firmware upgrades are supported only for X4 and later cameras. Use the UploadFile interface to upload the firmware binary.

Process:

1. Identify the correct firmware filename (e.g., Insta360X4FW.bin or Insta360X5FW.bin).
2. Call UploadFile with the local path and the firmware name, providing a progress callback.
3. Crucial: After a successful upload, you must call camera->close() and power off the camera. The camera must restart to complete the upgrade.

const std::string local_file = "/path/to/firmware/Insta360X4FW.bin";
const std::string fireware_name = "Insta360X4FW.bin";

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

if (ret) {
    std::cout << "succeeded to upload file" << std::endl;
    // Must close and power off after success
    camera->close();
}

Firmware upgrades are supported for X4 and later models.

1. Identify the correct firmware filename (e.g., Insta360X4FW.bin or Insta360X5FW.bin).
2. Use UploadFile(local_path, firmware_name, callback) to upload the firmware. The callback tracks upload progress.
3. Crucial: After a successful upload, you must call camera->close() and wait for the camera to restart to complete the upgrade process.

// Example for X4
const std::string fireware_name = "Insta360X4FW.bin";
const std::string local_file = "/path/to/firmware/Insta360X4FW.bin";

bool ret = cam->UploadFile(local_file, fireware_name, [](int64_t current, int64_t total_size) {
    std::cout << "current :" << current << "; total_size: " << total_size << std::endl;
});

if (ret) {
    std::cout << "succeed to Upload file !!!" << std::endl;
    // Must close camera to allow upgrade to complete
    camera->close();
}

List Files

• GetCameraFilesCount(): Returns the number of files on the SD card.
• GetCameraFilesList(): Returns a list of all file paths on the SD card.
• GetRecordingFiles(): Returns the names of files currently being recorded.

Download Files

Use DownloadCameraFile(camera_path, local_path, callback) to download files.

• The callback provides current and total_size for progress tracking.
• Important: Ensure the local directory exists before downloading.
• Port Conflict: The SDK starts an HTTP server (default port 9099). If the port is occupied, use SetServicePort before calling Open to change it.
• Use CancelDownload() to abort an ongoing download.

Delete Files

Use DeleteCameraFile(camera_path) to remove a file from the SD card.

// List files
auto file_list = camera->GetCameraFilesList();
for(const auto& file : file_list) {
    std::cout << file << std::endl;
}

// Download file with progress
std::string camera_file = "/DCIM/Camera01/VID_20250122_071405_00_001.insv";
std::string local_save_file = "/path/to/local/VID_20250122_071405_00_001.insv";

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

// Delete file
camera->DeleteCameraFile("/DCIM/Camera01/VID_20250122_071405_00_001.insv");

To perform a timelapse recording:

1. Switch the camera to timelapse mode using SetVideoSubMode(SubVideoMode::VIDEO_TIMELAPSE).
2. Set the resolution and frame rate using SetVideoCaptureParams with the appropriate CameraFunctionMode (e.g., FUNCTION_MODE_MOBILE_TIMELAPSE).
3. Configure timelapse-specific parameters (mode, duration, interval) using SetTimeLapseOption and a TimelapseParam struct.
4. Start the timelapse with StartTimeLapse(mode).
5. Stop the timelapse with StopTimeLapse(mode).

// 1. Switch 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 resolution and frame rate
auto function_mode = ins_camera::CameraFunctionMode::FUNCTION_MODE_MOBILE_TIMELAPSE;
ins_camera::RecordParams record_params;
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 timelapse parameters
auto timelapse_mode = ins_camera::CameraTimelapseMode::MOBILE_TIMELAPSE_VIDEO;
const uint32_t record_duration_s = 10; // 10 seconds duration
const uint32_t lapseTime_ms = 1000;    // 1 second interval
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 timelapse
    const auto ret = cam->StartTimeLapse(param.mode);
    if (ret) {
        std::cerr << "success!" << std::endl;
    }
    else {
        std::cerr << "failed to start timelapse" << std::endl;
    }
}

// ... later to stop ...
auto url = cam->StopTimeLapse(timelapse_mode );
if (!url.Empty()) {
    auto& origins = url.OriginUrls();
    for (auto& origin_url : origins) {
        std::cout << "url:" << origin_url << std::endl;
    }
}