Scripting Utility Sample

One of the features of Microsoft NetShow Advanced Streaming format (ASF) is the ability to embed script commands into the stream. The embedded script commands are two Unicode strings associated with a designated time in the stream. One string specifies the type of command, and the other string contains the actual command. When the stream reaches the time associated with the command, the NetShow Player control issues an event that can be captured and processed by an event handling routine.

Both of the command strings are passed as parameters to the event handler. The type parameter is used to determine how the command parameter should be processed, and the command parameter specifies the action to be performed. For example, commands to launch URLs can be embedded into ASF streams. The type parameter for these commands is URL and the command parameter would contain the URL to be launched by the browser.

The Player control automatically handles the following types of embedded script commands;

• URL - The specified URL is launched in the default browser.
• FILENAME - The Player control opens the file specified and plays the stream.

Any type of command can be embedded into an ASF stream, and reciprocal code can be written for the client application to handle the command. Unknown types of commands are ignored by the Player control; however, they are still handed off to the event handling routine for processing.

The Encoder provides a Commands dialog box for embedding script commands into the ASF streams it is producing. Script commands entered into the Commands dialog box are dropped into the stream to be executed by the client application.

The Encoder Commands dialog box does have limitations. Once a command is sent, it is not retained in the Commands dialog box, requiring users to retype the command before it can be sent again. Another drawback is that it can not import commands stored in a script file.

About the Scripting Utility Sample

The scripting utility sample demonstrates how to design a Microsoft Visual Basic utility by using the methods and properties exposed through Automation for embedding script commands. It provides an easy–to-use interface for embedding commands into an ASF stream. The utility provides the following features, which extend the functionality of the standard interface:

• Importing a text file containing script commands. The imported commands are displayed in a hierarchical list.
• Sorting the list of script commands.
• Copying a command from the list into the Commands dialog box by clicking the command. The command can then be edited in the Commands dialog box before it is sent.
• Keeping a list of the most recently used (MRU) commands for future use.

The utility also incorporates the following features of the Encoder:

• The ability to import an .asd file.
• The ability to start and stop the Encoder.
• A display for viewing the properties of the Encoder while it is running.

Sample Components

The sample components are installed by clicking the link specified below. The following components are downloaded when the sample is installed:

• The ASF Real-Time Scripting Utility Sample (RTEScript.exe).
• Sample Web pages for viewing the results, (RTESample.htm, Frame1.htm, and Frame2.htm).
• The Visual Basic source code used to build the utility.
• A sample script file (Sample.txt).

Requirements

The sample uses an .asd file containing the settings needed by the Encoder. Currently there is no programmatic way to create an .asd file. Use the Encoder to perform this task. For more information about creating an .asd file to specify the settings, see the Encoder documentation. The .asd file must specify the following settings:

• The input must be from a live source. This utility will not work with input from .avi or .wav files.
• The option "Enable Script Commands" must be enabled.
• The output destination can not be a local .asf file.

To Use the Utility

The steps outlined below demonstrate how to use the utility:

1. Open the .asd file by clicking the icon on the toolbar or selecting the Open ASD File option from the drop-down File menu. For the utility to work correctly, the .asd file must meet the requirements listed above.
   
   
2. Open the script command file by clicking the icon on the toolbar or selecting the Open Script File option from the drop-down File menu. The syntax for creating script command files is outlined in the “Creating a Sample Script File” section. The commands imported from the file are displayed by a listview control.
   
   
3. Start the Encoder by clicking the Start Encoding button.
   
   
4. Select a command to be sent by clicking the command displayed in the listview control. The command should appear in the Current Command dialog box. Alternatively, commands may be typed directly into this dialog box. Commands can be altered once they are in the dialog box.
   
   
5. When the command appears correctly in the Current Command dialog box, click the Send button. A message is displayed to indicate that the command has been sent. The Current Command dialog box is cleared, and the command that was just sent is added to the 10 most recently used commands.

   No error codes are returned when the script command is sent. The best way to determine if the command was received and processed successfully is by observing the results on a NetShow Player connected to the Encoder. The Web page included with this sample is ideal for testing the output generated from the Encoder. Instructions for using the Web page are outlined below.

6. To view properties of the Encoder while it is running, select the View ASD File Properties option from the drop down File menu.

Creating a Sample Script File

Any text editor can be used to create a script file used by the scripting utility. The following list outlines the format of a script file:

• Only one command or comment is allowed per line. A carriage return indicates a new line.
• The format for a command line is the command type followed by a comma, followed by the command. In addition to the URL and FILE command types that are automatically processed by the Player control, the Web page included with this sample also processes CAPTION and TEXT command types. There are no restrictions on the types of commands that can be sent; however, only URL, FILE, CAPTION, and TEXT will be processed by the sample Web page. Instructions for using the Web page are outlined in the “Viewing Output on the Sample Web Page” section. See the Sample.txt file included with this sample for examples of command lines.
• Comments are denoted by a semicolon (;) in the first column of the line. See the Sample.txt file included with this sample for examples of comment lines.
• To specify a destination frame for URL commands, append two ampersands (&&) and the name of the frame to the end of the command.

Viewing Output on the Sample Web Page

The Web page included with the sample uses two frames. One frame (Frame1.htm) contains the embedded player and the other (Frame2.htm) is available for launching URL commands received from the scripting utility. Launching URLs in Frame2 allows the player to continue rendering the stream from the Encoder in Frame 1.

While it is possible to run the sample utility and the Web page on the same computer, running the Encoder and the scripting utility on one computer and the sample Web page on another computer is recommended.

The following list outlines the steps for using the Web page:

1. Start the Encoder Scripting Utility.
   
   
2. From the utility, open the .asd file and start the Encoder.
   
   
3. Launch the sample Web page from a browser.
   
   
4. Connect the Web page to the ASF Encoder.
   
   
5. Send script commands from the utility and view the results on the Web page.

Troubleshooting

The status bar at the bottom of the sample utility displays whether or not the .asd file is loaded and whether or not encoding has started.

The Start Encoding option remains disabled until a valid .asd file is loaded.

The Send Command button remains disabled until the encoding process starts successfully.

If the Encoder can not be started from the utility ,or script commands are not being processed as expected on the sample Web page, try the following steps:

1. Stop the Encoder from the scripting utility.
   
   
2. Start the Encoder and open the .asd file that was loaded by the scripting utility.
   
   
3. Try using the Encoder to send script commands.
   
   
4. If the problems persist, check the configuration settings.
   
   
5. Use the Encoder's online Help to troubleshoot the problem and correct the settings.

Installing the Sample

You can download this sample by linking to http://www.microsoft.com/netshow/download/rtescript.exe.

These examples illustrate how to use HTML and the Visual Basic Scripting Edition, with attributes exposed by Microsoft NetShow. They may not be fully functional within the Platform SDK framework. To download the complete suite of NetShow products, which includes working samples, visit the NetShow web site (http://www.microsoft.com/NetShow)