Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for a specific release, use the drop-down menu on the left.

RTSP Server API Manual

Overview

librtsp_server provides RTSP server functionality based on live555, supporting the delivery of H.264, H.265, and MJPEG video streams and G711U audio streams to clients for playback via the RTSP protocol. It also supports the G711U audio back channel (BackChannel), enabling clients to send audio data to the server. The APIs documented in this document are intended for writing RTSP streaming applications in C++ on k230. After compilation into an executable file, the application runs on the development board.

Note:

1. The video type (H.264/H.265/MJPEG) is specified when creating a session. Each session supports only one video type;

2. The audio encoding format is fixed to G711U (PCMU);

3. The back-channel audio encoding format is also G711U;

4. Init() and CreateSession() must be called before calling Start();

5. The video data sent by SendVideoData should be an elementary stream (NAL units for H.264/H.265 and JPEG frame data for MJPEG);

6. The char* returned by GetRtspUrl points to dynamically allocated memory. The caller must call free() to release it after use; otherwise, a memory leak will occur.

Supported Media Types

Type	Encoding Format	Remarks
Video	H.264
Video	H.265
Video	MJPEG
Audio	G711U	Sampling rate 8000Hz, mono
BackChannel	G711U	The client sends audio data to the server

Parameter Type Introduction

VideoType

【Description】

VideoType is used to configure the encoding type of a video stream.

【Definition】

enum class VideoType {
    kVideoTypeH264,
    kVideoTypeH265,
    kVideoTypeMjpeg,
    kVideoTypeButt
};

【Notes】

Enumeration Value	Description
kVideoTypeH264	H.264 video encoding
kVideoTypeH265	H.265 video encoding
kVideoTypeMjpeg	MJPEG video encoding
kVideoTypeButt	Sentinel value, invalid type

SessionAttr

【Description】

SessionAttr is used to configure the media attributes of an RTSP session, including whether it contains video, audio, and a backchannel.

【Definition】

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
};

【Parameters】

Name	Type	Description
with_video	bool	Whether to include a video stream, false by default
with_audio	bool	Whether to include an audio stream (G711U), false by default
with_audio_backchannel	bool	Whether to include an audio backchannel (G711U), false by default
video_type	VideoType	Video encoding type, valid when with_video is true

【Example】

// Create session attributes containing H.264 video and G711U audio
SessionAttr attr;
attr.with_video = true;
attr.video_type = VideoType::kVideoTypeH264;
attr.with_audio = true;

IOnBackChannel

【Description】

IOnBackChannel is the callback interface for the audio backchannel. This callback is triggered when a client sends audio data through the backchannel.

【Definition】

class IOnBackChannel {
  public:
    virtual ~IOnBackChannel() {}
    virtual void OnBackChannelData(std::string &session_name, const uint8_t *data, size_t size, uint64_t timestamp) = 0;
};

【Parameters】

Name	Type	Description
session_name	std::string&	Session name
data	const uint8_t*	Pointer to the received audio data
size	size_t	Audio data size (bytes)
timestamp	uint64_t	Timestamp (milliseconds)

【Example】

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 Introduction

KdRtspServer::KdRtspServer

【Description】

Constructor for KdRtspServer, which creates an RTSP server instance.

【Definition】

KdRtspServer();

【Parameters】

None.

【Return Value】

None.

【Example】

KdRtspServer rtsp_server;

KdRtspServer::~KdRtspServer

【Description】

Destructor for KdRtspServer, which destroys the RTSP server instance.

【Definition】

~KdRtspServer();

【Parameters】

None.

【Return Value】

None.

KdRtspServer::Init

【Description】

Initializes the RTSP server, creates the RTSP server, and binds it to the specified port.

【Definition】

int Init(int port = 8554, IOnBackChannel *back_channel = nullptr);

【Parameters】

Name	Type	Description
port	int	RTSP service port number, defaults to 8554
back_channel	IOnBackChannel*	Audio back-channel callback pointer, defaults to nullptr

【Return Value】

Return Value	Description
0	Success
-1	Failure, failed to create the RTSP server

【Example】

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

【Description】

Deinitializes the RTSP server and releases resources related to the RTSP server.

【Definition】

void DeInit();

【Parameters】

None.

【Return Value】

None.

【Example】

rtsp_server.DeInit();

KdRtspServer::CreateSession

【Description】

Creates an RTSP session and configures the session’s media type according to SessionAttr. After successful creation, the session’s RTSP playback URL can be obtained through GetRtspUrl.

【Definition】

int CreateSession(const std::string &session_name, const SessionAttr &session_attr);

【Parameters】

Name	Type	Description
session_name	const std::string&	Session name used to identify a session
session_attr	const SessionAttr&	Session attributes

【Return Value】

Return Value	Description
0	Success, or the session already exists
-1	Failure, no child session or unsupported video type

【Example】

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

【Description】

Destroys the specified RTSP session and releases resources related to the session.

【Definition】

int DestroySession(const std::string &session_name);

【Parameters】

Name	Type	Description
session_name	const std::string&	Session name

【Return Value】

Return Value	Description
0	Success

【Example】

rtsp_server.DestroySession("live");

KdRtspServer::GetRtspUrl

【Description】

Obtains the RTSP playback URL of the specified session. The caller is responsible for freeing the memory of the returned string.

【Definition】

char* GetRtspUrl(const std::string &session_name);

【Parameters】

Name	Type	Description
session_name	const std::string&	Session name

【Return Value】

Return Value	Description
char*	RTSP URL string, which the caller must free
nullptr	The session does not exist

【Example】

char* url = rtsp_server.GetRtspUrl("live");
if (url) {
    printf("RTSP URL: %s\n", url);
    free(url);
}

KdRtspServer::Start

【Description】

Starts the RTSP server and begins listening for client connections. This method runs the event loop in a new thread.

【Definition】

void Start();

【Parameters】

None.

【Return Value】

None.

【Example】

rtsp_server.Start();

KdRtspServer::Stop

【Description】

Stops the RTSP server, closes all sessions, and stops the event loop thread.

【Definition】

void Stop();

【Parameters】

None.

【Return Value】

None.

【Example】

rtsp_server.Stop();

KdRtspServer::SendVideoData

【Description】

Sends video frame data to the specified session. For H.264/H.265, the data should be NAL units; for MJPEG, the data should be complete JPEG frames.

【Definition】

int SendVideoData(const std::string &session_name, const uint8_t *data, size_t size, uint64_t timestamp);

【Parameters】

Name	Type	Description
session_name	const std::string&	Session name
data	const uint8_t*	Video frame data pointer
size	size_t	Video frame data size (bytes)
timestamp	uint64_t	Timestamp (microseconds)

【Return Value】

Return Value	Description
0	Success
-1	Failure, the session does not exist

【Example】

// Send H.264 NAL unit
rtsp_server.SendVideoData("live", nal_data, nal_size, timestamp_us);

KdRtspServer::SendAudioData

【Description】

Sends audio frame data to the specified session. The audio encoding format is G711U.

【Definition】

int SendAudioData(const std::string &session_name, const uint8_t *data, size_t size, uint64_t timestamp);

【Parameters】

Name	Type	Description
session_name	const std::string&	Session name
data	const uint8_t*	Audio frame data pointer
size	size_t	Audio frame data size (bytes)
timestamp	uint64_t	Timestamp (microseconds)

【Return Value】

Return Value	Description
0	Success
-1	Failure, the session does not exist

【Example】

// Send G711U audio frame
rtsp_server.SendAudioData("live", audio_data, audio_size, timestamp_us);

Example

#include "rtsp_server.h"
#include <stdio.h>
#include <string.h>

int main()
{
    // Create an RTSP server
    KdRtspServer rtsp_server;

    // Initialize using the default port 8554
    int ret = rtsp_server.Init(8554);
    if (ret != 0) {
        printf("RTSP server init failed\n");
        return -1;
    }

    // Create a session containing H.264 video and G711U audio
    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;
    }

    // Get the RTSP playback URL
    char* url = rtsp_server.GetRtspUrl("live");
    if (url) {
        printf("Play this stream using the URL: %s\n", url);
        free(url);
    }

    // Start the service
    rtsp_server.Start();

    // Streaming loop
    while (running) {
        // Get video frame data video_data, video_size, video_timestamp
        rtsp_server.SendVideoData("live", video_data, video_size, video_timestamp);

        // Get audio frame data audio_data, audio_size, audio_timestamp
        rtsp_server.SendAudioData("live", audio_data, audio_size, audio_timestamp);
    }

    // Stop the service
    rtsp_server.Stop();
    rtsp_server.DeInit();

    return 0;
}

The above code needs to be compiled into an elf executable using the compilation tools in the k230 linux sdk environment, and then copied to the development board for execution.