previous next

Chapter 8: Broadcast Plug-in

To stream your datatype from a live source, you can use RealSystem's remote broadcast feature, which ties a broadcast application into the standard RealSystem broadcast plug-in. If this feature does not provide the required functionality, however, you can build your own broadcast plug-in to stream live content to clients. Live content can come from an encoder or other digital source on a network, or else directly from digitizing hardware on the server computer.

Broadcast Plug-in

As shown in the next figure, a broadcast plug-in creates two objects used by RealServer. RealServer uses the file object to verify URL requests to the broadcast. It uses the broadcast object to get the packets. The broadcast plug-in can use Network Services to communicate with the live source over a TCP/IP network. If the live content is created locally in hardware, the plug-in communicates directly with the hardware.

Additional Information
"Chapter 14: Network Services".

File and Broadcast Objects

Note
Because it delivers packets to RealServer, the broadcast plug-in performs the functions of both a file system plug-in and a file format plug-in.

Interfaces

A broadcast plug-in typically implements the following interfaces:

Coding the Plug-In

The following sections explain how RealServer and a broadcast plug-in use the RealSystem interfaces to stream data to a client. 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 plug-in. Refer to the RealSystem SDK header files for more information on function variables and return values.

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, the plug-in must be able to handle any call made to it while it is processing data or waiting for a response from another object. Do not code the plug-in so that it expects a specific sequence of events to occur as it interacts with RealServer.

Starting Up

When RealServer starts up, it loads each broadcast plug-in:

  1. RealServer calls RMACreateInstance to create an instance of an IRMABroadcastFormatObject interface. See "Creating a Plug-In Instance" for more on this method.

  2. RealServer calls IRMAPlugin::GetPluginInfo, which returns descriptive information about the plug-in, including its copyright and "more information" URL. The bLoadMultiple attribute must be set to FALSE to ensure that all clients can connect to the same global broadcast object.

  3. RealServer calls IRMABroadcastFormatObject::GetBroadcastFormatInfo, which returns the plug-in short name, a unique string that identifies the plug-in and is used in RealServer's FSMount configuration parameter.

    Additional Information
    See "FSMount Parameter".

  4. RealServer calls IRMAFileSystemObject::GetFileSystemInfo, which also returns the plug-in short name. The plug-in can return any value for the protocol variable, which is used only when RealPlayer plays from its local file system and is ignored for broadcast plug-ins.

Initializing

When RealServer receives the first request for a live feed, it selects the broadcast plug-in based on the requested URL's mount point. The FSMount configuration parameter associates plug-ins with URL mount points. (See"File Handling Overview".) RealServer then initializes the plug-in:

  1. RealServer calls the broadcast plug-in's IRMAPlugin::InitPlugin method, passing it a pointer to the system context. The plug-in then initializes a broadcast object from the context. For example:
    
    if(!g_example_broadcast_format)
    {
    // Initialize the global object
    g_example_broadcast_format = new ExampleBroadcastFormat(pContext);

    // Set our local pointer to the context in case this instance gets
    // used for anything else
    m_pContext = pContext;
    m_pContext-AddRef();
    }

    The global broadcast object exists until the live stream terminates, whether or not any clients are connected to it.

  2. RealServer calls IRMABroadcastFormatObject::InitBroadcastFormat, passing the broadcast plug-in a pointer to the live stream URL. RealServer also sets itself up as the broadcast response object that receives notification of plug-in actions through IRMAFormatResponse.

    The plug-in should use the context pointer to store a reference to IRMACommonClassFactory for later use. It should also use the context pointer to query for IRMAScheduler if it will use the Scheduler to receive callbacks.

    Additional Information
    See "Using the Scheduler".

  3. The plug-in notifies RealServer that the initialization has completed successfully by returning the status code PNR_OK through IRMAFormatResponse::InitDone.

    Additional Information
    See "Status Codes".

  4. RealServer calls IRMAFileSystemObject::InitFileSystem. The plug-in should return the status code PNR_OK.

Each time a client requests a connection to the live stream, RealServer performs the following steps to verify the connection. These are the standard steps that RealServer uses to verify the existence of any requested file. The broadcast plug-in verifies that the "file" is an available live stream. Once the client connection is validated, the file object is destroyed and the client connects to the global broadcast object.

  1. RealServer calls IRMAFileSystemObject::CreateFile to create a file object for the live broadcast. The plug-in creates an IRMAFileObject interface, which implements these interfaces:

  2. RealServer calls IRMAFileExists::DoesExist, passing the file object a pointer to the file path. The file object uses IRMAFileExistsResponse::DoesExistDone to return TRUE if the path is for a valid broadcast "file." Otherwise it returns FALSE.

  3. RealServer calls IRMABroadcastMapper::FindBroadcastType, passing the file object a pointer to the file path to determine the broadcast format. The file object returns a status code and the broadcast plug-in short name through IRMABroadcastMapperResponse::BroadcastTypeFound.

    Additional Information
    See "Status Codes".

  4. RealServer calls IRMABroadcastFormatObject::GetFileHeader to get the source header data. The plug-in retrieves the stream count and any opaque data it needs to send its rendering plug-ins, encapsulating this information in an IRMAValues interface and calling IRMAFormatResponse::FileHeaderReady to pass RealServer a status code and a pointer to the values interface.

Creating Stream Headers

After sending RealServer the file header for the requested URL, the broadcast plug-in sends it the stream headers for each stream:

  1. RealServer calls IRMABroadcastFormatObject::GetStreamHeader.

  2. The plug-in creates an IRMABuffer interface for each of the following:

  3. The plug-in creates an IRMAValues interface that points to the buffer interfaces and that contains the standard stream header properties.

    Additional Information
    See "Creating Stream Headers". See also "Timing and Synchronization" for information on stream start times, preroll, and so on.

  4. The plug-in calls IRMAFormatResponse::StreamHeaderReady to pass RealServer a status code and a pointer to the IRMAValues stream header object. It then uses IUnknown::Release to release the buffer and values interfaces.

    Additional Information
    See "Status Codes".

  5. If ASM is used, RealServer calls the plug-in's IRMAASMSource::Subscribe method to subscribe to all rules. The broadcast plug-in therefore just sends all packets for all ASM rules to RealServer, which determines which packets to stream to which clients based on each client's rule subscription.

    Additional Information
    "Chapter 11: Adaptive Stream Management".

Creating Stream Packets

After receiving the stream header or headers, RealServer requests packets for each live stream. This step is similar to packet creation in a file format plug-in, described in "Creating Stream Packets".

  1. RealServer calls the IRMABroadcastFormatObject::StartPackets method to start the stream of packets.

  2. The broadcast object starts sending RealServer IRMAPacket objects that contain the opaque data passed to the renderer, as well as values for the RealSystem stream properties. The plug-in typically sends packets to RealServer at regular intervals, prompted to do so by the Scheduler.

    Additional Information
    See the table "Stream Packet Properties". See "Using IRMAPacket to Create Stream Packets" for the basics of packet creation. See "Using the Scheduler" for information on receiving callbacks.

  3. RealServer receives packets until it calls IRMABroadcastFormatObject::StopPackets or until the stream source stops, at which point the plug-in calls IRMAFormatResponse::StreamDone.

A broadcast plug-in 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.

Modifying the Broadcast Plug-in Sample Code

You can use the sample broadcast plug-in as a starting point for building your own plug-in:

You need to create one broadcast object for each stream being broadcast. Perform the following steps to modify the sample code:

  1. Copy the sample files.

  2. Change the file name and class names to match your broadcast format name.

  3. In exlivobj.cpp, change the plug-in description, copyright, and more information URL stored in zm_pDescription, zm_pCopyright, and zm_pMoreInfoURL.

  4. In exlivobj.cpp, change the MIME type and description of each stream in ExampleBroadcastObject::GetStreamHeader to match the type of data in the stream. The stream MIME type determines which rendering plug-in is loaded to play that stream.

  5. In exlivobj.cpp, use the IRMANetworkServices interface to open a connection to the live data source. The example code does not currently demonstrate how to use Network Services.

    Additional Information
    See "Chapter 14: Network Services".

  6. In exlivobj.cpp, read the live source information and create packets to be delivered to RealServer using ExampleBroadcastObject::StartPackets.

  7. Define the plug-in's mount point in the RealServer FSMount parameter.

    Additional Information
    See "FSMount Parameter".

  8. Compile, debug, and test your plug-in.

    Additional Information
    See "Compiling a Plug-In".


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