rave/api.md

HTTP API 接口文档

所有 HTTP API 端点均运行在 HTTP-FLV 服务器端口上（默认 8080）。

响应头统一包含 Content-Type: application/json; charset=utf-8、Connection: close、Cache-Control: no-cache。

GET /api/stats

返回服务器运行统计信息。

curl http://localhost:8080/api/stats

响应示例:

{
  "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

返回当前所有活跃流的列表及其详细信息。

curl http://localhost:8080/api/streams

响应示例:

{
  "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} 为流名称。

# 使用 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