Daiki-Iijima/insta360-go-ultra-sdk

# insta360-go-ultra-sdk **无需官方应用即可通过 WiFi 控制 Insta360 GO Ultra 的非官方 Python 工具包。** [English](#english) | [日本語](#日本語) ## English ### Features - **Live stream** — pipe H.265 video directly to `ffplay`, VLC, or any HEVC-capable player - **Camera control** — take photos, start/stop recording - **File listing** — list all files stored on the camera - **Protocol probe** — inspect raw packet types for further reverse engineering ### Requirements ``` pip install protobuf==3.20.3 brew install ffmpeg # Mac ``` Protobuf definitions (pb2/ files) from [RigacciOrg/insta360-wifi-api](https://github.com/RigacciOrg/insta360-wifi-api): ``` git clone https://github.com/RigacciOrg/insta360-wifi-api cp -r insta360-wifi-api/pb2 scripts/ ``` ### Usage Connect your machine to the camera's WiFi (`GO Ultra XXXXXX.OSC`), then: #### Live Preview ``` python3 scripts/stream.py | ffplay -f hevc -i pipe:0 ``` Low-latency mode: ``` python3 scripts/stream.py | ffplay -f hevc -fflags nobuffer -flags low_delay -i pipe:0 ``` #### Via Raspberry Pi Zero 2W (recommended) Keeps your PC on home WiFi while the RPi connects to the camera: ``` ssh pi@ 'python3 stream.py' | ffplay -f hevc -i pipe:0 ``` #### Protocol Probe ``` python3 scripts/probe.py 10 # inspect packets for 10 seconds ``` ### How It Works ``` [Your Machine / RPi] ──── TCP 6666 ──── [Insta360 GO Ultra] protobuf ``` The camera exposes a binary TCP API on port 6666 using Google Protocol Buffers. Video streams as raw H.265 Annex B within the same connection. | Packet prefix | Role | |---------------|------| | `06 00 00` | Sync handshake | | `05 00 00` | Keepalive (2s interval) | | `04 00 00` | Command / Response | | `01 00 00` | H.265 video data | Full protocol spec: [`docs/protocol.md`](docs/protocol.md) ### Hardware Setup (Raspberry Pi Zero 2W) RPi Zero 2W + TP-Link Archer T2U Nano acts as a 5GHz relay: - `wlan0` (built-in) — stays on home WiFi → SSH access maintained - `wlan1` (T2U Nano) — connects to camera's 5GHz hotspot Setup guide: [`docs/rpi-setup.md`](docs/rpi-setup.md) ### Roadmap - [ ] Rust client (`tokio` + `prost`) - [ ] TUI controller (`ratatui`) - [ ] Native file download - [ ] In-process H.265 decode (no ffplay dependency) - [ ] Map unknown packet types (ports 11009, 12345) ## 日本語 **Insta360 GO Ultraを公式アプリなしでWiFi経由で操作するPythonツールキット。** ### 機能 - **ライブストリーミング** — H.265映像をそのまま`ffplay`やVLCに流してリアルタイムプレビュー - **カメラ制御** — 写真撮影・録画の開始/停止 - **ファイル一覧取得** — カメラ内のファイルをリスト表示 - **プロトコル探索** — 独自パケット解析ツール付き ### セットアップ ``` pip install protobuf==3.20.3 brew install ffmpeg # Mac ``` protobuf定義ファイル（pb2/）を取得: ``` git clone https://github.com/RigacciOrg/insta360-wifi-api cp -r insta360-wifi-api/pb2 scripts/ ``` ### 使い方 カメラのWiFi（`GO Ultra XXXXXX.OSC`）に接続した状態で: #### ライブプレビュー ``` python3 scripts/stream.py | ffplay -f hevc -i pipe:0 ``` #### Raspberry Pi Zero 2W経由（推奨） PCのWiFiを切断せずにカメラと通信できる: ``` ssh pi@ 'python3 stream.py' | ffplay -f hevc -i pipe:0 ``` #### パケット探索 ``` python3 scripts/probe.py 10 # 10秒間パケット種別をログ出力 ``` ### 仕組み カメラはTCP 6666番ポートでGoogle Protocol Buffersを使ったバイナリAPIを公開している。 映像データ（H.265 Annex B）も同じTCP接続上でストリーミングされる。 詳細プロトコル仕様: [`docs/protocol.md`](docs/protocol.md) ### 動作確認環境 | 項目 | 内容 | |------|------| | カメラ | Insta360 GO Ultra | | ファームウェア | v1.5.47 | | OS | macOS / Raspberry Pi OS (Debian trixie) | | Python | 3.8+ | ### 免責事項 本プロジェクトは教育・互換性目的のみ。自己責任で使用してください。

标签：6666 端口, ffplay, Google Protocol Buffers, H.265, HEVC, Home WiFi, Insta360 GO Ultra, low latency, Protobuf, Python SDK, Raspberry Pi Zero 2W, SSH 隧道, TCP 6666, WiFi 控制, 二进制协议, 内存分配, 协议探针, 协议逆向, 实时流媒体, 局域网流媒体, 录像控制, 文件列表, 无官方App, 照片拍摄, 相机控制, 视频直播, 逆向工具