# 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