Player.ScriptCommand event

Article
06/20/2023

[The feature associated with this page, Windows Media Player SDK, is a legacy feature. It has been superseded by MediaPlayer. MediaPlayer has been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer instead of Windows Media Player SDK, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The ScriptCommand event occurs when a synchronized command or URL is received.

Syntax

Player.ScriptCommand(
  scType,
  Param
)

Parameters

scType: String specifying the type of script command.
Param: String specifying the script command.

Return value

This event does not return a value.

Remarks

Commands can be embedded among the sounds and images of a Windows Media file or stream. The commands are a pair of Unicode strings associated with a designated time in the stream. When the stream reaches the time associated with the command, the Windows Media Player control sends a ScriptCommand event with two parameters. One parameter specifies the type of command being sent, and the other parameter specifies the command. The type of parameter is used to determine how the command parameter is processed. Any type of command can be embedded in a file or stream to be handled by the ScriptCommand event.

The following table lists script command types that are automatically processed by Windows Media Player.

Type	Description
CAPTION	The control displays the associated text in the DIV specified by ClosedCaption.captioningID.
EVENT	Tells the control to execute instructions defined for the specified event.
FILENAME	The control resets its URL property, attempts to open the specified file, and begins playing the new stream immediately.
OPENEVENT	Buffers the associated EVENT type command for timely execution of the EVENT script.
SYNCHRONIZEDLYRICLYRIC	The Param parameter contains the synchronized lyric text. Windows Media Player displays the lyric text in the closed caption area of the Now Playing feature.
TEXT	The control displays the associated text in the DIV specified by ClosedCaption.captioningID.
URL	The control automatically opens the URL specified using the default Internet browser if the Settings.invokeURLs property is set to true.

You can embed any other type of command as long as you provide reciprocal code to handle the command. Though unknown commands are ignored by the Windows Media Player control, they are still handed off to the ScriptCommand event.

URL commands received by the Windows Media Player control are invoked automatically in your default Web browser if the Settings.invokeURLs property is set to true. You can use the Settings.defaultFrame property to specify the target frame in which the webpage appears.

The URL sent to Windows Media Player is processed relative to the base URL specified by the Settings.baseURL property. The base URL is concatenated with the relatively specified URL, resulting in a fully specified URL that is passed as the command parameter by the ScriptCommand event.

The Windows Media Player control always processes incoming URL-type commands in the following manner:

A URL-type command is received.
Settings.baseURL is used to create a full URL from the relative URL specified in the script command.
ScriptCommand is called.
After ScriptCommand returns, Settings.invokeURLs is checked.
If Settings.invokeURLs is true and the command is a URL-type, the specified URL is invoked. If Settings.invokeURLs is false or if the command is not a URL-type, the command is ignored.

When authoring a Windows Media file, you can specify which frame the new URL is displayed in by concatenating two ampersands and the name of the frame in the parameter field. The example below illustrates typical ScriptCommand parameters. It specifies that the URL mypage must be launched in the myframe frame.

scType = "URL"
Param = https://myweb/mypage.html&&myframe

The ScriptCommand event is not called if the file is being scanned (fast-forwarded or fast-reversed).

The value of event parameters is specified by Windows Media Player, and can be accessed or passed to a method in an imported JScript file using the parameter name given. This parameter name must be typed exactly as shown, including capitalization.

Requirements

Requirement	Value
Version	Windows Media Player version 7.0 or later.
DLL	Wmp.dll