125 lines
4.0 KiB
Markdown
125 lines
4.0 KiB
Markdown
# 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
|