Overview of live555 Stream Source Creation

When developing with the live555 library for RTSP streaming, two essential virtual functions must be implemented: createNewStreamSource and doGetNextFrame. These are typically implemented in two separate classes: a media session class and a frame source class. For H264 video streaming, these might be named H264LiveVideoServerMediaSubsession and H264LiveFrameSource respectively.

The H264LiveVideoServerMediaSubsession class handles the media session and implements the createNewStreamSource function, while the H264LiveFrameSource class manages the video frame resources and implements the doGetNextFrame function. This article focuses on the implementation and purpose of the createNewStreamSource function.

Class Inheritance Hierarchy

Before diving into the implementation, it's important to understand the inheritance hierarchy for the media session class:

H264LiveVideoServerMediaSubsession : OnDemandServerMediaSubsession : ServerMediaSubsession : Medium

This hierarchy shows that our custom class inherits from OnDemandServerMediaSubsession, which provides the foundation for on-demand media srteaming.

The createNewStreamSource Function

The createNewStreamSource function is declared as a pure virtual function in the OnDemandServerMediaSubsession class:

virtual FramedSource* createNewStreamSource(unsigned clientSessionId,
                unsigned& estBitrate) = 0;

This function serves as a factory method for creating the media source object that will provide the video frames. It must be implemented by any concrete subclass, such as our H264LiveVideoServerMediaSubsession.

Implementation Example

Here's a basic implementation of the createNewStreamSource function:

FramedSource* H264LiveVideoServerMediaSubsession::createNewStreamSource(unsigned clientSessionId, unsigned& estBitrate)
{
    // Set the estimated bitrate
    estBitrate = 1000; // kbps, estimate

    // Create the video source
    H264LiveFrameSource* videoSource = H264LiveFrameSource::createNew(envir(), buffer_size, data_buffer, send_flag);
    if (videoSource == NULL) {
        return NULL;
    }

    // Create and return a framer for the H264 video stream
    return H264VideoStreamFramer::createNew(envir(), videoSource);
}

This implementation performs two main tasks:

1. Creates an instance of H264LiveFrameSource, which contains the doGetNextFrame implementation for retrieving video frames.
2. Wraps this source in an H264VideoStreamFramer and returns it. The framer will use our video source as its input, storing it in its fInputSource member variable.

When createNewStreamSource is Called

The createNewStreamSource function is invoked during the RTSP SETUP phase. When a client sends a SETUP request, the server processes it through the following call chain:

1. RTSPServer::RTSPClientConnection::handleRequestBytes - Handles incoming RTSP requests
2. handleCmd_SETUP - Processes the SETUP command specifically
3. OnDemandServerMediaSubsession::getStreamParameters - Sets up stream parameters

Within the getStreamParameters function, our implementation of createNewStreamSource is called:

void OnDemandServerMediaSubsession::getStreamParameters(unsigned clientSessionId,
                                                      struct sockaddr_storage const &clientAddress,
                                                      Port const &clientRTPPort,
                                                      Port const &clientRTCPort,
                                                      int tcpSocketNum,
                                                      unsigned char rtpChannelId,
                                                      unsigned char rtcpChannelId,
                                                      TLSState *tlsState,
                                                      struct sockaddr_storage &destinationAddress,
                                                      u_int8_t &destinationTTL,
                                                      Boolean &isMulticast,
                                                      Port &serverRTPPort,
                                                      Port &serverRTCPPort,
                                                      void *&streamToken)
{
    // ... parameter setup code ...
    
    // Create a new media source:
    unsigned streamBitrate;
    FramedSource *mediaSource = createNewStreamSource(clientSessionId, streamBitrate);
    
    // ... additional setup code ...
}

The returned mediaSource is then used to call doGetNextFrame when video frames are needed for streaming to the client.

The createNewStreamSource function essentially tells the RTSP server how to access video frame data by providing a properly configured source object. The actual frame retrieval happens through the doGetNextFrame function implemented in the source class.