Scripting Utility Sample

With Advanced Streaming Format (ASF), you can 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 Windows Media Player control issues an event that can be captured and processed by an event-handling routine.

Note   These samples are not fully functional unless Windows Media Services is installed. To download the complete suite of Windows Media Services, see the Windows Media Technologies page at the Microsoft Web site.

Both command strings are passed as parameters to the event handler. The type parameter is used to determine how the command parameter must be processed, and the command parameter specifies the action to be performed. For example, commands to launch Uniform Resource Locators (URLs) can be embedded into ASF streams. The type parameter for these commands is URL, and the command parameter contains the URL to be launched by the browser.

The Windows Media Player control automatically handles the following types of embedded script commands:

• URL. The specified URL is launched in the default browser.
  
  
• FILENAME. The Windows Media Player control opens the specified content file, and renders the presentation.
  
  
• Text. Microsoft® Windows Media™ Player displays the given text string in the closed-captioning window.
  
  
• Event. A jump to the named <EVENT> tag in the current show (.asx file) is specified. The <EVENT> tag generally specifies a portion of media content (clip) to be rendered by Windows Media Player.
  
  
• OpenEvent. Windows Media Player is notified of an upcoming Event-type script command. An OpenEvent script command notifies Windows Media Player to prepare for the new clip specified by the <EVENT> tag. Consequently, when the Event-type command is received, stream-switching in near real-time can be achieved.

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 Windows Media Player control; however, they are still handed off to the event-handling routine for processing.

Windows Media Encoder provides a Commands dialog box for embedding script commands into the ASF streams that it is producing. Script commands entered in the Commands dialog box are dropped into the stream, and executed by the client application.

The Commands dialog box does have limitations. Once a command is sent, it is not retained in the Commands dialog box, so users must retype the command to send it again. Another drawback is that commands stored in a script file cannot be imported into this dialog box.

The following topics are covered below:

• About the Scripting Utility Sample
  
  
• Sample Components
  
  
• Sample Requirements
  
  
• Using the Utility
  
  
• Creating a Sample Script File
  
  
• Viewing Output on the Sample Web Page
  
  
• Troubleshooting
  
  
• Location of the Sample

About the Scripting Utility Sample

The scripting utility sample demonstrates how to design a 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 and enable you to:

• Import a text file containing script commands. The imported commands are displayed in a hierarchical list.
  
  
• Sort the list of script commands.
  
  
• Copy a command from the list into the Commands dialog box by clicking the command. Before the command is sent, it can then be edited in the Commands dialog box.
  
  
• Keep a list of the most recently used (MRU) commands for future use.

The utility also incorporates the following features of Windows Media Encoder:

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

Sample Components

The sample components are installed by clicking one of the following links. The following components are downloaded when the sample is installed:

• The ASF Windows Media Encoder Scripting Utility Sample (WMEScript.exe).
  
  
• The Visual Basic source code used to build the utility.
  
  
• A sample script file (Sample.txt).

Sample Requirements

The sample uses an .asd file containing the settings used by Windows Media 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 Microsoft® Windows Media™ Tools documentation. The .asd file must specify the following settings:

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

Using the Utility

The following steps demonstrate how to use the utility.

1. Open the .asd file by clicking the icon on the toolbar or Open ASD File on the File menu. For the utility to work correctly, the .asd file must meet the preceding list of requirements.
   
   
2. Open the script command file by clicking the icon on the toolbar or Open Script File on the File menu. The syntax for creating script command files is outlined in Creating a Sample Script File. The commands imported from the file are displayed by a listview control.
   
   
3. Start the encoder by clicking Start Encoding.
   
   
4. Enter a command to be sent in the listview control or in the Current Command box. Commands can be altered after they are entered in the dialog box.
   
   
5. When the command appears correctly in the Current Command box, click Send. A message appears that indicates that the command has been sent. The Current Command box is cleared, and the command that was sent is added to the list of the 10 most recently used commands.

   No error codes are returned when the script command is sent. To determine if the command was received and processed successfully, review the results on an instance of Windows Media Player connected to Windows Media Encoder. The Web page included with this sample is ideal for testing the output generated by the encoder. For instructions on using the Web page, see Viewing Output on the Sample Web Page.

6. To view properties of Windows Media Encoder while it is running, click View ASD File Properties on the File menu.

Creating a Sample Script File

Any text editor can be used to create a script file for 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, and then by the command. In addition to the URL and FILE command types that are automatically processed by the Windows Media Player control, the Web page included with this sample 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 can be processed by the sample Web page. For instructions on using the Web page, see Viewing Output on the Sample Web Page. For examples of command lines, see the Sample.txt file included with this sample.
  
  
• Comments are denoted by a semicolon (;) in the first column of the line. For examples of command lines, see the Sample.txt file included with this sample.
  
  
• 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 instance of Windows Media Player. The other (Frame2.htm) is available for launching URL commands that are received from the scripting utility. Launching URLs in Frame 2 allows Windows Media Player to continue rendering the stream from Windows Media Encoder in Frame 1.

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

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

1. Start the Windows Media Encoder Scripting Utility.
   
   
2. From the utility, open the .asd file, and start the encoder.
   
   
3. Open the sample Web page from a browser.
   
   
4. Connect the Web page to the 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 the .asd file is loaded, and whether 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 cannot be started from the utility, or script commands are not being processed as expected on the sample Web page, try the following steps:

1. From the scripting utility, stop the encoder.
   
   
2. Restart 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 problem persists, check the configuration settings.
   
   
5. Use the Windows Media Tools documentation to troubleshoot the problem and correct the settings.

Location of the Sample

The sample is installed as part of the Windows Media Technologies SDK. By default, the encoder sample files are installed in \Program Files\Windows Media Components\Sdk\Samples\WMEScript.

These examples illustrate how to use HTML and Microsoft® Visual Basic® Scripting Edition, with attributes exposed by Windows Media Services.