RTSP Server API 手册#
概述#
librtsp_server 提供了基于 live555 的 RTSP 服务端功能，支持将 H.264、H.265、MJPEG 视频流和 G711U 音频流通过 RTSP 协议推送给客户端播放，同时支持 G711U 音频反向通道（BackChannel），实现客户端向服务端发送音频数据。本文档提供的 API 用于在 k230 上用 C++ 编写 RTSP 推流应用，编译成可执行文件后在开发板上运行。
注意：
1、视频类型（H.264/H.265/MJPEG）在创建会话时指定，同一会话只支持一种视频类型； 2、音频编码格式固定为 G711U（PCMU）； 3、反向通道音频编码格式同样为 G711U； 4、调用
Start()前需先调用Init()和CreateSession()； 5、SendVideoData发送的视频数据应为裸码流（H.264/H.265 为 NAL 单元，MJPEG 为 JPEG 帧数据）； 6、GetRtspUrl返回的char*为动态分配内存，调用者使用完毕后必须调用free()释放，否则会造成内存泄漏。
支持的媒体类型#
类型 |
编码格式 |
备注 |
|---|---|---|
视频 |
H.264 |
|
视频 |
H.265 |
|
视频 |
MJPEG |
|
音频 |
G711U |
采样率 8000Hz，单声道 |
反向通道 |
G711U |
客户端向服务端发送音频数据 |
参数类型介绍#
VideoType#
【描述】
VideoType 用于配置视频流的编码类型。
【定义】
enum class VideoType {
kVideoTypeH264,
kVideoTypeH265,
kVideoTypeMjpeg,
kVideoTypeButt
};
【说明】
枚举值 |
描述 |
|---|---|
kVideoTypeH264 |
H.264 视频编码 |
kVideoTypeH265 |
H.265 视频编码 |
kVideoTypeMjpeg |
MJPEG 视频编码 |
kVideoTypeButt |
哨兵值，无效类型 |
SessionAttr#
【描述】
SessionAttr 用于配置 RTSP 会话的媒体属性，包括是否包含视频、音频及反向通道。
【定义】
struct SessionAttr {
bool with_video {false};
bool with_audio {false}; // G711U
bool with_audio_backchannel{false}; // G711U
VideoType video_type; // valid when with_video is true
};
【参数】
名称 |
类型 |
描述 |
|---|---|---|
with_video |
bool |
是否包含视频流，默认 false |
with_audio |
bool |
是否包含音频流（G711U），默认 false |
with_audio_backchannel |
bool |
是否包含音频反向通道（G711U），默认 false |
video_type |
VideoType |
视频编码类型，当 with_video 为 true 时有效 |
【示例】
// 创建包含 H.264 视频和 G711U 音频的会话属性
SessionAttr attr;
attr.with_video = true;
attr.video_type = VideoType::kVideoTypeH264;
attr.with_audio = true;
IOnBackChannel#
【描述】
IOnBackChannel 是音频反向通道的回调接口，当客户端通过反向通道发送音频数据时，会触发此回调。
【定义】
class IOnBackChannel {
public:
virtual ~IOnBackChannel() {}
virtual void OnBackChannelData(std::string &session_name, const uint8_t *data, size_t size, uint64_t timestamp) = 0;
};
【参数】
名称 |
类型 |
描述 |
|---|---|---|
session_name |
std::string& |
会话名称 |
data |
const uint8_t* |
接收到的音频数据指针 |
size |
size_t |
音频数据大小（字节） |
timestamp |
uint64_t |
时间戳（毫秒） |
【示例】
class MyBackChannelHandler : public IOnBackChannel {
public:
void OnBackChannelData(std::string &session_name, const uint8_t *data, size_t size, uint64_t timestamp) override {
printf("Received backchannel audio from session %s, size=%zu, ts=%llu\n",
session_name.c_str(), size, timestamp);
}
};
API 介绍#
KdRtspServer::KdRtspServer#
【描述】
KdRtspServer 的构造函数，创建 RTSP 服务端实例。
【定义】
KdRtspServer();
【参数】
无。
【返回值】
无。
【示例】
KdRtspServer rtsp_server;
KdRtspServer::~KdRtspServer#
【描述】
KdRtspServer 的析构函数，销毁 RTSP 服务端实例。
【定义】
~KdRtspServer();
【参数】
无。
【返回值】
无。
KdRtspServer::Init#
【描述】
初始化 RTSP 服务端，创建 RTSP 服务器并绑定指定端口。
【定义】
int Init(int port = 8554, IOnBackChannel *back_channel = nullptr);
【参数】
名称 |
类型 |
描述 |
|---|---|---|
port |
int |
RTSP 服务端口号，默认 8554 |
back_channel |
IOnBackChannel* |
音频反向通道回调指针，默认 nullptr |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
-1 |
失败，RTSP 服务器创建失败 |
【示例】
KdRtspServer rtsp_server;
MyBackChannelHandler handler;
int ret = rtsp_server.Init(8554, &handler);
if (ret != 0) {
printf("RTSP server init failed\n");
return -1;
}
KdRtspServer::DeInit#
【描述】
反初始化 RTSP 服务端，释放 RTSP 服务器相关资源。
【定义】
void DeInit();
【参数】
无。
【返回值】
无。
【示例】
rtsp_server.DeInit();
KdRtspServer::CreateSession#
【描述】
创建 RTSP 会话，根据 SessionAttr 配置会话的媒体类型。创建成功后可通过 GetRtspUrl 获取该会话的 RTSP 播放地址。
【定义】
int CreateSession(const std::string &session_name, const SessionAttr &session_attr);
【参数】
名称 |
类型 |
描述 |
|---|---|---|
session_name |
const std::string& |
会话名称，用于标识一个会话 |
session_attr |
const SessionAttr& |
会话属性 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功，或会话已存在 |
-1 |
失败，无子会话或不支持的视频类型 |
【示例】
SessionAttr attr;
attr.with_video = true;
attr.video_type = VideoType::kVideoTypeH264;
attr.with_audio = true;
int ret = rtsp_server.CreateSession("live", attr);
if (ret != 0) {
printf("Create session failed\n");
}
KdRtspServer::DestroySession#
【描述】
销毁指定的 RTSP 会话，释放该会话相关的资源。
【定义】
int DestroySession(const std::string &session_name);
【参数】
名称 |
类型 |
描述 |
|---|---|---|
session_name |
const std::string& |
会话名称 |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
【示例】
rtsp_server.DestroySession("live");
KdRtspServer::GetRtspUrl#
【描述】
获取指定会话的 RTSP 播放 URL。调用者需负责释放返回的字符串内存。
【定义】
char* GetRtspUrl(const std::string &session_name);
【参数】
名称 |
类型 |
描述 |
|---|---|---|
session_name |
const std::string& |
会话名称 |
【返回值】
返回值 |
描述 |
|---|---|
char* |
RTSP URL 字符串，需调用者 free 释放 |
nullptr |
会话不存在 |
【示例】
char* url = rtsp_server.GetRtspUrl("live");
if (url) {
printf("RTSP URL: %s\n", url);
free(url);
}
KdRtspServer::Start#
【描述】
启动 RTSP 服务端，开始监听客户端连接。此方法会在新线程中运行事件循环。
【定义】
void Start();
【参数】
无。
【返回值】
无。
【示例】
rtsp_server.Start();
KdRtspServer::Stop#
【描述】
停止 RTSP 服务端，关闭所有会话并停止事件循环线程。
【定义】
void Stop();
【参数】
无。
【返回值】
无。
【示例】
rtsp_server.Stop();
KdRtspServer::SendVideoData#
【描述】
向指定会话发送视频帧数据。对于 H.264/H.265，数据应为 NAL 单元；对于 MJPEG，数据应为完整的 JPEG 帧。
【定义】
int SendVideoData(const std::string &session_name, const uint8_t *data, size_t size, uint64_t timestamp);
【参数】
名称 |
类型 |
描述 |
|---|---|---|
session_name |
const std::string& |
会话名称 |
data |
const uint8_t* |
视频帧数据指针 |
size |
size_t |
视频帧数据大小（字节） |
timestamp |
uint64_t |
时间戳（微秒） |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
-1 |
失败，会话不存在 |
【示例】
// 发送 H.264 NAL 单元
rtsp_server.SendVideoData("live", nal_data, nal_size, timestamp_us);
KdRtspServer::SendAudioData#
【描述】
向指定会话发送音频帧数据，音频编码格式为 G711U。
【定义】
int SendAudioData(const std::string &session_name, const uint8_t *data, size_t size, uint64_t timestamp);
【参数】
名称 |
类型 |
描述 |
|---|---|---|
session_name |
const std::string& |
会话名称 |
data |
const uint8_t* |
音频帧数据指针 |
size |
size_t |
音频帧数据大小（字节） |
timestamp |
uint64_t |
时间戳（微秒） |
【返回值】
返回值 |
描述 |
|---|---|
0 |
成功 |
-1 |
失败，会话不存在 |
【示例】
// 发送 G711U 音频帧
rtsp_server.SendAudioData("live", audio_data, audio_size, timestamp_us);
示例#
#include "rtsp_server.h"
#include <stdio.h>
#include <string.h>
int main()
{
// 创建 RTSP 服务端
KdRtspServer rtsp_server;
// 初始化，使用默认端口 8554
int ret = rtsp_server.Init(8554);
if (ret != 0) {
printf("RTSP server init failed\n");
return -1;
}
// 创建会话，包含 H.264 视频和 G711U 音频
SessionAttr attr;
attr.with_video = true;
attr.video_type = VideoType::kVideoTypeH264;
attr.with_audio = true;
ret = rtsp_server.CreateSession("live", attr);
if (ret != 0) {
printf("Create session failed\n");
rtsp_server.DeInit();
return -1;
}
// 获取 RTSP 播放地址
char* url = rtsp_server.GetRtspUrl("live");
if (url) {
printf("Play this stream using the URL: %s\n", url);
free(url);
}
// 启动服务
rtsp_server.Start();
// 推流循环
while (running) {
// 获取视频帧数据 video_data, video_size, video_timestamp
rtsp_server.SendVideoData("live", video_data, video_size, video_timestamp);
// 获取音频帧数据 audio_data, audio_size, audio_timestamp
rtsp_server.SendAudioData("live", audio_data, audio_size, audio_timestamp);
}
// 停止服务
rtsp_server.Stop();
rtsp_server.DeInit();
return 0;
}
上述代码需要在 k230 linux sdk 环境下使用编译工具编译成 elf 可执行文件，然后拷贝到开发板运行。