Skip to main content

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.

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

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):

from pyinsta360.decode import VideoDecoder

decoder = VideoDecoder(cam.video_encode_type())
for frame in decoder.decode(packet):          # list of HxWx3 uint8 RGB arrays
    ...

One decoding thread barely keeps up with an X3's 3840x1920 stream (about 35 fps for 29 sent), and the camera then drops the oldest packets. VideoDecoder(encode_type, threads=4) decodes on four frame threads, about 90 fps, at the cost of about 100 ms more delay, because each thread holds back a frame.

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. 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:

    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. 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).

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:

python tools/gen_enums.py --sdk-dir "$INSTA360_SDK_DIR"      # add --check to only verify

Metadata

Release files for pyinsta360 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyinsta360 0.1.1
File Size Uploaded Provenance Actions
pyinsta360-0.1.1.tar.gz 52.1 kB Without provenance Details for pyinsta360-0.1.1.tar.gz

Release files / pyinsta360-0.1.1.tar.gz

Download URL pyinsta360-0.1.1.tar.gz
Size 52.1 kB
Tags Source
SHA-256 checksum
How to use checksums
1af0563ab7fc1a16f563a53c2bd0d69e5218d4285af2ff76b5752c43b35f68ea
BLAKE2b-256 checksum
How to use checksums
6dec6b8199b9f307eca7a526f07e1a0e928a8fd273589e770c629ec1e9ee3cc5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for pyinsta360 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page