modify: 说明文档

README.md

@@ -0,0 +1,79 @@
+# 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 依赖）

test/test_manager.py

@@ -1,7 +1,7 @@
 import asyncio
 from chongming_stream_manager import StreamManager
 
-stream_manager = StreamManager("rtsp://172.21.110.223:8554/")
+stream_manager = StreamManager("rtsp://127.0.0.1:8554/")
 
 async def main():
     await stream_manager.start_stream(