From 6a3ccda6263df8bec08d5d8ac1d3054fc4b7509a Mon Sep 17 00:00:00 2001 From: DaiChaoXiong Date: Tue, 2 Jun 2026 11:16:24 +0800 Subject: [PATCH] DOC: add api.md --- README.md | 12 ++++++ api.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 api.md diff --git a/README.md b/README.md index caa4481..dfe3761 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,18 @@ ffplay rtsp://localhost:5544/live/test | **RTMP** | ✅ | ✅ | ⚠️ | | **RTSP** | ✅ | ✅ | ⚠️ | +## HTTP API 接口 + +所有 HTTP 端点运行在 HTTP-FLV 服务器端口（默认 `8080`）： + +| 端点 | 方法 | 说明 | +|------|------|------| +| `/api/stats` | GET | 服务器运行统计（带宽、帧率、连接数） | +| `/api/streams` | GET | 活跃流列表（编解码器、订阅者数、GOP 缓存） | +| `/{app}/{stream}.flv` | GET | HTTP-FLV 实时拉流 | + +详细接口文档见 [api.md](api.md)。 + ## 配置 默认端口可在 `rave.conf` (TOML 格式) 中配置： diff --git a/api.md b/api.md new file mode 100644 index 0000000..c3706d4 --- /dev/null +++ b/api.md @@ -0,0 +1,124 @@ +# HTTP API 接口文档 + +所有 HTTP API 端点均运行在 HTTP-FLV 服务器端口上（默认 `8080`）。 + +响应头统一包含 `Content-Type: application/json; charset=utf-8`、`Connection: close`、`Cache-Control: no-cache`。 + +## GET /api/stats + +返回服务器运行统计信息。 + +```bash +curl http://localhost:8080/api/stats +``` + +响应示例: + +```json +{ + "uptime_secs": 120, + "streams": 2, + "bytes_in": 1048576, + "bytes_out": 524288, + "in_bitrate_kbps": 69, + "out_bitrate_kbps": 34, + "video_frames_in": 3600, + "audio_frames_in": 3600, + "video_frames_out": 7200, + "audio_frames_out": 7200, + "video_fps_in": 30, + "audio_fps_in": 30, + "video_fps_out": 60, + "audio_fps_out": 60, + "push_connections": 1, + "pull_connections": 2, + "total_push_connections": 3, + "total_pull_connections": 5 +} +``` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `uptime_secs` | u64 | 服务器运行时长（秒） | +| `streams` | usize | 当前活跃流数量 | +| `bytes_in` | u64 | 入站总字节数 | +| `bytes_out` | u64 | 出站总字节数 | +| `in_bitrate_kbps` | u64 | 入站码率（kbps），基于最近采样周期计算 | +| `out_bitrate_kbps` | u64 | 出站码率（kbps），基于最近采样周期计算 | +| `video_frames_in` | u64 | 入站视频帧总数 | +| `audio_frames_in` | u64 | 入站音频帧总数 | +| `video_frames_out` | u64 | 出站视频帧总数（所有订阅者之和） | +| `audio_frames_out` | u64 | 出站音频帧总数（所有订阅者之和） | +| `video_fps_in` | u64 | 入站视频帧率（fps），基于最近采样周期计算 | +| `audio_fps_in` | u64 | 入站音频帧率（fps），基于最近采样周期计算 | +| `video_fps_out` | u64 | 出站视频帧率（fps），基于最近采样周期计算 | +| `audio_fps_out` | u64 | 出站音频帧率（fps），基于最近采样周期计算 | +| `push_connections` | usize | 当前推流连接数 | +| `pull_connections` | usize | 当前拉流连接数 | +| `total_push_connections` | u64 | 历史累计推流连接数 | +| `total_pull_connections` | u64 | 历史累计拉流连接数 | + +## GET /api/streams + +返回当前所有活跃流的列表及其详细信息。 + +```bash +curl http://localhost:8080/api/streams +``` + +响应示例: + +```json +{ + "streams": [ + { + "path": "live/test", + "video_codec": "H264", + "audio_codec": "AAC", + "subscribers": 3, + "last_video_ts": 15000, + "last_audio_ts": 15020, + "gop_cache_size": 15, + "total_video_frames": 4500, + "total_audio_frames": 4500 + } + ] +} +``` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `path` | String | 流路径，格式为 `{app}/{stream}` | +| `video_codec` | String | 视频编解码器，取值: `"H264"`, `"H265"`, `"Unknown"` | +| `audio_codec` | String | 音频编解码器，取值: `"AAC"`, `"G711A"`, `"G711U"`, `"Opus"`, `"Unknown"` | +| `subscribers` | usize | 当前订阅者数量 | +| `last_video_ts` | u64 \| null | 最近一帧视频的时间戳（毫秒），无视频帧时为 `null` | +| `last_audio_ts` | u64 \| null | 最近一帧音频的时间戳（毫秒），无音频帧时为 `null` | +| `gop_cache_size` | usize | GOP 缓存中的帧数量 | +| `total_video_frames` | u64 | 该流累计视频帧数 | +| `total_audio_frames` | u64 | 该流累计音频帧数 | + +## GET /{app}/{stream}.flv + +HTTP-FLV 实时拉流端点。建立连接后，服务器持续推送 FLV 数据流，直到客户端断开或流结束。 + +URL 格式: `/{app}/{stream}.flv`，其中 `{app}` 为应用名，`{stream}` 为流名称。 + +```bash +# 使用 ffplay 拉流 +ffplay http://localhost:8080/live/test.flv + +# 使用 curl 下载（会持续写入直到中断） +curl http://localhost:8080/live/test.flv -o stream.flv +``` + +| 参数 | 位置 | 说明 | +|------|------|------| +| `app` | URL 路径第一段 | 应用名称，如 `live` | +| `stream` | URL 路径第二段 | 流名称，如 `test`，须以 `.flv` 结尾 | + +响应: + +- 成功: HTTP 200，`Content-Type: video/x-flv`，Body 为 FLV 头部 + 持续的 FLV tag 数据流 +- 流不存在: HTTP 404 +- 路径格式错误: HTTP 404