diff --git a/plugin/rtsp/README.md b/plugin/rtsp/README.md new file mode 100644 index 0000000..dbca923 --- /dev/null +++ b/plugin/rtsp/README.md @@ -0,0 +1,273 @@ +# RTSP Plugin + +The RTSP plugin provides complete RTSP server and client functionality for Monibuca, enabling RTSP stream publishing, playback, and proxying. + +## Features + +- **RTSP Server**: Accept RTSP client connections for stream publishing and playback +- **RTSP Client**: Pull streams from remote RTSP sources +- **Dual Transport Modes**: Support both TCP and UDP transport protocols +- **Authentication**: Built-in username/password authentication +- **Bidirectional Proxy**: Support for both pull and push proxying +- **Standard Compliance**: Implements RTSP protocol (RFC 2326/RFC 7826) + +## Configuration + +```yaml +rtsp: + tcp: + listenaddr: :554 # RTSP server listening address + username: "" # Authentication username (optional) + password: "" # Authentication password (optional) + udpport: 20001-30000 # UDP port range for media transmission +``` + +### Configuration Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `tcp.listenaddr` | string | `:554` | RTSP server listening address and port | +| `username` | string | `""` | Authentication username (empty = no auth) | +| `password` | string | `""` | Authentication password | +| `udpport` | range | `20001-30000` | UDP port range for RTP/RTCP transmission | + +## Usage + +### Pull RTSP Stream + +Pull a remote RTSP stream into Monibuca: + +```yaml +rtsp: + pull: + camera1: + url: rtsp://admin:password@192.168.1.100/stream +``` + +Or use the unified API: +```bash +curl -X POST http://localhost:8080/api/stream/pull \ + -H "Content-Type: application/json" \ + -d '{ + "protocol": "rtsp", + "streamPath": "camera1", + "remoteURL": "rtsp://admin:password@192.168.1.100/stream" + }' +``` + +### Push Stream via RTSP + +Push a stream from Monibuca to a remote RTSP server: + +```yaml +rtsp: + push: + camera1: + target: rtsp://192.168.1.200/live/stream +``` + +### Publish Stream to Monibuca RTSP Server + +Use FFmpeg or other RTSP clients to publish streams: + +```bash +ffmpeg -re -i input.mp4 -c copy -f rtsp rtsp://localhost:554/live/stream +``` + +### Play Stream from Monibuca RTSP Server + +Use any RTSP client to play streams: + +```bash +ffplay rtsp://localhost:554/live/stream +``` + +Or with VLC, OBS, or other RTSP-compatible players. + +## Transport Modes + +### TCP Transport (Interleaved Mode) + +- More reliable, works through firewalls +- Higher latency +- Automatic fallback option + +### UDP Transport + +- Lower latency +- Better for local networks +- Requires open UDP port range +- RTP/RTCP use separate ports + +## RTSP Methods Supported + +| Method | Direction | Description | +|--------|-----------|-------------| +| OPTIONS | Both | Query supported methods | +| DESCRIBE | Pull | Get stream SDP information | +| ANNOUNCE | Push | Declare stream for publishing | +| SETUP | Both | Setup transport parameters | +| PLAY | Pull | Start playing stream | +| RECORD | Push | Start recording/publishing | +| TEARDOWN | Both | Close connection | + +## Authentication + +When username and password are configured, the server requires HTTP Basic Authentication: + +```yaml +rtsp: + username: admin + password: secret123 +``` + +Clients must provide credentials in the URL: +``` +rtsp://admin:secret123@localhost:554/live/stream +``` + +## Advanced Features + +### Pull Proxy + +Automatically pull and cache remote RTSP streams. Configure under the `global` node: + +```yaml +global: + pullproxy: + - id: 1 # Unique ID, must be > 0 + name: "camera-1" # Pull proxy name + type: "rtsp" # Protocol type + streampath: "live/camera1" # Stream path in Monibuca + pullonstart: true # Auto-pull on startup + pull: + url: "rtsp://admin:password@192.168.1.100/stream" + description: "Front door camera" + - id: 2 + name: "camera-2" + type: "rtsp" + streampath: "live/camera2" + pullonstart: false + pull: + url: "rtsp://admin:password@192.168.1.101/stream" +``` + +Or use the API to manage pull proxies dynamically (see API Endpoints section below). + +### Push Proxy + +Automatically push streams to remote RTSP servers. Configure under the `global` node: + +```yaml +global: + pushproxy: + - id: 1 # Unique ID, must be > 0 + name: "push-1" # Push proxy name + type: "rtsp" # Protocol type + streampath: "live/stream1" # Source stream path + pushonstart: true # Auto-push on startup + push: + url: "rtsp://192.168.1.200/live/stream1" + description: "Push to remote server" +``` + +Or use the API to manage push proxies dynamically (see API Endpoints section below). + +## Compatibility + +### Tested Devices/Software + +- ✅ FFmpeg +- ✅ VLC Media Player +- ✅ OBS Studio +- ✅ ONVIF-compliant devices + +### Known Issues + +See [BAD_DEVICE.md](BAD_DEVICE.md) for devices with non-standard RTSP implementations. + +## Codec Support + +The plugin transparently passes through codec information. Supported codecs depend on the source and destination: + +**Video**: H.264, H.265/HEVC, MPEG-4, MJPEG +**Audio**: AAC, G.711 (PCMA/PCMU), G.726, MP3, OPUS + +## Performance Tips + +- Use TCP transport for streams over the internet +- Use UDP transport for local network streams (lower latency) +- Adjust UDP port range based on concurrent stream count +- Enable authentication to prevent unauthorized access +- For high-concurrency scenarios, consider hardware transcoding + +## Troubleshooting + +### Connection Refused +- Check if port 554 requires root/administrator privileges +- Try a different port (e.g., 8554) +- Verify firewall settings + +### No Video/Audio +- Check codec compatibility between source and client +- Verify SDP information in logs +- Test with VLC or FFplay to isolate issues + +### UDP Packet Loss +- Increase UDP port range +- Switch to TCP transport +- Check network quality and bandwidth + +## API Endpoints + +### Pull Stream + +Use the unified pull API with `protocol` set to `rtsp`: + +```bash +POST /api/stream/pull +Content-Type: application/json + +{ + "protocol": "rtsp", + "streamPath": "camera1", + "remoteURL": "rtsp://admin:password@192.168.1.100/stream", + "pubAudio": true, + "pubVideo": true +} +``` + +**Parameters:** +- `protocol` (required): Set to `"rtsp"` +- `streamPath` (required): Local stream path in Monibuca +- `remoteURL` (required): Remote RTSP URL to pull from +- `pubAudio` (optional): Enable audio publishing +- `pubVideo` (optional): Enable video publishing +- `testMode` (optional): 0 = normal pull, 1 = pull without publishing +- Additional publish configuration options available (see GlobalPullRequest in global.proto) + +### Stop Stream + +```bash +POST /api/stream/stop/{streamPath} +``` + +### Manage Pull/Push Proxy + +- `GET /api/proxy/pull/list` - List all pull proxies +- `POST /api/proxy/pull/add` - Add a pull proxy +- `POST /api/proxy/pull/update` - Update a pull proxy +- `POST /api/proxy/pull/remove/{id}` - Remove a pull proxy +- `GET /api/proxy/push/list` - List all push proxies +- `POST /api/proxy/push/add` - Add a push proxy +- `POST /api/proxy/push/update` - Update a push proxy +- `POST /api/proxy/push/remove/{id}` - Remove a push proxy + +## Acknowledgments + +This plugin references code and implementation ideas from the excellent [go2rtc](https://github.com/AlexxIT/go2rtc) project by AlexxIT, which provides a comprehensive media server solution with advanced streaming capabilities. + +## License + +This plugin is part of the Monibuca project and follows the same license terms. + diff --git a/plugin/rtsp/README_CN.md b/plugin/rtsp/README_CN.md new file mode 100644 index 0000000..cbcccf3 --- /dev/null +++ b/plugin/rtsp/README_CN.md @@ -0,0 +1,273 @@ +# RTSP 插件 + +RTSP 插件为 Monibuca 提供完整的 RTSP 服务器和客户端功能,支持 RTSP 流的发布、播放和代理。 + +## 功能特性 + +- **RTSP 服务器**:接受 RTSP 客户端连接,支持流发布和播放 +- **RTSP 客户端**:从远程 RTSP 源拉取流 +- **双传输模式**:支持 TCP 和 UDP 两种传输协议 +- **身份认证**:内置用户名/密码认证功能 +- **双向代理**:支持拉流和推流代理 +- **标准兼容**:实现 RTSP 协议标准 (RFC 2326/RFC 7826) + +## 配置说明 + +```yaml +rtsp: + tcp: + listenaddr: :554 # RTSP 服务器监听地址 + username: "" # 认证用户名(可选) + password: "" # 认证密码(可选) + udpport: 20001-30000 # 媒体传输的 UDP 端口范围 +``` + +### 配置参数 + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `tcp.listenaddr` | string | `:554` | RTSP 服务器监听地址和端口 | +| `username` | string | `""` | 认证用户名(为空表示不启用认证)| +| `password` | string | `""` | 认证密码 | +| `udpport` | range | `20001-30000` | RTP/RTCP 传输使用的 UDP 端口范围 | + +## 使用方法 + +### 拉取 RTSP 流 + +将远程 RTSP 流拉取到 Monibuca: + +```yaml +rtsp: + pull: + camera1: + url: rtsp://admin:password@192.168.1.100/stream +``` + +或使用统一的 API: +```bash +curl -X POST http://localhost:8080/api/stream/pull \ + -H "Content-Type: application/json" \ + -d '{ + "protocol": "rtsp", + "streamPath": "camera1", + "remoteURL": "rtsp://admin:password@192.168.1.100/stream" + }' +``` + +### 通过 RTSP 推流 + +将 Monibuca 中的流推送到远程 RTSP 服务器: + +```yaml +rtsp: + push: + camera1: + target: rtsp://192.168.1.200/live/stream +``` + +### 向 Monibuca RTSP 服务器发布流 + +使用 FFmpeg 或其他 RTSP 客户端发布流: + +```bash +ffmpeg -re -i input.mp4 -c copy -f rtsp rtsp://localhost:554/live/stream +``` + +### 从 Monibuca RTSP 服务器播放流 + +使用任何 RTSP 客户端播放流: + +```bash +ffplay rtsp://localhost:554/live/stream +``` + +或使用 VLC、OBS 等任何支持 RTSP 的播放器。 + +## 传输模式 + +### TCP 传输(交织模式) + +- 更可靠,可穿透防火墙 +- 延迟较高 +- 自动回退选项 + +### UDP 传输 + +- 延迟更低 +- 适合局域网环境 +- 需要开放 UDP 端口范围 +- RTP/RTCP 使用独立端口 + +## 支持的 RTSP 方法 + +| 方法 | 方向 | 说明 | +|------|------|------| +| OPTIONS | 双向 | 查询支持的方法 | +| DESCRIBE | 拉流 | 获取流的 SDP 信息 | +| ANNOUNCE | 推流 | 声明要发布的流 | +| SETUP | 双向 | 设置传输参数 | +| PLAY | 拉流 | 开始播放流 | +| RECORD | 推流 | 开始录制/发布 | +| TEARDOWN | 双向 | 关闭连接 | + +## 身份认证 + +配置用户名和密码后,服务器将要求 HTTP 基本认证: + +```yaml +rtsp: + username: admin + password: secret123 +``` + +客户端必须在 URL 中提供凭据: +``` +rtsp://admin:secret123@localhost:554/live/stream +``` + +## 高级功能 + +### 拉流代理 + +自动拉取和缓存远程 RTSP 流。需要在 `global` 节点下配置: + +```yaml +global: + pullproxy: + - id: 1 # 唯一ID标识,必须大于0 + name: "camera-1" # 拉流代理名称 + type: "rtsp" # 拉流协议类型 + streampath: "live/camera1" # 在Monibuca中的流路径 + pullonstart: true # 是否在启动时自动拉流 + pull: + url: "rtsp://admin:password@192.168.1.100/stream" + description: "前门摄像头" + - id: 2 + name: "camera-2" + type: "rtsp" + streampath: "live/camera2" + pullonstart: false + pull: + url: "rtsp://admin:password@192.168.1.101/stream" +``` + +或使用 API 动态管理拉流代理(参见下方 API 接口部分)。 + +### 推流代理 + +自动将流推送到远程 RTSP 服务器。需要在 `global` 节点下配置: + +```yaml +global: + pushproxy: + - id: 1 # 唯一ID标识,必须大于0 + name: "push-1" # 推流代理名称 + type: "rtsp" # 推流协议类型 + streampath: "live/stream1" # 源流路径 + pushonstart: true # 是否在启动时自动推流 + push: + url: "rtsp://192.168.1.200/live/stream1" + description: "推送到远程服务器" +``` + +或使用 API 动态管理推流代理(参见下方 API 接口部分)。 + +## 兼容性 + +### 已测试设备/软件 + +- ✅ FFmpeg +- ✅ VLC Media Player +- ✅ OBS Studio +- ✅ ONVIF 兼容设备 + +### 已知问题 + +查看 [BAD_DEVICE.md](BAD_DEVICE.md) 了解非标准 RTSP 实现的设备。 + +## 编解码器支持 + +插件透明传递编解码器信息。支持的编解码器取决于源和目标: + +**视频**:H.264、H.265/HEVC、MPEG-4、MJPEG +**音频**:AAC、G.711 (PCMA/PCMU)、G.726、MP3、OPUS + +## 性能优化建议 + +- 互联网传输使用 TCP 模式 +- 局域网传输使用 UDP 模式(延迟更低) +- 根据并发流数量调整 UDP 端口范围 +- 启用身份认证防止未授权访问 +- 高并发场景考虑使用硬件转码 + +## 故障排查 + +### 连接被拒绝 +- 检查 554 端口是否需要 root/管理员权限 +- 尝试使用其他端口(如 8554) +- 检查防火墙设置 + +### 无视频/音频 +- 检查源和客户端之间的编解码器兼容性 +- 查看日志中的 SDP 信息 +- 使用 VLC 或 FFplay 测试以隔离问题 + +### UDP 丢包 +- 增加 UDP 端口范围 +- 切换到 TCP 传输 +- 检查网络质量和带宽 + +## API 接口 + +### 拉取流 + +使用统一的拉流 API,将 `protocol` 设置为 `rtsp`: + +```bash +POST /api/stream/pull +Content-Type: application/json + +{ + "protocol": "rtsp", + "streamPath": "camera1", + "remoteURL": "rtsp://admin:password@192.168.1.100/stream", + "pubAudio": true, + "pubVideo": true +} +``` + +**参数说明:** +- `protocol` (必填): 设置为 `"rtsp"` +- `streamPath` (必填): Monibuca 中的本地流路径 +- `remoteURL` (必填): 要拉取的远程 RTSP URL +- `pubAudio` (可选): 是否发布音频 +- `pubVideo` (可选): 是否发布视频 +- `testMode` (可选): 0 = 正常拉流,1 = 拉流但不发布 +- 其他发布配置选项可用(参见 global.proto 中的 GlobalPullRequest) + +### 停止流 + +```bash +POST /api/stream/stop/{streamPath} +``` + +### 管理拉流/推流代理 + +- `GET /api/proxy/pull/list` - 列出所有拉流代理 +- `POST /api/proxy/pull/add` - 添加拉流代理 +- `POST /api/proxy/pull/update` - 更新拉流代理 +- `POST /api/proxy/pull/remove/{id}` - 删除拉流代理 +- `GET /api/proxy/push/list` - 列出所有推流代理 +- `POST /api/proxy/push/add` - 添加推流代理 +- `POST /api/proxy/push/update` - 更新推流代理 +- `POST /api/proxy/push/remove/{id}` - 删除推流代理 + +## 致谢 + +本插件参考了 AlexxIT 开发的优秀项目 [go2rtc](https://github.com/AlexxIT/go2rtc) 的代码和实现思路,该项目提供了一个功能全面的媒体服务器解决方案,具有先进的流媒体处理能力。 + +## 许可证 + +本插件是 Monibuca 项目的一部分,遵循相同的许可证条款。 +