# StreamSight

**Repository Path**: rubio/stream-insight

## Basic Information

- **Project Name**: StreamSight
- **Description**: StreamSight：专注于实时数据流处理与分析的开源项目，提供高效、灵活的解决方案，支持多种数据源和应用场景。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-22
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StreamPlayerDemo（stream-insight）

基于 **Kotlin + Jetpack Compose + Media3（ExoPlayer）** 的 Android 流媒体播放与物联网演示工程：支持 **RTMP / RTSP / HLS**、**断流自动重连**、**多档缓冲/延迟策略**、可选 **MQTT 上报** 与 **端侧视觉检测（TFLite）**。

## 仓库地址（Gitee）

| 方式 | 地址 |
|------|------|
| **HTTPS** | `https://gitee.com/rubio/stream-insight.git` |
| **SSH** | `git@gitee.com:rubio/stream-insight.git` |

```bash
git clone https://gitee.com/rubio/stream-insight.git
cd stream-insight
```

> 若你 fork 到自己的 Gitee 账号，请将上面地址替换为你的仓库 URL。

## 项目简介

- **单 Activity + Compose**，播放器通过 `AndroidView` 嵌入 `PlayerView`。
- 播放核心封装在 **`features/player`**（`StreamPlayerEngine`、`StreamPlayerConfig`、`LatencyProfile` 等），便于复用。
- 工程按 **common / features / products** 分层（见 `settings.gradle`）。
- **Media3**（`media3-exoplayer`），RTSP 等能力见各模块 `build.gradle`。

## 模块一览

| 路径 | 说明 |
|------|------|
| `products/streamplayer-demo` | 可安装 Demo 应用（`applicationId`: `com.example.streamplayerdemo`） |
| `features/player` | 播放引擎、重连策略、缓冲档位、遥测 |
| `features/mqtt` | HiveMQ MQTT 5 客户端封装（`MqttClientManager`、可选 `DeviceMqttBusiness`） |
| `features/vision` | TFLite 检测（EfficientDet Lite / SSD MobileNet 等），枚举 [`VisionObjectDetectionModel`](features/vision/src/main/java/com/example/visioncore/VisionObjectDetectionModel.kt)；模块构建脚本为 [`build.gradle.kts`](features/vision/build.gradle.kts)；Demo 在 **启用「RTSP 视觉识别」** 后显示模型切换；`downloadVisionModels` 可拉取除 Lite0 外的官方模型（亦可将 `.tflite` 放入 `src/main/assets`） |
| `features/device` / `features/ui` | 设备与 UI 组件 |
| `common/*` | 存储、遥测、内存遥测等基础库 |

## 核心功能

### 播放与协议

- 支持 **`rtmp://`**、**`rtsp://`**、**`http(s)://…m3u8`**（HLS）等常见直播/点播地址。
- 播放控制：播放/暂停、进度条、全屏。
- 状态：**加载 / 缓冲 / 重连中 / 播放 / 暂停 / 错误 / 结束**。

### 重连与恢复

- **`ReconnectPolicy`**：最大次数、指数退避、抖动，避免多路同时重连打满服务端。
- **`onPlayerError`**：可配置自动重连；与 **`reconnectOnStreamEnded`**（推流停后 `ENDED`）**共用同一套策略与重试计数**。
- **`bufferingStallTimeoutMs`**：长时间停在 **BUFFERING** 且**无 Error**（弱网卡死）时，超时后主动重拉；与上两者仍共用计数（见 `StreamPlayerConfig` 注释）。

### 低延迟与缓冲档位

- **`LatencyProfile`**：多档（如弱网厂区、低延迟、均衡、稳定、高平滑），通过 **`DefaultLoadControl`** 及流媒体专用参数调节缓冲窗口。
- Demo 默认 **`LOW_LATENCY`**，可在界面选择档位并 **「应用重连与缓冲档位」** 生效。

### MQTT（可选）

- 连接 Mosquitto 等 Broker，支持订阅/发布；识别开启时可向 `devices/<deviceId>/detections` 上报 JSON。
- 局域网联调说明：**[docs/mqtt-mosquitto-windows-zh.md](docs/mqtt-mosquitto-windows-zh.md)**；Broker 示例配置见 **[docs/mosquitto.streamplayer.conf](docs/mosquitto.streamplayer.conf)**，启动脚本见 **`scripts/windows/start-mosquitto-streamplayer.ps1`**；**手机浏览器**打开 **[docs/mqtt-detections-viewer.html](docs/mqtt-detections-viewer.html)** 前需**先启动**静态服务：**`scripts/windows/start-mqtt-viewer-server.cmd`**（或 **`serve-mqtt-viewer.ps1`**），并以管理员运行 **`open-firewall-mosquitto.ps1`** 放行 **8000**（详见该文档 §6、§6.3）。网页可向 **`devices/<clientId>/commands/vision_model`** 切换四款 TFLite 模型，向 **`devices/<clientId>/commands/vision_enable`** 下发 **`{"enabled":true|false}`** 控制「启用 RTSP 视觉识别」开关，与播放页联动。

### 视觉检测（可选）

- 从播放画面采样帧跑检测；**播放页「识别模型」** 可在 **EfficientDet-Lite0 / SSD MobileNet V1 / EfficientDet-Lite1 / Lite2** 间切换（对应 `VisionObjectDetectionModel`）。
- **首次构建**：`features:vision` 的 `preBuild` 会执行 **`downloadVisionModels`**，从 TensorFlow 官方地址下载缺失的 `.tflite`（需联网）；亦可手动执行 `./gradlew :features:vision:downloadVisionModels`。
- 模型说明与许可证见 **`features/vision/src/main/assets/README_MODEL.md`**。
- 与 MQTT、播放同屏相关的规划见：**[docs/rtsp-vision-mqtt-plan-zh.md](docs/rtsp-vision-mqtt-plan-zh.md)**。

### Bugly（可选）

- 在 [Bugly 控制台](https://bugly.qq.com) 创建应用（包名与 `applicationId` 一致）后，在根目录 **`gradle.properties`** 或 **`local.properties`** 配置 **`BUGLY_APP_ID`**；**Sync 后 Clean/Rebuild** 再安装。
- 拉流重连上报走 **`CrashReport.postCatchedException`**，请在控制台 **「异常上报」→「捕获异常」** 等入口查看（非「崩溃」Tab）；类名含 `StreamReconnectTelemetry`。

## 技术要点（简述）

- **`StreamPlayerEngine`**：按 URL 协议选择 `RtspMediaSource`、`HlsMediaSource`、`ProgressiveMediaSource`（RTMP）等；统一生命周期与状态回调。
- **硬件解码**：`DefaultRenderersFactory` + 解码回退。
- **ABR**：`DefaultTrackSelector` + `DefaultBandwidthMeter`。

## 使用说明

1. 使用 **Android Studio** 打开项目根目录，**Gradle Sync**（需 **JDK 17**，见各模块配置）。
2. 复制 **`local.properties`** 中的 **`sdk.dir`**（模板可参考仓库内说明；**勿提交含本机路径的 `local.properties`**，已在 `.gitignore` 中忽略）。
3. 连接真机或模拟器（**RTSP/RTMP 建议真机**）。
4. 运行 **`products:streamplayer-demo`**，输入流地址后 **加载并播放**。

**OBS 本机推 RTSP、手机填局域网 IP 仍 `Host unreachable` 时**：多为防火墙、AP 隔离或监听地址问题，见 **[docs/rtsp-obs-troubleshooting-zh.md](docs/rtsp-obs-troubleshooting-zh.md)**。

## 公共测试流（可能随时间失效）

- HLS：`https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8`
- RTSP：`rtsp://wowzaec2demo.streamlock.net/vod/mp4:BigBuckBunny_115k.mov`
- RTMP：`rtmp://wowzaec2demo.streamlock.net/vod/mp4:BigBuckBunny_115k.mov`

## 目录结构（节选）

```text
StreamPlayerDemo/
├── products/streamplayer-demo/     # Demo 应用
├── features/
│   ├── player/                     # 播放与重连核心
│   ├── mqtt/
│   ├── vision/
│   ├── device/
│   └── ui/
├── common/                         # core, network, storage, telemetry, memory-telemetry
├── docs/                           # RTSP/MQTT/视觉 等说明与网页/脚本
├── scripts/                        # Windows：Mosquitto、MQTT 网页静态服务等
├── build.gradle
├── settings.gradle
└── gradle.properties
```

## 构建命令

```bash
# Windows（在项目根目录）
gradlew :products:streamplayer-demo:assembleDebug

# 若已配置 Gradle Wrapper 为可执行
./gradlew :products:streamplayer-demo:assembleDebug
```

## 提交到 Gitee（维护者）

首次或更换机器时，确认远程：

```bash
git remote -v
# 应指向 gitee.com 上你的仓库，例如：
# git@gitee.com:rubio/stream-insight.git
```

推送当前分支（示例为 `main`）：

```bash
git add -A
git status
git commit -m "chore: 描述你的改动"
git push -u origin main
```

若尚未关联远程仓库，可先 **在 Gitee 新建空仓库**，再执行：

```bash
git remote add origin https://gitee.com/<用户名>/<仓库名>.git
git push -u origin main
```

---

**说明**：本 README 随功能迭代更新；具体默认值以源码中的 `StreamPlayerConfig`、`LatencyProfile`、`MainActivity` 为准。