previous next

Chapter 16: Remote Broadcast

RealSystem lets you stream any datatype from a live source. The remote broadcast feature ties a broadcast application into a RealSystem broadcast plug-in. This minimizes overhead on the broadcast application because the broadcast plug-in manages the connection to RealServer. As shown in the following figure, the broadcast application passes buffers of encoded data to the Remote Broadcast Library, which then connects to a RealSystem broadcast plug-in and delivers the stream to RealServer.

Remote Broadcast Library

Suppose that the live broadcast has the following URL:


rtsp://www.real.com/live/newvids 

When the broadcast begins, the broadcast application connects to the Remote Broadcast Library, passing it the name of the live broadcast "file" (newvids), as well as identifying which broadcast plug-in to use. When the first client requests the live feed, RealServer determines which broadcast plug-in to use based on the URL's mount point (/live/). RealServer's FSMount configuration parameter ties the mount point to a specific broadcast plug-in.

Additional Information
See "FSMount Parameter".

Remote Broadcast Components

The following table lists the components you use to broadcast data with RealSystem. RealSystem G2 components are included with a RealServer G2 installation.

RealSystem Remote Broadcast Components
Datatype Component On Windows On UNIX
RealAudio 3.0,
RealVideo 4.0
broadcast library RealAudio or
RealVideo Encoder
RealAudio or
RealVideo Encoder
broadcast plug-in
(short name: pn-live3)
liv33260.dll liv3pln.so.6.0
RealSystem G2 Datatypes broadcast library encn3260.dll encnet.so.6.0
broadcast plug-in
(short name: pn-encoder)
enco3260.dll encoplin.so.0.1
RealText See "Chapter 17: RealText Broadcast".
RealPix See "Chapter 18: RealPix Broadcast".

Additional Information
To broadcast RealAudio 3.0 or RealVideo 4.0, get an encoder from http://www.real.com/products/tools/ and use it to connect to the live broadcast plug-in. Documentation included with the download explains how to use the encoder. To broadcast with the encoder and plug-in, see "Broadcasting".

Note
If the remote broadcast feature does not provide all the functionality you require, you can build your own broadcast plug-in as described in "Chapter 8: Broadcast Plug-in". As well, if you want to encode directly on the RealServer machine, you may get better performance by developing a broadcast plug-in.

Interfaces

The remote broadcast application implements the following interfaces:

Coding the Remote Broadcast Application

The following sections explain how a broadcast application interacts with the Remote Broadcast Library through the RealSystem interfaces. The sample files included with this SDK illustrate many of these features. You can use these sample files as a starting point for building your own broadcast application.

Note
The order of function calls listed in the following sections provides a generalized explanation and is for illustrative purposes only. Because RealSystem is asynchronous, your application must be able to handle any call made to it while it is processing data or waiting for a response from a RealSystem object. Do not code your application so that it expects a specific sequence of events to occur as it interacts with the Remote Broadcast Library.

Initializing the Broadcast Library

When a broadcast application starts up, it creates a request object that contains information about the live feed and initializes the Remote Broadcast Library:

  1. The broadcast application calls the broadcast library's CreateContext function, which returns a pointer to the RealSystem context. From the context pointer the application obtains a pointer to IRMACommonClassFactory. The application can use this interface as necessary to create RealSystem objects.

  2. With the content pointer, the application uses IUnknown::QueryInterface to query for IRMAEncoderResponse. The application uses this response interface for all subsequent communication with the broadcast library.

  3. The application uses IRMACommonClassFactory to create an IRMARequest interface.

  4. The application calls IRMARequest::SetURL to set the "file name" for the live broadcast. This is not the full URL, but the name that follows the broadcast plug-in's mount point in the full URL. For example, in this requested broadcast URL:
    
    rtsp://www.real.com/live/newvids 
    

    the broadcast plug-in has a mount point of /live/ and the broadcast application creates an IRMARequest interface with a URL of newvids.

    Note
    The request object can also contain RFC822 request headers. These headers are currently ignored by the broadcast system.

  5. The application calls IRMAEncoderResponse::InitEncoderResponse to pass the object the following parameters.

    Remote Broadcast Library Initialization Parameters
    Parameter Defines
    Host Host name or IP address of RealServer.
    Port The server port the broadcast plug-in listens on. This plug-in's FSMount setting defines this.
    Request Pointer to the IRMARequest interface.
    Encoder Name Name the broadcast application uses to connect to the broadcast plug-in. This should be encoder if a password is used.
    Encoder Password Password the broadcast application uses to connect to the broadcast plug-in. The plug-in's FSMount setting defines this.
    Encoder Pointer Pointer to the IRMAEncoder broadcast application.

  6. The encoder response interface returns a status code through IRMAEncoder::InitEncoderResponseDone.

    Additional Information
    See "Status Codes".

Creating File and Stream Headers

After initializing the broadcast library, the broadcast application sends the library the file and stream headers for the live source:

  1. The encoder response interface calls IRMAEncoder::GetFileHeader.

  2. The broadcast application retrieves the stream count and any opaque data it needs to send its rendering plug-ins, encapsulating this information in an IRMAValues interface. For example:
    
    pHeader-SetPropertyULONG32("StreamCount", 1); 
    

  3. The broadcast application calls IRMAEncoderResponse::FileHeaderReady to pass the response interface a pointer to the values interface.

  4. The encoder response interface calls IRMAEncoder::GetStreamHeader for each stream.

  5. The broadcast application creates a separate IRMABuffer interface for each of the following:

  6. The broadcast application uses IRMAEncoderResponse::StreamHeaderReady to return to the encoder response interface a pointer to the IRMAValues interface that points to these buffers and contains the stream header data.

    Additional Information
    See "Creating Stream Headers" and "Timing and Synchronization".

Creating Stream Packets

After receiving the stream header or headers, the encoder response object requests packets for each live stream. This step is similar to packet creation in a file format plug-in.

Additional Information
See "Creating Stream Packets".

  1. The encoder response interface calls IRMAEncoder::StartPackets to start the stream of packets.

  2. The broadcast application starts sending the encoder response interface IRMAPacket interfaces that contain the opaque data passed to the renderer, as well as values for the RealSystem stream properties.

    Additional Information
    See the table "Stream Packet Properties". For the basics of packet creation, see "Using IRMAPacket to Create Stream Packets". Refer to "Using the Scheduler" for information on using the RealSystem Scheduler to receive scheduled callbacks for sending packets.

  3. The broadcast application calls IRMAEncoderResponse::Process to allow the broadcast library to perform any necessary processing. This step is required because of the asynchronous nature of RealSystem. The broadcast application should call IRMAEncoderResponse::Process after creating each packet or at regular intervals (approximately every five seconds) if it is not sending packets.

  4. The encoder response interface receives packets until it calls IRMAEncoder::StopPackets or until the stream source stops.

  5. The broadcast application calls IRMAEncoderResponse::StreamDone when it stops the stream. The broadcast library responds by passing a status code to the broadcast application through IRMAEncoderCompletion::EncoderDone. Until it receives IRMAEncoderCompletion::EncoderDone, the application should continue to call IRMAEncoderResponse::Process regularly.

    Additional Information
    See "Status Codes".

A broadcast application should generally create packets of 430 to 500 bytes for the opaque data. Staying under 500 bytes decreases the likelihood of packet fragmentation. RealNetworks also recommends that you write code that lets you quickly change the size of the packets the plug-in sends.

Simulated Live Transfer Agent (SLTA)

For replaying a pre-recorded stream as if it were live, RealSystem exposes the simulated live transfer agent (SLTA) interface. During a simulated live broadcast, viewers who watch a presentation join the event in progress; no matter when visitors connect, they all see the same thing at the same time.

RealServer comes with the G2SLTA application that can be used for most simulations. However, you can create your own customized version of this application if you need a particular play list format, a special interface, remote control, or other individual requirement. The SLTA library, shipped in the \lib subdirectory of the RealServer installation, provides the IRMASLTA interface for this purpose.

If you are creating your own simulation application using the IRMASLTA interface, keep the following design considerations in mind:

  1. The SLTA library uses the generic file format interface to read the static content files, so it can use any file format plug-in, but has currently only been tested with the RealVideo and RealAudio file format (rmffplin.so.6.0 on Unix, rmff3260.dll on Windows). SLTA does not work well with time stamp delivery or "sparse" data types. A sparse data type is one whose presentation duration is larger that its data delivery duration. For example, RealPix can send one image, with five seconds as the delivery duration, but move that image around for an hour (presentation duration).

  2. You must properly set up your application to locate plug-ins and other libraries. Your application must do this by setting the DT_Plugins and DT_Common directories, then calling the SetDLLAccessPath function in the SLTA library to pass in these paths. The sample application provided with this SDK shows how to properly set up your application.

A file format plug-in can implement some interfaces that help SLTA properly turn the contents from a static file into a live presentation (SLTA currently only supports RealAudio and RealVideo formats). These interfaces are:

The file format plug-in implements the IRMAPacketTimeOffsetHandler interface. This interface lets the file format plug-in adjust the timestamps on packets that are being sent in the live stream. Whereas a group of static files contain their own sets of timestamps for the packets in the file, SLTA expects a set of timestamps that are in logical order. This interface allows the file format plug-in to change the timestamp of the packet being sent from the static file, using a time offset. This way, the timestamp conforms with logical order required by SLTA.

The SLTA library supplied with RealServer implements the IRMAPacketTimeOffsetHandlerResponse interface. This interface returns the packet with the time offset.

The file format plug-in implements the IRMALiveFileFormatInfo interface. This interface lets the plug-in ask a few miscellaneous questions to make live streaming work better for the requested data type. For example, some data types contain packets whose playback durations are fairly long. If a player joins the live stream after one of these packets has been sent, they will be unable to make use of the data in that packet, since they joined too late to receive it. To solve this problem, the IRMALiveFileFormatInfo interface allows the file format plug-in to specify that a stream requires resends. The file format will be allowed to determine how long each packet should be resent (duration) and how often to resend it (bitrate), as well as how those resend packets are constructed. This lets a player who joins after the original packet has already been sent receive a resent "copy" of that packet at a later time and still be able to make use of some of the packets contents.

You can use the sample SLTA application as a starting point for building your own application. The sample is found in:

Modifying the Remote Broadcast Sample Code

Interfaces to the Remote Broadcast Library are defined in rmaencod.h. Sample code that uses the library is provided in these files:

The RealSystem SDK also contains sample code that demonstrates an RTP-audio remote broadcast encoder that streams live audio. This sample code could be modified to provide live audio streams from, for example, a microphone, a sound card, or a database. The exencaud.h file contains the details of the types of audio this sample supports. If you want to support a different type of audio, such as G721, G728, or some other compression types, you can use this sample as a basis from which to start. The sample code is contained in the following files:

Carry out the following steps to modify the sample code and implement remote broadcasting for your application:

  1. On Windows, install the Remote Broadcast Library in a directory on your PATH (LD_LIBRARY_PATH on UNIX). Be sure to put the static library in a directory where the link-editor can find it.

  2. Copy the sample code to a working directory. Change the file names and class names to match your application name.

  3. For the broadcast file header, specify the number of broadcast streams. For example, audio may be one stream and video a second stream:
    
    pHeader-SetPropertyULONG32("StreamCount", 2); 
    

  4. Provide a way for your application to get the required initialization parameters, then initialize the Remote Broadcast Library. For example:
    
    m_pEncoderResponse-InitEncoderResponse(m_address, m_port, pFilename, "password", (IRMAEncoder*)this); 
    

  5. Change the example MIME type to the correct values for your datatype. For example:
    
    pMimeType-Set((BYTE*)"application/x-pn-examplestream",
    strlen("application/x-pn-examplestream") + 1);

  6. Write the application-specific processing code for your datatype. The application should produce packets in a way similar to a file format plug-in.

    Note
    Be sure to call IRMAEncoderResponse::Process at least once for each packet passed to the library.

  7. Compile your application and link-edit it to the Remote Broadcast Library.

    Additional Information
    See "Compiling a Plug-In" for general build instructions.

Broadcasting

Do the following to test broadcasting with your application:

  1. Make sure the broadcast plug-in is installed in RealServer's plug-in directory.

  2. Edit RealServer's FSMount parameter to specify the broadcast plug-in's mount point, short name, port, and, optionally, password. If the parameter does not specify a password, passwords passed to the Remote Broadcast Library are ignored and any broadcast application can connect to the plug-in.

    Additional Information
    See "FSMount Parameter".

  3. Restart RealServer.

    Start the broadcast application, connecting it to the port defined in the plug-in's FSMount parameter. The following example shows how to do this from the command line for an application connecting to RealServer port 7072 and broadcasting a file named livefile (the syntax may differ for your application):

    
    % exencoder rmaserver.site.com 7072 livefile
    

  4. Debug receiving a live stream in RealPlayer. Using File>Open Location, enter the URL for receiving the live stream. The URL should be in this form:
    
    rtsp://serverhost.domain.com/mountpoint/filename 
    

    Or, for RealAudio 3.0 or RealVideo 4.0:

    
    pnm://serverhost.domain.com/mountpoint/filename 
    

    For example, with the livefile broadcast example above, the URL would be:

    
    rtsp://rmaserver.site.com/live/livefile 
    

    RealPlayer should buffer then play the broadcast. The scrollbar is disabled when RealPlayer receives live content.

  5. Debug sending multiple streams, one of which is live, to RealPlayer. Do this by creating an SMIL file that groups one live track of your datatype with another datatype.


Copyright © 2000 RealNetworks
For technical support, please contact supportsdk@real.com.
This file last updated on 05/17/00 at 12:50:22.
previous next