previous next

Chapter 17: RealText Broadcast

The RealText broadcast feature lets you stream live broadcasts of RealText over a network. You can use it, for example, to broadcast a live stock ticker feed. To set up a text broadcast, you create a broadcast application that adds RealText mark-up to a text feed. You then integrate the broadcast application with the RealText Broadcast Library through a single system interface. That library takes care of the overhead of integrating with the standard RealSystem Remote Broadcast Library and a RealSystem broadcast plug-in, which manages the connection to RealServer.

Additional Information
For information on RealText mark-up, see RealText Authoring Guide, available in HTML or PDF format from http://service.real.com/help/library/index.html. The bundled HTML download of this manual contains a compiled application that you can use to broadcast RealText. You need to build a new application with this SDK only if that application does not fit your needs.

RealText Broadcast

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

RealText Broadcast Components
Component On Windows On UNIX
RealText Broadcast Library rtli3260.dll rtlive.so.6.0
Remote Broadcast Library encn3260.dll encnet.so.6.0
Broadcast Plug-In
(short name: pn-encoder)
enco3260.dll encoplin.so.0.1

Suppose that the live broadcast has the following URL:


rtsp://www.real.com/encoder/ticker 

When the broadcast begins, the broadcast application connects to the RealText Broadcast Library, passing it the name of the live broadcast "file" (ticker), 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 (/encoder/). RealServer's FSMount configuration parameter ties the mount point to a specific broadcast plug-in.

Additional Information
See "FSMount Parameter".

Interfaces

The RealText broadcast application uses the following interface:

Coding the Remote Text Broadcast Application

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

Initializing the RealText Broadcast Library

When a RealText broadcast application starts up, it performs these actions:

  1. The application loads the RealText Broadcast Library and the Remote Broadcast Library listed in the table "RealText Broadcast Components".

  2. The application gets the RealText library's CreateLiveText process address, as shown in this extract from the sample file:
    
    m_fpCreateLiveText = (FPRMCREATELIVETEXT) GetProcAddress(hDllRtlive,
    "CreateLiveText");

  3. The application uses the CreateLiveText function to create a live text encoding object:
    
    if(PNR_OK == m_fpCreateLiveText((IRMALiveText**) &pLiveTextEncoder))
    

  4. The application uses IRMALiveText::InitLiveText to pass the live text object the following parameters.

    Live Text 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.
    Username Name the application uses to connect to the broadcast plug-in. It should be encoder if a password is used.
    Password Password the application uses to connect to the broadcast plug-in. The plug-in's FSMount setting defines this.
    Filename The "file name" that follows the broadcast plug-in's mount point in the URL. For example, in rtsp://www.real.com/encoder/ticker, the broadcast plug-in has a mount point of /encoder/ and the file name is ticker.

  5. The application calls IRMALiveText::EncoderIsInitialized, which returns a Boolean value, to determine if the library is initialized and ready to receive text.

Defining the RealText Window

Before sending data, the broadcast application can define RealText <window> tag properties. Because this tag is typically not included in a live broadcast, the application calls the following IRMALiveText methods to set the properties. If the application does not use one of these methods, the property's default value is used:

Sending Text to the Library

After initializing the RealText Broadcast Library, the broadcast application passes text to the library, which then creates the RealSystem packets transmitted by the broadcast plug-in. The broadcast application uses the following IRMALiveText methods to pass the text:

Communicating with the Library

The IRMALiveText interface does not have a corresponding response interface that the broadcast application implements to receive feedback from the RealText Broadcast Library. The application can call the following methods, however, to determine the library's status:

Modifying the RealText Broadcast Sample Code

Interfaces to the RealText Broadcast Library are defined in rmalvtxt.h. Sample code for streaming text that uses the library is provided in:

The sample code includes a simple command-line interface for gathering the required initialization parameters. Both main.cpp and main2.cpp contain comments telling you how to modify the applications, including where text is added to the stream. The comments in rmalvtxt.h tell how to alter the stream's window attributes, such as background color, height, and width.

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

  1. Install the broadcast libraries in a directory on your PATH (LD_LIBRARY_PATH for UNIX). These libraries are listed in the table "RealText Broadcast Components".

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

  3. Provide a way for your application to get the required initialization parameters, then initialize the broadcast library. For example:
    
    pLiveTextEncoder-InitLiveText(szHost, atoi(szPort), szUsername, szPassword, szFilename);
    

  4. Write the application-specific processing code. Be sure to call IRMALiveText::Process frequently to allow the library to perform its necessary processing.

  5. Compile your application. The application does not need to link to the broadcast libraries as long as it calls LoadLibrary as shown in main.cpp.

    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 the RealServer 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 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 ticker (the syntax may differ for your application):

    
    % exlvtext rmaserver.site.com 7072 <user name> <password> ticker
    

  4. Debug receiving a live text 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
    

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

    
    rtsp://rmaserver.site.com/encoder/ticker
    

    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:23.
previous next