pyinsta360 0.1.0__tar.gz

pyinsta360-0.1.0/CMakeLists.txt

@@ -0,0 +1,48 @@
+cmake_minimum_required(VERSION 3.18)
+project(pyinsta360 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+if(NOT INSTA360_SDK_DIR AND DEFINED ENV{INSTA360_SDK_DIR})
+  set(INSTA360_SDK_DIR "$ENV{INSTA360_SDK_DIR}")
+endif()
+if(NOT INSTA360_SDK_DIR)
+  message(FATAL_ERROR
+    "INSTA360_SDK_DIR is not set. Point it at the extracted Insta360 CameraSDK "
+    "(the directory containing include/ and lib/libCameraSDK.so), either as an "
+    "environment variable or with -DINSTA360_SDK_DIR=... (the SDK is proprietary "
+    "and is not shipped with this repository).")
+endif()
+get_filename_component(INSTA360_SDK_DIR "${INSTA360_SDK_DIR}" ABSOLUTE)
+set(INSTA360_SDK_LIB "${INSTA360_SDK_DIR}/lib/libCameraSDK.so")
+if(NOT EXISTS "${INSTA360_SDK_DIR}/include/camera/camera.h" OR NOT EXISTS "${INSTA360_SDK_LIB}")
+  message(FATAL_ERROR
+    "INSTA360_SDK_DIR='${INSTA360_SDK_DIR}' does not look like the Insta360 CameraSDK: "
+    "expected include/camera/camera.h and lib/libCameraSDK.so.")
+endif()
+
+find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG REQUIRED)
+
+pybind11_add_module(_sdk MODULE
+  src/module.cc
+  src/py_camera.cc
+  src/stream_queues.cc)
+target_include_directories(_sdk PRIVATE src "${INSTA360_SDK_DIR}/include")
+target_compile_options(_sdk PRIVATE -Wall -Wextra)
+target_link_libraries(_sdk PRIVATE "${INSTA360_SDK_LIB}")
+
+# DT_RUNPATH (not DT_RPATH) so LD_LIBRARY_PATH can override the SDK location;
+# the tests rely on that to substitute the fake SDK.
+set_target_properties(_sdk PROPERTIES
+  BUILD_WITH_INSTALL_RPATH ON
+  INSTALL_RPATH "${INSTA360_SDK_DIR}/lib"
+  INSTALL_RPATH_USE_LINK_PATH OFF)
+target_link_options(_sdk PRIVATE LINKER:--enable-new-dtags)
+
+install(TARGETS _sdk LIBRARY DESTINATION pyinsta360)

pyinsta360-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chuoru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyinsta360-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: pyinsta360
+Version: 0.1.0
+Summary: Python bindings for the Insta360 CameraSDK (X3 tested; X4/X5 nominal)
+Keywords: insta360,camera,360,imu,pybind11,robotics
+Author-Email: chuoru <tranvietthanh0101@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Topic :: Scientific/Engineering
+Project-URL: Homepage, https://github.com/chuoru/pyinsta360
+Project-URL: Issues, https://github.com/chuoru/pyinsta360/issues
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.21
+Provides-Extra: decode
+Requires-Dist: av>=12; extra == "decode"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: av>=12; extra == "test"
+Description-Content-Type: text/markdown
+
+# pyinsta360
+
+Python bindings for the Insta360 CameraSDK: discover a camera, control it, and read its live
+video, IMU and exposure streams from Python. Tested with an X3; X4 and X5 are nominal.
+
+The SDK is proprietary and is **not** part of this repository. You supply your own copy.
+
+## Install
+
+pyinsta360 ships as source only. It compiles on your machine against your own copy of the SDK,
+which you get by applying at <https://www.insta360.com/sdk/apply>.
+
+```bash
+INSTA360_SDK_DIR=/path/to/insta360_sdk pip install pyinsta360             # from PyPI
+INSTA360_SDK_DIR=/path/to/insta360_sdk pip install 'pyinsta360[decode]'   # plus PyAV for decoding
+INSTA360_SDK_DIR=/path/to/insta360_sdk pip install -e .                   # from a checkout
+```
+
+`INSTA360_SDK_DIR` is the directory that contains `include/` and `lib/libCameraSDK.so`. The build
+fails with a clear message if it is missing. The extension records `${INSTA360_SDK_DIR}/lib` as its
+`DT_RUNPATH`, so the library is found without setting `LD_LIBRARY_PATH`, and `LD_LIBRARY_PATH` still
+takes precedence if you set it. Needs a C++17 compiler, CMake 3.18+ and Python 3.10+. The SDK itself
+needs glibc 2.17 / libstdc++ GLIBCXX_3.4.30, which means Ubuntu 22.04 or newer.
+
+> A wheel built here links against, and embeds the path of, the proprietary SDK. Do not publish
+> wheels built against it.
+
+## Usage
+
+```python
+import pyinsta360 as pi
+
+print(pi.sdk_version(), pi.discover())        # [] when no camera is attached
+
+with pi.Camera() as cam:                      # or Camera("<serial>") to pick one
+    cam.start_live_streaming()                # LiveStreamParam() defaults to 1920x960P30
+    for _ in range(100):
+        packet = cam.read_video(timeout=1.0)  # VideoPacket (H.264/H.265 bytes) or None
+        imu = cam.read_imu()                  # structured array, every pending sample
+        ...
+    print(cam.stream_stats())                 # {'video_dropped': 0, 'imu_dropped': 0}
+```
+
+Decoding the stream to RGB frames (needs PyAV):
+
+```python
+from pyinsta360.decode import VideoDecoder
+
+decoder = VideoDecoder(cam.video_encode_type())
+for frame in decoder.decode(packet):          # list of HxWx3 uint8 RGB arrays
+    ...
+```
+
+`examples/stream_smoke.py` runs the whole path against a real camera and reports video fps, IMU rate
+and drops: `python examples/stream_smoke.py --seconds 10 --save-frame first.png`.
+
+Besides streaming, `Camera` offers battery and storage status, file list/download/delete, photo and
+video capture, exposure and capture parameters, and clock sync. Enums such as `VideoResolution`,
+`CameraFunctionMode` and `ExposureMode` are generated from the SDK headers. Type stubs ship in the
+package.
+
+## Units and clocks
+
+Stream data is passed through in raw SDK units.
+
+- IMU acceleration (`ax`, `ay`, `az`) is in **g**, not m/s^2. Multiply by 9.80665 for m/s^2. This
+  is the finding of the reference bridge, cross-checked against another driver that uses the same
+  SDK struct. Gyro (`gx`, `gy`, `gz`) is treated as rad/s there, which has not been verified
+  independently.
+- Video and IMU `timestamp` values are in unspecified units and come from independent clocks: on
+  real hardware they sat tens of seconds apart at the start of one session. To align the two
+  streams, stamp each item with your own receipt time.
+- The SDK delivers gyro data in bursts (about 50 samples every ~100 ms on an X3), so
+  `read_imu()` returns whole bursts, not a smooth trickle.
+- Findings from the reference bridge worth knowing: `LiveStreamParam.using_lrv=True` delivered no
+  video in dual-lens (360) mode, and the camera may ignore the requested preview resolution.
+
+## Known issues
+
+- **SDK crash during discovery.** Reported upstream as [Insta360Develop/Desktop-CameraSDK-Cpp#95](https://github.com/Insta360Develop/Desktop-CameraSDK-Cpp/issues/95). Report and reproducer: `docs/sdk-bugs/discovery-crash/`. CameraSDK 2.1.8 sometimes aborts the process with `std::bad_function_call` during `discover()` or `Camera.open()`. The exception is thrown on the SDK's own session thread, so pyinsta360 cannot catch it. A plain C++ program reproduces it (4 of 10 runs under CPU load). In Python on an idle machine it hit between 0 of 10 and 6 of 10 runs. Retrying the process works, and `run_supervised` does that for you:
+
+  ```python
+  import pyinsta360
+
+  def main():  # module-level, so it can be pickled
+      with pyinsta360.Camera() as cam: ...
+
+  if __name__ == "__main__":
+      pyinsta360.run_supervised(main)
+  ```
+- **Wrong clip path from `stop_recording()`.** Reported upstream as [Insta360Develop/Desktop-CameraSDK-Cpp#96](https://github.com/Insta360Develop/Desktop-CameraSDK-Cpp/issues/96). Report and reproducer: `docs/sdk-bugs/stop-recording-url/`. With SDK 2.1.8 on an X3, the returned origin URL ended in `.lrv` while the file on the card ends in `.insv`. Downloading the returned path fails. pyinsta360 passes the SDK's URLs through unchanged. To find a new recording, diff `files_list()` from before and after.
+- **Multiple video streams.** Some modes deliver each lens as its own stream. The X3 in `RES_2880_2880P30` mode sends `stream_index` 0 and 1 with independent timestamps. Group packets by `stream_index` and use one `VideoDecoder` per stream.
+
+## Supervised runs
+
+`run_supervised(target, *args, retries=3, **kwargs)` runs `target` in a spawned child process and
+returns its result. If the child is killed by a signal while inside `discover()` or `Camera.open()`,
+the target is rerun from the start (up to `retries` extra attempts, each logged as a warning on the
+`pyinsta360` logger). A crash anywhere else, or a nonzero exit with no result, raises
+`SupervisedProcessError` at once. Its `exitcode`, `attempts` and `during_discovery` say what
+happened. Exceptions raised by `target` are re-raised in the parent.
+
+- The target restarts from the beginning, so anything it did before `open()` repeats.
+- `target`, its arguments and its result must be picklable. Use a module-level function.
+- Notebooks that call `discover()` directly are not protected. Wrap the work in a function and
+  pass it to `run_supervised`.
+
+## Threading model
+
+- The SDK calls back on one of its own threads, and a video callback delays the gyro callback queued
+  behind it. The callbacks therefore only copy into bounded buffers and notify. They never touch
+  Python or the GIL.
+- Buffers drop their **oldest** entries when full (`video_queue_size` 64 packets, `imu_queue_size`
+  20000 samples by default, exposure 256). Drops are counted in `stream_stats()`.
+- Every call that can block releases the GIL, including `read_video`, which also wakes every
+  100 ms so Ctrl-C works.
+- `close()` and `stop_live_streaming()` may be called from any thread. A thread blocked in
+  `read_video()` is woken and gets `None`. Reads on a camera that is not streaming return `None` or
+  an empty array, and a stop discards whatever was still buffered.
+- Other camera calls are serialized by one lock, so `close()` waits for an SDK call that is already
+  running (for example a download) instead of racing it.
+- The `progress(downloaded, total)` callback of `download_file` runs on an SDK thread with the GIL
+  held. An exception it raises is re-raised after the download returns, and the download is not
+  cancelled.
+- Lifecycle is an explicit state, `Camera.state`: `CLOSED`, `OPEN`, `STREAMING`. A call that the
+  current state does not allow raises `pyinsta360.Insta360Error` (a `RuntimeError`), as does any
+  SDK action that returns failure, naming the method.
+
+## Testing without hardware
+
+`tests/fake_sdk/fake_camera_sdk.cc` is a stand-in `libCameraSDK.so` built against the real SDK
+headers. It reports one X3 (serial `FAKE0001`), streams deterministic video packets at 30 Hz and
+gyro batches of 17 samples, and has environment knobs for failure paths (see its header comment).
+
+```bash
+export INSTA360_SDK_DIR=/path/to/insta360_sdk
+pip install -e '.[test]'
+tools/test.sh            # builds the fake, puts it first on LD_LIBRARY_PATH, runs pytest
+```
+
+`LD_LIBRARY_PATH` has to be set before Python starts, which is why this is a wrapper script. Running
+plain `pytest` stops with a message if it finds the real library. The suite also checks that every
+`ins_camera` symbol the extension imports exists in both the fake and the real SDK, and that the
+generated enums and type stubs are current. Hardware behavior is not covered; use the smoke example.
+
+After changing the SDK headers, regenerate the enum bindings:
+
+```bash
+python tools/gen_enums.py --sdk-dir "$INSTA360_SDK_DIR"      # add --check to only verify
+```

pyinsta360-0.1.0/README.md

@@ -0,0 +1,150 @@
+# pyinsta360
+
+Python bindings for the Insta360 CameraSDK: discover a camera, control it, and read its live
+video, IMU and exposure streams from Python. Tested with an X3; X4 and X5 are nominal.
+
+The SDK is proprietary and is **not** part of this repository. You supply your own copy.
+
+## Install
+
+pyinsta360 ships as source only. It compiles on your machine against your own copy of the SDK,
+which you get by applying at <https://www.insta360.com/sdk/apply>.
+
+```bash
+INSTA360_SDK_DIR=/path/to/insta360_sdk pip install pyinsta360             # from PyPI
+INSTA360_SDK_DIR=/path/to/insta360_sdk pip install 'pyinsta360[decode]'   # plus PyAV for decoding
+INSTA360_SDK_DIR=/path/to/insta360_sdk pip install -e .                   # from a checkout
+```
+
+`INSTA360_SDK_DIR` is the directory that contains `include/` and `lib/libCameraSDK.so`. The build
+fails with a clear message if it is missing. The extension records `${INSTA360_SDK_DIR}/lib` as its
+`DT_RUNPATH`, so the library is found without setting `LD_LIBRARY_PATH`, and `LD_LIBRARY_PATH` still
+takes precedence if you set it. Needs a C++17 compiler, CMake 3.18+ and Python 3.10+. The SDK itself
+needs glibc 2.17 / libstdc++ GLIBCXX_3.4.30, which means Ubuntu 22.04 or newer.
+
+> A wheel built here links against, and embeds the path of, the proprietary SDK. Do not publish
+> wheels built against it.
+
+## Usage
+
+```python
+import pyinsta360 as pi
+
+print(pi.sdk_version(), pi.discover())        # [] when no camera is attached
+
+with pi.Camera() as cam:                      # or Camera("<serial>") to pick one
+    cam.start_live_streaming()                # LiveStreamParam() defaults to 1920x960P30
+    for _ in range(100):
+        packet = cam.read_video(timeout=1.0)  # VideoPacket (H.264/H.265 bytes) or None
+        imu = cam.read_imu()                  # structured array, every pending sample
+        ...
+    print(cam.stream_stats())                 # {'video_dropped': 0, 'imu_dropped': 0}
+```
+
+Decoding the stream to RGB frames (needs PyAV):
+
+```python
+from pyinsta360.decode import VideoDecoder
+
+decoder = VideoDecoder(cam.video_encode_type())
+for frame in decoder.decode(packet):          # list of HxWx3 uint8 RGB arrays
+    ...
+```
+
+`examples/stream_smoke.py` runs the whole path against a real camera and reports video fps, IMU rate
+and drops: `python examples/stream_smoke.py --seconds 10 --save-frame first.png`.
+
+Besides streaming, `Camera` offers battery and storage status, file list/download/delete, photo and
+video capture, exposure and capture parameters, and clock sync. Enums such as `VideoResolution`,
+`CameraFunctionMode` and `ExposureMode` are generated from the SDK headers. Type stubs ship in the
+package.
+
+## Units and clocks
+
+Stream data is passed through in raw SDK units.
+
+- IMU acceleration (`ax`, `ay`, `az`) is in **g**, not m/s^2. Multiply by 9.80665 for m/s^2. This
+  is the finding of the reference bridge, cross-checked against another driver that uses the same
+  SDK struct. Gyro (`gx`, `gy`, `gz`) is treated as rad/s there, which has not been verified
+  independently.
+- Video and IMU `timestamp` values are in unspecified units and come from independent clocks: on
+  real hardware they sat tens of seconds apart at the start of one session. To align the two
+  streams, stamp each item with your own receipt time.
+- The SDK delivers gyro data in bursts (about 50 samples every ~100 ms on an X3), so
+  `read_imu()` returns whole bursts, not a smooth trickle.
+- Findings from the reference bridge worth knowing: `LiveStreamParam.using_lrv=True` delivered no
+  video in dual-lens (360) mode, and the camera may ignore the requested preview resolution.
+
+## Known issues
+
+- **SDK crash during discovery.** Reported upstream as [Insta360Develop/Desktop-CameraSDK-Cpp#95](https://github.com/Insta360Develop/Desktop-CameraSDK-Cpp/issues/95). Report and reproducer: `docs/sdk-bugs/discovery-crash/`. CameraSDK 2.1.8 sometimes aborts the process with `std::bad_function_call` during `discover()` or `Camera.open()`. The exception is thrown on the SDK's own session thread, so pyinsta360 cannot catch it. A plain C++ program reproduces it (4 of 10 runs under CPU load). In Python on an idle machine it hit between 0 of 10 and 6 of 10 runs. Retrying the process works, and `run_supervised` does that for you:
+
+  ```python
+  import pyinsta360
+
+  def main():  # module-level, so it can be pickled
+      with pyinsta360.Camera() as cam: ...
+
+  if __name__ == "__main__":
+      pyinsta360.run_supervised(main)
+  ```
+- **Wrong clip path from `stop_recording()`.** Reported upstream as [Insta360Develop/Desktop-CameraSDK-Cpp#96](https://github.com/Insta360Develop/Desktop-CameraSDK-Cpp/issues/96). Report and reproducer: `docs/sdk-bugs/stop-recording-url/`. With SDK 2.1.8 on an X3, the returned origin URL ended in `.lrv` while the file on the card ends in `.insv`. Downloading the returned path fails. pyinsta360 passes the SDK's URLs through unchanged. To find a new recording, diff `files_list()` from before and after.
+- **Multiple video streams.** Some modes deliver each lens as its own stream. The X3 in `RES_2880_2880P30` mode sends `stream_index` 0 and 1 with independent timestamps. Group packets by `stream_index` and use one `VideoDecoder` per stream.
+
+## Supervised runs
+
+`run_supervised(target, *args, retries=3, **kwargs)` runs `target` in a spawned child process and
+returns its result. If the child is killed by a signal while inside `discover()` or `Camera.open()`,
+the target is rerun from the start (up to `retries` extra attempts, each logged as a warning on the
+`pyinsta360` logger). A crash anywhere else, or a nonzero exit with no result, raises
+`SupervisedProcessError` at once. Its `exitcode`, `attempts` and `during_discovery` say what
+happened. Exceptions raised by `target` are re-raised in the parent.
+
+- The target restarts from the beginning, so anything it did before `open()` repeats.
+- `target`, its arguments and its result must be picklable. Use a module-level function.
+- Notebooks that call `discover()` directly are not protected. Wrap the work in a function and
+  pass it to `run_supervised`.
+
+## Threading model
+
+- The SDK calls back on one of its own threads, and a video callback delays the gyro callback queued
+  behind it. The callbacks therefore only copy into bounded buffers and notify. They never touch
+  Python or the GIL.
+- Buffers drop their **oldest** entries when full (`video_queue_size` 64 packets, `imu_queue_size`
+  20000 samples by default, exposure 256). Drops are counted in `stream_stats()`.
+- Every call that can block releases the GIL, including `read_video`, which also wakes every
+  100 ms so Ctrl-C works.
+- `close()` and `stop_live_streaming()` may be called from any thread. A thread blocked in
+  `read_video()` is woken and gets `None`. Reads on a camera that is not streaming return `None` or
+  an empty array, and a stop discards whatever was still buffered.
+- Other camera calls are serialized by one lock, so `close()` waits for an SDK call that is already
+  running (for example a download) instead of racing it.
+- The `progress(downloaded, total)` callback of `download_file` runs on an SDK thread with the GIL
+  held. An exception it raises is re-raised after the download returns, and the download is not
+  cancelled.
+- Lifecycle is an explicit state, `Camera.state`: `CLOSED`, `OPEN`, `STREAMING`. A call that the
+  current state does not allow raises `pyinsta360.Insta360Error` (a `RuntimeError`), as does any
+  SDK action that returns failure, naming the method.
+
+## Testing without hardware
+
+`tests/fake_sdk/fake_camera_sdk.cc` is a stand-in `libCameraSDK.so` built against the real SDK
+headers. It reports one X3 (serial `FAKE0001`), streams deterministic video packets at 30 Hz and
+gyro batches of 17 samples, and has environment knobs for failure paths (see its header comment).
+
+```bash
+export INSTA360_SDK_DIR=/path/to/insta360_sdk
+pip install -e '.[test]'
+tools/test.sh            # builds the fake, puts it first on LD_LIBRARY_PATH, runs pytest
+```
+
+`LD_LIBRARY_PATH` has to be set before Python starts, which is why this is a wrapper script. Running
+plain `pytest` stops with a message if it finds the real library. The suite also checks that every
+`ins_camera` symbol the extension imports exists in both the fake and the real SDK, and that the
+generated enums and type stubs are current. Hardware behavior is not covered; use the smoke example.
+
+After changing the SDK headers, regenerate the enum bindings:
+
+```bash
+python tools/gen_enums.py --sdk-dir "$INSTA360_SDK_DIR"      # add --check to only verify
+```

pyinsta360-0.1.0/docs/sdk-bugs/discovery-crash/REPORT.md

@@ -0,0 +1,92 @@
+# CameraSDK 2.1.8: `DeviceDiscovery::GetAvailableDevices` intermittently aborts the process with `std::bad_function_call`
+
+## Summary
+
+`ins_camera::DeviceDiscovery::GetAvailableDevices()` sometimes terminates the whole process. An internal SDK thread, `ins_camera::connection::CameraSession::ReadLoop()`, invokes an empty `std::function`. The resulting `std::bad_function_call` is not caught on that thread, so `std::terminate` aborts the process (SIGABRT, exit code 134). The calling application cannot catch or recover from it.
+
+It reproduces with a minimal C++ program that only discovers and opens a camera. It happens more often when the CPU is busy, which points to a race inside the SDK.
+
+## Environment
+
+- CameraSDK 2.1.8 (Linux x86_64, `lib/libCameraSDK.so`)
+- Camera: Insta360 X3, firmware v1.1.6, connected over USB (vid:pid `2e1a:0002`)
+- OS: Ubuntu 24.04.5 LTS, kernel 7.0.0, glibc 2.39
+- Compiler: GCC 13.3.0, `-std=c++17`
+- CPU: Intel Core i9-13900HX (32 threads)
+
+## Steps to reproduce
+
+1. Connect an X3 over USB and make sure the user can open the USB device.
+2. Build and run the attached `repro.cc`, which only calls `GetAvailableDevices`, `Camera::Open`, `FreeDeviceDescriptors` and `Close`. The attached `run.sh` builds it and runs it repeatedly with every CPU core busy:
+
+   ```bash
+   INSTA360_SDK_DIR=/path/to/CameraSDK ./run.sh 30
+   ```
+
+3. Some runs exit with code 134 and print:
+
+   ```
+   terminate called after throwing an instance of 'std::bad_function_call'
+     what():  bad_function_call
+   ```
+
+## Expected
+
+`GetAvailableDevices()` returns the device list, or an empty list on failure. It never terminates the process.
+
+## Actual
+
+The process aborts during `GetAvailableDevices()`. `repro.cc` prints a `STEP` line before each SDK call. In every crash the last line printed was `STEP discover`, so the abort happens inside `GetAvailableDevices()` and never in `Open()`, `FreeDeviceDescriptors()` or `Close()`.
+
+Measured results:
+
+| Program | Condition | Crashed |
+|---|---|---|
+| discover + open (`repro.cc`) | all cores busy | 7 of 72 runs, all in `GetAvailableDevices` |
+| discover only | all cores busy | 4 of 10 runs |
+| discover only | idle | 0 of 12 runs |
+| The same calls through a Python binding | idle | between 0 of 10 and 6 of 10 runs per batch |
+
+## Stack trace
+
+Captured with gdb on the crashing thread (frames below `ReadLoop` are libstdc++'s thread start):
+
+```
+#7  std::terminate()                                  libstdc++.so.6
+#8  __cxa_throw ()                                    libstdc++.so.6
+#9  std::__throw_bad_function_call()                  libstdc++.so.6
+#10 ins_camera::connection::CameraSession::ReadLoop() libCameraSDK.so
+#11 ?? (std::thread start routine)                    libstdc++.so.6
+```
+
+Just before the abort, the SDK log (level VERBOSE) shows the session's first heartbeat:
+
+```
+I camera_session.cpp:0275:  heartbeat is coming
+I camera_session.cpp:0277:  package version: 0
+I camera_session.cpp:0250:  first heart beat package is coming
+I camera_session.cpp:0063:  heartbeat package is coming
+terminate called after throwing an instance of 'std::bad_function_call'
+```
+
+## Analysis
+
+These points are inferences, not confirmed against SDK source:
+
+- `ReadLoop` calls a `std::function` member (a packet or heartbeat handler) that is empty at that moment. It seems to be read without synchronization while it is being set or cleared, for example while the temporary session that `GetAvailableDevices` opens to read the serial number is set up or torn down.
+- The application cannot work around it inside the process. We tried a `std::set_terminate` handler that recognizes this exception on the SDK thread:
+  - calling `pthread_exit` from the handler re-enters `std::terminate` (the thread's start routine is `noexcept`) until the process segfaults;
+  - parking the thread in the handler makes `GetAvailableDevices()` hang, because the SDK waits for that thread to finish.
+
+## Suggested fix
+
+Ensure `ReadLoop` never invokes an empty handler. Either check it before calling (`if (handler) handler(...)`) under the same lock that guards assignment, or set the handler before the read thread starts and clear it only after the thread has been joined. Catching exceptions at the top of `ReadLoop` would also stop a single bad packet from killing the host process.
+
+## Impact
+
+Any application that discovers or opens a camera can be killed at startup, at random. We currently run discovery in a supervised child process and restart it when it aborts.
+
+## Attachments
+
+- `repro.cc` is the minimal reproducer.
+- `run.sh` builds it and runs it under CPU load.

pyinsta360-0.1.0/docs/sdk-bugs/discovery-crash/repro.cc

@@ -0,0 +1,20 @@
+#include <camera/camera.h>
+#include <camera/device_discovery.h>
+#include <cstdio>
+int main() {
+  ins_camera::SetLogLevel(ins_camera::LogLevel::ERR);
+  ins_camera::DeviceDiscovery discovery;
+  fprintf(stderr, "STEP discover\n");
+  auto list = discovery.GetAvailableDevices();
+  if (list.empty()) { fprintf(stderr, "STEP none\n"); return 3; }
+  fprintf(stderr, "STEP construct\n");
+  auto cam = std::make_shared<ins_camera::Camera>(list[0].info);
+  fprintf(stderr, "STEP open\n");
+  bool ok = cam->Open();
+  fprintf(stderr, "STEP free (open=%d)\n", ok);
+  discovery.FreeDeviceDescriptors(list);
+  fprintf(stderr, "STEP close\n");
+  cam->Close();
+  fprintf(stderr, "STEP done\n");
+  return 0;
+}

pyinsta360-0.1.0/docs/sdk-bugs/discovery-crash/run.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Builds repro.cc against the CameraSDK and runs it N times with every core busy.
+# Usage: INSTA360_SDK_DIR=/path/to/sdk ./run.sh [runs]
+set -uo pipefail
+: "${INSTA360_SDK_DIR:?set INSTA360_SDK_DIR to the CameraSDK directory}"
+runs="${1:-30}"
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+out="$(mktemp -d)"
+g++ -std=c++17 -g -I"$INSTA360_SDK_DIR/include" "$here/repro.cc" \
+  -L"$INSTA360_SDK_DIR/lib" -lCameraSDK -Wl,-rpath,"$INSTA360_SDK_DIR/lib" -o "$out/repro" || exit 1
+crashes=0
+for i in $(seq 1 "$runs"); do
+  for _ in $(seq 1 "$(nproc)"); do (timeout 5 sh -c 'while :; do :; done' &); done
+  timeout 40 "$out/repro" > "$out/run_$i.txt" 2>&1
+  code=$?
+  if [ "$code" -ne 0 ]; then
+    crashes=$((crashes + 1))
+    echo "run $i: exit $code, last step: $(grep STEP "$out/run_$i.txt" | tail -1)"
+  fi
+  sleep 5
+done
+echo "crashed $crashes of $runs runs (logs in $out)"

pyinsta360-0.1.0/docs/sdk-bugs/stop-recording-url/REPORT.md

@@ -0,0 +1,72 @@
+# CameraSDK 2.1.8: `Camera::StopRecording()` returns an origin URL with the wrong extension (`.lrv` instead of `.insv`)
+
+## Summary
+
+On an Insta360 X3, the `MediaUrl` returned by `Camera::StopRecording()` names an origin file that does not exist. The returned origin path ends in `.lrv`, while the recorded file on the camera ends in `.insv`. Downloading the returned path with `DownloadCameraFile` fails, while the `.insv` path downloads correctly. Applications that use the returned URL to fetch a recording cannot get the file.
+
+## Environment
+
+- CameraSDK 2.1.8 (Linux x86_64, `lib/libCameraSDK.so`)
+- Camera: Insta360 X3, firmware v1.1.6, connected over USB (vid:pid `2e1a:0002`)
+- OS: Ubuntu 24.04.5 LTS, kernel 7.0.0, glibc 2.39
+- Camera state before recording: `GetCurrentFunctionMode()` returned `FUNCTION_MODE_HDR_IMAGE`. No `SetVideoCaptureParams` call was made before `StartRecording()`.
+
+## Steps to reproduce
+
+1. Connect an X3 over USB.
+2. Build and run the attached `repro.cc`. It records for 3 seconds, prints the returned `MediaUrl`, compares it with the camera's file list, and tries to download each returned path:
+
+   ```bash
+   g++ -std=c++17 -I$SDK/include repro.cc -L$SDK/lib -lCameraSDK -Wl,-rpath,$SDK/lib -o repro
+   ./repro 3 --delete     # --delete removes the clip afterwards
+   ```
+
+## Expected
+
+`MediaUrl::OriginUrls()` lists the recorded `.insv` file, and `LRVUrls()` lists its `.lrv` proxy. Every returned path exists in `GetCameraFilesList()` and can be downloaded.
+
+## Actual
+
+Observed on 2026-11-16 (3-second recording):
+
+| Source | Path |
+|---|---|
+| `StopRecording().OriginUrls()` | `/DCIM/Camera01/VID_20261116_051448_00_007.lrv` |
+| `StopRecording().LRVUrls()` | `/DCIM/Camera01/LRV_20261116_051448_01_007.lrv` |
+| New in `GetCameraFilesList()` | `/DCIM/Camera01/VID_20261116_051448_00_007.insv` |
+| New in `GetCameraFilesList()` | `/DCIM/Camera01/LRV_20261116_051448_01_007.lrv` |
+
+- `DownloadCameraFile("/DCIM/Camera01/VID_20261116_051448_00_007.lrv", ...)` returned `false`.
+- `DownloadCameraFile("/DCIM/Camera01/VID_20261116_051448_00_007.insv", ...)` returned `true` and produced a valid 22,028,003-byte file (3840x1920 H.264 video with AAC audio, 3.27 s, 98 frames).
+- The `LRVUrls()` entry was correct and present on the camera.
+- `TakePhoto()` in the same session returned a correct path (`IMG_20261116_051438_00_006.insp`), so the problem appears specific to `StopRecording()`.
+
+The origin URL has the right base name (`VID_…_00_007`) and the wrong extension. It looks like the extension is taken from the LRV entry when the origin URL is built. That is an inference from the output, not confirmed.
+
+## Reproduced with the plain C++ API
+
+The first observation was made through a Python binding that copies `MediaUrl::OriginUrls()` and `LRVUrls()` without modification. The attached `repro.cc` makes the same calls directly against the C++ API, with no binding involved. Run on the same camera on 2026-11-16 (`./repro 3 --delete`, camera in function mode 8, `FUNCTION_MODE_HDR_IMAGE`), it reproduced the problem:
+
+```
+returned origin: /DCIM/Camera01/VID_20261116_055409_00_006.lrv
+returned lrv:    /DCIM/Camera01/LRV_20261116_055409_01_006.lrv
+new on camera:   /DCIM/Camera01/LRV_20261116_055409_01_006.lrv
+new on camera:   /DCIM/Camera01/VID_20261116_055409_00_006.insv
+BAD  listed=0 downloaded=0 /DCIM/Camera01/VID_20261116_055409_00_006.lrv
+OK   listed=1 downloaded=1 /DCIM/Camera01/LRV_20261116_055409_01_006.lrv
+RESULT: returned MediaUrl names a file that does not exist
+```
+
+Two out of two recordings showed the same wrong extension.
+
+## Suggested fix
+
+Build each origin URL from the recorded file's own name, with its `.insv` extension, and check that every returned path exists in the camera's file list before returning it.
+
+## Impact
+
+Any application that downloads a recording right after `StopRecording()` fails to fetch it. The current workaround is to compare `GetCameraFilesList()` from before and after the recording.
+
+## Attachments
+
+- `repro.cc` is the reproducer. It exits 1 when a returned path is missing or cannot be downloaded.