# insta360_streaming

**Repository Path**: endless-edge/insta360_streaming

## Basic Information

- **Project Name**: insta360_streaming
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# insta360_streaming

#### 介绍
本项目仓库是用于在lubancat-3（或者其他支持linux的平台）板卡上推流insta360 x5全景相机捕获的全景视频，此时insta360 x5相机作为usb摄像头使用。

#### 项目目录
- `insta360x5_stream.py`：使用FFmepg对全景视频进行推流的文件。
- `x5_stream.service`：设置推流系统服务的文件。
- `README.md`：项目说明。
#### 使用说明
1.  需要提前设置insta360x5_stream.py文件中的“DEVICE”参数，也即usb摄像头中的设备节点。
关于设备节点，可以采用lsub查看x5相机的总线号（Bus XXX）、其总线上的设备编号（Device YYY）以及设备ID（ID VVVV:PPPP, 由设备的唯一标识符，由厂商 ID (Vendor ID) 和产品 ID (Product ID) 组成）:
```
cat@lubancat:~/insta360$ lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 004: ID 0bda:c822 Realtek Semiconductor Corp. Bluetooth Radio
Bus 001 Device 018: ID 2e1a:0005 Insta Insta360 X5
Bus 001 Device 002: ID 1a40:0201 Terminus Technology Inc. FE 2.1 7-port Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
```
x5相机的信息在第三行，然后执行`ls /dev/video*`识别与视频相关的设备节点。
```
cat@lubancat:~/insta360$ ls /dev/video*
/dev/video-dec0  /dev/video-enc0  /dev/video0  /dev/video1
```
需要注意的是，在现代 Linux 内核的 UVC（USB Video Class）驱动中，为了支持更高级的功能，内核会为同一个 USB 摄像头创建多个设备节点（V4L2（Video for Linux 2）框架的一种特性）。在这里，`/dev/video0`与`/dev/video1`就是x5相机在此就有两个相关的设备节点。其中，`/dev/video0`是主设备节点，负责视频的捕获并传输摄像头拍摄的图像流（如 MJPEG 或 H.264 格式），所有的视频录制、直播推流软件（如 FFmpeg, OBS, OpenCV）都应该使用这个节点；`/dev/video1`是元数据节点，这个是个辅助节点，用于捕获并传输摄像头传感器的额外信息，例如 IMU（惯性测量单元）数据、时间戳、曝光参数等，一些专业的视频分析软件或稳定算法会利用这些数据。二者可以使用`udevadm info --query=all --name=/dev/video* | grep ID_V4L_CAPABILITIES `命令检查各个设备节点，依据输出来判断节点功能，如果输出是“E: ID_V4L_CAPABILITIES=:capture:”(带有capture)则表示该节点是负责视频捕获的，如果输出是“E: ID_V4L_CAPABILITIES=:”（为空或者是元数据标识），那么他就是负责捕获有元数据的。
检查`/dev/video0`节点：
```
P: /devices/platform/23400000.usb/xhci-hcd.0.auto/usb1/1-1/1-1.1/1-1.1:1.0/video4linux/video0
M: video0
R: 0
U: video4linux
D: c 81:0
N: video0
L: 0
S: v4l/by-id/usb-Insta_Insta360_X5_0001-video-index0
S: v4l/by-path/platform-xhci-hcd.0.auto-usb-0:1.1:1.0-video-index0
E: DEVPATH=/devices/platform/23400000.usb/xhci-hcd.0.auto/usb1/1-1/1-1.1/1-1.1:1.0/video4linux/video0
E: DEVNAME=/dev/video0
E: MAJOR=81
E: MINOR=0
E: SUBSYSTEM=video4linux
E: USEC_INITIALIZED=1989890317740
E: ID_V4L_VERSION=2
E: ID_V4L_PRODUCT=Insta360 X5: Insta360 X5
E: ID_V4L_CAPABILITIES=:capture:
E: ID_BUS=usb
E: ID_MODEL=Insta360_X5
E: ID_MODEL_ENC=Insta360\x20X5
E: ID_MODEL_ID=0005
E: ID_SERIAL=Insta_Insta360_X5_0001
E: ID_SERIAL_SHORT=0001
E: ID_VENDOR=Insta
E: ID_VENDOR_ENC=Insta
E: ID_VENDOR_ID=2e1a
E: ID_REVISION=0200
E: ID_TYPE=video
E: ID_USB_MODEL=Insta360_X5
E: ID_USB_MODEL_ENC=Insta360\x20X5
E: ID_USB_MODEL_ID=0005
E: ID_USB_SERIAL=Insta_Insta360_X5_0001
E: ID_USB_SERIAL_SHORT=0001
E: ID_USB_VENDOR=Insta
E: ID_USB_VENDOR_ENC=Insta
E: ID_USB_VENDOR_ID=2e1a
E: ID_USB_REVISION=0200
E: ID_USB_TYPE=video
E: ID_USB_INTERFACES=:0e0100:0e0200:010100:010200:
E: ID_USB_INTERFACE_NUM=00
E: ID_USB_DRIVER=uvcvideo
E: ID_PATH=platform-xhci-hcd.0.auto-usb-0:1.1:1.0
E: ID_PATH_TAG=platform-xhci-hcd_0_auto-usb-0_1_1_1_0
E: ID_FOR_SEAT=video4linux-platform-xhci-hcd_0_auto-usb-0_1_1_1_0
E: COLORD_DEVICE=1
E: COLORD_KIND=camera
E: DEVLINKS=/dev/v4l/by-id/usb-Insta_Insta360_X5_0001-video-index0 /dev/v4l/by-path/platform-xhci-hcd.0.auto-usb-0:1.1:1.0-video-index0
E: TAGS=:uaccess:seat:
E: CURRENT_TAGS=:uaccess:seat:
```
检查`/dev/video1`节点
```
cat@lubancat:~/insta360$ udevadm info --query=all --name=/dev/video* | grep ID_V4L_CAPABILITIES
Unknown device "/dev/video*": No such device
cat@lubancat:~/insta360$ udevadm info --query=all --name=/dev/video0 | grep ID_V4L_CAPABILITIES
E: ID_V4L_CAPABILITIES=:capture:
cat@lubancat:~/insta360$ udevadm info --query=all --name=/dev/video1 | grep ID_V4L_CAPABILITIES
E: ID_V4L_CAPABILITIES=:
cat@lubancat:~/insta360$ udevadm info --query=all --name=/dev/video1
P: /devices/platform/23400000.usb/xhci-hcd.0.auto/usb1/1-1/1-1.1/1-1.1:1.0/video4linux/video1
M: video1
R: 1
U: video4linux
D: c 81:1
N: video1
L: 0
S: v4l/by-id/usb-Insta_Insta360_X5_0001-video-index1
S: v4l/by-path/platform-xhci-hcd.0.auto-usb-0:1.1:1.0-video-index1
E: DEVPATH=/devices/platform/23400000.usb/xhci-hcd.0.auto/usb1/1-1/1-1.1/1-1.1:1.0/video4linux/video1
E: DEVNAME=/dev/video1
E: MAJOR=81
E: MINOR=1
E: SUBSYSTEM=video4linux
E: USEC_INITIALIZED=1989890317742
E: ID_V4L_VERSION=2
E: ID_V4L_PRODUCT=Insta360 X5: Insta360 X5
E: ID_V4L_CAPABILITIES=:
E: ID_BUS=usb
E: ID_MODEL=Insta360_X5
E: ID_MODEL_ENC=Insta360\x20X5
E: ID_MODEL_ID=0005
E: ID_SERIAL=Insta_Insta360_X5_0001
E: ID_SERIAL_SHORT=0001
E: ID_VENDOR=Insta
E: ID_VENDOR_ENC=Insta
E: ID_VENDOR_ID=2e1a
E: ID_REVISION=0200
E: ID_TYPE=video
E: ID_USB_MODEL=Insta360_X5
E: ID_USB_MODEL_ENC=Insta360\x20X5
E: ID_USB_MODEL_ID=0005
E: ID_USB_SERIAL=Insta_Insta360_X5_0001
E: ID_USB_SERIAL_SHORT=0001
E: ID_USB_VENDOR=Insta
E: ID_USB_VENDOR_ENC=Insta
E: ID_USB_VENDOR_ID=2e1a
E: ID_USB_REVISION=0200
E: ID_USB_TYPE=video
E: ID_USB_INTERFACES=:0e0100:0e0200:010100:010200:
E: ID_USB_INTERFACE_NUM=00
E: ID_USB_DRIVER=uvcvideo
E: ID_PATH=platform-xhci-hcd.0.auto-usb-0:1.1:1.0
E: ID_PATH_TAG=platform-xhci-hcd_0_auto-usb-0_1_1_1_0
E: ID_FOR_SEAT=video4linux-platform-xhci-hcd_0_auto-usb-0_1_1_1_0
E: COLORD_DEVICE=1
E: COLORD_KIND=camera
E: DEVLINKS=/dev/v4l/by-id/usb-Insta_Insta360_X5_0001-video-index1 /dev/v4l/by-path/platform-xhci-hcd.0.auto-usb-0:1.1:1.0-video-index1
E: TAGS=:uaccess:seat:
E: CURRENT_TAGS=:uaccess:seat:
```
最后将insta360x5_stream.py文件中的`DEVICE`参数赋值为`/dev/video0`。
除此之外，也可以用Video4Linux2（V4L2）的控制工具`v4l2-ctl`来查看设备信息，可以可以获取摄像头的驱动、设备名称、支持的格式等。
```
cat@lubancat:~/insta360$ v4l2-ctl -d /dev/video0 --all
Driver Info:
        Driver name      : uvcvideo
        Card type        : Insta360 X5: Insta360 X5
        Bus info         : usb-xhci-hcd.0.auto-1.1
        Driver version   : 6.1.99
        Capabilities     : 0x84a00001
                Video Capture
                Metadata Capture
                Streaming
                Extended Pix Format
                Device Capabilities
        Device Caps      : 0x04200001
                Video Capture
                Streaming
                Extended Pix Format
Media Driver Info:
        Driver name      : uvcvideo
        Model            : Insta360 X5: Insta360 X5
        Serial           : 0001
        Bus info         : usb-xhci-hcd.0.auto-1.1
        Media version    : 6.1.99
        Hardware revision: 0x00000200 (512)
        Driver version   : 6.1.99
Interface Info:
        ID               : 0x03000002
        Type             : V4L Video
Entity Info:
        ID               : 0x00000001 (1)
        Name             : Insta360 X5: Insta360 X5
        Function         : V4L2 I/O
        Flags            : default
        Pad 0x01000007   : 0: Sink
          Link 0x02000010: from remote pad 0x100000a of entity 'Extension 10' (Video Pixel Formatter): Data, Enabled, Immutable
Priority: 2
Video input : 0 (Input 1: ok)
Format Video Capture:
        Width/Height      : 2880/1440
        Pixel Format      : 'MJPG' (Motion-JPEG)
        Field             : None
        Bytes per Line    : 0
        Size Image        : 2097152
        Colorspace        : sRGB
        Transfer Function : Default (maps to sRGB)
        YCbCr/HSV Encoding: Default (maps to ITU-R 601)
        Quantization      : Default (maps to Full Range)
        Flags             :
Crop Capability Video Capture:
        Bounds      : Left 0, Top 0, Width 2880, Height 1440
        Default     : Left 0, Top 0, Width 2880, Height 1440
        Pixel Aspect: 1/1
Selection Video Capture: crop_default, Left 0, Top 0, Width 2880, Height 1440, Flags:
Selection Video Capture: crop_bounds, Left 0, Top 0, Width 2880, Height 1440, Flags:
Streaming Parameters Video Capture:
        Capabilities     : timeperframe
        Frames per second: 30.000 (30/1)
        Read buffers     : 0

User Controls

                     brightness 0x00980900 (int)    : min=-256 max=256 step=1 default=0 value=0
cat@lubancat:~/insta360$ v4l2-ctl -d /dev/video1 --all
Driver Info:
        Driver name      : uvcvideo
        Card type        : Insta360 X5: Insta360 X5
        Bus info         : usb-xhci-hcd.0.auto-1.1
        Driver version   : 6.1.99
        Capabilities     : 0x84a00001
                Video Capture
                Metadata Capture
                Streaming
                Extended Pix Format
                Device Capabilities
        Device Caps      : 0x04a00000
                Metadata Capture
                Streaming
                Extended Pix Format
Media Driver Info:
        Driver name      : uvcvideo
        Model            : Insta360 X5: Insta360 X5
        Serial           : 0001
        Bus info         : usb-xhci-hcd.0.auto-1.1
        Media version    : 6.1.99
        Hardware revision: 0x00000200 (512)
        Driver version   : 6.1.99
Interface Info:
        ID               : 0x03000005
        Type             : V4L Video
Entity Info:
        ID               : 0x00000004 (4)
        Name             : Insta360 X5: Insta360 X5
        Function         : V4L2 I/O
Priority: 2
Format Metadata Capture:
        Sample Format   : 'UVCH' (UVC Payload Header Metadata)
        Buffer Size     : 10240
```
2.  关于FFmepg推流参数的理解。
总体功能是：从摄像头（video_device）采集视频，从声卡（hw:3,0）采集音频，将它们编码成 H.264+AAC 格式，然后通过 RTMP 协议推送到服务器。
**输入参数(Input)**：
```
'-loglevel', 'warning',  # 只显示警告及以上级别的日志，减少屏幕输出干扰
'-f', 'v4l2',            # 指定输入格式为 Video4Linux2 (Linux 摄像头驱动)
'-input_format', 'mjpeg', # 告诉 ffmpeg，摄像头输入的是 MJPEG 流（效率高，CPU 占用低）
'-video_size', f'{WIDTH}x{HEIGHT}', # 分辨率，例如 1920x1080
'-framerate', FPS,       # 帧率，例如 30
'-i', VIDEO_DEVICE,      # 输入视频设备，即你的 /dev/video0
'-f', 'alsa',            # 指定音频输入格式为 ALSA (Linux 音频系统)
'-i', 'hw:3,0',          # 输入音频设备，即第 3 号声卡的第 0 个设备
```

**编码与处理参数（Codec & Filter）**：
```
'-c:v', 'libx264',       # 视频编码器：使用软件编码 H.264 (兼容性最好)
'-preset', 'ultrafast',  # 编码速度预设：最快模式（为了降低延迟，牺牲压缩率）
'-tune', 'zerolatency',  # 调优选项：零延迟（关键！用于直播）
'-profile:v', 'baseline', # H.264 编码档次：baseline（兼容性好，适合移动端）
'-level', '4.2',         # H.264 级别：4.2（限制码率和分辨率，确保播放器能解码）
'-c:a', 'aac',           # 音频编码器：AAC 格式
'-ar', '44100',          # 音频采样率：44.1kHz (标准 CD 音质)
'-b:a', '128k',          # 音频比特率：128kbps
'-pix_fmt', 'yuv420p',   # 像素格式：yuv420p (最通用的格式，兼容所有播放器)
'-g', str(int(FPS) * 2), # 关键帧间隔 (GOP)：例如每 2 秒一个关键帧 (FPS*2)
'-keyint_min', '30',     # 最小关键帧间隔：至少 30 帧才允许插入关键帧
```

**输出参数（Output）**:
```
'-f', 'flv',             # 输出封装格式：FLV (RTMP 推流的标准格式)
RTMP_URL                 # 输出目标：RTMP 服务器地址
```

**为什么用 mjpeg 输入？**
因为 Insta360 X5 等现代摄像头通常支持 MJPEG 格式输出。相比于 YUV 格式，MJPEG 数据量小，传输快，且解码（解压缩）非常省 CPU，非常适合树莓派这种 ARM 设备。
**低延迟设置 (zerolatency)**
直播最怕卡顿和延迟。-preset ultrafast 和 -tune zerolatency 告诉 libx264 编码器不要为了压缩率去耗费时间做复杂的计算，而是要以最快的速度编码，保证画面实时性。
**音频设备 (hw:3,0)**
这里的 3,0 是 ALSA 音频设备的索引。你需要确保 arecord -l 命令中能看到第 3 号声卡（通常是你的 USB 麦克风或采集卡）。

**ps**:
- 各个level支持的分辨率与码率：

| Level | 最大宏块数/秒 | 典型分辨率与帧率上限 | 最大视频码率 (Baseline/Main Profile) | 最大视频码率 (High Profile) |
| :--- | :--- | :--- | :--- | :--- |
| 3.1 | 108,000 | 1280×720 @ 30fps | 14,000 kbps | 17,500 kbps |
| 4.0 | 245,760 | 1920×1080 @ 30fps | 20,000 kbps | 25,000 kbps |
| 4.1 | 245,760 | 1920×1080 @ 30fps | 50,000 kbps | 62,500 kbps |
| 4.2 | 522,240 | 1920×1080 @ 60fps | 50,000 kbps | 62,500 kbps |
| 5.1 | 983,040 | 4096×2160 (4K) @ 30fps | 135,000 kbps | 150,000 kbps |
| 5.2 | 2,073,600 | 4096×2160 (4K) @ 60fps | 240,000 kbps | 240,000 kbps |

- 分辨率与码率对照表：https://www.lighterra.com/papers/videoencodingh264/

3. 设置系统服务
```
cp x5_stream.service /etc/systemd/system/
systemctl daemon-reload
systemctl status x5_stream.service
```