# `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】

```cpp
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】

```cpp
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】

```cpp
// 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】

```cpp
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】

```cpp
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】

```cpp
KdRtspServer();
```

【Parameters】

None.

【Return Value】

None.

【Example】

```cpp
KdRtspServer rtsp_server;
```

### KdRtspServer::~KdRtspServer

【Description】

Destructor for KdRtspServer, which destroys the RTSP server instance.

【Definition】

```cpp
~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】

```cpp
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】

```cpp
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】

```cpp
void DeInit();
```

【Parameters】

None.

【Return Value】

None.

【Example】

```cpp
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】

```cpp
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】

```cpp
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】

```cpp
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】

```cpp
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】

```cpp
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】

```cpp
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】

```cpp
void Start();
```

【Parameters】

None.

【Return Value】

None.

【Example】

```cpp
rtsp_server.Start();
```

### KdRtspServer::Stop

【Description】

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

【Definition】

```cpp
void Stop();
```

【Parameters】

None.

【Return Value】

None.

【Example】

```cpp
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】

```cpp
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】

```cpp
// 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】

```cpp
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】

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

## Example

```cpp
#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.