chongming-stream-manager/README.md

# chongming-stream-manager

基于 ffmpeg + MediaMTX 的 RTSP 流代理管理器，用于将本地视频文件或 RTSP 网络流转发为 RTSP 流。

---

## 安装

```
uv pip install -e utils/stream_manager
```

前置依赖：系统需安装 ffmpeg。

---

## 使用场景

- 将本地视频文件循环推流为 RTSP 供外部消费
- 将 RTSP 网络流代理转发到 MediaMTX 统一出口
- AI Box 设备告警视频的实时流化

---

## API

### StreamManager 类

```
from chongming_stream_manager import StreamManager

manager = StreamManager(
    mediamtx_addr="rtsp://localhost:8554/",
    max_streams=16,
    video_path=""
)
```

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| mediamtx_addr | str | — | MediaMTX 服务器地址 |
| max_streams | int | 16 | 最大并发流数 |
| video_path | str | "" | 视频文件路径前缀 |

### start_stream(stream_id, source_url, duration=0, loop=-1) -> bool

启动一个转码推流任务。

```
success = await manager.start_stream(
    stream_id="camera_01",
    source_url="/path/to/video.mp4",
    duration=0,
    loop=-1
)
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| stream_id | str | 流标识，输出路径 {mediamtx_addr}{stream_id} |
| source_url | str | 源：本地文件路径或 RTSP URL |
| duration | int | 推流时长（秒），0 = 不限 |
| loop | int | 循环次数，-1 = 无限（仅本地文件模式） |

### 内部机制

- 使用 asyncio.Semaphore 限制并发流数
- 每个流对应一个 ffmpeg 子进程，通过 asyncio.create_subprocess_exec 管理
- 本地文件模式：-re -stream_loop N 按原始帧率循环读取
- RTSP 模式：-rtsp_transport tcp -reconnect 1 自动重连
- 输出统一为 -c copy -f rtsp 流复制到 MediaMTX
- 后台 asyncio.Task 监控进程生命周期，超时自动终止

---

## 依赖

- ffmpeg — 系统级依赖，需单独安装
- Python 标准库（无额外 PyPI 依赖）